agentleFS
mshobeyrimshobeyri/multimeter/AGENTS.md

multimeter

AGENTS.md14 starsChanged 3 months agoApache-2.0View on GitHub

  • Commits and pushes
  • Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.

    Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

  • In this repository2 other files it gives its agents.

The file

Show its rules and text

We split this AGENTS.md into the rules it gives an agent

22 rules. About 0 are common, 2 are distinctive, and 20 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 20

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Do not reimplement parsing or execution pipelines in the extension or CLI – always go through runner.

    line 21
  2. Very specific:

    No imports from vscode, fs, path, browser APIs, or Node globals that assume a specific runtime.

    line 25
  3. Very specific:

    All file access, code execution, logging, and network plumbing come in via injected functions (fileLoader, jsRunner, logger, etc.).

    line 26
  4. Very specific:

    Add/adjust unit tests in core/src/*.test.ts that cover the new pure logic.

    line 37
  5. Very specific:

    Keep UI logic (layout, focus, interactions) here.

    line 49
  6. Very specific:

    If you add new CLI flags, wire them through to runner.runFile rather than duplicating parsing/execution.

    line 56
  7. Very specific:

    All HTTP/WS traffic flows through core/src/network/networkCore.ts + core/src/network/network.ts using NetworkConfig from NetworkData.ts.

    line 68
  8. Very specific:

    If status < 0, the wrapper builds outputs then fails the run so the Response panel can still show the network error.

    line 73
  9. Very specific:

    When extending logs, reuse helpers from createApiLogHelpers instead of ad-hoc console.log, and treat logs as append-only (especially in the …

    line 74
  10. Very specific:

    Do NOT add a VS Code preLaunchTask (or similar) that rebuilds webview/extension on every Extension Development Host F5/restart — compile …

    line 81
  11. Very specific:

    Do NOT touch CHANGELOG.md for regular fixes or features.

    line 82
  12. Distinctive:

    Ask for the exact version.

    line 86
  13. Distinctive:

    Never ship a VSIX whose version contains a hyphen.

    line 99
  14. Very specific:

    Avoid per-package custom build scripts.

    line 108
  15. Very specific:

    Always use curly braces for all control structures (e.g.

    line 113
  16. Very specific:

    Keep core free of editor/FS/UI dependencies.

    line 114
  17. Very specific:

    Commit message style: short, imperative (Add test auto complete, Improve UI of doc view).

    line 115
  18. Very specific:

    Prefer implementing behavior in core first, then wiring it to the extension (src/), webview (mmtview/), CLI (mmtcli/), and finally updating …

    line 117
  19. Very specific:

    Before refactoring shared APIs like runner.runFile or network helpers, search call sites in:

    line 118
  20. Very specific:

    After the run, buildApiTesterResponse (core/src/runner/apiRunResult.ts) shapes outputs._ into the Response panel payload.

    line 146
  21. Very specific:

    Not urgent — no current testlight breaking changes — but keep in mind:

    line 230
  22. Very specific:

    MCP scaffold (mmtmcp/): When changing scaffold_test / agent write paths, prefer PR-ready .mmt with real asserts/schema (“receipt”).

    line 233

≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

Copilot Instructions for multimeter (mmt)

Project structure & architecture

  • Website: https://mmt.dev (NOT multimeter.dev). Public test server: https://test.mmt.dev. In-process twin: https://local.mmt.dev (and ws:// / wss:// / *.local.mmt.dev) — answered inside networkCore via core/src/network/localTestServer.ts (shared with the Cloudflare worker); no DNS/sockets/internet.
  • Monorepo layout:
    • core/: pure TypeScript library with all parsing, execution and network logic (no VS Code, no fs – use dependency injection).
    • mmtview/: React + VS Code webview UI for editing/running .mmt files.
    • mmtcli/: CLI app; binary is testlight, used for CI and local runs.
    • mmtaction/: GitHub Action product (action.yml), published to mshobeyri/testlight-action. Not an action this repo consumes.
    • mmtazure/: Azure Pipelines task product (Testlight@1). Same idea as mmtaction/.
    • mmtmcp/: MCP server package.
    • Root src/: VS Code extension host code (activation, editor provider, assistant, network bridge).
    • docs/: user-facing documentation (API, test, env, suite, CLI, convertor, etc.).
    • AI/: internal AI-assisted development artifacts. Not shipped to users.
      • sdd/: Software Design Documents (SDDs) — architectural decisions, competitive strategy, feature designs.
      • marketing/: LinkedIn, YouTube, Hacker News / Show HN skills, drafts, and meeting memos (meetings/). Not part of the published Cursor plugin.
      • skills/: local/dev agent skills (e.g. release & deploy). Not part of the published Cursor plugin.
      • doc/: handover and context documents for AI agent sessions.
  • Single source of truth for running .mmt files is core/src/runner/runner.ts:
    • Use runner.runFile({ rawFile, filePath, inputs, envvar, fileLoader, jsRunner, logger }).
    • Do not reimplement parsing or execution pipelines in the extension or CLI – always go through runner.

Core library (core/) patterns

  • Keep core platform-neutral:
    • No imports from vscode, fs, path, browser APIs, or Node globals that assume a specific runtime.
    • All file access, code execution, logging, and network plumbing come in via injected functions (fileLoader, jsRunner, logger, etc.).
  • Key modules to know:
    • runner.ts: orchestrates .mmt execution, builds API/test runners, and formats logs/docs.
    • JSer.ts, testParsePack.ts, apiParsePack.ts: turn YAML .mmt into executable JS flows.
    • networkCore.ts, network.ts, NetworkData.ts: HTTP/WebSocket client, message routing, and shared network config types.
    • outputExtractor.ts + pathAtPosition.test.ts: JSON/XML/xpath/jsonpath/regex extraction and “path at cursor” helpers.
    • tokens/variableReplacer.ts: single source of truth for all token-matching regex and replacement logic. All regex patterns and token accessor handling for e:, i:, r:, c: tokens (including forms like [0], [0:3], and .field) live here. Other modules (JSerHelper, JSerTestFlow, JSerAPI, etc.) import helpers from variableReplacer — they must NOT define their own token-matching regexes.
    • YAML on disk: bare whole-value tokens (r:int) and embedded <<prefix:name>>. API tester UI uses {{prefix:name}}; that curly form is also accepted in YAML and normalized to bare / <<>> on parse (markupConvertor + reviveDisplayRuntimeTokensInValue). See AI/sdd/sdd-token-form-consistency.md.
    • Return types for JSON UI quoting: randomTokenValueType / currentTokenValueType in Random.ts / Current.ts (not hardcoded allowlists in the UI layer).
  • When extending behavior:
    • First update the relevant data model types in core/src/*Data.ts (e.g. APIData, TestData, NetworkConfig).
    • Add/adjust unit tests in core/src/*.test.ts that cover the new pure logic.

VS Code extension + webview

  • Extension host (src/):
    • extension.ts: entrypoint; registers the .mmt custom editor, side panels (temp files, history, mock server, environment, certificates), and chat participants from src/assistant.ts.
    • mmtEditorProvider.ts: glue between webview messages and runner.runFile. It:
      • Receives command messages like runCurrentDocument, runCurlCommand, etc.
      • Calls runner.runFile({ rawFile: document.getText(), filePath: document.uri.fsPath, inputs, envvar, fileLoader, jsRunner, logger }).
    • vscodeNetwork.ts: adapts VS Code configuration and environment to NetworkConfig and bridges webview/network messages into core.
  • Webview React app (mmtview/src/):
    • Uses window.vscode.postMessage via helpers in vsAPI.ts instead of importing core directly.
    • text/YamlEditorPanel.tsx drives run glyphs for .mmt files; it sends structured inputs shapes (type: 'defaults' | 'manual' | 'exampleId' | 'exampleIndex') back to the extension.
    • Keep UI logic (layout, focus, interactions) here; keep parsing/execution in core.

CLI (mmtcli/) workflow

  • Entrypoint: mmtcli/src/cli.ts wraps core and exposes the testlight binary.
  • Typical usage (see mmtcli/README.md and docs/features/testlight/index.md):
    • npx testlight run path/to/test.mmt
    • Pass env via --env-file, --preset, and -e KEY=VALUE flags; types are coerced by coerceCliValue/parsePairs in cli.ts (unquoted numbers/bools → numbers/bools, quoted → strings).
  • If you add new CLI flags, wire them through to runner.runFile rather than duplicating parsing/execution.

.mmt data model and docs

  • .mmt is YAML with type driving behavior, parsed by JSer.fileType:
    • type: api → HTTP/WebSocket API definitions (see docs/files/api/index.md).
    • type: test → executable test flows (call, assert, check, etc.; see docs/files/test/index.md).
    • type: env → environment and variable files (see docs/files/env/index.md).
  • Converters and docs:
    • core/src/convert/openapiConvertor.ts, postmanConvertor.ts: turn OpenAPI/Postman into .mmt API/test files.
    • core/src/doc/docHtml.ts, docMarkdown.ts, core/src/parse/docParsePack.ts and res/doc-template.html: generate HTML/Markdown API docs from .mmt.

Network, logging, and errors

  • All HTTP/WS traffic flows through core/src/network/networkCore.ts + core/src/network/network.ts using NetworkConfig from NetworkData.ts.
  • HTTP helpers always return a structured HttpResponse; network-level failures are normalized (e.g. status = -1, descriptive statusText) so callers can distinguish unreachable hosts from HTTP errors.
  • Two layers: (1) Execution — request/response via runner.runFile / send_ (HTTP, GraphQL, gRPC, one-shot WS). (2) Live sessions — API tester Connect + Connections panel via the network bridge. Do not dual-fire HTTP Send (webview send + core run).
  • API runs use buildApiRunnerWrapper in runApi.ts:
    • Log Request, Response, Environment, and Inputs sections with consistent key/value formatting.
    • If status < 0, the wrapper builds outputs then fails the run so the Response panel can still show the network error.
  • When extending logs, reuse helpers from createApiLogHelpers instead of ad-hoc console.log, and treat logs as append-only (especially in the extension output channel).

Workflow / agent rules

  • Start a Multimeter project. When the user (or you) is starting/scaffolding a project with several APIs + tests and no other layout is requested, follow docs/AI/project-layout.md and the mother guide docs/tasks/start-a-project.md (especially Where values live: env = user knobs / API Send defaults; JSON = fixed shared catalogs; direct in the test = scenario values like date windows). Defaults: root multimeter.mmt, api/, test/<area>/{suite.mmt,test_*.mmt}, +/… imports, unquoted operator expects, expect+report: all over single-output check. Sample repos under examples/real-projects/ illustrate the same rules; they are not the only use of this layout.
  • Compile on every finished coding task. Whenever you finish a coding task with the user (task complete, “done”, wrapping up a multi-step change, or handing work back), run npm run compile at the repo root, fix any compile errors, and only then treat the work as finished. Do this even if tests already passed. Skip only when no source files were changed (docs-only / SDD-only / config-only with no code).
  • Do NOT create, stage, or push git commits unless the user explicitly asks you to do so. Always ask for confirmation before running any git add, git commit, or git push operations. You may edit files in the workspace to make suggested changes, but do not record those changes in version control until the user gives explicit permission. When edits are made without committing, clearly list the modified files and the intended commit message so the user can approve.
  • Do NOT add a VS Code preLaunchTask (or similar) that rebuilds webview/extension on every Extension Development Host F5/restart — compile explicitly via npm run compile / watch instead. Reloading the target while a heavy preLaunch rebuild runs is a common cause of the debug host stopping.
  • Do NOT touch CHANGELOG.md for regular fixes or features. It is written only as part of the release workflow, from the commits included in that release.

Release workflow

Ask for the exact version. Do not invent one.

  • "release X.Y.Z" → stable. package.json, mmtcli/package.json, and mmtmcp/package.json are all X.Y.Z. Tag vX.Y.Z.
  • "pre-release X.Y.Z" → extension package.json is X.Y.Z (Marketplace cannot have -pre). CLI and MCP are X.Y.Z-pre. Tag vX.Y.Z-pre.

CLI (mmt-testlight) and MCP (mmt-mcp) share one npm version and dist-tag: stable → @latest, pre → @pre. mmtmcp/server.json must match that same MCP version (CI --check enforces it). Then CHANGELOG, always pack a local VSIX (npm run pack or npm run pack-pre-release), commit Release version …, push the tag.

GitHub Actions (.github/workflows/release-testlight.yml) builds binaries, creates the GitHub Release, then publishes npm (both packages), Docker, Homebrew (stable), and the GitHub Action (stable only).

VS Code Marketplace pre-releases are published from Azure Pipelines (azure-pipelines.yml in Azure DevOps project mehrdadshobeyri / multimeter), not from GitHub Actions. Pushing vX.Y.Z-pre packs the VSIX and runs vsce publish --pre-release (publisher mshobeyri; secret VSCE_PAT on that pipeline). Manual pipeline runs on a branch only pack. v1.44.0-pre is skipped. After a pre-release tag, confirm that Azure run succeeded.

Stable Marketplace, Open VSX, and the official MCP Registry are not published from GitHub CI. After a stable release, publish the same VSIX to Marketplace and to Open VSX (npx ovsx publish ./multimeter-X.Y.Z.vsix), then check https://open-vsx.org/user-settings/extensions/mshobeyri/multimeter matches X.Y.Z. After npm mmt-mcp@X.Y.Z is on @latest, publish mmtmcp/server.json with mcp-publisher publish and confirm https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.mshobeyri/multimeter shows X.Y.Z. Skip Open VSX and the MCP Registry on pre-releases.

Never ship a VSIX whose version contains a hyphen.

Secrets: NPM_TOKEN, DOCKERHUB_*, TESTLIGHT_ACTION_TOKEN, HOMEBREW_TAP_TOKEN. Marketplace pre-release: Azure DevOps pipeline secret VSCE_PAT.

Build, test, and packaging

  • From repo root:
    • npm run compile --silent – build all apps (core, extension, webview, CLI) via the shared pipeline.
    • npm run test – run Jest tests (mostly core/src/*.test.ts).
  • VS Code extension packaging: run npm run pack at the repo root to create the .vsix (uses EXTENSION.md as the marketplace readme).
  • Avoid per-package custom build scripts; integrate new build steps into the root package.json.

Conventions and change strategy

  • Style:
    • 2-space indentation, no tabs; always use braces even for single-line if/loops.
    • Always use curly braces for all control structures (e.g. if, else, for, while, do, switch, etc.), even when the body is a single line. This avoids ambiguous or hard-to-read one-line constructs.
    • Keep core free of editor/FS/UI dependencies; put VS Code, fs, browser, and React code in src/ or mmtview/ instead.
    • Commit message style: short, imperative (Add test auto complete, Improve UI of doc view).
  • Change flow:
    • Prefer implementing behavior in core first, then wiring it to the extension (src/), webview (mmtview/), CLI (mmtcli/), and finally updating docs under docs/.
    • Before refactoring shared APIs like runner.runFile or network helpers, search call sites in:
      • core/src/runner/runner.ts, src/mmtEditorProvider.ts, src/assistant.ts, src/vscodeNetwork.ts, mmtcli/src/cli.ts, mmtview/src/**.
    • For new user-facing features (commands, panels, assistant behaviors), keep CLI and VS Code behavior aligned when reasonable and document any intentional differences.

Real execution flows (current code)

This section captures the current runtime flow through the webview → extension host → core runner, including how leafId is used end-to-end for suite targeting and report routing.

Run an API .mmt file (type: api)

flowchart TD
  A["Webview UI - Send / Run API"] --> B["postMessage (runCurrentDocument)"]
  B --> C["Extension host (mmtAPI/run)"]
  C --> D["core runner (runner.runFile)"]
  D --> E["JSer.fileType"]
  E -->|api| F["runApi"]
  F --> G["runCommon.runGeneratedJs"]
  G --> H["jsRunner exec (sets globals)"]
  F --> I["networkCore send_ / sendGrpc_"]
  I --> F
  F --> J["outputs + finish log duration from res.duration"]
  J --> K["Extension posts multimeter.api.run.result"]
  K --> L["Webview Response panel + toolbar duration"]

Notes:

  • Send (HTTP/GraphQL/gRPC) and Run in Core share this path — one network round-trip. Do not also call webview network.send for those protocols.
  • After the run, buildApiTesterResponse (core/src/runner/apiRunResult.ts) shapes outputs._ into the Response panel payload.
  • For API finish logs, jsRunner prefers last send_/sendGrpc_ res.duration over wall-clock.
  • Interactive WebSocket Connect/live Send stays on the live network bridge (network.ts + Connections panel), not runCurrentDocument.
  • One-shot WS in tests/CLI uses sendWsRequest (connect → send → one reply → close).
  • Plain API runs generally don’t originate a leafId.

Run a Test .mmt file (type: test)

flowchart TD
  A["Webview UI - Run Test"] --> B["postMessage (runCurrentDocument)"]
  B --> C["Extension host (mmtEditorProvider/run)"]
  C --> D["core runner (runner.runFile)"]
  D --> E["JSer.fileType"]
  E -->|test| F["runTest (JSer -> JS)"]
  F --> G["runCommon.runGeneratedJs"]
  G --> H["jsRunner exec (with globals)"]
  H --> I["testHelper emits test-step/test-step-run (includes leafId when set)"]
  I --> J["Reporter callback (extension)"]
  J --> K["Extension forwards runFileReport"]
  K --> L["Webview shows steps/asserts"]

Run a Suite .mmt file (type: suite) - suite bundle run (current)

flowchart TD
  A["Suite webview - Run Suite"] --> B["postMessage (runSuite)"]
  B --> C["Extension host (src/mmtAPI/run.ts)"]
  C --> C0["Build suite hierarchy (core/suiteHierarchy)"]
  C0 --> C1["Build suite bundle (core/suiteBundle)"]
  C1 --> D["core runner (runner.runFile + suiteBundle + suiteTargets)"]
  D --> E["executeSuiteBundle"]
  E --> S0["Reporter: scope=suite-run-start"]
  E --> G["Reporter: scope=suite-item + id (running/passed/failed)"]
  E --> H["For each runnable node: run as child with runId + id"]
  H --> D
  D --> I["Child events (test-step/test-step-run/api logs) include id"]
  S0 --> J0["Extension maps to command=suiteRunStart"]
  G --> J1["Extension forwards command=runFileReport"]
  I --> J1
  E --> S1["Reporter: scope=suite-run-finished"]
  S1 --> J2["Extension maps to command=suiteRunEnd"]
  J0 --> K["Webview updates UI"]
  J1 --> K
  J2 --> K

Notes:
- A suite entry can resolve to a `type: test` file or another `type: suite` file. Both are runnable bundle node kinds.
- Targeting is by a single `target` **node id** (webview sends `target: string`), not a `leafId[]`.
- Execution semantics: bundle is traversed sequentially at the top-level, but `group` children run in parallel (mirrors `then` stage behavior).
- Child `runId` values are generated per runnable node and are stable enough for routing within a run.

Run a subtree / node in the suite tree (partial run)

Per-item Run buttons send a single target: string (the bundle node id). The extension passes this into suiteBundle.createSuiteBundle({ target }), and core executes the subtree rooted at target.

flowchart TD
  A["Click Run on node"] --> B["Suite webview computes targets (leafId[])"]
  B --> C["postMessage (runSuite + target)"]
  C --> D["Extension host (src/mmtAPI/run.ts)"]
  D --> E["core runner.runFile (suiteBundle)"]
  E --> F["executeSuiteBundle selects root by id"]
  F --> G["Reporter events include id"]
  G --> H["Webview routes output by id"]

Notes:

  • The bundle is built in the extension using core helpers, but execution happens in core.
  • The UI must never invent ids for targeting; only deterministic bundle node ids are valid targets.

Suite bundle (current)

Suite runs are executed via a core-native suite bundle runner.

  • Node identity: id is the single end-to-end identifier for runnable nodes.
  • Lifecycle: core emits scope: 'suite-run-start' / scope: 'suite-run-finished' reporter events.
  • Per-item: core emits scope: 'suite-item' with status: 'running' | 'passed' | 'failed' and the related id.
  • Step routing: child runs receive id, and downstream test-step events should be routed by id (extension currently backfills id using runId mapping when needed).

Open follow-ups (community, 2026-11-14)

Not urgent — no current testlight breaking changes — but keep in mind:

  1. CI docs (pinning): Quick-start may keep floating npx for try-it. Production CI docs should say to pin mshobeyri/testlight-action@v1 (or lock mmt-testlight in package.json + lockfile). Floating runner ⇒ green can break with no .mmt change.
  2. MCP scaffold (mmtmcp/): When changing scaffold_test / agent write paths, prefer PR-ready .mmt with real asserts/schema (“receipt”). Avoid defaults that only pass against invented mocks so agents don’t ship green fiction.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.