@nm-lang/cli 0.2.1 → 0.3.0

package/LICENSE.txt

@@ -42,7 +42,7 @@ CANNOT BE EXCLUDED UNDER APPLICABLE LAW ARE NOT AFFECTED.
 
 6. Permission requests
 For additional permissions, contact the publisher through:
-https://quantumsoftware-tech.vercel.app/en/#contact
+https://quantumsoftware.tech/en/#contact
 
 Türkçe açıklama
 Resmî dört npm paketi kişisel, eğitim ve ticari amaçlarla ücretsiz kurulup

package/README.md

@@ -3,29 +3,32 @@
 N/M 0.2.0 Preview command-line tools for running, formatting, linting, testing,
 exporting and managing local N/M workspaces.
 
-Package release **0.2.1** targets the N/M **0.2.0** language contract.
+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@next
+npm install --global @nm-lang/cli
 nm --version
 ```
 
 Or run without a global install:
 
 ```sh
-npx --package=@nm-lang/cli@next nm --version
+npx --package=@nm-lang/cli nm --version
 ```
 
-The `next` tag selects the preview channel. To pin this version after publication,
-replace `@next` with `@0.2.1`. npm installs the matching Core dependency.
+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: `next` önizleme kanalını seçer. Yayından sonra `@0.2.1` ile sürümü
-sabitleyebilirsiniz. Core bağımlılığı otomatik kurulur; depoyu indirmeniz gerekmez.
+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
 
@@ -53,6 +56,67 @@ 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
@@ -61,9 +125,9 @@ 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.vercel.app/en/docs/nm-language/cli)
-- [Türkçe CLI rehberi](https://quantumsoftware-tech.vercel.app/tr/docs/nm-language/cli)
-- [Support / Destek](https://quantumsoftware-tech.vercel.app/en/#contact)
+- [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
 

package/bin/doctor-runtime.mjs

@@ -0,0 +1,172 @@
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+/** Read only the selected runtime and locally resolvable package entries. */
+export async function observeNMDoctorRuntime({ cliPackageRoot, workspaceRoot, runtimeSource, runtimePath, runtimeModule, versionManifest }) {
+  const cliMetadata = readMetadata(cliPackageRoot, "@nm-lang/cli");
+  const source = runtimeSource === "repository-source" ? "repository-source" : "package-artifact";
+  const cli = {
+    id: "cli", availability: cliMetadata ? "observed" : "unavailable", source,
+    packageVersion: cliMetadata?.version, languageVersion: versionManifest?.languageVersion,
+    corePackageVersion: versionManifest?.packageVersion,
+    protocols: pickStrings({ cliContract: runtimeModule.NM_CLI_CONTRACT_VERSION }),
+    evidence: [path.join(cliPackageRoot, "package.json"), runtimePath],
+    ...(!cliMetadata ? { reason: "invalid-cli-package-metadata" } : {}),
+  };
+  const coreRoot = runtimeSource === "repository-source" ? path.join(workspaceRoot, "packages/nm-core") : runtimeSource === "core-package-fallback" ? path.dirname(path.dirname(runtimePath)) : undefined;
+  const coreMetadata = coreRoot ? readMetadata(coreRoot, "@nm-lang/core") : undefined;
+  const core = {
+    id: "core", availability: versionManifest && (!coreRoot || coreMetadata) ? "observed" : "unavailable",
+    source: runtimeSource === "repository-source" ? "repository-source" : runtimeSource === "core-package-fallback" ? "package-artifact" : "bundled-core",
+    packageVersion: coreMetadata?.version ?? versionManifest?.packageVersion,
+    corePackageVersion: versionManifest?.packageVersion,
+    languageVersion: versionManifest?.languageVersion,
+    capabilities: pickStrings(versionManifest?.capabilities ?? {}),
+    evidence: [runtimeSource === "repository-source" ? path.join(workspaceRoot, "lib/nm/version.ts") : runtimePath, ...(coreRoot ? [path.join(coreRoot, "package.json")] : [])],
+    ...(!versionManifest ? { reason: "loaded-core-manifest-not-exported" } : coreRoot && !coreMetadata ? { reason: "invalid-core-package-metadata" } : {}),
+  };
+  const optional = [];
+  for (const [id, packageName, directory] of [
+    ["language-server", "@nm-lang/language-server", "nm-language-server"],
+    ["mcp", "@nm-lang/mcp", "nm-mcp"],
+  ]) {
+    optional.push(await observeLocalComponent({ id, packageName, directory, workspaceRoot }));
+  }
+  return { components: [cli, core, ...optional, {
+    id: "vscode", availability: "not-observed", source: "none",
+    reason: "editor-installation-and-running-servers-not-queried",
+  }] };
+}
+
+async function observeLocalComponent({ id, packageName, directory, workspaceRoot }) {
+  let entryPath;
+  let packageRoot;
+  const resolutionRoot = path.dirname(fileURLToPath(import.meta.url));
+  try {
+    // This helper ships inside CLI/bin; native ESM resolution therefore uses
+    // the same package scope as the CLI, including import-only export maps.
+    entryPath = fileURLToPath(import.meta.resolve(packageName));
+    packageRoot = findPackageRoot(entryPath, packageName, resolutionRoot);
+  } catch {
+    const present = findLocalPackageRoot(resolutionRoot, packageName);
+    if (present) return {
+      id, availability: "unavailable", source: "package-artifact",
+      evidence: [path.join(present, "package.json")],
+      reason: readMetadata(present, packageName) ? "local-package-entry-not-resolvable" : "invalid-local-package-metadata",
+    };
+    // Explicit repository sibling only; never search user homes, PATH, or global installs.
+    if (workspaceRoot) {
+      const candidate = path.join(workspaceRoot, "packages", directory);
+      if (existsSync(path.join(candidate, "package.json"))) {
+        packageRoot = candidate;
+        entryPath = path.join(candidate, "dist/index.js");
+      }
+    }
+  }
+  if (!packageRoot) {
+    const present = findLocalPackageRoot(resolutionRoot, packageName);
+    if (present) return { id, availability: "unavailable", source: "package-artifact",
+      evidence: [present], reason: "invalid-local-package-metadata" };
+    return { id, availability: "not-installed", source: "none", reason: "package-not-resolvable-from-cli" };
+  }
+  const metadataPath = path.join(packageRoot, "package.json");
+  const metadata = readMetadata(packageRoot, packageName);
+  const evidence = [metadataPath, entryPath];
+  if (!metadata) return { id, availability: "unavailable", source: "package-artifact", evidence, reason: "invalid-local-package-metadata" };
+  if (!existsSync(entryPath)) {
+    const repositoryArtifact = workspaceRoot && sameDirectory(packageRoot, path.join(workspaceRoot, "packages", directory));
+    return { id, availability: repositoryArtifact ? "not-observed" : "unavailable",
+      source: repositoryArtifact ? "repository-source" : "package-artifact", packageVersion: metadata.version,
+      evidence, reason: repositoryArtifact ? "repository-package-artifact-not-built" : "local-package-artifact-missing" };
+  }
+  try {
+    const runtime = await import(pathToFileURL(entryPath).href);
+    // Generated wrappers re-export the manifest from the very Core they import.
+    const manifest = runtime.nmVersionManifest;
+    if (!manifest) throw new Error("loaded-core-manifest-not-exported");
+    let protocols;
+    let languageVersion;
+    let serverVersion;
+    if (id === "language-server") {
+      const responses = runtime.handleNMLanguageServerMessage(
+        runtime.createNMLanguageServerState({ requireInitialize: true }),
+        { jsonrpc: "2.0", id: 1, method: "initialize", params: { capabilities: {} } },
+      );
+      const response = responses.find((item) => item.id === 1);
+      if (response?.error || !response?.result?.serverInfo) throw new Error("initialize-failed");
+      languageVersion = response.result.serverInfo.version;
+      serverVersion = response.result.serverInfo.version;
+      protocols = pickStrings({ lspContract: response.result.capabilities?.experimental?.nmContractVersion });
+    } else {
+      const response = runtime.handleNMMCPMessage(
+        { jsonrpc: "2.0", id: 1, method: "initialize", params: { protocolVersion: runtime.NM_MCP_PROTOCOL_VERSION, capabilities: {}, clientInfo: { name: "nm-doctor", version: "0.1" } } },
+        runtime.createNMMCPServerState({ requireInitialize: true }),
+      );
+      if (response?.error || !response?.result?.serverInfo) throw new Error("initialize-failed");
+      serverVersion = response.result.serverInfo.version;
+      languageVersion = manifest?.languageVersion;
+      protocols = pickStrings({ mcpContract: runtime.NM_MCP_CONTRACT_VERSION, mcpProtocol: response.result.protocolVersion, mcpToolSchema: runtime.NM_MCP_TOOL_SCHEMA_VERSION });
+    }
+    return {
+      id, availability: "observed", source: "package-artifact", packageVersion: metadata.version,
+      languageVersion, corePackageVersion: manifest?.packageVersion, serverVersion,
+      protocols, capabilities: manifest ? pickStrings(manifest.capabilities ?? {}) : undefined,
+      evidence,
+    };
+  } catch {
+    return { id, availability: "unavailable", source: "package-artifact", packageVersion: metadata.version, evidence, reason: "local-package-runtime-probe-failed" };
+  }
+}
+
+function findLocalPackageRoot(start, packageName) {
+  let directory = start;
+  // Only Node's ancestor node_modules locations; no NODE_PATH/global/home scan.
+  for (let depth = 0; depth < 64; depth++) {
+    const candidate = path.join(directory, "node_modules", packageName);
+    try { if (statSync(candidate).isDirectory()) return candidate; } catch { /* absent local package */ }
+    const parent = path.dirname(directory);
+    if (parent === directory) break;
+    directory = parent;
+  }
+}
+
+function sameDirectory(left, right) {
+  try {
+    const normalize = (value) => process.platform === "win32" ? value.toLowerCase() : value;
+    return normalize(realpathSync(left)) === normalize(realpathSync(right));
+  } catch { return false; }
+}
+
+function findPackageRoot(entryPath, expectedName, resolutionRoot) {
+  const localRoot = findLocalPackageRoot(resolutionRoot, expectedName);
+  if (!localRoot) return undefined;
+  try {
+    // An export may sit below unnamed package.json scopes or many directories.
+    // Anchor its metadata to the locally selected package, including symlinks,
+    // rather than accepting a nested scope or an enclosing repository manifest.
+    const packageRoot = realpathSync(localRoot);
+    const entryExists = existsSync(entryPath);
+    const resolvedEntry = entryExists ? realpathSync(entryPath) : path.resolve(entryPath);
+    const containsEntry = (root) => {
+      const relative = path.relative(root, resolvedEntry);
+      return relative !== "" && relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+    };
+    if (!containsEntry(packageRoot) && (entryExists || !containsEntry(path.resolve(localRoot)))) return undefined;
+    return readMetadata(packageRoot, expectedName) ? packageRoot : undefined;
+  } catch { return undefined; }
+}
+
+function readMetadata(directory, expectedName) {
+  try {
+    const metadataPath = path.join(directory, "package.json");
+    if (statSync(metadataPath).size > 65_536) return undefined;
+    const value = JSON.parse(readFileSync(metadataPath, "utf8").replace(/^\uFEFF/u, ""));
+    if (value.name !== expectedName || typeof value.version !== "string") return undefined;
+    return { version: value.version };
+  } catch { return undefined; }
+}
+
+function pickStrings(value) {
+  return Object.fromEntries(Object.entries(value).filter(([, item]) => typeof item === "string"));
+}

package/bin/nm.mjs

@@ -10,6 +10,10 @@ let NM_WORKSPACE_MAX_DOCUMENTS;
 let NM_WORKSPACE_MAX_SOURCE_BYTES;
 let nmWorkspaceDiagnosticCodes;
 let getNMWorkspaceModuleName;
+let loadedRuntime;
+let loadedVersionManifest;
+let runtimeSource;
+let runtimePath;
 const workspaceRoot = path.resolve(
   path.dirname(fileURLToPath(import.meta.url)),
   "../../..",
@@ -36,6 +40,10 @@ if (isPackedVersionCommand) {
     ]);
     installWorkspaceAliasResolver(Module);
     const jiti = createJiti(import.meta.url);
+    loadedRuntime = jiti(workspaceCLIPath);
+    loadedVersionManifest = jiti(path.join(workspaceRoot, "lib/nm/version.ts")).nmVersionManifest;
+    runtimeSource = "repository-source";
+    runtimePath = workspaceCLIPath;
     ({
       runNMCLI,
       validateNMWorkspaceManifestJsonText,
@@ -43,7 +51,7 @@ if (isPackedVersionCommand) {
       NM_WORKSPACE_MAX_SOURCE_BYTES,
       nmWorkspaceDiagnosticCodes,
       getNMWorkspaceModuleName,
-    } = jiti(workspaceCLIPath));
+    } = loadedRuntime);
   } else {
     try {
       ({
@@ -53,7 +61,10 @@ if (isPackedVersionCommand) {
         NM_WORKSPACE_MAX_SOURCE_BYTES,
         nmWorkspaceDiagnosticCodes,
         getNMWorkspaceModuleName,
-      } = await import("../dist/index.js"));
+      } = loadedRuntime = await import("../dist/index.js"));
+      loadedVersionManifest = loadedRuntime.nmVersionManifest;
+      runtimeSource = "cli-package-artifact";
+      runtimePath = fileURLToPath(new URL("../dist/index.js", import.meta.url));
     } catch {
       ({
         runNMCLI,
@@ -62,7 +73,10 @@ if (isPackedVersionCommand) {
         NM_WORKSPACE_MAX_SOURCE_BYTES,
         nmWorkspaceDiagnosticCodes,
         getNMWorkspaceModuleName,
-      } = await import("../../nm-core/dist/index.js"));
+      } = loadedRuntime = await import("../../nm-core/dist/index.js"));
+      loadedVersionManifest = loadedRuntime.nmVersionManifest;
+      runtimeSource = "core-package-fallback";
+      runtimePath = fileURLToPath(new URL("../../nm-core/dist/index.js", import.meta.url));
     }
   }
   const packageAction = cliArgs[0] === "package" ? cliArgs[1] : undefined;
@@ -78,7 +92,14 @@ if (isPackedVersionCommand) {
     packageAction === "verify"
       ? createConfiguredPackageVerifier(crypto)
       : undefined;
-  const result = runNMCLI(cliArgs, {
+  const watching = cliArgs.includes("--watch");
+  const executionArgs = cliArgs.filter(arg => arg !== "--watch");
+  const runOptions = {
+    ...(cliArgs[0] === "doctor" ? { doctorRuntime: await (await import("./doctor-runtime.mjs")).observeNMDoctorRuntime({
+      cliPackageRoot: path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."),
+      workspaceRoot: existsSync(workspaceCLIPath) ? workspaceRoot : undefined,
+      runtimeSource, runtimePath, runtimeModule: loadedRuntime, versionManifest: loadedVersionManifest,
+    }) } : {}),
     readFile: (filePath) => readFileSync(filePath, "utf8"),
     readWorkspaceModules: (entryPath) => getWorkspaceIndex(entryPath).modules,
     readWorkspaceDocuments: (entryPath) =>
@@ -91,15 +112,24 @@ if (isPackedVersionCommand) {
       }),
     packageSigner,
     packageVerifier,
-  });
-
-  if (result.stdout.length > 0) {
-    process.stdout.write(`${result.stdout.join("\n")}\n`);
-  }
-  if (result.stderr.length > 0) {
-    process.stderr.write(`${result.stderr.join("\n")}\n`);
+  };
+  const reportFormat = executionArgs[executionArgs.indexOf("--report-format") + 1];
+  const reportFile = executionArgs.includes("--output") ? executionArgs[executionArgs.indexOf("--output") + 1] : undefined;
+  if (watching && (executionArgs[0] !== "test" || !executionArgs[1] || executionArgs[1].startsWith("--") || cliArgs.filter(arg => arg === "--watch").length !== 1 || executionArgs.includes("--report-format") && reportFormat !== "json" && !reportFile)) {
+    process.stderr.write("--watch requires nm test <file>; JUnit/SARIF watch reports require --output.\n");
+    process.exitCode = 1;
+  } else if (watching) {
+    await (await import("./test-watch.mjs")).watchNMTests({
+      entryPath: executionArgs[1], asJson: executionArgs.includes("--json"), reportFormat, reportFile,
+      workspaceRoot: () => { const entryDirectory = path.dirname(path.resolve(executionArgs[1])); const manifest = findWorkspaceManifest(entryDirectory); return manifest ? path.dirname(manifest) : entryDirectory; },
+      run: () => { workspaceCache.clear(); return runNMCLI(executionArgs, runOptions); },
+    });
+  } else {
+    const result = runNMCLI(cliArgs, runOptions);
+    if (result.stdout.length > 0) process.stdout.write(`${result.stdout.join("\n")}\n`);
+    if (result.stderr.length > 0) process.stderr.write(`${result.stderr.join("\n")}\n`);
+    process.exitCode = result.exitCode;
   }
-  process.exitCode = result.exitCode;
 }
 
 function getWorkspaceIndex(entryPath) {

package/bin/test-watch.mjs

@@ -0,0 +1,84 @@
+import { watch } from "node:fs";
+import path from "node:path";
+
+/** One execution at a time, including a queued rerun when changes arrive mid-run. */
+export async function watchNMTests({ entryPath, run, workspaceRoot, asJson, reportFile, reportFormat, debounceMs = 150 }) {
+  let timer, running = false, dirty = false, stopped = false, sequence = 0;
+  let watchers = [], watchedRoot;
+  const ignored = new Set(["node_modules", ".git", ".next", "dist", ".qa"]);
+  const comparable = value => process.platform === "win32" ? value.toLowerCase() : value;
+  const canonical = value => comparable(path.resolve(value));
+  const entry = canonical(entryPath);
+  const reportPath = reportFile ? canonical(reportFile) : undefined;
+  const emit = (event) => process.stdout.write(asJson ? `${JSON.stringify(event)}\n` : `${event.event === "run" ? `N/M watch run ${event.sequence}: exit ${event.exitCode}` : `N/M watch: ${event.event}${event.message ? `: ${event.message}` : ""}`}\n`);
+  const closeWatchers = () => { for (const watcher of watchers) watcher.close(); watchers = []; };
+  const changed = (filename, manifestOnly = false, event = "change", directory = watchedRoot) => {
+    if (stopped) return;
+    const name = filename?.toString() ?? "";
+    const matchName = comparable(name);
+    if (matchName.split(/[\\/]/u).some(part => ignored.has(part))) return;
+    const changedPath = name ? canonical(path.join(directory, name)) : undefined;
+    if (changedPath && changedPath === reportPath) return;
+    const entryChanged = changedPath === entry;
+    const manifestChanged = path.basename(matchName) === "nm-workspace.json";
+    // Native watchers can report a moved/deleted directory without reporting its
+    // individual .nm children. Rescan structural events and unknown filenames.
+    // Explicit entry paths are valid even when they do not use lowercase .nm.
+    if (!entryChanged && (manifestOnly ? !manifestChanged : name && event !== "rename" && !matchName.endsWith(".nm") && !manifestChanged)) return;
+    dirty = true;
+    clearTimeout(timer);
+    timer = setTimeout(() => void execute(), debounceMs);
+  };
+  const installWatchers = () => {
+    const root = workspaceRoot();
+    const rootPath = canonical(root);
+    if (watchedRoot && rootPath === canonical(watchedRoot) && watchers.length) return;
+    closeWatchers(); watchedRoot = root;
+    const attach = (directory, recursive, manifestOnly) => {
+      const watcher = watch(directory, { recursive }, (event, filename) => changed(filename, manifestOnly, event, directory));
+      watcher.on("error", error => { emit({ event: "error", message: error.message }); stop(1); });
+      watchers.push(watcher);
+    };
+    attach(root, true, false);
+    // A newly created nearer/ancestor manifest can change the workspace roots.
+    for (let directory = path.dirname(path.resolve(entryPath)); ; directory = path.dirname(directory)) {
+      if (canonical(directory) !== rootPath) attach(directory, false, true);
+      if (path.dirname(directory) === directory) break;
+    }
+  };
+  const stop = (code) => {
+    if (stopped) return;
+    stopped = true; clearTimeout(timer); closeWatchers();
+    process.off("SIGINT", onInterrupt); process.off("SIGTERM", onTerminate);
+    process.exitCode = code;
+    emit({ event: "stopped", exitCode: code });
+  };
+  const onInterrupt = () => stop(130), onTerminate = () => stop(143);
+  const execute = async () => {
+    if (stopped || running) return;
+    running = true; dirty = false;
+    try {
+      const result = await run();
+      if (stopped) return;
+      process.exitCode = result.exitCode;
+      sequence++;
+      if (asJson) {
+        let report;
+        try { report = JSON.parse(result.stdout.join("\n")); } catch { /* Invocation failures have no report. */ }
+        emit({ event: "run", sequence, exitCode: result.exitCode, report: report ?? null, diagnostics: result.stderr });
+      } else {
+        emit({ event: "run", sequence, exitCode: result.exitCode });
+        if (reportFile && reportFormat && reportFormat !== "json") process.stdout.write(`report file: ${reportFile}\n`);
+        else if (result.stdout.length) process.stdout.write(`${result.stdout.join("\n")}\n`);
+        if (result.stderr.length) process.stderr.write(`${result.stderr.join("\n")}\n`);
+      }
+      installWatchers();
+    } catch (error) { emit({ event: "error", message: error.message }); stop(1); }
+    finally { running = false; if (dirty && !stopped) { clearTimeout(timer); timer = setTimeout(() => void execute(), debounceMs); } }
+  };
+  process.on("SIGINT", onInterrupt); process.on("SIGTERM", onTerminate);
+  // Install before the first run so asynchronous runs cannot miss source changes.
+  try { installWatchers(); await execute(); }
+  catch (error) { emit({ event: "error", message: error.message }); stop(1); }
+  return { dispose: () => stop(process.exitCode ?? 0) };
+}

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { getNMWorkspaceModuleName, evaluateNMLanguagePreviewReadiness, NM_CLI_CONTRACT_VERSION, NM_LANGUAGE_PREVIEW_READINESS_FORMAT, NM_LANGUAGE_PREVIEW_READINESS_VERSION, NM_WORKSPACE_MAX_DOCUMENTS, NM_WORKSPACE_MAX_SOURCE_BYTES, nmCliCommandContracts, nmCliCommands, nmCliExitCodeContract, nmLanguagePreviewReadiness, nmLanguageReleaseChangelog, nmVersionManifest, nmWorkspaceDiagnosticCodes, runNMCLI, validateNMWorkspaceManifestJsonText } from "@nm-lang/core/cli";
-export type { NMCapabilityStatus, NMCLICommand, NMCLICommandContract, NMCLIDeterminism, NMCLIExportTarget, NMCLIOptions, NMCLIOutputKind, NMCLIResult, NMLanguagePreviewReadiness, NMLanguageReleaseChange, NMVersionManifest } from "@nm-lang/core/cli";
+export { NM_DOCTOR_REPORT_FORMAT, NM_DOCTOR_REPORT_VERSION, createNMDoctorReport, formatNMDoctorReport, nmDoctorExpectedVersions, getNMWorkspaceModuleName, evaluateNMLanguagePreviewReadiness, NM_CLI_CONTRACT_VERSION, NM_LANGUAGE_PREVIEW_READINESS_FORMAT, NM_LANGUAGE_PREVIEW_READINESS_VERSION, NM_WORKSPACE_MAX_DOCUMENTS, NM_WORKSPACE_MAX_SOURCE_BYTES, nmCliCommandContracts, nmCliCommands, nmCliExitCodeContract, nmLanguagePreviewReadiness, nmLanguageReleaseChangelog, nmVersionManifest, nmWorkspaceDiagnosticCodes, runNMCLI, validateNMWorkspaceManifestJsonText } from "@nm-lang/core/cli";
+export type { NMDoctorCheck, NMDoctorComponentId, NMDoctorObservation, NMDoctorReport, NMDoctorRuntimeObservation, NMCapabilityStatus, NMCLICommand, NMCLICommandContract, NMCLIDeterminism, NMCLIExportTarget, NMCLIOptions, NMCLIOutputKind, NMCLIResult, NMLanguagePreviewReadiness, NMLanguageReleaseChange, NMVersionManifest } from "@nm-lang/core/cli";