@nm-lang/cli 0.3.0 → 0.5.0

package/README.md

@@ -1,140 +1,200 @@
-# @nm-lang/cli
-
-N/M 0.2.0 Preview command-line tools for running, formatting, linting, testing,
-exporting and managing local N/M workspaces.
-
-Package release **0.3.0** targets the N/M **0.2.0** language contract.
-
-## Install / Kurulum
-
-Requires Node.js 20 or newer. Release checks use Node.js 22.23.1.
-
-```sh
-npm install --global @nm-lang/cli
-nm --version
-```
-
-Or run without a global install:
-
-```sh
-npx --package=@nm-lang/cli nm --version
-```
-
-An untagged install selects npm's `latest` channel. To pin this version after
-publication, append `@0.3.0` to the package name. The N/M language remains
-Preview independently of the npm channel. npm installs the matching Core dependency.
-No repository checkout or TypeScript build is needed to use a published package.
-
-Türkçe: Etiketsiz kurulum npm'in `latest` kanalını seçer. Yayından sonra
-`@0.3.0` ile sürümü sabitleyebilirsiniz. N/M dili, npm kanalından bağımsız
-olarak Önizleme durumundadır. Core bağımlılığı otomatik kurulur; depoyu
-indirmeniz gerekmez.
-
-## First program / İlk program
-
-Save the following as `bell.nm`:
-
-```nm
-module npm_bell;
-fn main() {
-  let q = qreg[2];
-  H(q[0]);
-  CNOT(q[0], q[1]);
-  let a = measure(q[0]);
-  let b = measure(q[1]);
-  return (a, b);
-}
-```
-
-```sh
-nm run bell.nm --json
-```
-
-The program creates and measures a Bell pair using a local simulator.
-Türkçe: Kodu `bell.nm` olarak kaydedip komutla çalıştırın. Sonuç yerel
-simülasyondan gelir; gerçek kuantum donanımı kanıtı değildir.
-
-## Language options / Dil seçenekleri
-
-### Selected tests and CI reports / Test seçimi ve CI raporları
-
-The `0.3.0` package adds test selection, watch mode and JSON, JUnit and SARIF
-reports for CI integrations.
-
-Türkçe: `0.3.0` paketi test seçimini, izleme modunu ve CI entegrasyonları için
-JSON, JUnit ve SARIF raporlarını içerir.
-
-```sh
-nm test main.nm --name "Bell contract" --json
-nm test main.nm --id nmtest-0123456789abcdef
-nm test main.nm --report-format junit --output results.xml
-nm test main.nm --report-format sarif --output results.sarif
-nm test main.nm --watch --json
-```
-
-`--name` matches the exact declared name; repeat `--name` or `--id` to select a
-union. Copy real IDs from a JSON report for the same input path and source lines.
-Selection happens before execution, preserving surrounding setup and original
-source locations; unknown/stale IDs or names fail with `NM-TEST-SELECT-001`.
-Direct selection of a nested check fails with `NM-TEST-SELECT-002`; select its
-top-level enclosing check. Source syntax and capability validation still cover
-the complete file, including its original register allocation and qubit limits.
-Empty suites and failed execution exit 1.
-
-`--report-format json|junit|sarif` writes that format to stdout. `--output` also
-replaces the explicitly named `.json`, `.xml` or `.sarif` report on each run;
-parent directories must already exist. The default output remains human readable.
-`--json` cannot be combined with a non-JSON report format.
-
-`--watch` is available in the Node command-line host. It runs immediately, then
-debounces source and workspace-manifest changes, including imported modules,
-clears the workspace cache and queues runs without overlap. Ctrl+C/SIGTERM closes
-watchers. With `--json`, stdout is NDJSON: each `event:"run"` has a sequence,
-exitCode, report (or null for invocation errors) and diagnostics; lifecycle errors
-and stopping also have event objects. JUnit/SARIF watch mode requires `--output`
-and prints run summaries while replacing the report file. The exit status follows
-the latest run; signal termination uses 130/143.
-
-Türkçe: Tam test adı veya mevcut rapordaki kimlikle seçim yapın; seçenekler
-tekrarlanabilir. Seçilmeyen test blokları yürütülmez, ortak kurulum korunur.
-İç içe kontrolleri doğrudan seçmek yerine üst kontrolü seçin. Kaynağın tamamındaki
-kayıt tahsisi ve qubit sınırları seçimden sonra da geçerlidir. İzleme modu bağımlı
-`.nm` dosyaları ve manifest değişince yeniden çalışır. `--output` belirtilen rapor
-dosyasını her çalıştırmada yeniler.
-
-### Toolchain doctor / Araç zinciri kontrolü
-
-The `0.3.0` CLI provides `nm doctor --json` and `nm doctor --locale tr`.
-It compares the loaded CLI/Core and locally resolvable LSP/MCP packages, reporting
-package, language and protocol versions separately. Missing optional packages and
-the VS Code installation remain unobserved; this is not a check of running servers.
-Exit code 1 means an observed mismatch or failed package probe; 0 may still mean
-partial coverage. The report format is `nm-toolchain-doctor` version `0.1`.
-
-Türkçe: `nm doctor` yüklenen CLI/Core ile yerelden çözümlenebilen LSP/MCP
-paketlerini karşılaştırır. Paket, dil ve protokol sürümleri ayrı değerlendirilir.
-Gözlenmeyen isteğe bağlı araçlar ve VS Code kurulumu doğrulanmış sayılmaz.
-Çıkış kodu 1 uyuşmazlık veya paket sorgusu hatasıdır; 0 kısmi gözlem anlamına da
-gelebilir. Bu komutlar `0.3.0` paketinin parçasıdır.
-
-New CLI invocations enable the default language profile: classical functions,
-typed values/Result, module visibility, parameter groups and compute/apply.
-Use `--legacy-features` for the previous opt-in behavior. Other experimental
-features still require their own flags; export/backend limits remain enforced.
-
-Türkçe: Yeni CLI çağrılarında varsayılan dil profili açıktır. Eski davranış için
-`--legacy-features` kullanın. Diğer deneysel özellikler ayrıca açılmalıdır.
-
-- [CLI documentation](https://quantumsoftware.tech/en/docs/nm-language/cli)
-- [Türkçe CLI rehberi](https://quantumsoftware.tech/tr/docs/nm-language/cli)
-- [Support / Destek](https://quantumsoftware.tech/en/#contact)
-
-## License / Lisans
-
-Free personal, educational and commercial use; source-code rights are reserved.
-Modification or redistribution of QuantumSoftware-owned package code requires
-separate permission. Your N/M programs and results remain yours. See
-[LICENSE.txt](./LICENSE.txt) and [NOTICE.txt](./NOTICE.txt).
-
-Türkçe: Kullanım ücretsizdir; açık kaynak lisansı verilmez. Paket kodunu
-değiştirme ve yeniden dağıtma için ayrıca izin gerekir.
+# @nm-lang/cli
+
+N/M 0.2.0 Preview command-line tools for running, formatting, linting, testing,
+exporting and managing local N/M workspaces.
+
+Package **0.5.0** targets the N/M **0.2.0** language contract.
+
+## Install / Kurulum
+
+Requires Node.js 20 or newer. Release checks use Node.js 22.23.1.
+
+```sh
+npm install --global @nm-lang/cli
+nm --version
+```
+
+Or run without a global install:
+
+```sh
+npx --package=@nm-lang/cli nm --version
+```
+
+An untagged install selects npm's `latest` channel. To pin this version,
+append `@0.5.0` to the package name. The N/M language remains
+Preview independently of the npm channel. npm installs the matching Core dependency.
+No repository checkout or TypeScript build is needed to use a published package.
+
+Türkçe: Etiketsiz kurulum npm'in `latest` kanalını seçer.
+`@0.5.0` ile sürümü sabitleyebilirsiniz. N/M dili, npm kanalından bağımsız
+olarak Önizleme durumundadır. Core bağımlılığı otomatik kurulur; depoyu
+indirmeniz gerekmez.
+
+## First program / İlk program
+
+Save the following as `bell.nm`:
+
+```nm
+module npm_bell;
+fn main() {
+  let q = qreg[2];
+  H(q[0]);
+  CNOT(q[0], q[1]);
+  let a = measure(q[0]);
+  let b = measure(q[1]);
+  return (a, b);
+}
+```
+
+```sh
+nm run bell.nm --json
+```
+
+The program creates and measures a Bell pair using a local simulator.
+Türkçe: Kodu `bell.nm` olarak kaydedip komutla çalıştırın. Sonuç yerel
+simülasyondan gelir; gerçek kuantum donanımı kanıtı değildir.
+
+## Language options / Dil seçenekleri
+
+### Selected tests and CI reports / Test seçimi ve CI raporları
+
+The CLI provides test selection, watch mode and JSON, JUnit and SARIF
+reports for CI integrations.
+
+Türkçe: CLI test seçimini, izleme modunu ve CI entegrasyonları için
+JSON, JUnit ve SARIF raporlarını içerir.
+
+```sh
+nm test main.nm --name "Bell contract" --json
+nm test main.nm --id nmtest-0123456789abcdef
+nm test main.nm --report-format junit --output results.xml
+nm test main.nm --report-format sarif --output results.sarif
+nm test main.nm --watch --json
+```
+
+`--name` matches the exact declared name; repeat `--name` or `--id` to select a
+union. Copy real IDs from a JSON report for the same input path and source lines.
+Selection happens before execution, preserving surrounding setup and original
+source locations; unknown/stale IDs or names fail with `NM-TEST-SELECT-001`.
+Direct selection of a nested check fails with `NM-TEST-SELECT-002`; select its
+top-level enclosing check. Source syntax and capability validation still cover
+the complete file, including its original register allocation and qubit limits.
+Empty suites and failed execution exit 1.
+
+`--report-format json|junit|sarif` writes that format to stdout. `--output` also
+replaces the explicitly named `.json`, `.xml` or `.sarif` report on each run;
+parent directories must already exist. The default output remains human readable.
+`--json` cannot be combined with a non-JSON report format.
+
+`--watch` is available in the Node command-line host. It runs immediately, then
+debounces source and workspace-manifest changes, including imported modules,
+clears the workspace cache and queues runs without overlap. Ctrl+C/SIGTERM closes
+watchers. With `--json`, stdout is NDJSON: each `event:"run"` has a sequence,
+exitCode, report (or null for invocation errors) and diagnostics; lifecycle errors
+and stopping also have event objects. JUnit/SARIF watch mode requires `--output`
+and prints run summaries while replacing the report file. The exit status follows
+the latest run; signal termination uses 130/143.
+
+Türkçe: Tam test adı veya mevcut rapordaki kimlikle seçim yapın; seçenekler
+tekrarlanabilir. Seçilmeyen test blokları yürütülmez, ortak kurulum korunur.
+İç içe kontrolleri doğrudan seçmek yerine üst kontrolü seçin. Kaynağın tamamındaki
+kayıt tahsisi ve qubit sınırları seçimden sonra da geçerlidir. İzleme modu bağımlı
+`.nm` dosyaları ve manifest değişince yeniden çalışır. `--output` belirtilen rapor
+dosyasını her çalıştırmada yeniler.
+
+### Toolchain doctor / Araç zinciri kontrolü
+
+The `0.3.0` CLI provides `nm doctor --json` and `nm doctor --locale tr`.
+It compares the loaded CLI/Core and locally resolvable LSP/MCP packages, reporting
+package, language and protocol versions separately. Missing optional packages and
+the VS Code installation remain unobserved; this is not a check of running servers.
+Exit code 1 means an observed mismatch or failed package probe; 0 may still mean
+partial coverage. The report format is `nm-toolchain-doctor` version `0.1`.
+
+Türkçe: `nm doctor` yüklenen CLI/Core ile yerelden çözümlenebilen LSP/MCP
+paketlerini karşılaştırır. Paket, dil ve protokol sürümleri ayrı değerlendirilir.
+Gözlenmeyen isteğe bağlı araçlar ve VS Code kurulumu doğrulanmış sayılmaz.
+Çıkış kodu 1 uyuşmazlık veya paket sorgusu hatasıdır; 0 kısmi gözlem anlamına da
+gelebilir. Bu komutlar `0.3.0` paketinin parçasıdır.
+
+New CLI invocations enable the default language profile: classical functions,
+typed values/Result, module visibility, parameter groups and compute/apply.
+Use `--legacy-features` for the previous opt-in behavior. Other experimental
+features still require their own flags; export/backend limits remain enforced.
+
+Türkçe: Yeni CLI çağrılarında varsayılan dil profili açıktır. Eski davranış için
+`--legacy-features` kullanın. Diğer deneysel özellikler ayrıca açılmalıdır.
+
+- [CLI documentation](https://quantumsoftware.tech/en/docs/nm-language/cli)
+- [Türkçe CLI rehberi](https://quantumsoftware.tech/tr/docs/nm-language/cli)
+- [Support / Destek](https://quantumsoftware.tech/en/#contact)
+
+
+## 0.5.0: Trainable evolution / Eğitilebilir evrim
+
+This package adds scalar-parameter evolution time and Hamiltonian coefficients,
+fixed gate topology at zero time/weight, and exact-statevector circuit/operator
+derivatives. The training host supports fixed or adaptive QWC allocation with
+one total shot budget, separate pilots/held-out confidence evidence, and optional
+final-cost precision targets. Required-shot estimates are informational; they do
+not spend extra shots, increase the 4096 limit or certify convergence. These
+features require the existing explicit Hamiltonian and grouping permissions.
+
+Türkçe: Parametreli evrim süresi/katsayıları, sıfırda korunan kapı yapısı ve kesin
+statevector devre/operatör türevleri eklenir. Eğitim host'u sabit/adaptif QWC,
+tek toplam ölçüm bütçesi, ayrı pilot/değerlendirme güven kanıtı ve isteğe bağlı
+son maliyet hassasiyetini destekler. Ölçüm tahmini bilgi amaçlıdır; ek ölçüm almaz,
+4096 sınırını artırmaz veya yakınsamayı belgelemez. Mevcut iki açık izin korunur.
+
+The N/M language contract remains 0.2.0; package and artifact versions are separate.
+N/M dil sözleşmesi 0.2.0 olarak kalır; paket ve dosya biçimi sürümleri ayrıdır.
+
+## Hamiltonian 0.4.0 / Hamiltonian 0.4.0
+
+Version 0.4.0 includes Hamiltonian evolution and shared-shot QWC expectations.
+Earlier releases do not include these additions.
+Both `hamiltonianEvolution` and `measurementGrouping` require explicit permission.
+Source printing and N/M IR v0.5 preserve original source, parser context, seed and
+shot plans. Imports rebuild with caller permissions; stored flags never grant them.
+QASM/framework export and source optimization/transpilation reject these semantics.
+
+CLI: `--experimental-hamiltonian-evolution`, `--experimental-measurement-grouping`,
+`--from-ir` for a saved v0.5 IR, `--locale en|tr` for diagnostics. MCP: the matching
+`experimentalHamiltonianEvolution` / `experimentalMeasurementGrouping` booleans,
+`nm_export` target `ir` and `nm_import_ir`. LSP initialization uses
+`initializationOptions.nm.experimental`; VS Code uses
+`nm.experimental.hamiltonianEvolution` / `nm.experimental.measurementGrouping`.
+The editor offers completion/hover, closed-default diagnostics and original
+source columns for generated gates in the recorded debugger.
+
+Türkçe: 0.4.0 bu geliştirmeleri içerir; iki yeni izin varsayılan kapalıdır.
+Yazdırma/IR özgün kaynağı ve ortak ölçüm bütçesini korur; içe aktarım
+kaydı çalıştırma yetkisi saymaz. CLI/MCP/LSP/Monaco/VS Code aynı izinleri taşır;
+tanılar ve ayarlar TR/EN destekler. TR/EN laboratuvarı sitede erişilebilirdir.
+N/M dil sözleşmesi 0.2.0 ve ön izleme olgunluğu korunur.
+
+[Release notes](https://quantumsoftware.tech/en/docs/nm-language/releases) ·
+[Türkçe sürüm notları](https://quantumsoftware.tech/tr/docs/nm-language/releases)
+
+## License / Lisans
+
+Free personal, educational and commercial use; source-code rights are reserved.
+Modification or redistribution of QuantumSoftware-owned package code requires
+separate permission. Your N/M programs and results remain yours. See
+[LICENSE.txt](./LICENSE.txt) and [NOTICE.txt](./NOTICE.txt).
+
+Türkçe: Kullanım ücretsizdir; açık kaynak lisansı verilmez. Paket kodunu
+değiştirme ve yeniden dağıtma için ayrıca izin gerekir.
+
+## Python/Jupyter bridge / Python/Jupyter köprüsü
+
+Version 0.5.0 adds `nm bridge` for bounded JSON `check`, `run` and
+`train` requests through stdin. The `python/nm_bridge.py` stdlib adapter and
+`python/examples/training.ipynb` preserve source, explicit caller permissions,
+training options and complete measurement/confidence evidence. TR/EN output is
+supported; saved records never self-grant replay permissions. No separate PyPI
+release is provided. See `python/README.md` and the repository's
+`docs/NM_PYTHON_JUPYTER_BRIDGE_GUIDE.md`. The earlier npm 0.4.0 release does not include this bridge.
+Türkçe: 0.5.0, standart kütüphaneli yerel Python/Jupyter köprüsünü içerir;
+kayıtlar özgün kaynak, eğitim seçenekleri, bütçe ve güven kanıtını korur.
+Kayıt okumak çalıştırma izni vermez; ayrı bir PyPI paketi yayımlanmaz.

package/bin/bridge-host.mjs

@@ -0,0 +1,78 @@
+import { Worker } from "node:worker_threads";
+
+// Transport caps also cover stdin waiting, runtime loading and forced termination.
+export const nmBridgeTransportLimits = Object.freeze({ requestBytes: 262144, responseBytes: 4194304, defaultTimeoutMs: 30000, maxTimeoutMs: 60000 });
+const copy = {
+  en: { input: "Invalid bridge arguments, UTF-8 input, or request size.", timeout: "Bridge deadline exceeded. The Worker was terminated; no completed measurement or precision evidence is available.", execution: "Bridge Worker failed. No completed result is available.", cancel: "Bridge cancelled; no completed result is available." },
+  tr: { input: "Köprü bağımsız değişkenleri, UTF-8 girdisi veya istek boyutu geçersiz.", timeout: "Köprü süre sınırı aşıldı. Worker sonlandırıldı; tamamlanmış ölçüm veya hassasiyet kanıtı yoktur.", execution: "Köprü Worker hatası. Tamamlanmış sonuç yoktur.", cancel: "Köprü iptal edildi; tamamlanmış sonuç yoktur." },
+};
+function rejection(key, locale) {
+  return { exitCode: 1, stdout: [JSON.stringify({ format: "nm-python-bridge", version: 1, success: false, status: "rejected", locale,
+    error: { code: key === "timeout" ? "NM-PY-008" : key === "cancel" ? "NM-PY-009" : key === "execution" ? "NM-PY-007" : "NM-PY-001", message: copy[locale][key] } })], stderr: [] };
+}
+
+export async function runNMBridgeHost(args) {
+  const locale = args[args.indexOf("--locale") + 1] === "tr" ? "tr" : "en";
+  const forwarded = [], seen = new Set(), features = new Set();
+  let timeoutMs = nmBridgeTransportLimits.defaultTimeoutMs;
+  for (let index = 0; index < args.length; index++) {
+    const flag = args[index];
+    if (flag === "--allow-feature") {
+      const feature = args[++index];
+      if (!/^[A-Za-z]+$/u.test(feature ?? "") || features.has(feature)) return emit(rejection("input", locale));
+      features.add(feature); forwarded.push(flag, feature); continue;
+    }
+    if (seen.has(flag)) return emit(rejection("input", locale));
+    seen.add(flag);
+    if (flag === "--json") { forwarded.push(flag); continue; }
+    if (flag === "--locale" && ["en", "tr"].includes(args[index + 1])) { forwarded.push(flag, args[++index]); continue; }
+    if (flag === "--timeout-ms") {
+      const value = args[++index];
+      if (!/^\d+$/u.test(value ?? "") || Number(value) < 100 || Number(value) > nmBridgeTransportLimits.maxTimeoutMs) return emit(rejection("input", locale));
+      timeoutMs = Number(value); continue;
+    }
+    return emit(rejection("input", locale));
+  }
+  await new Promise(resolve => {
+    let worker, settled = false, size = 0;
+    const chunks = [];
+    const finish = async result => {
+      if (settled) return;
+      settled = true; clearTimeout(timer);
+      process.stdin.removeListener("data", onData); process.stdin.removeListener("end", onEnd); process.stdin.removeListener("error", onInputError);
+      process.removeListener("SIGINT", onCancel); process.removeListener("SIGTERM", onCancel);
+      chunks.length = 0; process.stdin.destroy();
+      if (worker) await worker.terminate();
+      emit(result); resolve();
+    };
+    const onCancel = () => void finish(rejection("cancel", locale));
+    const onInputError = () => void finish(rejection("input", locale));
+    const onData = chunk => {
+      size += chunk.length;
+      if (size > nmBridgeTransportLimits.requestBytes) return void finish(rejection("input", locale));
+      chunks.push(chunk);
+    };
+    const onEnd = () => {
+      let input;
+      try { input = new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks)); }
+      catch { return void finish(rejection("input", locale)); }
+      chunks.length = 0;
+      try {
+        worker = new Worker(new URL("./bridge-worker.mjs", import.meta.url), {
+          workerData: { args: forwarded, input }, resourceLimits: { maxOldGenerationSizeMb: 512, stackSizeMb: 8 },
+        });
+        worker.once("message", result => {
+          const valid = result && [0, 1].includes(result.exitCode) && result.stdout?.length === 1 && result.stderr?.length === 0
+            && typeof result.stdout[0] === "string" && Buffer.byteLength(result.stdout[0]) <= nmBridgeTransportLimits.responseBytes;
+          void finish(valid ? result : rejection("execution", locale));
+        });
+        worker.once("error", () => void finish(rejection("execution", locale)));
+        worker.once("exit", () => { if (!settled) void finish(rejection("execution", locale)); });
+      } catch { void finish(rejection("execution", locale)); }
+    };
+    const timer = setTimeout(() => void finish(rejection("timeout", locale)), timeoutMs);
+    process.once("SIGINT", onCancel); process.once("SIGTERM", onCancel);
+    process.stdin.on("data", onData); process.stdin.once("end", onEnd); process.stdin.once("error", onInputError);
+  });
+}
+function emit(result) { process.exitCode = result.exitCode; process.stdout.write(`${result.stdout.join("\n")}\n`); }

package/bin/bridge-worker.mjs

@@ -0,0 +1,27 @@
+import { parentPort, workerData } from "node:worker_threads";
+import Module from "node:module";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Same repository-source/installed-artifact selection as nm.mjs, inside the deadline.
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../..");
+const sourceCLI = path.join(root, "lib/nm/cli.ts");
+let runtime;
+if (existsSync(sourceCLI) && process.env.NM_CLI_FORCE_PACKED !== "1") {
+  const original = Module._resolveFilename;
+  Module._resolveFilename = function (request, ...args) {
+    if (typeof request === "string" && request.startsWith("@/")) {
+      const absolute = path.join(root, request.slice(2));
+      request = existsSync(`${absolute}.ts`) ? `${absolute}.ts` : absolute;
+    }
+    return original.call(this, request, ...args);
+  };
+  const { createJiti } = await import("jiti");
+  runtime = createJiti(import.meta.url)(sourceCLI);
+} else runtime = await import("../dist/index.js");
+const result = runtime.runNMCLI(["bridge", ...workerData.args], {
+  readStdin: () => workerData.input,
+  readFile: () => { throw new Error("The JSON bridge does not read filesystem sources."); },
+});
+parentPort.postMessage(result);

package/bin/nm.mjs

@@ -25,7 +25,9 @@ const isPackedVersionCommand =
   process.env.NM_CLI_FORCE_PACKED === "1" &&
   (cliArgs[0] === "--version" || cliArgs[0] === "version");
 
-if (isPackedVersionCommand) {
+if (cliArgs[0] === "bridge") {
+  await (await import("./bridge-host.mjs")).runNMBridgeHost(cliArgs.slice(1));
+} else if (isPackedVersionCommand) {
   const { nmVersionManifest } = await import("../dist/version.js");
   process.stdout.write(
     cliArgs.includes("--json")