From ee5d2653b2c7fb513d281444abc5ccf9fa8d074f Mon Sep 17 00:00:00 2001 From: ZyntroAI Date: Sat, 12 Sep 2026 22:31:15 +0700 Subject: [PATCH] commit --- .http-forge/AGENTS.md | 218 ++++++++++++++++++++++++++++++++++++++++ .snapshots/config.json | 151 ++++++++++++++++++++++++++++ .snapshots/readme.md | 11 ++ .snapshots/sponsors.md | 44 ++++++++ .vscode/extensions.json | 3 +- .vscode/launch.json | 35 +++++++ 6 files changed, 461 insertions(+), 1 deletion(-) create mode 100644 .http-forge/AGENTS.md create mode 100644 .snapshots/config.json create mode 100644 .snapshots/readme.md create mode 100644 .snapshots/sponsors.md diff --git a/.http-forge/AGENTS.md b/.http-forge/AGENTS.md new file mode 100644 index 0000000..cb49c1e --- /dev/null +++ b/.http-forge/AGENTS.md @@ -0,0 +1,218 @@ +# HTTP Forge — AI Agent Guide + +This folder is already the **HTTP Forge workspace root**. Do not create a second nested `.http-forge/` directory inside it. + +> **GitHub Copilot tip:** To keep this guide in every Copilot conversation, add one line to +> `.github/copilot-instructions.md`: `See .http-forge/AGENTS.md for the HTTP Forge AI guide.` + +--- + +## Decision Tree — What to Use and When + +HTTP Forge gives AI agents three ways to interact with a workspace. +**Choose the lowest-cost option that can complete the task:** + +``` +Task + │ + ├─ Discover structure / read or edit collections, requests, environments, suites? + │ └─ ✅ Read / write the JSON files directly (zero token cost, always available) + │ + ├─ Execute a request, collection, folder, or suite? + │ ├─ Is @http-forge/cli installed? (check: http-forge --version) + │ │ ├─ YES → ✅ CLI (lower token cost — no tool schema preloaded) + │ │ │ http-forge run collection --env --json + │ │ │ http-forge run suite --json + │ │ │ http-forge run request --collection --json + │ │ └─ NO → ✅ MCP run_collection / run_suite / run_request + │ │ + │ └─ Need async execution or real-time polling? + │ └─ ✅ MCP run_collection --async, then get_run_status / get_run_summary + │ + └─ Diagnose failures, suggest assertions, explain errors? + └─ ✅ MCP explain_failure / suggest_assertions / analyze-test-failure prompt + + └─ Design a NEW API from a plain-English intent (endpoints + DTOs + auth)? + ├─ Is @http-forge/cli installed? (check: http-forge --version) + │ └─ YES → ✅ CLI http-forge architect "I need a shopping cart" + └─ NO → ✅ MCP design_api_from_intent (then review; apply:true to approve) +``` + +--- + +## Why This Ordering? + +| Method | Token cost | Always available | Can execute | Best for | +|--------|:----------:|:----------------:|:-----------:|---------| +| Direct file access | **Zero** | ✅ (if file system access) | ❌ | Discover, read, create, edit | +| CLI `http-forge run` | **Low** (no tool schema) | ❌ (must be installed + shell access) | ✅ | Execution when CLI is present | +| MCP tools | **Medium** (schemas preloaded) | ✅ (when extension runs) | ✅ | Execution fallback; AI analysis | + +**Key rule:** Never use MCP or CLI to discover structure — just read the JSON files. +`list_collections`, `list_requests`, `get_request` are redundant when you have file access. + +--- + +## Folder Structure + +> Important: this directory is the workspace root. Use the paths below as-is; do not create another nested `.http-forge/` directory. + +``` +assets/ + collections/ + {collection-slug}/ + collection.json ← collection metadata (id, name, variables, auth, order) + scripts/ + pre-request.js ← collection-level pre-request script + post-response.js ← collection-level post-response script + {folder-slug}/ + folder.json ← folder metadata + scripts/ + pre-request.js ← folder-level pre-request script + post-response.js ← folder-level post-response script + {request-slug}/ + request.json ← request (method, url, headers, auth, body, scripts…) + body.json ← JSON body (when bodyContentType is application/json) + body.txt ← raw text body + body.graphql ← GraphQL query + doc.md ← optional business docs for this request (fed to AI) + scripts/ + pre-request.js ← request-level pre-request script + post-response.js ← assertions live here (pm.test() calls) + environments/ + _global.json ← global variables + defaultHeaders (all envs) + {env}.json ← per-environment variables + {env}.local.json ← local overrides — gitignored, never commit + suites/ + {name}.suite.json ← test suite with control-flow nodes +``` + +--- + +## Business Knowledge (`.http-forge/knowledge/`) + +HTTP Forge feeds business context into every AI feature (assertion suggestions, +failure diagnosis, request generation, scenario generation, env-var suggestions, +collection enhancement, and the `analyze-test-failure` / `suggest-assertions` / +`review-collection` prompts). The AI uses it to write realistic tests and +accurate diagnoses. + +Drop markdown files into `.http-forge/knowledge/` (any depth): + +``` +.http-forge/ + knowledge/ + api-overview.md ← Confluence export: what the API does, auth model + jira/API-123.md ← Jira ticket summaries / ACs relevant to tests + decisions/adr-007.md ← Architecture decision records + field-glossary.md ← Meanings of domain fields the tests assert on +``` + +Every `*.md` file under `.http-forge/knowledge/` is loaded and included in AI +prompts, along with the workspace `README.md` and `AGENTS.md`. Prefer short, +dense notes — the knowledge is bounded to keep token cost predictable. There is +no need to paste Confluence/Jira content into collection files themselves. + +Per-request business docs can also live next to a request as `doc.md` +(alongside `request.json`) — HTTP Forge loads it and passes it to AI features +automatically. + +--- + +## JSON Schemas + +Every file contains a `$schema` field — your editor and AI can validate files automatically. + +| File | Schema URL | +|------|-----------| +| `collection.json` | `https://raw.githubusercontent.com/hsl1230/http-forge/main/resources/collection.schema.json` | +| `folder.json` | `https://raw.githubusercontent.com/hsl1230/http-forge/main/resources/folder.schema.json` | +| `request.json` | `https://raw.githubusercontent.com/hsl1230/http-forge/main/resources/request.schema.json` | +| `{env}.json` | `https://raw.githubusercontent.com/hsl1230/http-forge/main/resources/environment.schema.json` | +| `_global.json` | `https://raw.githubusercontent.com/hsl1230/http-forge/main/resources/global-environment.schema.json` | +| `*.suite.json` | `https://raw.githubusercontent.com/hsl1230/http-forge/main/resources/suite.schema.json` | + +--- + +## Authoring by Direct File Editing + +### Create a new request +1. Create directory: `assets/collections/{collection-slug}/{optional-folder-slug}/{request-slug}/` +2. Write `request.json` (use the schema above for all valid fields) +3. Add the slug to `order` in the parent `collection.json` or `folder.json` +4. Optionally add `pre-request.js` and/or `post-response.js` for scripts/assertions + +### Edit a request +Read `request.json`, modify fields, write it back. +Variables: `{{variableName}}`. Filters: `{{value | upper}}`, `{{date | date:'YYYY-MM-DD'}}`. + +### Bulk update (e.g. change baseUrl across all requests) +Find-and-replace across the `assets/collections/` tree — no MCP needed. + +### Add / update environment variables +Edit `assets/environments/{env}.json` directly. + +### Create or edit a test suite +Write or edit `assets/suites/{name}.suite.json`. +Supports: `request`, `block`, `if/elseif/else`, `for`, `while`, `switch`, `script` nodes. + +--- + +## Execution: CLI Commands (when installed) + +```bash +# Check if CLI is available +http-forge --version + +# Run a collection (outputs JSON to stdout) +http-forge run collection --env --json + +# Run a specific folder within a collection +http-forge run folder --collection --json + +# Run a single request +http-forge run request --collection --json + +# Run a test suite +http-forge run suite --json + +# Design a new API from an intent (persists a collection; add --apply to +# persist the suite + write flow/docs/OpenAPI byproducts) +http-forge architect "I need a shopping cart" +http-forge architect "a todo list" --apply --flow-out ./todo.flow.js --docs-out ./todo.md + +# Pipe output to filter results (saves tokens — AI only sees what it needs) +http-forge run collection auth --json | jq '.failedRequests' +http-forge run suite checkout --json | jq '.summary' +``` + +Output always contains: `summary` (total/passed/failed) and `failedRequests` (when failures exist). +For collection/suite/folder runs, add `--include report` to generate an HTML report (`report.uri`) with full response details — useful for inspecting large response bodies without consuming extra tokens. + +--- + +## Execution: MCP Tools (always available when extension runs) + +Use MCP when: +- CLI is not installed or no shell access is available +- Async / long-running execution with real-time polling is needed +- AI analysis tools are needed (failure diagnosis, assertion suggestions) + +``` +run_request → execute one request +run_folder → execute a folder within a collection +run_collection → execute an entire collection +run_suite → execute a test suite + └─ add async:true for background execution, then poll with get_run_status + +get_run_summary → summary + failed requests after a run completes +get_failed_requests → paginated failed request details +explain_failure → AI-powered root cause analysis +suggest_assertions → generate pm.test() assertions for a request +``` + +> **Token tip:** Response bodies are truncated at 4 KB by default. +> Pass `include: ["fullBody"]` to get the complete body. +> For collection / suite / folder runs, pass `include: ["report"]` to generate an HTML report +> (`report.uri`) — open it in a browser to inspect full response details without consuming tokens. +> Single `run_request` calls do not generate a report unless `include: ["report"]` is also passed. diff --git a/.snapshots/config.json b/.snapshots/config.json new file mode 100644 index 0000000..dfadca2 --- /dev/null +++ b/.snapshots/config.json @@ -0,0 +1,151 @@ +{ + "excluded_patterns": [ + ".git", + ".gitignore", + "gradle", + "gradlew", + "gradlew.*", + "node_modules", + ".snapshots", + ".idea", + ".vscode", + "*.log", + "*.tmp", + "target", + "dist", + "build", + ".DS_Store", + "*.bak", + "*.swp", + "*.swo", + "*.lock", + "*.iml", + "coverage", + "*.min.js", + "*.min.css", + "__pycache__", + ".marketing", + ".env", + ".env.*", + "*.jpg", + "*.jpeg", + "*.png", + "*.gif", + "*.bmp", + "*.tiff", + "*.ico", + "*.svg", + "*.webp", + "*.psd", + "*.ai", + "*.eps", + "*.indd", + "*.raw", + "*.cr2", + "*.nef", + "*.mp4", + "*.mov", + "*.avi", + "*.wmv", + "*.flv", + "*.mkv", + "*.webm", + "*.m4v", + "*.wfp", + "*.prproj", + "*.aep", + "*.psb", + "*.xcf", + "*.sketch", + "*.fig", + "*.xd", + "*.db", + "*.sqlite", + "*.sqlite3", + "*.mdb", + "*.accdb", + "*.frm", + "*.myd", + "*.myi", + "*.ibd", + "*.dbf", + "*.rdb", + "*.aof", + "*.pdb", + "*.sdb", + "*.s3db", + "*.ddb", + "*.db-shm", + "*.db-wal", + "*.sqlitedb", + "*.sql.gz", + "*.bak.sql", + "dump.sql", + "dump.rdb", + "*.vsix", + "*.jar", + "*.war", + "*.ear", + "*.zip", + "*.tar", + "*.tar.gz", + "*.tgz", + "*.rar", + "*.7z", + "*.exe", + "*.dll", + "*.so", + "*.dylib", + "*.app", + "*.dmg", + "*.iso", + "*.msi", + "*.deb", + "*.rpm", + "*.apk", + "*.aab", + "*.ipa", + "*.pkg", + "*.nupkg", + "*.snap", + "*.whl", + "*.gem", + "*.pyc", + "*.pyo", + "*.pyd", + "*.class", + "*.o", + "*.obj", + "*.lib", + "*.a", + "*.map", + ".npmrc" + ], + "default": { + "default_prompt": "Enter your prompt here", + "default_include_all_files": false, + "default_include_entire_project_structure": true + }, + "included_patterns": [ + "build.gradle", + "settings.gradle", + "gradle.properties", + "pom.xml", + "Makefile", + "CMakeLists.txt", + "package.json", + "requirements.txt", + "Pipfile", + "Gemfile", + "composer.json", + ".editorconfig", + ".eslintrc.json", + ".eslintrc.js", + ".prettierrc", + ".babelrc", + ".dockerignore", + ".gitattributes", + ".stylelintrc", + ".npmrc" + ] +} \ No newline at end of file diff --git a/.snapshots/readme.md b/.snapshots/readme.md new file mode 100644 index 0000000..21fa917 --- /dev/null +++ b/.snapshots/readme.md @@ -0,0 +1,11 @@ +# Snapshots Directory + +This directory contains snapshots of your code for AI interactions. Each snapshot is a markdown file that includes relevant code context and project structure information. + +## What's included in snapshots? +- Selected code files and their contents +- Project structure (if enabled) +- Your prompt/question for the AI + +## Configuration +You can customize snapshot behavior in `config.json`. diff --git a/.snapshots/sponsors.md b/.snapshots/sponsors.md new file mode 100644 index 0000000..2df337f --- /dev/null +++ b/.snapshots/sponsors.md @@ -0,0 +1,44 @@ +# Thank you for using Snapshots for AI + +Thanks for using Snapshots for AI. We hope this tool has helped you solve a problem or two. + +If you would like to support our work, please help us by considering the following offers and requests: + +## Ways to Support + +### Join the GBTI Network!!! 🙏🙏🙏 +The GBTI Network is a community of developers who are passionate about open source and community-driven development. Members enjoy access to exclussive tools, resources, a private MineCraft server, a listing in our members directory, co-op opportunities and more. + +- Support our work by becoming a [GBTI Network member](https://gbti.network/membership/). + +### Try out BugHerd 🐛 +BugHerd is a visual feedback and bug-tracking tool designed to streamline website development by enabling users to pin feedback directly onto web pages. This approach facilitates clear communication among clients, designers, developers, and project managers. + +- Start your free trial with [BugHerd](https://partners.bugherd.com/55z6c8az8rvr) today. + +### Hire Developers from Codeable 👥 +Codeable connects you with top-tier professionals skilled in frameworks and technologies such as Laravel, React, Django, Node, Vue.js, Angular, Ruby on Rails, and Node.js. Don't let the WordPress focus discourage you. Codeable experts do it all. + +- Visit [Codeable](https://www.codeable.io/developers/?ref=z8h3e) to hire your next team member. + +### Lead positive reviews on our marketplace listing ⭐⭐⭐⭐⭐ +- Rate us on [VSCode marketplace](https://marketplace.visualstudio.com/items?itemName=GBTI.snapshots-for-ai) +- Review us on [Cursor marketplace](https://open-vsx.org/extension/GBTI/snapshots-for-ai) + +### Star Our GitHub Repository ⭐ +- Star and watch our [repository](https://github.com/gbti-network/vscode-snapshots-for-ai) + +### 📡 Stay Connected +Follow us on your favorite platforms for updates, news, and community discussions: +- **[Twitter/X](https://twitter.com/gbti_network)** +- **[GitHub](https://github.com/gbti-network)** +- **[YouTube](https://www.youtube.com/channel/UCh4FjB6r4oWQW-QFiwqv-UA)** +- **[Dev.to](https://dev.to/gbti)** +- **[Daily.dev](https://dly.to/zfCriM6JfRF)** +- **[Hashnode](https://gbti.hashnode.dev/)** +- **[Discord Community](https://gbti.network)** +- **[Reddit Community](https://www.reddit.com/r/GBTI_network)** + +--- + +Thank you for supporting open source software! 🙏 diff --git a/.vscode/extensions.json b/.vscode/extensions.json index c198485..d243198 100644 --- a/.vscode/extensions.json +++ b/.vscode/extensions.json @@ -2,6 +2,7 @@ "recommendations": [ "dbaeumer.vscode-eslint", "esbenp.prettier-vscode", - "ms-python.python" + "ms-python.python", + "rakshex.rakshex-vscode" ] } diff --git a/.vscode/launch.json b/.vscode/launch.json index e0e5b1d..79cd3a9 100644 --- a/.vscode/launch.json +++ b/.vscode/launch.json @@ -1,6 +1,41 @@ { "version": "0.2.0", "configurations": [ + { + "name": ".NET Core Launch (console)", + "type": "coreclr", + "request": "launch", + "preLaunchTask": "build", + "program": "${workspaceFolder}/bin/Debug//", + "args": [], + "cwd": "${workspaceFolder}", + "stopAtEntry": false, + "console": "internalConsole" + }, + { + "name": ".NET Core Attach", + "type": "coreclr", + "request": "attach" + }, + { + "type": "myriaddreamin.typst-debugger", + "request": "launch", + "name": "Ask for file name", + "program": "${workspaceFolder}/${command:AskForProgramName}", + "stopOnEntry": true + }, + { + "args": [ + "--extensionDevelopmentPath=${workspaceFolder}" + ], + "name": "Launch Extension", + "outFiles": [ + "${workspaceFolder}/out/**/*.js" + ], + "preLaunchTask": "npm", + "request": "launch", + "type": "extensionHost" + }, { "name": "Launch Extension", "type": "extensionHost",