mmt-testlight 0.4.4 → 0.4.5

package/dist/guides/min/constraints.md

@@ -0,0 +1,9 @@
+# Constraints (min)
+
+- Valid YAML only; first non-comment line is `type: …`
+- No YAML comments (`#`) in generated `.mmt`
+- Snake_case tokens: `e:`, `i:`, `r:`, `c:`
+- New API tests: scaffold first, then minimal edits
+- Modify: patch only; validate after every edit
+- Never invent Postman/`pm.` syntax
+- Prefer smoke coverage unless asked for more

package/dist/guides/min/doc.md

@@ -0,0 +1,17 @@
+# Generate `type: doc` (min)
+
+```yaml
+type: doc
+title: My API docs
+sources:
+  - ./apis
+```
+
+## Essentials
+
+- First line: `type: doc`
+- `sources` lists API `.mmt` files or directories
+- Optional: `description`, `logo`, `services`
+- Build with `testlight doc <file.mmt>`
+
+Request `pack: full` for multi-service layouts.

package/dist/guides/min/env.md

@@ -0,0 +1,26 @@
+# Generate `type: env` (min)
+
+```yaml
+type: env
+variables:
+  api_url:
+    dev: http://localhost:8080
+    prod: https://test.mmt.dev
+  mode:
+    - debug
+    - info
+presets:
+  runner:
+    dev:
+      api_url: http://localhost:8080
+      mode: debug
+```
+
+## Essentials
+
+- First line: `type: env`
+- `variables` required; each var is a map of choices or a list of allowed values
+- `presets` optional; values must match variable choices
+- APIs/tests consume via `e:api_url` / `<<e:api_url>>`
+
+Request `pack: full` for multi-group presets and UI details.

package/dist/guides/min/loadtest.md

@@ -0,0 +1,17 @@
+# Generate `type: loadtest` (min)
+
+```yaml
+type: loadtest
+test: ./echo_test.mmt
+threads: 10
+repeat: 30s
+rampup: 5s
+```
+
+## Essentials
+
+- First line: `type: loadtest`
+- Points at a `type: test` file
+- `threads`, `repeat`, optional `rampup` / `duration`
+
+Request `pack: full` for metrics and advanced timing.

package/dist/guides/min/overview.md

@@ -0,0 +1,25 @@
+# Multimeter overview (min)
+
+Prefer MCP tools when available. Offline: `testlight docs`, `testlight scaffold`, `testlight validate`.
+
+## Types
+
+- `api` — one endpoint
+- `test` — call APIs/tests + assert
+- `env` — variables/presets
+- `suite` — group runnable files
+- `doc` / `server` / `loadtest` / `report` — as named
+
+## Tokens
+
+- `e:name`, `i:name`, `r:uuid`, `c:epoch_ms`
+- Embed with `<<e:api_url>>/path`
+
+## Agent loop
+
+1. New test from API → `scaffold_test` / `testlight scaffold test --from`
+2. Patch only on modify
+3. `validate` before finishing
+4. Never web-search Multimeter syntax
+
+Request `pack: full` only when min docs are not enough.

package/dist/guides/min/suite.md

@@ -0,0 +1,18 @@
+# Generate `type: suite` (min)
+
+```yaml
+type: suite
+title: Smoke suite
+items:
+  - ./tests/login-smoke.mmt
+  - ./tests/echo-smoke.mmt
+```
+
+## Essentials
+
+- First line: `type: suite`
+- `items` lists `.mmt` paths (tests, apis, suites)
+- Use `then` between groups for sequencing; same group runs in parallel
+- Optional root-only: `servers`, `environment`, `export`
+
+Request `pack: full` for nested suites, env export, and report options.

package/dist/guides/min/test.md

@@ -0,0 +1,42 @@
+# Generate `type: test` (min)
+
+Prefer `scaffold_test` / `testlight scaffold test --from` for new API tests.
+
+```yaml
+type: test
+title: Login smoke
+tags: [smoke]
+import:
+  login: ../apis/login.mmt
+inputs:
+  username: i:username
+  password: i:password
+steps:
+  - call: login
+    id: iLogin
+    inputs:
+      username: i:username
+      password: i:password
+    expect:
+      status: 200
+```
+
+## Essentials
+
+- First line: `type: test`
+- Use `steps` **or** `stages`, not both
+- Every `call` needs unique `id`
+- Import aliases before calling them
+- Assert with `expect` on call, or `assert` / `check` steps
+- No YAML comments (`#`)
+- Tokens: `e:`, `i:`, `r:`, `c:` (snake_case)
+
+## Common steps
+
+- `call: <alias>` — invoke imported API/test
+- `http: <url>` — inline HTTP
+- `assert: ${id.status} == 200`
+- `check:` map of path → expected
+- `js: |` — small helper script when needed
+
+Request `pack: full` for stages, loops, CSV, cache, and advanced expect ops.

package/dist/guides/min/workflow.md

@@ -0,0 +1,16 @@
+# Agent workflow (min)
+
+MCP-first when Multimeter MCP is registered.
+
+| Intent | First tool | Then |
+|--------|------------|------|
+| Test from API | `scaffold_test` | Write yaml → **`validate` → `format`** |
+| Few-shot | `list_examples` | Mirror `goldenSmoke` |
+| Inspect API | `api_card` | Prefer card over full file dump |
+| Tighten asserts | `suggest_assertions` | Patch → **`validate` → `format`** |
+| Modify `.mmt` | **patch only** | **`validate` → `format`** (no full rewrite) |
+| Run | `run` | tool JSON; then suggest_assertions if asked |
+
+Offline: `testlight docs` → `scaffold` → edit → `validate`.
+
+Hard rules: no web search; no blank-page invent; modify = patch only unless user asks to rewrite.

package/dist/guides/offline-agent.md

@@ -0,0 +1,46 @@
+# Offline / no-MCP agent profile
+
+Use this when Multimeter MCP is **not** registered, or the host cannot call MCP tools.
+
+## Prefer MCP when available
+
+If Multimeter MCP tools exist (`scaffold_test`, `validate`, `run`, …), use those first. See `agent-workflow.md`.
+
+## Offline loop
+
+```
+testlight docs <topic>          # local syntax (pack min by default)
+testlight scaffold test --from <api.mmt> [-o path]
+testlight suggest asserts --from <api.mmt> [--body-file resp.json]
+# patch the file if needed (never rewrite whole file unless asked)
+testlight validate <file.mmt>
+testlight run <file.mmt>        # only when asked to execute
+```
+
+Few-shot: mirror `examples/ai/golden_smoke/` (see `docs/AI/golden-smoke.md`).
+
+### Topics
+
+`overview` | `workflow` | `test` | `api` | `suite` | `env` | `doc` | `loadtest` | `constraints`
+
+```
+testlight docs test
+testlight docs api --pack full
+```
+
+## Hard rules
+
+1. Do **not** open mmt.dev / GitHub / web search for Multimeter YAML syntax.
+2. New tests from an API: **scaffold first** — do not invent blank YAML.
+3. Modify: **patch only** — do not rewrite the whole file.
+4. Always **validate** before claiming done (format when using MCP).
+5. Modify: **patch only** unless the user asks to rewrite.
+6. Set `MMT_GUIDES_DIR` if guides are not next to the CLI binary.
+
+## Guides location
+
+`testlight docs` reads from, in order:
+
+1. `MMT_GUIDES_DIR`
+2. Guides bundled next to the CLI (`guides/` beside `cli.js`)
+3. Repo `docs/AI` when developing from source

package/esbuild.mjs

@@ -1,9 +1,12 @@
 import * as esbuild from 'esbuild';
+import fs from 'fs';
 import path from 'path';
 import {fileURLToPath} from 'url';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const coreDir = path.resolve(__dirname, '..', 'core', 'src');
+const guidesSrc = path.resolve(__dirname, '..', 'docs', 'AI');
+const guidesOut = path.join(__dirname, 'dist', 'guides');
 
 // Plugin to resolve 'mmt-core' and 'mmt-core/<subpath>' to local core sources
 const mmtCorePlugin = {
@@ -21,6 +24,26 @@ const mmtCorePlugin = {
   },
 };
 
+function copyMarkdownTree(from, to) {
+  fs.mkdirSync(to, {recursive: true});
+  for (const entry of fs.readdirSync(from, {withFileTypes: true})) {
+    const src = path.join(from, entry.name);
+    const dest = path.join(to, entry.name);
+    if (entry.isDirectory()) {
+      copyMarkdownTree(src, dest);
+    } else if (entry.name.endsWith('.md')) {
+      fs.copyFileSync(src, dest);
+    }
+  }
+}
+
+function copyGuides() {
+  fs.rmSync(guidesOut, {recursive: true, force: true});
+  if (fs.existsSync(guidesSrc)) {
+    copyMarkdownTree(guidesSrc, guidesOut);
+  }
+}
+
 await esbuild.build({
   entryPoints: ['src/cli.ts'],
   bundle: true,
@@ -43,3 +66,5 @@ await esbuild.build({
     'unsupported-dynamic-import': 'silent',
   },
 });
+
+copyGuides();

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "mmt-testlight",
-  "version": "0.4.4",
+  "version": "0.4.5",
   "description": "Multimeter CLI test runner",
+  "license": "Apache-2.0",
   "private": false,
   "bin": {
     "testlight": "dist/cli.js",

package/src/aiDocs.ts

@@ -0,0 +1,88 @@
+import fs from 'fs';
+import path from 'path';
+
+export type CliDocTopic =
+  'overview'|'workflow'|'test'|'api'|'loadtest'|'suite'|'env'|'doc'|'constraints'|'all'|'offline';
+
+export type CliDocPack = 'min'|'full';
+
+const FULL_TOPIC_FILES: Record<Exclude<CliDocTopic, 'all'|'offline'>, string[]> = {
+  overview: ['agent-workflow.md', 'general.md', 'generate.md'],
+  workflow: ['agent-workflow.md'],
+  test: ['generate-test.md'],
+  api: ['generate-api.md'],
+  loadtest: ['generate-loadtest.md'],
+  suite: ['generate-suite.md'],
+  env: ['generate-env.md'],
+  doc: ['generate-doc.md'],
+  constraints: ['generate-test-skill.md'],
+};
+
+const MIN_TOPIC_FILES: Record<Exclude<CliDocTopic, 'all'|'offline'>, string[]> = {
+  overview: ['min/overview.md'],
+  workflow: ['min/workflow.md'],
+  test: ['min/test.md'],
+  api: ['min/api.md'],
+  loadtest: ['min/loadtest.md'],
+  suite: ['min/suite.md'],
+  env: ['min/env.md'],
+  doc: ['min/doc.md'],
+  constraints: ['min/constraints.md'],
+};
+
+export function resolveCliGuidesDir(): string {
+  if (process.env.MMT_GUIDES_DIR && fs.existsSync(process.env.MMT_GUIDES_DIR)) {
+    return process.env.MMT_GUIDES_DIR;
+  }
+  const besideCli = path.join(__dirname, 'guides');
+  if (fs.existsSync(besideCli)) {
+    return besideCli;
+  }
+  const repoGuides = path.resolve(__dirname, '..', '..', 'docs', 'AI');
+  if (fs.existsSync(repoGuides)) {
+    return repoGuides;
+  }
+  // mmtcli/dist → ../../docs/AI from repo; when installed as package:
+  const pkgGuides = path.resolve(__dirname, '..', 'docs', 'AI');
+  if (fs.existsSync(pkgGuides)) {
+    return pkgGuides;
+  }
+  return besideCli;
+}
+
+function readGuide(guidesDir: string, fileName: string): string {
+  const fullPath = path.join(guidesDir, fileName);
+  if (!fs.existsSync(fullPath)) {
+    throw new Error(`Guide not found: ${fullPath}`);
+  }
+  return fs.readFileSync(fullPath, 'utf8');
+}
+
+export function formatCliDocs(topic: CliDocTopic, pack: CliDocPack = 'min'): string {
+  const guidesDir = resolveCliGuidesDir();
+  if (topic === 'offline') {
+    return readGuide(guidesDir, 'offline-agent.md');
+  }
+  const table = pack === 'full' ? FULL_TOPIC_FILES : MIN_TOPIC_FILES;
+  const files = topic === 'all' ?
+      Array.from(new Set(Object.values(table).flat())) :
+      table[topic];
+  const parts = files.map(fileName => {
+    const body = readGuide(guidesDir, fileName);
+    return `<!-- ${fileName} -->\n${body.trim()}\n`;
+  });
+  return [
+    `# Multimeter docs — topic=${topic} pack=${pack}`,
+    `guidesDir: ${guidesDir}`,
+    '',
+    ...parts,
+  ].join('\n');
+}
+
+export function listCliDocTopics(): string[] {
+  return [
+    ...Object.keys(MIN_TOPIC_FILES),
+    'all',
+    'offline',
+  ];
+}