@nm-lang/cli 0.0.0-stage → 0.2.0

package/LICENSE.txt

@@ -0,0 +1,57 @@
+QuantumSoftware N/M npm Packages — Free Use License
+Version 1.0, 5 October 2026
+
+Copyright (c) 2026 QuantumSoftware.tech contributors. All rights reserved.
+
+1. Scope
+This license covers QuantumSoftware-owned code and assets in the official
+@nm-lang/core, @nm-lang/cli, @nm-lang/language-server and @nm-lang/mcp npm
+packages. It does not license the rest of the repository or the separately
+distributed VS Code extension. Third-party components remain subject to their
+respective licenses; their notices and permissions take precedence for those
+components.
+
+2. Free use
+You may download, install and use these official packages without charge for
+personal, educational and commercial purposes, import their APIs into your own
+programs, and make backup copies for your own use. QuantumSoftware authorizes
+distribution of its official packages through the nm-lang organization on the
+npm registry, including the registry's normal delivery and package-manager
+installation and caching mechanisms.
+
+3. Reserved rights
+This is not an open-source license. Except for the permissions above, rights
+to QuantumSoftware-owned code and assets are reserved. Modification,
+redistribution, sublicensing, sale or publication of that code or those assets
+requires separate permission from the rights holders, unless applicable law
+provides otherwise. Do not remove copyright or license notices. These
+restrictions do not override rights granted by any third-party license.
+
+4. Your programs
+This license imposes no restrictions on N/M programs you write, their source
+code, or simulation results produced using these packages. It does not
+transfer ownership of your work to QuantumSoftware. This clause does not grant
+additional redistribution rights to QuantumSoftware-owned runtime code bundled
+with your application; those rights are governed by sections 2 and 3.
+
+5. No warranty
+THE PACKAGES ARE PROVIDED "AS IS", WITHOUT WARRANTIES OF ANY KIND, TO THE
+EXTENT PERMITTED BY APPLICABLE LAW. TO THAT SAME EXTENT, THE RIGHTS HOLDERS
+ARE NOT LIABLE FOR DAMAGES ARISING FROM USE OF THE PACKAGES. RIGHTS THAT
+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
+
+Türkçe açıklama
+Resmî dört npm paketi kişisel, eğitim ve ticari amaçlarla ücretsiz kurulup
+kullanılabilir; API'leri kendi programlarınızdan çağırabilir ve kendi kullanımınız
+için yedek kopya alabilirsiniz. Bu bir açık kaynak lisansı değildir.
+QuantumSoftware'a ait kod ve varlıkları değiştirmek veya yeniden dağıtmak için
+ayrıca izin gerekir. Paketleri indirilebilir kılmak, kaynak kodu üzerinde açık
+kaynak hakları vermez. Üçüncü taraf lisanslarının ve yürürlükteki hukukun verdiği
+haklar korunur. Yazdığınız N/M programları ve ürettiğiniz sonuçların mülkiyeti
+size aittir. Uygulamanızla birlikte dağıtacağınız QuantumSoftware çalışma zamanı
+dosyaları için yukarıdaki izin ve kısıtlamalar geçerlidir. Yukarıdaki İngilizce
+metin lisansın koşullarını belirler.

package/NOTICE.txt

@@ -0,0 +1,11 @@
+QuantumSoftware N/M package notices
+
+Copyright (c) 2026 QuantumSoftware.tech contributors. All rights reserved.
+QuantumSoftware-owned code is licensed under LICENSE.txt.
+
+Runtime dependencies listed in package.json are installed separately by npm.
+Their own licenses and notices remain applicable. The QuantumSoftware license
+does not restrict the rights granted for those third-party components.
+
+jiti 2.x is a separately installed runtime dependency licensed under MIT.
+Its original LICENSE is included in the jiti package.

package/README.md

@@ -1,3 +1,74 @@
-# Temporary Holding Version
+# @nm-lang/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+N/M 0.2.0 Preview command-line tools for running, formatting, linting, testing,
+exporting and managing local N/M workspaces.
+
+## Install / Kurulum
+
+Requires Node.js 20 or newer. Release checks use Node.js 22.23.1.
+
+```sh
+npm install --global @nm-lang/cli@next
+nm --version
+```
+
+Or run without a global install:
+
+```sh
+npx --package=@nm-lang/cli@next nm --version
+```
+
+The `next` tag selects the preview channel. To pin this version after publication,
+replace `@next` with `@0.2.0`. 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.0` ile sürümü
+sabitleyebilirsiniz. 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
+
+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.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)
+
+## 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.

package/bin/nm.mjs

@@ -0,0 +1,315 @@
+#!/usr/bin/env node
+import { readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+let runNMCLI;
+let validateNMWorkspaceManifestJsonText;
+let NM_WORKSPACE_MAX_DOCUMENTS;
+let NM_WORKSPACE_MAX_SOURCE_BYTES;
+let nmWorkspaceDiagnosticCodes;
+let getNMWorkspaceModuleName;
+const workspaceRoot = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "../../..",
+);
+const workspaceCLIPath = path.join(workspaceRoot, "lib/nm/cli.ts");
+const workspaceCache = new Map();
+const cliArgs = process.argv.slice(2);
+const isPackedVersionCommand =
+  process.env.NM_CLI_FORCE_PACKED === "1" &&
+  (cliArgs[0] === "--version" || cliArgs[0] === "version");
+
+if (isPackedVersionCommand) {
+  const { nmVersionManifest } = await import("../dist/version.js");
+  process.stdout.write(
+    cliArgs.includes("--json")
+      ? `${JSON.stringify(nmVersionManifest, null, 2)}\n`
+      : `N/M ${nmVersionManifest.languageVersion} (${nmVersionManifest.stability})\n`,
+  );
+} else {
+  if (existsSync(workspaceCLIPath) && process.env.NM_CLI_FORCE_PACKED !== "1") {
+    const [{ default: Module }, { createJiti }] = await Promise.all([
+      import("node:module"),
+      import("jiti"),
+    ]);
+    installWorkspaceAliasResolver(Module);
+    const jiti = createJiti(import.meta.url);
+    ({
+      runNMCLI,
+      validateNMWorkspaceManifestJsonText,
+      NM_WORKSPACE_MAX_DOCUMENTS,
+      NM_WORKSPACE_MAX_SOURCE_BYTES,
+      nmWorkspaceDiagnosticCodes,
+      getNMWorkspaceModuleName,
+    } = jiti(workspaceCLIPath));
+  } else {
+    try {
+      ({
+        runNMCLI,
+        validateNMWorkspaceManifestJsonText,
+        NM_WORKSPACE_MAX_DOCUMENTS,
+        NM_WORKSPACE_MAX_SOURCE_BYTES,
+        nmWorkspaceDiagnosticCodes,
+        getNMWorkspaceModuleName,
+      } = await import("../dist/index.js"));
+    } catch {
+      ({
+        runNMCLI,
+        validateNMWorkspaceManifestJsonText,
+        NM_WORKSPACE_MAX_DOCUMENTS,
+        NM_WORKSPACE_MAX_SOURCE_BYTES,
+        nmWorkspaceDiagnosticCodes,
+        getNMWorkspaceModuleName,
+      } = await import("../../nm-core/dist/index.js"));
+    }
+  }
+  const packageAction = cliArgs[0] === "package" ? cliArgs[1] : undefined;
+  const crypto =
+    packageAction === "sign" || packageAction === "verify"
+      ? await import("node:crypto")
+      : undefined;
+  const packageSigner =
+    packageAction === "sign"
+      ? createConfiguredPackageSigner(crypto)
+      : undefined;
+  const packageVerifier =
+    packageAction === "verify"
+      ? createConfiguredPackageVerifier(crypto)
+      : undefined;
+  const result = runNMCLI(cliArgs, {
+    readFile: (filePath) => readFileSync(filePath, "utf8"),
+    readWorkspaceModules: (entryPath) => getWorkspaceIndex(entryPath).modules,
+    readWorkspaceDocuments: (entryPath) =>
+      getWorkspaceIndex(entryPath).documents,
+    fileExists: (filePath) => existsSync(filePath),
+    writeFile: (filePath, content, { overwrite }) =>
+      writeFileSync(filePath, content, {
+        encoding: "utf8",
+        flag: overwrite ? "w" : "wx",
+      }),
+    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`);
+  }
+  process.exitCode = result.exitCode;
+}
+
+function getWorkspaceIndex(entryPath) {
+  const cacheKey = path.resolve(entryPath);
+  const cached = workspaceCache.get(cacheKey);
+  if (cached) {
+    return cached;
+  }
+
+  const entryDirectory = path.dirname(cacheKey);
+  const manifestPath = findWorkspaceManifest(entryDirectory);
+  const manifest = manifestPath
+    ? validateWorkspaceManifest(manifestPath)
+    : undefined;
+  const root = manifestPath ? path.dirname(manifestPath) : entryDirectory;
+  const sourceRoots = manifest
+    ? manifest.sourceRoots.map((sourceRoot) =>
+        resolveInsideWorkspace(root, sourceRoot),
+      )
+    : [root];
+  const modules = Object.create(null);
+  const documents = [];
+  const seenFiles = new Set();
+  let sourceBytes = 0;
+  for (const sourceRoot of sourceRoots) {
+    for (const filePath of collectNMFiles(sourceRoot)) {
+      if (seenFiles.has(filePath)) {
+        continue;
+      }
+      seenFiles.add(filePath);
+      const source = readFileSync(filePath, "utf8");
+      sourceBytes += new TextEncoder().encode(source).byteLength;
+      if (sourceBytes > NM_WORKSPACE_MAX_SOURCE_BYTES) {
+        throw new Error(
+          `${nmWorkspaceDiagnosticCodes.limit}: N/M workspace source exceeded ${NM_WORKSPACE_MAX_SOURCE_BYTES} UTF-8 bytes.`,
+        );
+      }
+      const moduleName = getNMWorkspaceModuleName(source);
+      if (!moduleName) {
+        continue;
+      }
+      if (Object.prototype.hasOwnProperty.call(modules, moduleName)) {
+        throw new Error(
+          `${nmWorkspaceDiagnosticCodes.duplicateModule}: Duplicate N/M workspace module: ${moduleName}.`,
+        );
+      }
+      modules[moduleName] = source;
+      documents.push({
+        path: path.relative(root, filePath).split(path.sep).join("/"),
+        source,
+      });
+    }
+  }
+  const index = { modules, documents, manifest, root };
+  workspaceCache.set(cacheKey, index);
+  return index;
+}
+
+function findWorkspaceManifest(startDirectory) {
+  let directory = startDirectory;
+  while (true) {
+    const candidate = path.join(directory, "nm-workspace.json");
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+    const parent = path.dirname(directory);
+    if (parent === directory) {
+      return undefined;
+    }
+    directory = parent;
+  }
+}
+
+function validateWorkspaceManifest(manifestPath) {
+  const validation = validateNMWorkspaceManifestJsonText(
+    readFileSync(manifestPath, "utf8"),
+  );
+  if (!validation.valid) {
+    throw new Error(
+      `Invalid ${manifestPath}: ${validation.issues.map((issue) => `${issue.code} ${issue.path}: ${issue.message}`).join(" ")}`,
+    );
+  }
+  return validation.manifest;
+}
+
+function resolveInsideWorkspace(root, relativePath) {
+  const resolved = path.resolve(root, relativePath);
+  const relative = path.relative(root, resolved);
+  if (relative.startsWith("..") || path.isAbsolute(relative)) {
+    throw new Error(
+      `Workspace source root escapes its manifest directory: ${relativePath}.`,
+    );
+  }
+  return resolved;
+}
+
+function collectNMFiles(root) {
+  const ignoredDirectories = new Set(["node_modules", ".git", ".next", "dist"]);
+  const files = [];
+  const pending = [root];
+  while (pending.length > 0) {
+    const directory = pending.pop();
+    if (!directory) {
+      continue;
+    }
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+      const entryPath = path.join(directory, entry.name);
+      if (entry.isDirectory() && !ignoredDirectories.has(entry.name)) {
+        pending.push(entryPath);
+      } else if (entry.isFile() && entry.name.endsWith(".nm")) {
+        files.push(entryPath);
+      }
+    }
+    if (files.length > NM_WORKSPACE_MAX_DOCUMENTS) {
+      throw new Error(
+        `${nmWorkspaceDiagnosticCodes.limit}: N/M workspace index exceeded ${NM_WORKSPACE_MAX_DOCUMENTS} files under ${root}.`,
+      );
+    }
+  }
+  return files.sort();
+}
+
+function installWorkspaceAliasResolver(Module) {
+  const originalResolveFilename = Module._resolveFilename;
+  Module._resolveFilename = function resolveWorkspaceAlias(
+    request,
+    parent,
+    isMain,
+    options,
+  ) {
+    if (typeof request === "string" && request.startsWith("@/")) {
+      const absoluteRequest = path.join(workspaceRoot, request.slice(2));
+      const tsRequest = `${absoluteRequest}.ts`;
+      return originalResolveFilename.call(
+        this,
+        existsSync(tsRequest) ? tsRequest : absoluteRequest,
+        parent,
+        isMain,
+        options,
+      );
+    }
+    return originalResolveFilename.call(this, request, parent, isMain, options);
+  };
+}
+
+function createConfiguredPackageSigner(crypto) {
+  const privateKeyText = process.env.NM_PACKAGE_SIGNING_PRIVATE_KEY?.replaceAll(
+    "\\n",
+    "\n",
+  ).trim();
+  const keyId = process.env.NM_PACKAGE_SIGNING_KEY_ID?.trim();
+  if (!privateKeyText && !keyId) return undefined;
+  if (!privateKeyText || !keyId) {
+    throw new Error(
+      "NM_PACKAGE_SIGNING_PRIVATE_KEY and NM_PACKAGE_SIGNING_KEY_ID must be configured together.",
+    );
+  }
+  const privateKey = crypto.createPrivateKey(privateKeyText);
+  if (privateKey.asymmetricKeyType !== "ed25519")
+    throw new Error("NM package signing key must be Ed25519.");
+  return {
+    algorithm: "ed25519",
+    keyId,
+    sign: (payload) =>
+      crypto.sign(null, payload, privateKey).toString("base64url"),
+  };
+}
+
+function createConfiguredPackageVerifier(crypto) {
+  const keyringText = process.env.NM_PACKAGE_TRUSTED_PUBLIC_KEYS_JSON?.trim();
+  if (!keyringText) return undefined;
+  let keyringValue;
+  try {
+    keyringValue = JSON.parse(keyringText);
+  } catch {
+    throw new Error("NM_PACKAGE_TRUSTED_PUBLIC_KEYS_JSON must be valid JSON.");
+  }
+  if (
+    !keyringValue ||
+    typeof keyringValue !== "object" ||
+    Array.isArray(keyringValue)
+  ) {
+    throw new Error(
+      "NM_PACKAGE_TRUSTED_PUBLIC_KEYS_JSON must be an object keyed by key id.",
+    );
+  }
+  const keyring = new Map();
+  for (const [keyId, publicKeyText] of Object.entries(keyringValue)) {
+    if (typeof publicKeyText !== "string" || !publicKeyText.trim())
+      throw new Error(`Trusted public key is invalid: ${keyId}.`);
+    const publicKey = crypto.createPublicKey(
+      publicKeyText.replaceAll("\\n", "\n"),
+    );
+    if (publicKey.asymmetricKeyType !== "ed25519")
+      throw new Error(`Trusted public key must be Ed25519: ${keyId}.`);
+    keyring.set(keyId, publicKey);
+  }
+  return {
+    verify: ({ algorithm, keyId, payload, signature }) => {
+      const publicKey = keyring.get(keyId);
+      return (
+        algorithm === "ed25519" &&
+        Boolean(publicKey) &&
+        crypto.verify(
+          null,
+          payload,
+          publicKey,
+          Buffer.from(signature, "base64url"),
+        )
+      );
+    },
+  };
+}

package/dist/index.d.ts

@@ -0,0 +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";