mmt-testlight 0.4.4 → 0.4.5

package/src/cli.ts

@@ -10,13 +10,17 @@ import path from 'path';
 import {createRequire} from 'module';
 
 const requireFromCli = createRequire(__filename);
-const {resolveUserPath} = requireFromCli('../src/pathNormalize.cjs') as {
+const {resolveUserPath, writeTextFile} = requireFromCli('../src/pathNormalize.cjs') as {
   resolveUserPath: (input: string, baseDir?: string, pathMod?: typeof path) => string;
+  writeTextFile: (filePath: string, content: string) => string;
 };
 
 import {summarize} from './loadTest.js';
 import {startMockServerFromPath, stopAllServers} from './mockRunner.js';
 import {buildCliRunArgs} from './runArgs.js';
+import {formatCliDocs, listCliDocTopics} from './aiDocs.js';
+import {resolveValidatePath, validateMmtFile} from './validateMmt.js';
+import {runUpdate} from './selfUpdate.js';
 
 // Defer importing runTest until needed to avoid pulling axios for to-js
 
@@ -269,6 +273,13 @@ program.name('testlight')
           '  testlight run path/to/test.mmt',
           '  testlight run path/to/test.mmt -F env.mmt -P runner.dev -P custom.prod',
           '  testlight run path/to/suite.mmt --report html',
+          '  testlight scaffold test --from path/to/api.mmt',
+          '  testlight scaffold test --from path/to/api.mmt -o tests/api-smoke.mmt',
+          '  testlight docs test',
+          '  testlight validate path/to/test.mmt',
+          '  testlight suggest asserts --from path/to/api.mmt',
+          '  testlight update',
+          '  testlight update --check',
           '',
           'Run `testlight <command> --help` for command-specific options.',
         ].join('\n'));
@@ -315,8 +326,12 @@ program.command('run')
         const {runJSCode, setRunnerNetworkConfig} = await loadJsRunnerModule();
         const full = resolveUserPath(file, process.cwd(), path);
         const rawText = fs.readFileSync(full, 'utf8');
+        // Quote unsafe expect/check operators (!=, >60%, …) before js-yaml
+        // so summarize does not throw on valid .mmt that the runner accepts.
         const raw =
-            /\.json$/i.test(full) ? JSON.parse(rawText) : yaml.load(rawText);
+            /\.json$/i.test(full) ?
+                JSON.parse(rawText) :
+                yaml.load(mmtcore.testParsePack.quoteExpectOperators(rawText));
         const summary = summarize(raw);
         if (!opts.quiet) {
           console.log(`Loaded: ${full} (${summary})`);
@@ -380,8 +395,7 @@ program.command('run')
           }
         }
         if (outFile) {
-          const outPath = path.resolve(outFile);
-          fs.writeFileSync(outPath, JSON.stringify(result, null, 2), 'utf8');
+          const outPath = writeTextFile(outFile, JSON.stringify(result, null, 2));
           if (!opts.quiet) {
             console.log(`Result written: ${outPath}`);
           }
@@ -402,8 +416,7 @@ program.command('run')
             reportContent = serializer(collectedResults);
           }
           if (reportContent) {
-            const reportPath = path.resolve(reportFile);
-            fs.writeFileSync(reportPath, reportContent, 'utf8');
+            const reportPath = writeTextFile(reportFile, reportContent);
             if (!opts.quiet) {
               console.log(`Report written: ${reportPath}`);
             }
@@ -554,6 +567,269 @@ program.command('version-info')
       console.log('Node:', process.version);
     });
 
+program.command('update')
+    .description(
+        'Update standalone/portal testlight binary from GitHub releases (or a mirror)')
+    .option('--check', 'Only check whether an update is available', false)
+    .option(
+        '--to <version>',
+        'Install a specific version (e.g. 1.38.1). Avoids GitHub latest lookup.')
+    .option(
+        '--channel <name>',
+        'Pick latest matching channel from GitHub (beta, rc, prerelease)')
+    .option(
+        '--force',
+        'Reinstall even when the current version is already newest',
+        false)
+    .option(
+        '--repo <owner/name>',
+        'GitHub repo for releases (default: mshobeyri/multimeter or TESTLIGHT_REPO)')
+    .option(
+        '--base-url <url>',
+        'Portal/mirror base URL: <url>/v<version>/testlight-<platform>.tar.gz|zip (or TESTLIGHT_RELEASE_BASE_URL)')
+    .action(async (opts: {
+      check?: boolean;
+      to?: string;
+      channel?: string;
+      force?: boolean;
+      repo?: string;
+      baseUrl?: string;
+    }) => {
+      try {
+        const result = await runUpdate({
+          currentVersion: CLI_VERSION,
+          checkOnly: !!opts.check,
+          version: opts.to,
+          channel: opts.channel,
+          force: !!opts.force,
+          repo: opts.repo,
+          releaseBaseUrl: opts.baseUrl,
+        });
+        console.log(result.message);
+        if (!result.ok) {
+          process.exit(2);
+        }
+      } catch (e: any) {
+        console.error('Error updating testlight:', e?.message || e);
+        process.exit(2);
+      }
+    });
+
+{
+  const scaffold = program.command('scaffold').description(
+      'Scaffold Multimeter .mmt files (AI/offline-friendly)');
+  scaffold.command('test')
+      .description('Scaffold a smoke test from an API .mmt')
+      .requiredOption('--from <file>', 'Source API .mmt file')
+      .option(
+          '-s, --strategy <name>', 'smoke (default) or example', 'smoke')
+      .option('-a, --alias <name>', 'Import alias override')
+      .option(
+          '-o, --out <file>',
+          'Write test YAML to file (default: print to stdout)')
+      .action(async (
+          opts: {from: string; strategy?: string; alias?: string; out?: string}) => {
+        try {
+          const {scaffoldTestFromApi, buildApiDetailsSummary, suggestTestPath} =
+              await import('mmt-core/testScaffold');
+          const apiFull = resolveUserPath(opts.from, process.cwd(), path);
+          if (!fs.existsSync(apiFull)) {
+            console.error(`API file not found: ${apiFull}`);
+            process.exit(2);
+          }
+          const apiText = fs.readFileSync(apiFull, 'utf8');
+          if (mmtcore.JSer.fileType(apiFull, apiText) !== 'api') {
+            console.error(`Expected type: api: ${apiFull}`);
+            process.exit(2);
+          }
+          const api = apiParsePack.yamlToAPIStrict(apiText);
+          const cwd = process.cwd();
+          const apiRel = path.relative(cwd, apiFull).replace(/\\/g, '/') ||
+              path.basename(apiFull);
+          const strategyRaw = String(opts.strategy || 'smoke').toLowerCase();
+          if (strategyRaw !== 'smoke' && strategyRaw !== 'example') {
+            console.error(`Invalid --strategy (use smoke or example): ${opts.strategy}`);
+            process.exit(2);
+          }
+          const outRel = opts.out ?
+              path.relative(cwd, resolveUserPath(opts.out, cwd, path))
+                  .replace(/\\/g, '/') :
+              suggestTestPath(apiRel);
+          const summary = buildApiDetailsSummary(apiRel, api, outRel);
+          const alias = opts.alias || summary.suggestedAlias;
+          const test = scaffoldTestFromApi(api, {
+            alias,
+            importPath: summary.suggestedImportPath,
+            strategy: strategyRaw as 'smoke' | 'example',
+          });
+          const yamlOut = mmtcore.testParsePack.testToYaml(test);
+          mmtcore.testParsePack.yamlToTestStrict(yamlOut);
+          if (opts.out) {
+            const outFull = resolveUserPath(opts.out, cwd, path);
+            const outDir = path.dirname(outFull);
+            if (!fs.existsSync(outDir)) {
+              fs.mkdirSync(outDir, {recursive: true});
+            }
+            writeTextFile(outFull, yamlOut.endsWith('\n') ? yamlOut : `${yamlOut}\n`);
+            console.error(`Scaffolded: ${outFull}`);
+          } else {
+            process.stdout.write(yamlOut.endsWith('\n') ? yamlOut : `${yamlOut}\n`);
+          }
+        } catch (e: any) {
+          console.error('Error scaffolding test:', e?.message || e);
+          process.exit(2);
+        }
+      });
+}
+
+program.command('docs')
+    .description('Print bundled Multimeter AI docs (offline-friendly)')
+    .argument(
+        '[topic]',
+        `Topic: ${listCliDocTopics().join('|')}`,
+        'overview')
+    .option(
+        '-p, --pack <name>',
+        'min (default, low token) or full',
+        'min')
+    .action((topic: string, opts: {pack?: string}) => {
+      try {
+        const packRaw = String(opts.pack || 'min').toLowerCase();
+        if (packRaw !== 'min' && packRaw !== 'full') {
+          console.error(`Invalid --pack (use min or full): ${opts.pack}`);
+          process.exit(2);
+        }
+        const allowed = new Set(listCliDocTopics());
+        if (!allowed.has(topic)) {
+          console.error(`Unknown topic "${topic}". Use: ${listCliDocTopics().join(', ')}`);
+          process.exit(2);
+        }
+        const text = formatCliDocs(topic as any, packRaw as 'min'|'full');
+        process.stdout.write(text.endsWith('\n') ? text : `${text}\n`);
+      } catch (e: any) {
+        console.error('Error reading docs:', e?.message || e);
+        process.exit(2);
+      }
+    });
+
+program.command('validate')
+    .description('Validate a .mmt API or test file')
+    .argument('<file>', 'Path to .mmt file')
+    .option(
+        '-t, --type <name>',
+        'Expected type: api|test')
+    .action((file: string, opts: {type?: string}) => {
+      try {
+        const full = resolveValidatePath(file);
+        if (!fs.existsSync(full)) {
+          console.error(`File not found: ${full}`);
+          process.exit(2);
+        }
+        const expected = opts.type ? String(opts.type).toLowerCase() : undefined;
+        if (expected && expected !== 'api' && expected !== 'test') {
+          console.error(`Unsupported --type (use api or test): ${opts.type}`);
+          process.exit(2);
+        }
+        const result = validateMmtFile(full, expected);
+        if (result.valid) {
+          console.log(JSON.stringify({
+            file: full,
+            valid: true,
+            detectedType: result.detectedType,
+          }, null, 2));
+          return;
+        }
+        console.error(JSON.stringify({
+          file: full,
+          valid: false,
+          detectedType: result.detectedType,
+          errors: result.errors,
+        }, null, 2));
+        process.exit(1);
+      } catch (e: any) {
+        console.error('Error validating:', e?.message || e);
+        process.exit(2);
+      }
+    });
+
+{
+  const suggest = program.command('suggest').description(
+      'Suggest low-token patches for .mmt files (AI/offline-friendly)');
+  suggest.command('asserts')
+      .description('Suggest expect/assert patches from API outputs or JSON body')
+      .option('--from <file>', 'API .mmt file (reads outputs)')
+      .option('--body-file <file>', 'JSON response body file')
+      .option('--body <json>', 'JSON response body string')
+      .option('--status <n>', 'HTTP status to expect', (v) => Number(v))
+      .option('--step-id <id>', 'Call step id for ${id.field} asserts')
+      .option(
+          '--style <name>', 'expect | assert | both (default both)', 'both')
+      .option('--max-fields <n>', 'Max body fields', (v) => Number(v))
+      .action(async (opts: {
+        from?: string;
+        bodyFile?: string;
+        body?: string;
+        status?: number;
+        stepId?: string;
+        style?: string;
+        maxFields?: number;
+      }) => {
+        try {
+          const {suggestAssertions} = await import('mmt-core/suggestAssertions');
+          const {safeStepIdFromAlias, suggestAliasFromPath} =
+              await import('mmt-core/testScaffold');
+          let outputs: Record<string, string>|undefined;
+          let stepId = opts.stepId;
+          if (opts.from) {
+            const apiFull = resolveUserPath(opts.from, process.cwd(), path);
+            const apiText = fs.readFileSync(apiFull, 'utf8');
+            if (mmtcore.JSer.fileType(apiFull, apiText) !== 'api') {
+              console.error(`Expected type: api: ${apiFull}`);
+              process.exit(2);
+            }
+            const api = apiParsePack.yamlToAPIStrict(apiText);
+            outputs = (api.outputs || {}) as Record<string, string>;
+            if (!stepId) {
+              const apiRel =
+                  path.relative(process.cwd(), apiFull).replace(/\\/g, '/') ||
+                  path.basename(apiFull);
+              stepId = safeStepIdFromAlias(suggestAliasFromPath(apiRel));
+            }
+          }
+          let body: unknown;
+          if (opts.bodyFile) {
+            const full = resolveUserPath(opts.bodyFile, process.cwd(), path);
+            body = JSON.parse(fs.readFileSync(full, 'utf8'));
+          } else if (opts.body) {
+            body = JSON.parse(opts.body);
+          }
+          if (!outputs && body === undefined && opts.status === undefined) {
+            console.error('Provide --from, --body/--body-file, and/or --status');
+            process.exit(2);
+          }
+          const styleRaw = String(opts.style || 'both').toLowerCase();
+          if (styleRaw !== 'expect' && styleRaw !== 'assert' && styleRaw !== 'both') {
+            console.error(`Invalid --style: ${opts.style}`);
+            process.exit(2);
+          }
+          const result = suggestAssertions({
+            stepId,
+            status: opts.status,
+            outputs,
+            body: body as any,
+            style: styleRaw as any,
+            maxFields: opts.maxFields,
+          });
+          process.stdout.write(
+              (result.patchHint.endsWith('\n') ? result.patchHint :
+                                                 `${result.patchHint}\n`));
+        } catch (e: any) {
+          console.error('Error suggesting asserts:', e?.message || e);
+          process.exit(2);
+        }
+      });
+}
+
 program.command('doc')
     .argument('<file>', 'Doc file (.mmt/.yaml/.yml)')
     .description('Generate documentation from a doc .mmt')
@@ -654,7 +930,7 @@ program.command('doc')
             path.resolve(
                 process.cwd(),
                 `${path.basename(full, path.extname(full))}${defExt}`);
-        fs.writeFileSync(outPath, htmlOrMd, 'utf8');
+        writeTextFile(outPath, htmlOrMd);
         console.log(`Doc generated: ${outPath}`);
       } catch (e: any) {
         console.error('Error generating doc:', e?.message || e);

package/src/pathNormalize.cjs

@@ -153,8 +153,24 @@ function resolveUserPathPreferExisting(input, baseDirs, pathMod, existsFn) {
   return first;
 }
 
+/**
+ * Write a UTF-8 file, creating missing parent directories.
+ * @param {string} filePath
+ * @param {string} content
+ * @returns {string} resolved path
+ */
+function writeTextFile(filePath, content) {
+  const api = pathApi();
+  const fs = require('fs');
+  const resolved = api.resolve(String(filePath ?? ''));
+  fs.mkdirSync(api.dirname(resolved), {recursive: true});
+  fs.writeFileSync(resolved, content, 'utf8');
+  return resolved;
+}
+
 module.exports = {
   normalizeUserPath,
   resolveUserPath,
   resolveUserPathPreferExisting,
+  writeTextFile,
 };

package/src/pathNormalize.test.ts

@@ -7,6 +7,7 @@ const {
   normalizeUserPath,
   resolveUserPath,
   resolveUserPathPreferExisting,
+  writeTextFile,
 } = require('./pathNormalize.cjs');
 
 describe('pathNormalize (Windows-shaped)', () => {
@@ -152,4 +153,11 @@ describe('pathNormalize FS layout (../../ file + env)', () => {
     expect(resolvedFile).toBe(testFile);
     expect(resolvedEnv).toBe(localEnv);
   });
+
+  it('creates missing parent directories when writing a report file', () => {
+    const reportPath = path.join(root, 'results', 'nested', 'junit.xml');
+    const written = writeTextFile(reportPath, '<testsuites/>');
+    expect(written).toBe(reportPath);
+    expect(fs.readFileSync(reportPath, 'utf8')).toBe('<testsuites/>');
+  });
 });

package/src/selfUpdate.test.ts

@@ -0,0 +1,79 @@
+import {
+  buildDownloadUrl,
+  compareVersions,
+  detectInstallChannel,
+  detectPlatform,
+  normalizeVersion,
+  planUpdate,
+} from './selfUpdate';
+
+describe('selfUpdate helpers', () => {
+  it('normalizes and compares versions', () => {
+    expect(normalizeVersion('v1.2.3')).toBe('1.2.3');
+    expect(compareVersions('1.2.3', '1.2.3')).toBe(0);
+    expect(compareVersions('1.2.3', '1.2.4')).toBe(-1);
+    expect(compareVersions('1.3.0', '1.2.9')).toBe(1);
+    expect(compareVersions('1.2.3-beta.1', '1.2.3')).toBe(-1);
+  });
+
+  it('detects platforms', () => {
+    expect(detectPlatform('darwin', 'arm64')).toBe('macos-arm64');
+    expect(detectPlatform('linux', 'x64')).toBe('linux-x64');
+    expect(detectPlatform('win32', 'arm64')).toBe('win-x64');
+  });
+
+  it('detects install channels', () => {
+    expect(detectInstallChannel('/usr/local/bin/testlight')).toBe('standalone');
+    expect(detectInstallChannel(
+               '/opt/homebrew/Cellar/mmt-testlight/0.4.4/bin/testlight'))
+        .toBe('homebrew');
+    expect(detectInstallChannel(
+               '/usr/local/bin/node',
+               '/usr/local/lib/node_modules/mmt-testlight/dist/cli.js'))
+        .toBe('npm');
+  });
+
+  it('builds github and portal download urls', () => {
+    expect(buildDownloadUrl({version: '1.2.3', platform: 'linux-x64'}))
+        .toBe(
+            'https://github.com/mshobeyri/multimeter/releases/download/v1.2.3/testlight-linux-x64.tar.gz');
+    expect(buildDownloadUrl({
+      version: '1.2.3',
+      platform: 'win-x64',
+      releaseBaseUrl: 'https://portal.example/testlight',
+    })).toBe('https://portal.example/testlight/v1.2.3/testlight-win-x64.zip');
+  });
+
+  it('plans npm advice instead of binary replace', async () => {
+    const plan = await planUpdate({
+      currentVersion: '0.4.0',
+      version: '0.4.4',
+      execPath: '/usr/local/bin/node',
+      scriptPath: '/usr/local/lib/node_modules/mmt-testlight/dist/cli.js',
+      fetchJson: async () => ({tag_name: 'v0.4.4'}),
+    });
+    expect(plan.action).toBe('advise-npm');
+    expect(plan.advice).toContain('npm install -g mmt-testlight@0.4.4');
+  });
+
+  it('plans noop when already current', async () => {
+    const plan = await planUpdate({
+      currentVersion: '1.2.3',
+      version: '1.2.3',
+      execPath: '/usr/local/bin/testlight',
+      fetchJson: async () => ({tag_name: 'v1.2.3'}),
+    });
+    expect(plan.action).toBe('noop');
+  });
+
+  it('plans download for standalone when newer', async () => {
+    const plan = await planUpdate({
+      currentVersion: '1.0.0',
+      version: '1.2.3',
+      execPath: '/opt/portal/bin/testlight',
+      fetchJson: async () => ({tag_name: 'v1.2.3'}),
+    });
+    expect(plan.action).toBe('download');
+    expect(plan.downloadUrl).toContain('/v1.2.3/testlight-');
+  });
+});