@penvhq/launcher 0.9.5 → 0.10.0

package/dist/index.cjs

@@ -41,6 +41,8 @@ __export(src_exports, {
   EngineEntryError: () => EngineEntryError,
   EnginePinMismatchError: () => EnginePinMismatchError,
   EnginePinUnreleasedError: () => EnginePinUnreleasedError,
+  ExtensionNotImportableError: () => ExtensionNotImportableError,
+  ExtensionUnloadableError: () => ExtensionUnloadableError,
   HOME_META_FILE: () => HOME_META_FILE,
   INSTALL_COMMAND: () => INSTALL_COMMAND,
   INTEGRITY_FILE: () => INTEGRITY_FILE,
@@ -51,7 +53,6 @@ __export(src_exports, {
   NPM_UPDATE_COMMAND: () => NPM_UPDATE_COMMAND,
   NoProjectError: () => NoProjectError,
   OfficialRegistryError: () => OfficialRegistryError,
-  PENV_HOME_VAR: () => PENV_HOME_VAR,
   PackageCorruptError: () => PackageCorruptError,
   PackageMissingError: () => PackageMissingError,
   PackageTooYoungError: () => PackageTooYoungError,
@@ -77,9 +78,7 @@ __export(src_exports, {
   integrityOf: () => integrityOf,
   launcherUpdateCommand: () => launcherUpdateCommand,
   nodeSpawner: () => nodeSpawner,
-  packageDir: () => packageDir,
   packumentUrl: () => packumentUrl,
-  penvHome: () => penvHome,
   readExtensionPackage: () => readExtensionPackage,
   readProviderEntries: () => readProviderEntries,
   readTarball: () => readTarball,
@@ -96,6 +95,7 @@ module.exports = __toCommonJS(src_exports);
 var import_node_fs4 = require("fs");
 var import_node_module = require("module");
 var import_node_path4 = require("path");
+var import_node_url = require("url");
 var import_core5 = require("@penvhq/core");
 
 // src/config-edit.ts
@@ -274,6 +274,9 @@ function addCommand(name, version, extra) {
   const spec = version === void 0 ? name : `${name}@${version}`;
   return `penv add ${spec}${extra === void 0 ? "" : ` ${extra}`}`;
 }
+function addCommandFor(name, local) {
+  return local ? `penv add ${LOCAL_FLAG} ${name}` : addCommand(name);
+}
 var NoProjectError = class extends import_core.PenvError {
   name = "NoProjectError";
   constructor(cwd) {
@@ -385,6 +388,26 @@ var AddLocalFlagError = class extends import_core.PenvError {
     );
   }
 };
+var ExtensionNotImportableError = class extends import_core.PenvError {
+  name = "ExtensionNotImportableError";
+  constructor(name, entry, local) {
+    super(
+      "PENV_EXTENSION_NOT_IMPORTABLE",
+      entry === void 0 ? `${name} declares no entry point penv can import` : `${name} resolves to ${entry}, which penv cannot import`,
+      `penv imports a provider with no transform, so its entry has to be built JavaScript. Point the package's \`exports\` at its build output \u2014 \`dist/index.js\` \u2014 then run \`${addCommandFor(name, local)}\` again.`
+    );
+  }
+};
+var ExtensionUnloadableError = class extends import_core.PenvError {
+  name = "ExtensionUnloadableError";
+  constructor(name, entry, detail, local) {
+    super(
+      "PENV_EXTENSION_UNLOADABLE",
+      `${name} threw while penv imported ${entry}: ${detail}`,
+      `Build the package and install its dependencies, then run \`${addCommandFor(name, local)}\` again. penv adds a provider it has loaded once, or none.`
+    );
+  }
+};
 var LocalExtensionUnresolvedError = class extends import_core.PenvError {
   name = "LocalExtensionUnresolvedError";
   constructor(name, root) {
@@ -689,35 +712,14 @@ function writeDeclaration(options) {
 // src/store.ts
 var import_node_fs3 = require("fs");
 var import_node_path3 = require("path");
+var import_core3 = require("@penvhq/core");
 
 // src/home.ts
 var import_node_fs2 = require("fs");
-var import_node_os = require("os");
 var import_node_path2 = require("path");
-var import_core3 = require("@penvhq/core");
-var PENV_HOME_VAR = "PENV_HOME";
 var HOME_META_FILE = "meta.json";
 var INTEGRITY_FILE = ".penv-integrity";
 var NPM_UPDATE_COMMAND = "npm install -g @penvhq/launcher";
-function penvHome(env) {
-  const declared = env[PENV_HOME_VAR];
-  if (declared !== void 0 && declared.trim() !== "") {
-    return (0, import_node_path2.resolve)(declared);
-  }
-  return (0, import_node_path2.join)((0, import_node_os.homedir)(), ".penv");
-}
-function packageDir(home, kind, name, version) {
-  const bucket = (0, import_node_path2.resolve)(home, kind);
-  const dir = (0, import_node_path2.resolve)(bucket, ...name.split("/"), version);
-  if (!dir.startsWith(bucket + import_node_path2.sep)) {
-    throw new import_core3.PenvError(
-      "PENV_HOME_ESCAPE",
-      `\`${name}\` at \`${version}\` resolves to ${dir}, which is outside ${bucket}`,
-      "Name the package exactly as npm does, e.g. `@penvhq/provider-vault`."
-    );
-  }
-  return dir;
-}
 function launcherUpdateCommand(home) {
   let meta;
   try {
@@ -819,7 +821,7 @@ function tarballUrl(pin) {
   return `${registry}/${pin.name}/-/${basename}-${pin.version}.tgz`;
 }
 function inspectInstall(home, kind, pin) {
-  const dir = packageDir(home, kind, pin.name, pin.version);
+  const dir = (0, import_core3.packageDir)(home, kind, pin.name, pin.version);
   if (!(0, import_node_fs3.existsSync)(dir)) {
     return { dir, state: "absent" };
   }
@@ -833,7 +835,7 @@ function inspectInstall(home, kind, pin) {
 }
 async function installPin(options) {
   const { home, kind, pin, fetcher } = options;
-  const dir = packageDir(home, kind, pin.name, pin.version);
+  const dir = (0, import_core3.packageDir)(home, kind, pin.name, pin.version);
   const url = tarballUrl(pin);
   let bytes;
   try {
@@ -1206,6 +1208,26 @@ function resolvePackageDir(name, root) {
     return void 0;
   }
 }
+function resolveProjectEntry(name, root) {
+  let file;
+  try {
+    file = (0, import_node_module.createRequire)((0, import_node_path4.resolve)(root, "noop.js")).resolve(name);
+  } catch {
+    return void 0;
+  }
+  return { file, importable: (0, import_core5.isImportableEntry)(file) };
+}
+async function assertLoadable(name, entry, local) {
+  if (entry === void 0 || !entry.importable) {
+    throw new ExtensionNotImportableError(name, entry?.file, local);
+  }
+  try {
+    await import((0, import_node_url.pathToFileURL)(entry.file).href);
+  } catch (cause) {
+    const detail = cause instanceof Error ? cause.message : String(cause);
+    throw new ExtensionUnloadableError(name, entry.file, detail, local);
+  }
+}
 function recordLocalExtension(root, name) {
   const file = (0, import_core5.localExtensionsFile)(root);
   let current;
@@ -1226,6 +1248,7 @@ async function addLocal(options, request) {
   if (dir === void 0) {
     throw new LocalExtensionUnresolvedError(request.name, root);
   }
+  await assertLoadable(request.name, resolveProjectEntry(request.name, root), true);
   const installed = readExtensionPackage(dir);
   const declaration = writeDeclaration({
     root,
@@ -1237,7 +1260,7 @@ async function addLocal(options, request) {
     types: installed.types
   });
   recordLocalExtension(root, request.name);
-  io.out(`\u2713 ${request.name} resolves from this project \u2014 nothing is pinned`);
+  io.out(`\u2713 ${request.name} resolves from this project and imports \u2014 nothing is pinned`);
   io.out(`\u2713 ${import_core5.LOCAL_EXTENSIONS_PATH} records it`);
   io.out(`\u2713 ${declaration} declares its config type`);
   await offerConfigEdit(options, request.name);
@@ -1282,6 +1305,7 @@ async function add(options) {
     },
     fetcher
   });
+  await assertLoadable(release.name, (0, import_core5.packageEntry)(dir), false);
   const installed = readExtensionPackage(dir);
   const declaration = writeDeclaration({
     root,
@@ -1302,10 +1326,10 @@ async function add(options) {
 
 // src/delegate.ts
 var import_node_child_process = require("child_process");
-var import_node_os2 = require("os");
+var import_node_os = require("os");
 var FORWARDED = ["SIGINT", "SIGTERM", "SIGHUP", "SIGQUIT"];
 function signalNumber(signal) {
-  const signals = import_node_os2.constants.signals;
+  const signals = import_node_os.constants.signals;
   return signals[signal] ?? 0;
 }
 function nodeSpawner() {
@@ -1414,16 +1438,48 @@ function httpFetcher() {
 // src/launcher.ts
 var import_node_fs7 = require("fs");
 var import_node_path7 = require("path");
-var import_core9 = require("@penvhq/core");
+var import_core10 = require("@penvhq/core");
 
-// src/pins.ts
+// src/help.ts
 var import_core7 = require("@penvhq/core");
+function printLauncherCommands(io) {
+  io.out("");
+  io.out("LAUNCHER COMMANDS (penv itself, whatever engine a project pins)");
+  io.out("");
+  io.out(`  install                Installs everything ${import_core7.MANIFEST_PATH} pins`);
+  io.out("  add <package>          Pins a provider extension, and commits the decision");
+  io.out(`  add ${LOCAL_FLAG} <package>  Adds the one this repository builds \u2014 nothing is pinned`);
+  io.out("");
+}
+function printInstallHelp(io) {
+  io.out(`${INSTALL_COMMAND}`);
+  io.out("");
+  io.out(`Downloads, verifies and installs every version ${import_core7.MANIFEST_PATH} pins \u2014 the engine and`);
+  io.out("every extension \u2014 into $PENV_HOME. The one penv command CI and production run that");
+  io.out("may reach the registry.");
+}
+function printAddHelp(io) {
+  io.out("penv add <package>[@<version>]");
+  io.out("");
+  io.out(`  ${LOCAL_FLAG}            Add the package this repository builds, resolved from it`);
+  io.out("  --registry <url>   Take the release from a private registry instead of npmjs");
+  io.out(
+    `  ${TRUST_YOUNG_FLAG}      Add a release published less than ${MIN_PACKAGE_AGE_DAYS} days ago`
+  );
+  io.out("");
+  io.out(`Pins the release in ${import_core7.MANIFEST_PATH} and writes its type declaration to`);
+  io.out(`${import_core7.EXTENSIONS_PATH}/. Both are committed, so \`${INSTALL_COMMAND}\` gives every machine`);
+  io.out(`the bytes you reviewed. \`${LOCAL_FLAG}\` pins nothing and touches no manifest.`);
+}
+
+// src/pins.ts
+var import_core8 = require("@penvhq/core");
 var DEV_PIN_INTEGRITY = "sha512-development-build-not-a-published-release";
 var DEV_PIN_VERSION = "0.0.0-dev";
 var BUNDLED_ENGINE_PIN = {
-  package: import_core7.ENGINE_PACKAGE,
-  version: "0.9.5",
-  integrity: "sha512-cacsvynscs6G0NThpGaK1BfKy3POQSoogI/vvQNZ5sTZaftzwg4mPtUpT+i2GSc3KbYAHQu4Kq9MpYLOvSvulA=="
+  package: import_core8.ENGINE_PACKAGE,
+  version: "0.10.0",
+  integrity: "sha512-b+U0c3xWbk1ILtMfPjJW8x5XBxSLAaw/IAOLMBmGvT2uuYv41JPED8PrenEj4s3ZJY5BxpWU9mQcJHEBouaw/Q=="
 };
 function assertReleasePin(pin) {
   if (pin.integrity === DEV_PIN_INTEGRITY || pin.version === DEV_PIN_VERSION) {
@@ -1441,8 +1497,8 @@ function releaseEnginePin(pin, ranVersion) {
 // src/project.ts
 var import_node_fs6 = require("fs");
 var import_node_path6 = require("path");
-var import_core8 = require("@penvhq/core");
-var MANIFEST_SEGMENTS = import_core8.MANIFEST_PATH.split("/");
+var import_core9 = require("@penvhq/core");
+var MANIFEST_SEGMENTS = import_core9.MANIFEST_PATH.split("/");
 function findUp(cwd, matches) {
   let dir = (0, import_node_path6.resolve)(cwd);
   for (; ; ) {
@@ -1461,7 +1517,7 @@ function findProject(cwd) {
   return root === void 0 ? void 0 : { root, manifestFile: (0, import_node_path6.join)(root, ...MANIFEST_SEGMENTS) };
 }
 function findAdoptedRoot(cwd) {
-  return findUp(cwd, (dir) => (0, import_node_fs6.existsSync)((0, import_core8.stateDir)(dir)));
+  return findUp(cwd, (dir) => (0, import_node_fs6.existsSync)((0, import_core9.stateDir)(dir)));
 }
 
 // src/launcher.ts
@@ -1510,14 +1566,14 @@ function pinsOf(manifest) {
   ];
 }
 function reportable(error, home, argv) {
-  return error instanceof import_core9.UnsupportedManifestFormatError ? error.withLauncherUpdate({
+  return error instanceof import_core10.UnsupportedManifestFormatError ? error.withLauncherUpdate({
     updateCommand: launcherUpdateCommand(home),
     invokedCommand: invokedCommand(argv)
   }) : error;
 }
 function readManifest(manifestFile, home, argv) {
   try {
-    return (0, import_core9.parseManifest)((0, import_node_fs7.readFileSync)(manifestFile, "utf8"));
+    return (0, import_core10.parseManifest)((0, import_node_fs7.readFileSync)(manifestFile, "utf8"));
   } catch (error) {
     throw reportable(error, home, argv);
   }
@@ -1530,7 +1586,7 @@ function readManifestToRepair(manifestFile, home, argv) {
   }
 }
 function report(error, io) {
-  if (error instanceof import_core9.PenvError && error.remedy !== void 0) {
+  if (error instanceof import_core10.PenvError && error.remedy !== void 0) {
     const suffix = `
   ${error.remedy}`;
     const message = error.message.endsWith(suffix) ? error.message.slice(0, -suffix.length) : error.message;
@@ -1552,7 +1608,17 @@ async function launch(options) {
   const { argv, cwd, env, io } = options;
   const { noDownload, forwarded } = splitLauncherFlags(argv);
   const first = forwarded[0];
-  const home = penvHome(env);
+  const home = (0, import_core10.penvHome)(env);
+  if (first !== void 0 && forwarded.slice(1).some((token) => HELP_FLAGS.has(token))) {
+    if (first === INSTALL) {
+      printInstallHelp(io);
+      return 0;
+    }
+    if (first === ADD) {
+      printAddHelp(io);
+      return 0;
+    }
+  }
   const project = findProject(cwd);
   if (project === void 0) {
     if (first !== void 0 && VERSION_FLAGS.has(first)) {
@@ -1597,16 +1663,16 @@ async function adopt(options, forwarded, home, cwd, noDownload) {
   if (root === void 0) {
     return 0;
   }
-  const manifestFile = (0, import_node_path7.join)(root, ...import_core9.MANIFEST_PATH.split("/"));
+  const manifestFile = (0, import_node_path7.join)(root, ...import_core10.MANIFEST_PATH.split("/"));
   if ((0, import_node_fs7.existsSync)(manifestFile)) {
     return 0;
   }
   const pin = releaseEnginePin(options.bundledPin, engine.version);
   (0, import_node_fs7.writeFileSync)(
     manifestFile,
-    (0, import_core9.serializeManifest)({ format: import_core9.MANIFEST_FORMAT, engine: pin, extensions: {} })
+    (0, import_core10.serializeManifest)({ format: import_core10.MANIFEST_FORMAT, engine: pin, extensions: {} })
   );
-  options.io.out(`\u2713 ${import_core9.MANIFEST_PATH} pins ${pin.package} ${pin.version}`);
+  options.io.out(`\u2713 ${import_core10.MANIFEST_PATH} pins ${pin.package} ${pin.version}`);
   await ensureAdoptedEngine(
     options,
     { name: pin.package, version: pin.version, integrity: pin.integrity },
@@ -1685,13 +1751,21 @@ async function addExtension(options, project, home, argv, noDownload) {
   const engine = engineAt(dir, enginePin.name, enginePin.version);
   return delegate(options, engine, onboard, home, options.cwd);
 }
-function delegate(options, engine, forwarded, home, cwd) {
-  return options.spawn({
+function isRootHelp(forwarded) {
+  const first = forwarded[0];
+  return first === void 0 || HELP_FLAGS.has(first);
+}
+async function delegate(options, engine, forwarded, home, cwd) {
+  const code = await options.spawn({
     command: process.execPath,
     args: [engine.entry, ...forwarded],
     cwd,
-    env: { ...options.env, [PENV_HOME_VAR]: home }
+    env: { ...options.env, [import_core10.PENV_HOME_VAR]: home }
   });
+  if (code === 0 && isRootHelp(forwarded)) {
+    printLauncherCommands(options.io);
+  }
+  return code;
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
@@ -1716,6 +1790,8 @@ function delegate(options, engine, forwarded, home, cwd) {
   EngineEntryError,
   EnginePinMismatchError,
   EnginePinUnreleasedError,
+  ExtensionNotImportableError,
+  ExtensionUnloadableError,
   HOME_META_FILE,
   INSTALL_COMMAND,
   INTEGRITY_FILE,
@@ -1726,7 +1802,6 @@ function delegate(options, engine, forwarded, home, cwd) {
   NPM_UPDATE_COMMAND,
   NoProjectError,
   OfficialRegistryError,
-  PENV_HOME_VAR,
   PackageCorruptError,
   PackageMissingError,
   PackageTooYoungError,
@@ -1752,9 +1827,7 @@ function delegate(options, engine, forwarded, home, cwd) {
   integrityOf,
   launcherUpdateCommand,
   nodeSpawner,
-  packageDir,
   packumentUrl,
-  penvHome,
   readExtensionPackage,
   readProviderEntries,
   readTarball,