@open-mercato/cli 0.10.1-develop.7990.1.82d0a183c5 → 0.10.1-develop.7994.1.c9f31972aa

package/dist/lib/module-identity.js

@@ -0,0 +1,131 @@
+import fs from "node:fs";
+import path from "node:path";
+import ts from "typescript-js";
+import { normalizeModuleLocator } from "@open-mercato/shared/modules/module-locators";
+import { readEnabledModules } from "./modules-config.js";
+function readJson(filePath) {
+  try {
+    const value = JSON.parse(fs.readFileSync(filePath, "utf8"));
+    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+  } catch {
+    return {};
+  }
+}
+function readMetadataLocator(moduleBase) {
+  const indexPath = ["index.ts", "index.js"].map((name) => path.join(moduleBase, name)).find((candidate) => fs.existsSync(candidate));
+  if (!indexPath) return void 0;
+  const source = ts.createSourceFile(indexPath, fs.readFileSync(indexPath, "utf8"), ts.ScriptTarget.Latest, true);
+  let locator;
+  function visit(node) {
+    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.name.text === "metadata" && node.initializer) {
+      let initializer = node.initializer;
+      while (ts.isAsExpression(initializer) || ts.isSatisfiesExpression(initializer) || ts.isParenthesizedExpression(initializer)) initializer = initializer.expression;
+      if (ts.isObjectLiteralExpression(initializer)) {
+        for (const property of initializer.properties) {
+          if (ts.isPropertyAssignment(property) && (ts.isIdentifier(property.name) || ts.isStringLiteralLike(property.name)) && property.name.text === "locator" && ts.isStringLiteralLike(property.initializer)) locator = property.initializer.text;
+        }
+      }
+    }
+    ts.forEachChild(node, visit);
+  }
+  visit(source);
+  return locator;
+}
+function sourceLocator(value) {
+  if (typeof value !== "string") return void 0;
+  const locator = normalizeModuleLocator(value);
+  return locator?.startsWith("npm:") || locator?.startsWith("github:") ? locator : void 0;
+}
+function installedDependencyLocator(specifier, canonicalName) {
+  if (typeof specifier !== "string") return void 0;
+  if (/^(?:github:|github\.com\/|(?:git\+)?https?:\/\/github\.com\/|git@github\.com:|(?:git\+)?ssh:\/\/|[a-z0-9][a-z0-9-]*\/[a-z0-9._-]+(?:[#@]|$))/i.test(specifier)) {
+    const locator = sourceLocator(specifier);
+    return locator?.startsWith("github:") ? locator : void 0;
+  }
+  if (specifier.startsWith("npm:")) {
+    const aliasTarget = specifier.match(/^npm:(@[^/]+\/[^@]+|[^@]+)(?:@.+)?$/)?.[1];
+    return aliasTarget ? sourceLocator(`npm:${aliasTarget}`) : void 0;
+  }
+  if (!canonicalName || /^(?:[a-z][a-z0-9+.-]*:|[./]|https?:)/i.test(specifier)) return void 0;
+  return sourceLocator(`npm:${canonicalName}`);
+}
+function assertDeclaredIdentity(entry, observedLocator, canonicalName) {
+  const binding = entry.from ?? "@open-mercato/core";
+  if (entry.packageName && canonicalName && entry.packageName !== canonicalName) {
+    throw new Error(`[modules] Cannot resolve module '${entry.id}' from binding '${binding}': declared package '${entry.packageName}' disagrees with installed package '${canonicalName}'. Restore the intended binding or correct src/modules.ts, then regenerate.`);
+  }
+  const declaredLocator = sourceLocator(entry.locator);
+  if (declaredLocator && observedLocator && declaredLocator !== observedLocator) {
+    throw new Error(`[modules] Cannot resolve module '${entry.id}' from binding '${binding}': declared origin '${declaredLocator}' disagrees with observed origin '${observedLocator}'. Disable the old provider before replacing it, then regenerate.`);
+  }
+  if (declaredLocator?.startsWith("npm:") && canonicalName && declaredLocator !== sourceLocator(`npm:${canonicalName}`)) {
+    throw new Error(`[modules] Cannot resolve module '${entry.id}' from binding '${binding}': declared origin '${declaredLocator}' disagrees with installed package '${canonicalName}'. Correct src/modules.ts to select the intended provider, then regenerate.`);
+  }
+}
+function readModuleLocators(entry, resolver, appManifest, packageManifests) {
+  const from = entry.from ?? "@open-mercato/core";
+  if (from === "@app") {
+    const retainedLocator = sourceLocator(entry.locator ?? readMetadataLocator(resolver.getModulePaths(entry).appBase));
+    assertDeclaredIdentity(entry, retainedLocator, entry.packageName);
+    return retainedLocator ? [retainedLocator] : [];
+  }
+  let manifest = packageManifests.get(from);
+  if (!manifest) {
+    manifest = readJson(path.join(resolver.getPackageRoot(from), "package.json"));
+    packageManifests.set(from, manifest);
+  }
+  const canonicalName = typeof manifest.name === "string" ? manifest.name : void 0;
+  const observedLocators = /* @__PURE__ */ new Set();
+  for (const section of ["dependencies", "devDependencies", "optionalDependencies"]) {
+    const dependencies = appManifest[section];
+    if (!dependencies || typeof dependencies !== "object" || Array.isArray(dependencies)) continue;
+    const specifier = dependencies[from];
+    const locator2 = installedDependencyLocator(specifier, canonicalName);
+    if (locator2?.startsWith("npm:") && canonicalName !== from && typeof specifier === "string" && !specifier.startsWith("npm:")) {
+      throw new Error(`[modules] Cannot resolve module '${entry.id}' from binding '${from}': installed package '${canonicalName}' does not match the dependency binding. Restore the intended package or declare an explicit npm alias, then regenerate.`);
+    }
+    if (locator2) observedLocators.add(locator2);
+  }
+  if (observedLocators.size > 1) {
+    throw new Error(`[modules] Cannot resolve module '${entry.id}' from binding '${from}': dependency sections declare conflicting origins. Keep one provider for this binding in package.json, then regenerate.`);
+  }
+  const observedLocator = [...observedLocators][0];
+  if (observedLocator?.startsWith("npm:") && canonicalName && observedLocator !== sourceLocator(`npm:${canonicalName}`)) {
+    throw new Error(`[modules] Cannot resolve module '${entry.id}' from binding '${from}': dependency origin '${observedLocator}' disagrees with installed package '${canonicalName}'. Restore the intended package through the package manager, then regenerate.`);
+  }
+  assertDeclaredIdentity(entry, observedLocator, canonicalName);
+  const locator = observedLocator ?? sourceLocator(entry.locator);
+  return locator ? [locator] : [];
+}
+function getModuleLocators(entry, resolver) {
+  return readModuleLocators(entry, resolver, readJson(path.join(resolver.getAppDir(), "package.json")), /* @__PURE__ */ new Map());
+}
+function assertUniqueEnabledModuleIds(enabledModules, resolver) {
+  const byId = /* @__PURE__ */ new Map();
+  for (const entry of enabledModules) {
+    const existing = byId.get(entry.id);
+    if (existing) {
+      const describe = (provider) => {
+        const binding = provider.from ?? "@open-mercato/core";
+        const source = sourceLocator(provider.locator);
+        return binding === "@app" ? `@app (${resolver.getModulePaths(provider).appBase})${source ? `, origin ${source}` : ""}` : `binding '${binding}'${source ? `, origin ${source}` : ""}`;
+      };
+      throw new Error(`[generate] Duplicate enabled module ID '${entry.id}': ${describe(existing)} and ${describe(entry)}. Keep one provider in src/modules.ts, then run yarn mercato generate. Installing under another package alias does not allow both module IDs to run.`);
+    }
+    byId.set(entry.id, entry);
+  }
+}
+function getEnabledModuleIdentities(resolver, enabledModules = resolver.loadEnabledModules()) {
+  const modulesPath = typeof resolver.getModulesConfigPath === "function" ? resolver.getModulesConfigPath() : path.join(resolver.getAppDir(), "src", "modules.ts");
+  if (fs.existsSync(modulesPath)) assertUniqueEnabledModuleIds(readEnabledModules(modulesPath), resolver);
+  assertUniqueEnabledModuleIds(enabledModules, resolver);
+  const appManifest = readJson(path.join(resolver.getAppDir(), "package.json"));
+  const packageManifests = /* @__PURE__ */ new Map();
+  return enabledModules.map((entry) => ({ id: entry.id, locators: readModuleLocators(entry, resolver, appManifest, packageManifests) }));
+}
+export {
+  assertUniqueEnabledModuleIds,
+  getEnabledModuleIdentities,
+  getModuleLocators
+};
+//# sourceMappingURL=module-identity.js.map

package/dist/lib/module-identity.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/lib/module-identity.ts"],
+  "sourcesContent": ["import fs from 'node:fs'\nimport path from 'node:path'\nimport ts from 'typescript-js'\nimport { normalizeModuleLocator, type ModuleIdentity } from '@open-mercato/shared/modules/module-locators'\nimport type { ModuleEntry, PackageResolver } from './resolver'\nimport { readEnabledModules } from './modules-config'\n\nfunction readJson(filePath: string): Record<string, unknown> {\n  try {\n    const value: unknown = JSON.parse(fs.readFileSync(filePath, 'utf8'))\n    return value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : {}\n  } catch {\n    return {}\n  }\n}\n\nfunction readMetadataLocator(moduleBase: string): string | undefined {\n  const indexPath = ['index.ts', 'index.js'].map((name) => path.join(moduleBase, name)).find((candidate) => fs.existsSync(candidate))\n  if (!indexPath) return undefined\n  const source = ts.createSourceFile(indexPath, fs.readFileSync(indexPath, 'utf8'), ts.ScriptTarget.Latest, true)\n  let locator: string | undefined\n  function visit(node: ts.Node): void {\n    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.name.text === 'metadata' && node.initializer) {\n      let initializer = node.initializer\n      while (ts.isAsExpression(initializer) || ts.isSatisfiesExpression(initializer) || ts.isParenthesizedExpression(initializer)) initializer = initializer.expression\n      if (ts.isObjectLiteralExpression(initializer)) {\n        for (const property of initializer.properties) {\n          if (ts.isPropertyAssignment(property) && (ts.isIdentifier(property.name) || ts.isStringLiteralLike(property.name)) && property.name.text === 'locator' && ts.isStringLiteralLike(property.initializer)) locator = property.initializer.text\n        }\n      }\n    }\n    ts.forEachChild(node, visit)\n  }\n  visit(source)\n  return locator\n}\n\nfunction sourceLocator(value: unknown): string | undefined {\n  if (typeof value !== 'string') return undefined\n  const locator = normalizeModuleLocator(value)\n  return locator?.startsWith('npm:') || locator?.startsWith('github:') ? locator : undefined\n}\n\nfunction installedDependencyLocator(specifier: unknown, canonicalName: string | undefined): string | undefined {\n  if (typeof specifier !== 'string') return undefined\n  if (/^(?:github:|github\\.com\\/|(?:git\\+)?https?:\\/\\/github\\.com\\/|git@github\\.com:|(?:git\\+)?ssh:\\/\\/|[a-z0-9][a-z0-9-]*\\/[a-z0-9._-]+(?:[#@]|$))/i.test(specifier)) {\n    const locator = sourceLocator(specifier)\n    return locator?.startsWith('github:') ? locator : undefined\n  }\n  if (specifier.startsWith('npm:')) {\n    const aliasTarget = specifier.match(/^npm:(@[^/]+\\/[^@]+|[^@]+)(?:@.+)?$/)?.[1]\n    return aliasTarget ? sourceLocator(`npm:${aliasTarget}`) : undefined\n  }\n  if (!canonicalName || /^(?:[a-z][a-z0-9+.-]*:|[./]|https?:)/i.test(specifier)) return undefined\n  return sourceLocator(`npm:${canonicalName}`)\n}\n\nfunction assertDeclaredIdentity(entry: ModuleEntry, observedLocator: string | undefined, canonicalName: string | undefined): void {\n  const binding = entry.from ?? '@open-mercato/core'\n  if (entry.packageName && canonicalName && entry.packageName !== canonicalName) {\n    throw new Error(`[modules] Cannot resolve module '${entry.id}' from binding '${binding}': declared package '${entry.packageName}' disagrees with installed package '${canonicalName}'. Restore the intended binding or correct src/modules.ts, then regenerate.`)\n  }\n  const declaredLocator = sourceLocator(entry.locator)\n  if (declaredLocator && observedLocator && declaredLocator !== observedLocator) {\n    throw new Error(`[modules] Cannot resolve module '${entry.id}' from binding '${binding}': declared origin '${declaredLocator}' disagrees with observed origin '${observedLocator}'. Disable the old provider before replacing it, then regenerate.`)\n  }\n  if (declaredLocator?.startsWith('npm:') && canonicalName && declaredLocator !== sourceLocator(`npm:${canonicalName}`)) {\n    throw new Error(`[modules] Cannot resolve module '${entry.id}' from binding '${binding}': declared origin '${declaredLocator}' disagrees with installed package '${canonicalName}'. Correct src/modules.ts to select the intended provider, then regenerate.`)\n  }\n}\n\nfunction readModuleLocators(\n  entry: ModuleEntry,\n  resolver: PackageResolver,\n  appManifest: Record<string, unknown>,\n  packageManifests: Map<string, Record<string, unknown>>,\n): string[] {\n  const from = entry.from ?? '@open-mercato/core'\n  if (from === '@app') {\n    const retainedLocator = sourceLocator(entry.locator ?? readMetadataLocator(resolver.getModulePaths(entry).appBase))\n    assertDeclaredIdentity(entry, retainedLocator, entry.packageName)\n    return retainedLocator ? [retainedLocator] : []\n  }\n\n  let manifest = packageManifests.get(from)\n  if (!manifest) {\n    manifest = readJson(path.join(resolver.getPackageRoot(from), 'package.json'))\n    packageManifests.set(from, manifest)\n  }\n  const canonicalName = typeof manifest.name === 'string' ? manifest.name : undefined\n  const observedLocators = new Set<string>()\n  for (const section of ['dependencies', 'devDependencies', 'optionalDependencies']) {\n    const dependencies = appManifest[section]\n    if (!dependencies || typeof dependencies !== 'object' || Array.isArray(dependencies)) continue\n    const specifier = (dependencies as Record<string, unknown>)[from]\n    const locator = installedDependencyLocator(specifier, canonicalName)\n    if (locator?.startsWith('npm:') && canonicalName !== from && typeof specifier === 'string' && !specifier.startsWith('npm:')) {\n      throw new Error(`[modules] Cannot resolve module '${entry.id}' from binding '${from}': installed package '${canonicalName}' does not match the dependency binding. Restore the intended package or declare an explicit npm alias, then regenerate.`)\n    }\n    if (locator) observedLocators.add(locator)\n  }\n  if (observedLocators.size > 1) {\n    throw new Error(`[modules] Cannot resolve module '${entry.id}' from binding '${from}': dependency sections declare conflicting origins. Keep one provider for this binding in package.json, then regenerate.`)\n  }\n  const observedLocator = [...observedLocators][0]\n  if (observedLocator?.startsWith('npm:') && canonicalName && observedLocator !== sourceLocator(`npm:${canonicalName}`)) {\n    throw new Error(`[modules] Cannot resolve module '${entry.id}' from binding '${from}': dependency origin '${observedLocator}' disagrees with installed package '${canonicalName}'. Restore the intended package through the package manager, then regenerate.`)\n  }\n  assertDeclaredIdentity(entry, observedLocator, canonicalName)\n  const locator = observedLocator ?? sourceLocator(entry.locator)\n  return locator ? [locator] : []\n}\n\nexport function getModuleLocators(entry: ModuleEntry, resolver: PackageResolver): string[] {\n  return readModuleLocators(entry, resolver, readJson(path.join(resolver.getAppDir(), 'package.json')), new Map())\n}\n\nexport function assertUniqueEnabledModuleIds(enabledModules: readonly ModuleEntry[], resolver: PackageResolver): void {\n  const byId = new Map<string, ModuleEntry>()\n  for (const entry of enabledModules) {\n    const existing = byId.get(entry.id)\n    if (existing) {\n      const describe = (provider: ModuleEntry): string => {\n        const binding = provider.from ?? '@open-mercato/core'\n        const source = sourceLocator(provider.locator)\n        return binding === '@app'\n          ? `@app (${resolver.getModulePaths(provider).appBase})${source ? `, origin ${source}` : ''}`\n          : `binding '${binding}'${source ? `, origin ${source}` : ''}`\n      }\n      throw new Error(`[generate] Duplicate enabled module ID '${entry.id}': ${describe(existing)} and ${describe(entry)}. Keep one provider in src/modules.ts, then run yarn mercato generate. Installing under another package alias does not allow both module IDs to run.`)\n    }\n    byId.set(entry.id, entry)\n  }\n}\n\nexport function getEnabledModuleIdentities(resolver: PackageResolver, enabledModules: readonly ModuleEntry[] = resolver.loadEnabledModules()): ModuleIdentity[] {\n  const modulesPath = typeof resolver.getModulesConfigPath === 'function'\n    ? resolver.getModulesConfigPath()\n    : path.join(resolver.getAppDir(), 'src', 'modules.ts')\n  if (fs.existsSync(modulesPath)) assertUniqueEnabledModuleIds(readEnabledModules(modulesPath), resolver)\n  assertUniqueEnabledModuleIds(enabledModules, resolver)\n  const appManifest = readJson(path.join(resolver.getAppDir(), 'package.json'))\n  const packageManifests = new Map<string, Record<string, unknown>>()\n  return enabledModules.map((entry) => ({ id: entry.id, locators: readModuleLocators(entry, resolver, appManifest, packageManifests) }))\n}\n"],
+  "mappings": "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",
+  "names": ["locator"]
+}

package/dist/lib/module-inspection.js

@@ -0,0 +1,124 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import spawn from "cross-spawn";
+import { assertModulePackageExports, isModulePackageExportError } from "./module-package.js";
+function record(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function inspectFiles(manifest, packageName, files, requiredModuleIds, readSource) {
+  if (manifest.name !== packageName) throw new Error(`Inspected package does not match "${packageName}". No package was installed.`);
+  const moduleIds = [...new Set(files.flatMap((file) => {
+    const match = /^src\/modules\/([a-z0-9]+(?:_[a-z0-9]+)*)\/index\.ts$/.exec(file);
+    return match && files.includes(`dist/modules/${match[1]}/index.js`) ? [match[1]] : [];
+  }))];
+  const checkedModuleIds = requiredModuleIds.length ? requiredModuleIds : moduleIds.length === 1 ? moduleIds : [];
+  for (const moduleId of checkedModuleIds) {
+    if (!moduleIds.includes(moduleId)) throw new Error(`Package "${packageName}" is missing source or compiled descriptors for "${moduleId}". No package was installed.`);
+    assertModulePackageExports(manifest, packageName, moduleId, files, readSource);
+  }
+  if (moduleIds.length === 0) throw new Error(`Package "${packageName}" is missing source or compiled module descriptors. Build the package before retrying. No package was installed.`);
+  return { moduleIds, ...typeof manifest.version === "string" ? { version: manifest.version } : {} };
+}
+function inspectArchive(archive, packageName, requiredModuleIds) {
+  const manifest = record(JSON.parse(execFileSync("tar", ["-xOf", archive, "package/package.json"], { encoding: "utf8", timeout: 15e3 })));
+  const files = execFileSync("tar", ["-tf", archive], { encoding: "utf8", timeout: 15e3, maxBuffer: 16 * 1024 * 1024 }).split("\n").filter((file) => file.startsWith("package/")).map((file) => file.slice("package/".length));
+  return inspectFiles(manifest, packageName, files, requiredModuleIds, (relativePath) => execFileSync("tar", ["-xOf", archive, `package/${relativePath}`], { encoding: "utf8", timeout: 15e3, maxBuffer: 1024 * 1024 }));
+}
+function packageFiles(packageRoot, relativeDir = "") {
+  return fs.readdirSync(path.join(packageRoot, relativeDir), { withFileTypes: true }).flatMap((entry) => {
+    if (entry.name === "node_modules" || entry.name.startsWith(".")) return [];
+    const relativePath = path.posix.join(relativeDir, entry.name);
+    return entry.isDirectory() ? packageFiles(packageRoot, relativePath) : entry.isFile() ? [relativePath] : [];
+  });
+}
+function isModernYarnProject(appDir) {
+  let directory = appDir;
+  while (true) {
+    if (fs.existsSync(path.join(directory, ".yarnrc.yml"))) return true;
+    const manifestPath = path.join(directory, "package.json");
+    if (fs.existsSync(manifestPath)) {
+      const manifest = record(JSON.parse(fs.readFileSync(manifestPath, "utf8")));
+      if (typeof manifest.packageManager === "string" && /^yarn@(?:[2-9]|[1-9][0-9]+)\./.test(manifest.packageManager)) return true;
+    }
+    const parent = path.dirname(directory);
+    if (parent === directory) return false;
+    directory = parent;
+  }
+}
+function yarnNpmConfiguration(appDir, packageName, temporaryDir) {
+  if (!isModernYarnProject(appDir)) return [];
+  const settings = /* @__PURE__ */ new Map();
+  for (const setting of ["npmRegistryServer", "npmScopes", "npmRegistries", "npmAuthToken", "npmAuthIdent"]) {
+    const result = spawn.sync(process.platform === "win32" ? "yarn.cmd" : "yarn", ["config", "get", setting, "--json", "--no-redacted"], {
+      cwd: appDir,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: 15e3
+    });
+    if (result.error || result.status !== 0) throw new Error("Cannot inspect project package registry configuration");
+    settings.set(setting, JSON.parse(result.stdout));
+  }
+  const scope = packageName.startsWith("@") ? packageName.slice(1).split("/")[0] : void 0;
+  const scopeSettings = scope ? record(record(settings.get("npmScopes"))[scope]) : {};
+  const registry = typeof scopeSettings.npmRegistryServer === "string" ? scopeSettings.npmRegistryServer : settings.get("npmRegistryServer");
+  if (typeof registry !== "string") throw new Error("Missing project package registry");
+  const registryUrl = new URL(registry);
+  if (!["http:", "https:"].includes(registryUrl.protocol) || registryUrl.username || registryUrl.password) throw new Error("Invalid project package registry");
+  const registryKey = `//${registryUrl.host}${registryUrl.pathname}`.replace(/\/$/, "");
+  const registries = record(settings.get("npmRegistries"));
+  const registrySettings = record(registries[registry.replace(/\/$/, "")] ?? registries[registryKey] ?? registries[`${registryKey}/`]);
+  const auth = scopeSettings.npmAuthToken || scopeSettings.npmAuthIdent ? scopeSettings : registrySettings.npmAuthToken || registrySettings.npmAuthIdent ? registrySettings : { npmAuthToken: settings.get("npmAuthToken"), npmAuthIdent: settings.get("npmAuthIdent") };
+  const userConfig = process.env.NPM_CONFIG_USERCONFIG ?? process.env.npm_config_userconfig ?? path.join(os.homedir(), ".npmrc");
+  const existingConfig = fs.existsSync(userConfig) ? fs.readFileSync(userConfig, "utf8") : "";
+  const lines = [existingConfig, `registry=${JSON.stringify(registry)}`];
+  if (scope) lines.push(`@${scope}:registry=${JSON.stringify(registry)}`);
+  if (typeof auth.npmAuthToken === "string" && auth.npmAuthToken) lines.push(`${registryKey}/:_authToken=${JSON.stringify(auth.npmAuthToken)}`);
+  else if (typeof auth.npmAuthIdent === "string" && auth.npmAuthIdent) lines.push(`${registryKey}/:_auth=${Buffer.from(auth.npmAuthIdent).toString("base64")}`);
+  const configPath = path.join(temporaryDir, "inspection.npmrc");
+  fs.writeFileSync(configPath, `${lines.join("\n")}
+`, { mode: 384 });
+  return ["--userconfig", configPath, "--registry", registry, ...scope ? [`--@${scope}:registry=${registry}`] : []];
+}
+function inspectNpmModuleTarget(packageSpec, packageName, appDir, requiredModuleIds = []) {
+  const filePrefix = `${packageName}@file:`;
+  if (packageSpec.startsWith(filePrefix)) {
+    const packageRoot = path.resolve(appDir, packageSpec.slice(filePrefix.length));
+    if (fs.statSync(packageRoot).isFile()) return { packageName, packageSpec, ...inspectArchive(packageRoot, packageName, requiredModuleIds) };
+    const manifest = record(JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8")));
+    const inspected = inspectFiles(manifest, packageName, packageFiles(packageRoot), requiredModuleIds, (relativePath) => fs.readFileSync(path.join(packageRoot, relativePath), "utf8"));
+    return { packageName, packageSpec, ...inspected };
+  }
+  const temporaryDir = fs.mkdtempSync(path.join(os.tmpdir(), "mercato-module-inspection-"));
+  let inspectionStep = "read the project registry configuration";
+  try {
+    const configurationArgs = yarnNpmConfiguration(appDir, packageName, temporaryDir);
+    inspectionStep = "fetch the exact npm artifact";
+    const packedProcess = spawn.sync(process.platform === "win32" ? "npm.cmd" : "npm", ["pack", packageSpec, "--ignore-scripts", "--json", "--pack-destination", temporaryDir, ...configurationArgs], {
+      cwd: appDir,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: 6e4,
+      maxBuffer: 16 * 1024 * 1024
+    });
+    if (packedProcess.error || packedProcess.status !== 0) throw new Error("Artifact inspection failed");
+    inspectionStep = "parse the npm artifact response";
+    const packages = JSON.parse(packedProcess.stdout);
+    const packed = record(Array.isArray(packages) ? packages[0] : void 0);
+    if (packed.name !== packageName || typeof packed.version !== "string" || !/^[0-9A-Za-z.+-]+$/.test(packed.version) || typeof packed.filename !== "string" || path.basename(packed.filename) !== packed.filename) throw new Error("Invalid packed manifest");
+    inspectionStep = "validate the packed module artifact";
+    const inspected = inspectArchive(path.join(temporaryDir, packed.filename), packageName, requiredModuleIds);
+    if (inspected.version !== packed.version) throw new Error("Packed artifact version disagrees with resolution");
+    return { packageName, packageSpec, ...inspected, locator: `npm:${packageName}` };
+  } catch (error) {
+    const safeDetail = isModulePackageExportError(error) && error instanceof Error ? ` ${error.message}` : "";
+    throw new Error(`Cannot inspect the exact module artifact for "${packageName}" while trying to ${inspectionStep}.${safeDetail} Check project registry credentials, package access and shipped src/dist module descriptors before retrying. No package was installed.`);
+  } finally {
+    fs.rmSync(temporaryDir, { recursive: true, force: true });
+  }
+}
+export {
+  inspectNpmModuleTarget
+};
+//# sourceMappingURL=module-inspection.js.map

package/dist/lib/module-inspection.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/lib/module-inspection.ts"],
+  "sourcesContent": ["import fs from 'node:fs'\nimport os from 'node:os'\nimport path from 'node:path'\nimport { execFileSync } from 'node:child_process'\nimport spawn from 'cross-spawn'\nimport { assertModulePackageExports, isModulePackageExportError } from './module-package'\n\nexport type InspectedModuleTarget = {\n  packageName: string\n  packageSpec: string\n  moduleIds: string[]\n  locator?: string\n  version?: string\n}\n\ntype ArtifactInspection = { moduleIds: string[]; version?: string }\n\nfunction record(value: unknown): Record<string, unknown> {\n  return value !== null && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : {}\n}\n\nfunction inspectFiles(manifest: Record<string, unknown>, packageName: string, files: string[], requiredModuleIds: readonly string[], readSource: (relativePath: string) => string): ArtifactInspection {\n  if (manifest.name !== packageName) throw new Error(`Inspected package does not match \"${packageName}\". No package was installed.`)\n  const moduleIds = [...new Set(files.flatMap((file) => {\n    const match = /^src\\/modules\\/([a-z0-9]+(?:_[a-z0-9]+)*)\\/index\\.ts$/.exec(file)\n    return match && files.includes(`dist/modules/${match[1]}/index.js`) ? [match[1]] : []\n  }))]\n  const checkedModuleIds = requiredModuleIds.length ? requiredModuleIds : moduleIds.length === 1 ? moduleIds : []\n  for (const moduleId of checkedModuleIds) {\n    if (!moduleIds.includes(moduleId)) throw new Error(`Package \"${packageName}\" is missing source or compiled descriptors for \"${moduleId}\". No package was installed.`)\n    assertModulePackageExports(manifest, packageName, moduleId, files, readSource)\n  }\n  if (moduleIds.length === 0) throw new Error(`Package \"${packageName}\" is missing source or compiled module descriptors. Build the package before retrying. No package was installed.`)\n  return { moduleIds, ...(typeof manifest.version === 'string' ? { version: manifest.version } : {}) }\n}\n\nfunction inspectArchive(archive: string, packageName: string, requiredModuleIds: readonly string[]): ArtifactInspection {\n  const manifest = record(JSON.parse(execFileSync('tar', ['-xOf', archive, 'package/package.json'], { encoding: 'utf8', timeout: 15_000 })))\n  const files = execFileSync('tar', ['-tf', archive], { encoding: 'utf8', timeout: 15_000, maxBuffer: 16 * 1024 * 1024 }).split('\\n').filter((file) => file.startsWith('package/')).map((file) => file.slice('package/'.length))\n  return inspectFiles(manifest, packageName, files, requiredModuleIds, (relativePath) => execFileSync('tar', ['-xOf', archive, `package/${relativePath}`], { encoding: 'utf8', timeout: 15_000, maxBuffer: 1024 * 1024 }))\n}\n\nfunction packageFiles(packageRoot: string, relativeDir = ''): string[] {\n  return fs.readdirSync(path.join(packageRoot, relativeDir), { withFileTypes: true }).flatMap((entry) => {\n    if (entry.name === 'node_modules' || entry.name.startsWith('.')) return []\n    const relativePath = path.posix.join(relativeDir, entry.name)\n    return entry.isDirectory() ? packageFiles(packageRoot, relativePath) : entry.isFile() ? [relativePath] : []\n  })\n}\n\nfunction isModernYarnProject(appDir: string): boolean {\n  let directory = appDir\n  while (true) {\n    if (fs.existsSync(path.join(directory, '.yarnrc.yml'))) return true\n    const manifestPath = path.join(directory, 'package.json')\n    if (fs.existsSync(manifestPath)) {\n      const manifest = record(JSON.parse(fs.readFileSync(manifestPath, 'utf8')))\n      if (typeof manifest.packageManager === 'string' && /^yarn@(?:[2-9]|[1-9][0-9]+)\\./.test(manifest.packageManager)) return true\n    }\n    const parent = path.dirname(directory)\n    if (parent === directory) return false\n    directory = parent\n  }\n}\n\nfunction yarnNpmConfiguration(appDir: string, packageName: string, temporaryDir: string): string[] {\n  if (!isModernYarnProject(appDir)) return []\n  const settings = new Map<string, unknown>()\n  for (const setting of ['npmRegistryServer', 'npmScopes', 'npmRegistries', 'npmAuthToken', 'npmAuthIdent']) {\n    const result = spawn.sync(process.platform === 'win32' ? 'yarn.cmd' : 'yarn', ['config', 'get', setting, '--json', '--no-redacted'], {\n      cwd: appDir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 15_000,\n    })\n    if (result.error || result.status !== 0) throw new Error('Cannot inspect project package registry configuration')\n    settings.set(setting, JSON.parse(result.stdout))\n  }\n  const scope = packageName.startsWith('@') ? packageName.slice(1).split('/')[0] : undefined\n  const scopeSettings = scope ? record(record(settings.get('npmScopes'))[scope]) : {}\n  const registry = typeof scopeSettings.npmRegistryServer === 'string' ? scopeSettings.npmRegistryServer : settings.get('npmRegistryServer')\n  if (typeof registry !== 'string') throw new Error('Missing project package registry')\n  const registryUrl = new URL(registry)\n  if (!['http:', 'https:'].includes(registryUrl.protocol) || registryUrl.username || registryUrl.password) throw new Error('Invalid project package registry')\n  const registryKey = `//${registryUrl.host}${registryUrl.pathname}`.replace(/\\/$/, '')\n  const registries = record(settings.get('npmRegistries'))\n  const registrySettings = record(registries[registry.replace(/\\/$/, '')] ?? registries[registryKey] ?? registries[`${registryKey}/`])\n  const auth = scopeSettings.npmAuthToken || scopeSettings.npmAuthIdent ? scopeSettings\n    : registrySettings.npmAuthToken || registrySettings.npmAuthIdent ? registrySettings\n      : { npmAuthToken: settings.get('npmAuthToken'), npmAuthIdent: settings.get('npmAuthIdent') }\n  const userConfig = process.env.NPM_CONFIG_USERCONFIG ?? process.env.npm_config_userconfig ?? path.join(os.homedir(), '.npmrc')\n  const existingConfig = fs.existsSync(userConfig) ? fs.readFileSync(userConfig, 'utf8') : ''\n  const lines = [existingConfig, `registry=${JSON.stringify(registry)}`]\n  if (scope) lines.push(`@${scope}:registry=${JSON.stringify(registry)}`)\n  if (typeof auth.npmAuthToken === 'string' && auth.npmAuthToken) lines.push(`${registryKey}/:_authToken=${JSON.stringify(auth.npmAuthToken)}`)\n  else if (typeof auth.npmAuthIdent === 'string' && auth.npmAuthIdent) lines.push(`${registryKey}/:_auth=${Buffer.from(auth.npmAuthIdent).toString('base64')}`)\n  const configPath = path.join(temporaryDir, 'inspection.npmrc')\n  fs.writeFileSync(configPath, `${lines.join('\\n')}\\n`, { mode: 0o600 })\n  return ['--userconfig', configPath, '--registry', registry, ...(scope ? [`--@${scope}:registry=${registry}`] : [])]\n}\n\nexport function inspectNpmModuleTarget(packageSpec: string, packageName: string, appDir: string, requiredModuleIds: readonly string[] = []): InspectedModuleTarget {\n  const filePrefix = `${packageName}@file:`\n  if (packageSpec.startsWith(filePrefix)) {\n    const packageRoot = path.resolve(appDir, packageSpec.slice(filePrefix.length))\n    if (fs.statSync(packageRoot).isFile()) return { packageName, packageSpec, ...inspectArchive(packageRoot, packageName, requiredModuleIds) }\n    const manifest = record(JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8')))\n    const inspected = inspectFiles(manifest, packageName, packageFiles(packageRoot), requiredModuleIds, (relativePath) => fs.readFileSync(path.join(packageRoot, relativePath), 'utf8'))\n    return { packageName, packageSpec, ...inspected }\n  }\n\n  const temporaryDir = fs.mkdtempSync(path.join(os.tmpdir(), 'mercato-module-inspection-'))\n  let inspectionStep = 'read the project registry configuration'\n  try {\n    const configurationArgs = yarnNpmConfiguration(appDir, packageName, temporaryDir)\n    inspectionStep = 'fetch the exact npm artifact'\n    const packedProcess = spawn.sync(process.platform === 'win32' ? 'npm.cmd' : 'npm', ['pack', packageSpec, '--ignore-scripts', '--json', '--pack-destination', temporaryDir, ...configurationArgs], {\n      cwd: appDir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 60_000, maxBuffer: 16 * 1024 * 1024,\n    })\n    if (packedProcess.error || packedProcess.status !== 0) throw new Error('Artifact inspection failed')\n    inspectionStep = 'parse the npm artifact response'\n    const packages: unknown = JSON.parse(packedProcess.stdout)\n    const packed = record(Array.isArray(packages) ? packages[0] : undefined)\n    if (packed.name !== packageName || typeof packed.version !== 'string' || !/^[0-9A-Za-z.+-]+$/.test(packed.version)\n      || typeof packed.filename !== 'string' || path.basename(packed.filename) !== packed.filename) throw new Error('Invalid packed manifest')\n    inspectionStep = 'validate the packed module artifact'\n    const inspected = inspectArchive(path.join(temporaryDir, packed.filename), packageName, requiredModuleIds)\n    if (inspected.version !== packed.version) throw new Error('Packed artifact version disagrees with resolution')\n    return { packageName, packageSpec, ...inspected, locator: `npm:${packageName}` }\n  } catch (error) {\n    const safeDetail = isModulePackageExportError(error) && error instanceof Error ? ` ${error.message}` : ''\n    throw new Error(`Cannot inspect the exact module artifact for \"${packageName}\" while trying to ${inspectionStep}.${safeDetail} Check project registry credentials, package access and shipped src/dist module descriptors before retrying. No package was installed.`)\n  } finally {\n    fs.rmSync(temporaryDir, { recursive: true, force: true })\n  }\n}\n"],
+  "mappings": "AAAA,OAAO,QAAQ;AACf,OAAO,QAAQ;AACf,OAAO,UAAU;AACjB,SAAS,oBAAoB;AAC7B,OAAO,WAAW;AAClB,SAAS,4BAA4B,kCAAkC;AAYvE,SAAS,OAAO,OAAyC;AACvD,SAAO,UAAU,QAAQ,OAAO,UAAU,YAAY,CAAC,MAAM,QAAQ,KAAK,IAAI,QAAmC,CAAC;AACpH;AAEA,SAAS,aAAa,UAAmC,aAAqB,OAAiB,mBAAsC,YAAkE;AACrM,MAAI,SAAS,SAAS,YAAa,OAAM,IAAI,MAAM,qCAAqC,WAAW,8BAA8B;AACjI,QAAM,YAAY,CAAC,GAAG,IAAI,IAAI,MAAM,QAAQ,CAAC,SAAS;AACpD,UAAM,QAAQ,wDAAwD,KAAK,IAAI;AAC/E,WAAO,SAAS,MAAM,SAAS,gBAAgB,MAAM,CAAC,CAAC,WAAW,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC;AAAA,EACtF,CAAC,CAAC,CAAC;AACH,QAAM,mBAAmB,kBAAkB,SAAS,oBAAoB,UAAU,WAAW,IAAI,YAAY,CAAC;AAC9G,aAAW,YAAY,kBAAkB;AACvC,QAAI,CAAC,UAAU,SAAS,QAAQ,EAAG,OAAM,IAAI,MAAM,YAAY,WAAW,oDAAoD,QAAQ,8BAA8B;AACpK,+BAA2B,UAAU,aAAa,UAAU,OAAO,UAAU;AAAA,EAC/E;AACA,MAAI,UAAU,WAAW,EAAG,OAAM,IAAI,MAAM,YAAY,WAAW,kHAAkH;AACrL,SAAO,EAAE,WAAW,GAAI,OAAO,SAAS,YAAY,WAAW,EAAE,SAAS,SAAS,QAAQ,IAAI,CAAC,EAAG;AACrG;AAEA,SAAS,eAAe,SAAiB,aAAqB,mBAA0D;AACtH,QAAM,WAAW,OAAO,KAAK,MAAM,aAAa,OAAO,CAAC,QAAQ,SAAS,sBAAsB,GAAG,EAAE,UAAU,QAAQ,SAAS,KAAO,CAAC,CAAC,CAAC;AACzI,QAAM,QAAQ,aAAa,OAAO,CAAC,OAAO,OAAO,GAAG,EAAE,UAAU,QAAQ,SAAS,MAAQ,WAAW,KAAK,OAAO,KAAK,CAAC,EAAE,MAAM,IAAI,EAAE,OAAO,CAAC,SAAS,KAAK,WAAW,UAAU,CAAC,EAAE,IAAI,CAAC,SAAS,KAAK,MAAM,WAAW,MAAM,CAAC;AAC7N,SAAO,aAAa,UAAU,aAAa,OAAO,mBAAmB,CAAC,iBAAiB,aAAa,OAAO,CAAC,QAAQ,SAAS,WAAW,YAAY,EAAE,GAAG,EAAE,UAAU,QAAQ,SAAS,MAAQ,WAAW,OAAO,KAAK,CAAC,CAAC;AACzN;AAEA,SAAS,aAAa,aAAqB,cAAc,IAAc;AACrE,SAAO,GAAG,YAAY,KAAK,KAAK,aAAa,WAAW,GAAG,EAAE,eAAe,KAAK,CAAC,EAAE,QAAQ,CAAC,UAAU;AACrG,QAAI,MAAM,SAAS,kBAAkB,MAAM,KAAK,WAAW,GAAG,EAAG,QAAO,CAAC;AACzE,UAAM,eAAe,KAAK,MAAM,KAAK,aAAa,MAAM,IAAI;AAC5D,WAAO,MAAM,YAAY,IAAI,aAAa,aAAa,YAAY,IAAI,MAAM,OAAO,IAAI,CAAC,YAAY,IAAI,CAAC;AAAA,EAC5G,CAAC;AACH;AAEA,SAAS,oBAAoB,QAAyB;AACpD,MAAI,YAAY;AAChB,SAAO,MAAM;AACX,QAAI,GAAG,WAAW,KAAK,KAAK,WAAW,aAAa,CAAC,EAAG,QAAO;AAC/D,UAAM,eAAe,KAAK,KAAK,WAAW,cAAc;AACxD,QAAI,GAAG,WAAW,YAAY,GAAG;AAC/B,YAAM,WAAW,OAAO,KAAK,MAAM,GAAG,aAAa,cAAc,MAAM,CAAC,CAAC;AACzE,UAAI,OAAO,SAAS,mBAAmB,YAAY,gCAAgC,KAAK,SAAS,cAAc,EAAG,QAAO;AAAA,IAC3H;AACA,UAAM,SAAS,KAAK,QAAQ,SAAS;AACrC,QAAI,WAAW,UAAW,QAAO;AACjC,gBAAY;AAAA,EACd;AACF;AAEA,SAAS,qBAAqB,QAAgB,aAAqB,cAAgC;AACjG,MAAI,CAAC,oBAAoB,MAAM,EAAG,QAAO,CAAC;AAC1C,QAAM,WAAW,oBAAI,IAAqB;AAC1C,aAAW,WAAW,CAAC,qBAAqB,aAAa,iBAAiB,gBAAgB,cAAc,GAAG;AACzG,UAAM,SAAS,MAAM,KAAK,QAAQ,aAAa,UAAU,aAAa,QAAQ,CAAC,UAAU,OAAO,SAAS,UAAU,eAAe,GAAG;AAAA,MACnI,KAAK;AAAA,MAAQ,UAAU;AAAA,MAAQ,OAAO,CAAC,UAAU,QAAQ,MAAM;AAAA,MAAG,SAAS;AAAA,IAC7E,CAAC;AACD,QAAI,OAAO,SAAS,OAAO,WAAW,EAAG,OAAM,IAAI,MAAM,uDAAuD;AAChH,aAAS,IAAI,SAAS,KAAK,MAAM,OAAO,MAAM,CAAC;AAAA,EACjD;AACA,QAAM,QAAQ,YAAY,WAAW,GAAG,IAAI,YAAY,MAAM,CAAC,EAAE,MAAM,GAAG,EAAE,CAAC,IAAI;AACjF,QAAM,gBAAgB,QAAQ,OAAO,OAAO,SAAS,IAAI,WAAW,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC;AAClF,QAAM,WAAW,OAAO,cAAc,sBAAsB,WAAW,cAAc,oBAAoB,SAAS,IAAI,mBAAmB;AACzI,MAAI,OAAO,aAAa,SAAU,OAAM,IAAI,MAAM,kCAAkC;AACpF,QAAM,cAAc,IAAI,IAAI,QAAQ;AACpC,MAAI,CAAC,CAAC,SAAS,QAAQ,EAAE,SAAS,YAAY,QAAQ,KAAK,YAAY,YAAY,YAAY,SAAU,OAAM,IAAI,MAAM,kCAAkC;AAC3J,QAAM,cAAc,KAAK,YAAY,IAAI,GAAG,YAAY,QAAQ,GAAG,QAAQ,OAAO,EAAE;AACpF,QAAM,aAAa,OAAO,SAAS,IAAI,eAAe,CAAC;AACvD,QAAM,mBAAmB,OAAO,WAAW,SAAS,QAAQ,OAAO,EAAE,CAAC,KAAK,WAAW,WAAW,KAAK,WAAW,GAAG,WAAW,GAAG,CAAC;AACnI,QAAM,OAAO,cAAc,gBAAgB,cAAc,eAAe,gBACpE,iBAAiB,gBAAgB,iBAAiB,eAAe,mBAC/D,EAAE,cAAc,SAAS,IAAI,cAAc,GAAG,cAAc,SAAS,IAAI,cAAc,EAAE;AAC/F,QAAM,aAAa,QAAQ,IAAI,yBAAyB,QAAQ,IAAI,yBAAyB,KAAK,KAAK,GAAG,QAAQ,GAAG,QAAQ;AAC7H,QAAM,iBAAiB,GAAG,WAAW,UAAU,IAAI,GAAG,aAAa,YAAY,MAAM,IAAI;AACzF,QAAM,QAAQ,CAAC,gBAAgB,YAAY,KAAK,UAAU,QAAQ,CAAC,EAAE;AACrE,MAAI,MAAO,OAAM,KAAK,IAAI,KAAK,aAAa,KAAK,UAAU,QAAQ,CAAC,EAAE;AACtE,MAAI,OAAO,KAAK,iBAAiB,YAAY,KAAK,aAAc,OAAM,KAAK,GAAG,WAAW,gBAAgB,KAAK,UAAU,KAAK,YAAY,CAAC,EAAE;AAAA,WACnI,OAAO,KAAK,iBAAiB,YAAY,KAAK,aAAc,OAAM,KAAK,GAAG,WAAW,WAAW,OAAO,KAAK,KAAK,YAAY,EAAE,SAAS,QAAQ,CAAC,EAAE;AAC5J,QAAM,aAAa,KAAK,KAAK,cAAc,kBAAkB;AAC7D,KAAG,cAAc,YAAY,GAAG,MAAM,KAAK,IAAI,CAAC;AAAA,GAAM,EAAE,MAAM,IAAM,CAAC;AACrE,SAAO,CAAC,gBAAgB,YAAY,cAAc,UAAU,GAAI,QAAQ,CAAC,MAAM,KAAK,aAAa,QAAQ,EAAE,IAAI,CAAC,CAAE;AACpH;AAEO,SAAS,uBAAuB,aAAqB,aAAqB,QAAgB,oBAAuC,CAAC,GAA0B;AACjK,QAAM,aAAa,GAAG,WAAW;AACjC,MAAI,YAAY,WAAW,UAAU,GAAG;AACtC,UAAM,cAAc,KAAK,QAAQ,QAAQ,YAAY,MAAM,WAAW,MAAM,CAAC;AAC7E,QAAI,GAAG,SAAS,WAAW,EAAE,OAAO,EAAG,QAAO,EAAE,aAAa,aAAa,GAAG,eAAe,aAAa,aAAa,iBAAiB,EAAE;AACzI,UAAM,WAAW,OAAO,KAAK,MAAM,GAAG,aAAa,KAAK,KAAK,aAAa,cAAc,GAAG,MAAM,CAAC,CAAC;AACnG,UAAM,YAAY,aAAa,UAAU,aAAa,aAAa,WAAW,GAAG,mBAAmB,CAAC,iBAAiB,GAAG,aAAa,KAAK,KAAK,aAAa,YAAY,GAAG,MAAM,CAAC;AACnL,WAAO,EAAE,aAAa,aAAa,GAAG,UAAU;AAAA,EAClD;AAEA,QAAM,eAAe,GAAG,YAAY,KAAK,KAAK,GAAG,OAAO,GAAG,4BAA4B,CAAC;AACxF,MAAI,iBAAiB;AACrB,MAAI;AACF,UAAM,oBAAoB,qBAAqB,QAAQ,aAAa,YAAY;AAChF,qBAAiB;AACjB,UAAM,gBAAgB,MAAM,KAAK,QAAQ,aAAa,UAAU,YAAY,OAAO,CAAC,QAAQ,aAAa,oBAAoB,UAAU,sBAAsB,cAAc,GAAG,iBAAiB,GAAG;AAAA,MAChM,KAAK;AAAA,MAAQ,UAAU;AAAA,MAAQ,OAAO,CAAC,UAAU,QAAQ,MAAM;AAAA,MAAG,SAAS;AAAA,MAAQ,WAAW,KAAK,OAAO;AAAA,IAC5G,CAAC;AACD,QAAI,cAAc,SAAS,cAAc,WAAW,EAAG,OAAM,IAAI,MAAM,4BAA4B;AACnG,qBAAiB;AACjB,UAAM,WAAoB,KAAK,MAAM,cAAc,MAAM;AACzD,UAAM,SAAS,OAAO,MAAM,QAAQ,QAAQ,IAAI,SAAS,CAAC,IAAI,MAAS;AACvE,QAAI,OAAO,SAAS,eAAe,OAAO,OAAO,YAAY,YAAY,CAAC,oBAAoB,KAAK,OAAO,OAAO,KAC5G,OAAO,OAAO,aAAa,YAAY,KAAK,SAAS,OAAO,QAAQ,MAAM,OAAO,SAAU,OAAM,IAAI,MAAM,yBAAyB;AACzI,qBAAiB;AACjB,UAAM,YAAY,eAAe,KAAK,KAAK,cAAc,OAAO,QAAQ,GAAG,aAAa,iBAAiB;AACzG,QAAI,UAAU,YAAY,OAAO,QAAS,OAAM,IAAI,MAAM,mDAAmD;AAC7G,WAAO,EAAE,aAAa,aAAa,GAAG,WAAW,SAAS,OAAO,WAAW,GAAG;AAAA,EACjF,SAAS,OAAO;AACd,UAAM,aAAa,2BAA2B,KAAK,KAAK,iBAAiB,QAAQ,IAAI,MAAM,OAAO,KAAK;AACvG,UAAM,IAAI,MAAM,iDAAiD,WAAW,qBAAqB,cAAc,IAAI,UAAU,wIAAwI;AAAA,EACvQ,UAAE;AACA,OAAG,OAAO,cAAc,EAAE,WAAW,MAAM,OAAO,KAAK,CAAC;AAAA,EAC1D;AACF;",
+  "names": []
+}

package/dist/lib/module-install.js

@@ -7,8 +7,12 @@ import {
   resolveInstalledOfficialModulePackage,
   validateEjectBoundaries
 } from "./module-package.js";
-import { assertModuleNotGatedOff, ensureModuleRegistration } from "./modules-config.js";
+import { assertModuleNotGatedOff, prepareModuleRegistration, prepareModuleRegistrationSource } from "./modules-config.js";
 import { resolveSpawnCommand } from "./spawn.js";
+import { parseModuleLocator, resolveModuleRequirement } from "@open-mercato/shared/modules/module-locators";
+import { getEnabledModuleIdentities, getModuleLocators } from "./module-identity.js";
+import { resolveGithubModuleTarget } from "./module-github.js";
+import { inspectNpmModuleTarget } from "./module-inspection.js";
 const OFFICIAL_PACKAGE_SCOPE = "@open-mercato/";
 const SAFE_PACKAGE_SPEC_PATTERN = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*(?:@.+)?$/i;
 const SAFE_PACKAGE_TAG_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
@@ -61,7 +65,7 @@ function runCommand(command, args, cwd) {
 function readFileIfExists(filePath) {
   return fs.existsSync(filePath) ? fs.readFileSync(filePath, "utf8") : null;
 }
-function isDeclaredAppDependency(appDir, packageName) {
+function isDeclaredAppDependency(appDir, packageName, packageSpecifier) {
   const packageJsonContent = readFileIfExists(path.join(appDir, "package.json"));
   if (!packageJsonContent) {
     return false;
@@ -73,10 +77,11 @@ function isDeclaredAppDependency(appDir, packageName) {
     const message = error instanceof Error ? error.message : String(error);
     throw new Error(`App package.json at ${path.join(appDir, "package.json")} is not valid JSON. ${message}`);
   }
-  return ["dependencies", "devDependencies", "optionalDependencies", "peerDependencies"].some((field) => {
+  const declarations = ["dependencies", "devDependencies", "optionalDependencies", "peerDependencies"].flatMap((field) => {
     const dependencies = packageJson[field];
-    return typeof dependencies === "object" && dependencies !== null && packageName in dependencies;
+    return typeof dependencies === "object" && dependencies !== null && packageName in dependencies ? [dependencies[packageName]] : [];
   });
+  return declarations.length > 0 && (packageSpecifier === void 0 || declarations.every((declaration) => declaration === packageSpecifier));
 }
 function isGatedOffError(error) {
   return error instanceof Error && error.code === "MODULE_GATED_OFF";
@@ -135,7 +140,7 @@ function assertThirdPartyAllowed(packageName, allowThirdParty) {
   );
 }
 function assertSupportedPackageSpec(packageSpec, allowThirdParty) {
-  const trimmed = packageSpec.trim();
+  const trimmed = packageSpec.trim().replace(/^npm:/, "");
   if (!SAFE_PACKAGE_SPEC_PATTERN.test(trimmed)) {
     throw new Error("Unsupported package spec. Provide a valid npm package name with an optional tag/version or file: locator.");
   }
@@ -154,10 +159,56 @@ function assertSupportedPackageSpec(packageSpec, allowThirdParty) {
 function validateBeforeRegistration(modulePackage, resolver, eject) {
   const appModuleDir = path.join(resolver.getAppDir(), "src", "modules", modulePackage.metadata.moduleId);
   if (eject && fs.existsSync(appModuleDir)) {
-    throw new Error(`Destination directory already exists: ${appModuleDir}. Remove it first or rerun without --eject.`);
+    throw new Error(`Destination directory already exists: ${appModuleDir}. Preserve local source and choose a different destination or resolve the conflict manually.`);
   }
   return appModuleDir;
 }
+function assertRequiredModulesEnabled(modulePackage, resolver) {
+  const enabledModules = getEnabledModuleIdentities(resolver);
+  const missingModuleIds = Array.from(new Set(modulePackage.moduleInfo.requires ?? [])).filter(
+    (requirement) => !resolveModuleRequirement(requirement, enabledModules)
+  );
+  if (missingModuleIds.length === 0) return;
+  throw new Error(
+    [
+      `Module "${modulePackage.metadata.moduleId}" requires module(s) that are not enabled: ${missingModuleIds.join(", ")}.`,
+      "Enable the missing module(s) in src/modules.ts first, then rerun this command.",
+      ...missingModuleIds.filter((requirement) => parseModuleLocator(requirement)?.kind !== "module").map(
+        (requirement) => `Install ${requirement}: npx create-mercato-module install ${shellQuote(requirement)}`
+      )
+    ].join("\n")
+  );
+}
+function shellQuote(value) {
+  return "'" + value.replace(/'/g, "'\\''") + "'";
+}
+function assertNoModuleCollision(resolver, moduleId, packageName, locator) {
+  const registrations = resolver.loadEnabledModules().filter((entry) => entry.id === moduleId);
+  if (registrations.length > 1) {
+    throw new Error(`Module name collision: "${moduleId}" is registered multiple times from ${registrations.map((entry) => entry.locator ?? entry.from ?? "@open-mercato/core").join(", ")}. Resolve duplicate registrations before retrying.`);
+  }
+  const existing = registrations[0];
+  if (existing && (existing.from ?? "@open-mercato/core") !== packageName) {
+    throw new Error(`Module name collision: "${moduleId}" is already registered from "${existing.locator ?? existing.from ?? "@open-mercato/core"}"; requested source is "${locator ?? packageName}". Two sources cannot share one module id. Remove or rename the conflicting module explicitly before retrying.`);
+  }
+  const existingGithub = existing ? getModuleLocators(existing, resolver).find((value) => value.startsWith("github:")) : void 0;
+  const requestedIdentity = locator ? parseModuleLocator(locator)?.identity : void 0;
+  if (existingGithub && requestedIdentity && existingGithub !== requestedIdentity) {
+    throw new Error(`Module name collision: "${moduleId}" is already registered from "${existingGithub}"; requested source is "${locator}". Remove or rename the conflicting module explicitly before retrying.`);
+  }
+  if (!existing && fs.existsSync(path.join(resolver.getAppDir(), "src", "modules", moduleId))) {
+    throw new Error(`Module name collision: local src/modules/${moduleId} already exists; requested source is "${locator ?? packageName}". Remove or rename the conflicting module explicitly before retrying.`);
+  }
+}
+function assertBindingPreserved(resolver, target) {
+  const consumers = resolver.loadEnabledModules().filter((entry) => (entry.from ?? "@open-mercato/core") === target.packageName);
+  for (const entry of consumers) {
+    const locators = getModuleLocators(entry, resolver);
+    if (!target.locator || !locators.includes(target.locator) || !target.moduleIds.includes(entry.id)) {
+      throw new Error(`Package binding collision: "${target.packageName}" supplies enabled module "${entry.id}" from "${locators.join(", ") || "unknown origin"}". Requested "${target.locator ?? "unknown origin"}" must preserve its source and module layout. Disable affected entries explicitly before replacing this binding. No package was installed.`);
+    }
+  }
+}
 function prepareRegistrationSource(modulePackage, resolver, packageName, eject) {
   const appModuleDir = validateBeforeRegistration(modulePackage, resolver, eject);
   if (!eject) {
@@ -176,17 +227,34 @@ function prepareRegistrationSource(modulePackage, resolver, packageName, eject)
   );
   return "@app";
 }
-async function registerResolvedOfficialModule(resolver, modulePackage, packageName, eject) {
+async function registerResolvedOfficialModule(resolver, modulePackage, packageName, eject, requestedLocator) {
   assertModuleNotGatedOff(resolver.getModulesConfigPath(), modulePackage.metadata.moduleId);
-  const from = prepareRegistrationSource(modulePackage, resolver, packageName, eject);
-  const registration = ensureModuleRegistration(
-    resolver.getModulesConfigPath(),
+  const locators = getModuleLocators({ id: modulePackage.metadata.moduleId, from: packageName }, resolver);
+  if (requestedLocator && locators.length > 0 && !locators.includes(requestedLocator)) {
+    throw new Error(`Installed package "${packageName}" disagrees with inspected origin "${requestedLocator}". It is installed but not enabled. Restore the binding and lockfile through your package manager before retrying.`);
+  }
+  const locator = requestedLocator ?? locators[0];
+  assertNoModuleCollision(resolver, modulePackage.metadata.moduleId, packageName, locator);
+  assertRequiredModulesEnabled(modulePackage, resolver);
+  const existing = resolver.loadEnabledModules().find((entry) => entry.id === modulePackage.metadata.moduleId);
+  const from = eject ? "@app" : packageName;
+  const provenance = {
+    ...locator ? { locator } : {},
+    ...eject || modulePackage.packageName !== packageName ? { packageName: modulePackage.packageName } : {}
+  };
+  const modulesPath = resolver.getModulesConfigPath();
+  const modulesSource = fs.readFileSync(modulesPath, "utf8");
+  const registration = existing && eject ? { changed: true, source: prepareModuleRegistrationSource(modulesSource, modulePackage.metadata.moduleId, from, provenance) } : prepareModuleRegistration(
+    modulesSource,
     {
       id: modulePackage.metadata.moduleId,
-      from
+      from,
+      ...locator || eject || modulePackage.packageName !== packageName ? provenance : {}
     }
   );
+  prepareRegistrationSource(modulePackage, resolver, packageName, eject);
   if (registration.changed) {
+    fs.writeFileSync(modulesPath, registration.source);
     await runGeneratorsWithRegistrationNotice(resolver, modulePackage.metadata.moduleId);
   }
   return {
@@ -197,26 +265,87 @@ async function registerResolvedOfficialModule(resolver, modulePackage, packageNa
   };
 }
 async function addOfficialModule(resolver, packageSpec, eject, moduleId, allowThirdParty = false) {
-  const safePackageSpec = assertSupportedPackageSpec(packageSpec, allowThirdParty);
-  const packageName = parsePackageNameFromSpec(safePackageSpec);
-  assertPackageName(packageName);
+  const input = packageSpec.trim();
+  getEnabledModuleIdentities(resolver);
+  const isGithub = !input.startsWith("@") && !input.startsWith("npm:") && (input.includes("/") && !input.includes("@file:") || /^(?:github:|git@|(?:git\+)?ssh:)/i.test(input));
+  let safePackageSpec;
+  let packageName;
+  let target;
+  if (isGithub) {
+    if (!allowThirdParty) {
+      throw new Error("GitHub repository installs require --allow-third-party, independently of the declared npm package scope.");
+    }
+    target = resolveGithubModuleTarget(input, resolver.getAppDir(), { moduleId, enabledModules: resolver.loadEnabledModules() });
+    assertThirdPartyAllowed(target.packageName, allowThirdParty);
+    const selectedModuleId2 = moduleId ?? (target.moduleIds.length === 1 ? target.moduleIds[0] : void 0);
+    if (!selectedModuleId2 || !target.moduleIds.includes(selectedModuleId2)) {
+      throw new Error(`Select a module with --module <moduleId>. Available in ${target.locator ?? target.packageName}: ${target.moduleIds.join(", ")}. No package was installed.`);
+    }
+    assertNoModuleCollision(resolver, selectedModuleId2, target.packageName, target.locator);
+    safePackageSpec = target.packageSpec;
+    packageName = target.packageName;
+  } else {
+    safePackageSpec = assertSupportedPackageSpec(input, allowThirdParty);
+    const parsedName = parsePackageNameFromSpec(safePackageSpec);
+    assertPackageName(parsedName);
+    packageName = parsedName;
+    if (moduleId) assertNoModuleCollision(resolver, moduleId, packageName, safePackageSpec.startsWith(`${packageName}@file:`) ? void 0 : `npm:${packageName}`);
+    const requiredModuleIds = resolver.loadEnabledModules().filter((entry) => (entry.from ?? "@open-mercato/core") === packageName).map((entry) => entry.id);
+    target = inspectNpmModuleTarget(safePackageSpec, packageName, resolver.getAppDir(), [.../* @__PURE__ */ new Set([...moduleId ? [moduleId] : [], ...requiredModuleIds])]);
+  }
+  const selectedModuleId = moduleId ?? (target.moduleIds.length === 1 ? target.moduleIds[0] : void 0);
+  if (!selectedModuleId || !target.moduleIds.includes(selectedModuleId)) {
+    throw new Error(`Select a module with --module <moduleId>. Available in ${target.locator ?? target.packageName}: ${target.moduleIds.join(", ")}. No package was installed.`);
+  }
+  assertNoModuleCollision(resolver, selectedModuleId, packageName, target.locator);
+  const existing = resolver.loadEnabledModules().find((entry) => entry.id === selectedModuleId);
+  if (!eject && existing && !target.locator && target.packageSpec.startsWith(`${packageName}@file:`) && getModuleLocators(existing, resolver).length === 0 && isDeclaredAppDependency(resolver.getAppDir(), packageName, target.packageSpec.slice(packageName.length + 1))) {
+    return enableOfficialModule(resolver, packageName, selectedModuleId, false, allowThirdParty);
+  }
+  assertBindingPreserved(resolver, target);
+  const modulesSource = fs.readFileSync(resolver.getModulesConfigPath(), "utf8");
+  const from = eject ? "@app" : packageName;
+  if (existing && eject) prepareModuleRegistrationSource(modulesSource, selectedModuleId, from, { locator: target.locator, packageName });
+  else prepareModuleRegistration(modulesSource, { id: selectedModuleId, from, locator: target.locator });
+  if (eject && fs.existsSync(path.join(resolver.getAppDir(), "src", "modules", selectedModuleId))) {
+    throw new Error(`Destination directory already exists for "${selectedModuleId}". Preserve local source and resolve the conflict manually. No package was installed.`);
+  }
+  safePackageSpec = target.packageSpec;
+  assertModuleNotGatedOff(resolver.getModulesConfigPath(), selectedModuleId);
   const wasDeclaredBefore = isDeclaredAppDependency(resolver.getAppDir(), packageName);
   const modulesConfigBefore = readFileIfExists(resolver.getModulesConfigPath());
   await installPackageSpec(resolver, safePackageSpec);
   try {
-    const modulePackage = resolveInstalledOfficialModulePackage(resolver, packageName, moduleId);
-    return await registerResolvedOfficialModule(resolver, modulePackage, packageName, eject);
+    const modulePackage = resolveInstalledOfficialModulePackage(resolver, packageName, selectedModuleId);
+    if (modulePackage.packageName !== packageName) throw new Error("Installed manifest differs from inspected package name.");
+    if (target.version && modulePackage.packageJson.version !== target.version) {
+      throw new Error(`Installed version "${modulePackage.packageJson.version ?? "unknown"}" differs from inspected version "${target.version}". No registration or source edits were made.`);
+    }
+    for (const entry of resolver.loadEnabledModules().filter((entry2) => (entry2.from ?? "@open-mercato/core") === packageName)) {
+      resolveInstalledOfficialModulePackage(resolver, packageName, entry.id);
+    }
+    return await registerResolvedOfficialModule(resolver, modulePackage, packageName, eject, target.locator);
   } catch (error) {
     const moduleWasRegistered = readFileIfExists(resolver.getModulesConfigPath()) !== modulesConfigBefore;
-    if (wasDeclaredBefore || moduleWasRegistered || isGatedOffError(error)) {
-      throw error;
-    }
-    throw withLeftoverPackageHint(error, resolver, packageName);
+    if (wasDeclaredBefore || moduleWasRegistered || isGatedOffError(error)) throw error;
+    const message = error instanceof Error ? error.message : String(error);
+    throw withLeftoverPackageHint(
+      new Error(`Package "${packageName}" is installed; enablement did not complete. Review src/modules.ts and restore the package binding/lockfile through the package manager if needed. ${message}`),
+      resolver,
+      packageName
+    );
   }
 }
 async function enableOfficialModule(resolver, packageName, moduleId, eject = false, allowThirdParty = false) {
-  assertThirdPartyAllowed(packageName, allowThirdParty);
+  if (!SAFE_PACKAGE_SPEC_PATTERN.test(packageName) || parsePackageNameFromSpec(packageName) !== packageName) {
+    throw new Error("Unsupported installed package binding. Use the installed npm package name or alias, without a locator, path or version selector.");
+  }
+  getEnabledModuleIdentities(resolver);
   const modulePackage = resolveInstalledOfficialModulePackage(resolver, packageName, moduleId);
+  assertThirdPartyAllowed(modulePackage.packageName, allowThirdParty);
+  if (!allowThirdParty && getModuleLocators({ id: modulePackage.metadata.moduleId, from: packageName }, resolver).some((locator) => locator.startsWith("github:"))) {
+    throw new Error("GitHub repository installs require --allow-third-party, independently of the declared npm package scope.");
+  }
   return registerResolvedOfficialModule(resolver, modulePackage, packageName, eject);
 }
 export {