Skip to content

AGENTS.md

Latest commit

 

History

History
100 lines (78 loc) · 4.92 KB

AGENTS.md

File metadata and controls

100 lines (78 loc) · 4.92 KB

Agent Instructions

This repo is a VS Code extension for penetration testing workflows, written in TypeScript with a few Python generator scripts. It includes an embedded MCP server for external AI client integration.

Project layout

src/
├── app/               # Composition root (activate, registerCommands, registerCodeLens)
├── core/              # Pure domain logic (zero vscode imports)
│   ├── domain/        # Host, UserCredential, Finding, Graph, Foam types
│   ├── markdown/      # Fenced block & YAML block parsing
│   └── env/           # Environment variable Collects
├── features/          # Vertical feature slices — most work goes here
│   ├── ai/            # @weapon Copilot Chat participant + AIService
│   ├── decoder/       # CyberChef text decoding
│   ├── definitions/   # BloodHound hover/go-to-definition
│   ├── editor/        # Virtual document display, in-file replacement
│   ├── http/          # HTTP repeater (raw request, curl conversion)
│   ├── mcp/           # Embedded MCP HTTP server (httpServer, install, portManager)
│   ├── notes/         # Foam-based notes, report generation
│   ├── setup/         # Workspace scaffolding
│   ├── shell/         # Shell command runner CodeLens
│   ├── targets/       # Target sync, state management, graph builder
│   ├── tasks/         # Task commands (hashcat, msfvenom, scan)
│   └── terminal/      # Terminal profiles, recorder, TerminalBridge
├── platform/vscode/   # VS Code integration helpers (logger, context, variables)
├── shared/            # Cross-cutting utilities (types, globs)
├── snippets/source/   # GTFOBins, LOLBAS, BloodHound, Weapon snippets
└── test/unit/         # Unit tests for core/ layer
resources/             # Templates and static assets for generators
scripts/               # Python/TS generator scripts
docs/                  # Documentation (en + zh)

Build system

  • Package manager: pnpm (lockfile: pnpm-lock.yaml)
  • Bundler: webpack (webpack.config.js → dist/extension.js)
  • The MCP server is embedded in the extension — no separate build target

Key scripts

Script Purpose
pnpm run compile Dev build (webpack)
pnpm run watch Dev build with watch mode
pnpm run package Production build (webpack --mode production)
pnpm run vscode:prepublish Runs package (triggered by vsce)
pnpm run vscode:publish vsce package --no-dependencies → produces .vsix
pnpm run lint ESLint
pnpm run compile-tests Compile tests to out/ via tsc
pnpm run test:unit Run unit tests (7 test files covering core/)
pnpm run gen-setup Regenerate src/features/setup/assets.ts
pnpm run gen-report-assets Regenerate src/features/notes/reports/assets.ts

If network access is restricted, do not add dependencies or run install commands without explicit approval.

Generated code (do not hand-edit)

  • src/features/setup/assets.ts — generated by scripts/gen-setup.py
  • src/features/notes/reports/assets.ts — generated by scripts/gen-report-assets.py

When changing inputs under resources/**, update the generator if needed and regenerate the corresponding assets.ts.

MCP Server (embedded)

The MCP server runs inside the extension host as an HTTP server on 127.0.0.1. It is NOT a separate process — no file-based IPC is used.

  • Source: src/features/mcp/httpServer.ts
  • Transport: Streamable HTTP (POST /mcp)
  • State access: reads directly from the Context singleton (in-memory)
  • Terminal interaction: via TerminalBridge (in-process method calls)
  • Configuration: .vscode/mcp.json with URL entry (not stdio)

TypeScript conventions

  • Keep strict TypeScript compliance (tsconfig.json enables strictness).
  • Prefer import type { ... } for type-only imports.
  • Avoid any unless there is no reasonable alternative; prefer narrow local types.
  • Keep changes focused; avoid broad refactors unrelated to the request.
  • Favor small, well-named functions over large monolithic ones.
  • core/ must have zero vscode imports — this is a hard architectural boundary.

Packaging (.vscodeignore)

The .vscodeignore controls what goes into the .vsix. Key rules:

  • src/** is excluded, except src/snippets/source/** (referenced by package.json contributes.snippets)
  • dist/ is included (extension.js)
  • Source maps (**/*.map), docs, scripts, tests, and dev config are excluded

Dependency caveats

  • Do not edit files under node_modules/**.
  • If build/typecheck fails due to upstream foam-vscode types, document it, but don't patch dependencies unless explicitly requested.

Git hygiene

  • DO NOT perform any git operations (commits, branches, merges, rebases, etc.) without explicit user approval.
  • Only modify files as explicitly requested.