@penvhq/launcher 0.9.5 → 0.10.0

package/dist/bin.js

@@ -5,7 +5,7 @@ import {
   httpFetcher,
   nodeSpawner,
   runLauncher
-} from "./chunk-4YZYBC5T.js";
+} from "./chunk-BNUZ52VN.js";
 
 // src/bin.ts
 function readLine() {

package/dist/{chunk-4YZYBC5T.js → chunk-BNUZ52VN.js}

@@ -176,6 +176,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 PenvError {
   name = "NoProjectError";
   constructor(cwd) {
@@ -287,6 +290,26 @@ var AddLocalFlagError = class extends PenvError {
     );
   }
 };
+var ExtensionNotImportableError = class extends 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 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 PenvError {
   name = "LocalExtensionUnresolvedError";
   constructor(name, root) {
@@ -593,32 +616,10 @@ function writeDeclaration(options) {
 
 // src/home.ts
 import { readFileSync as readFileSync2 } from "fs";
-import { homedir } from "os";
-import { join as join2, resolve as resolve2, sep as sep2 } from "path";
-import { PenvError as PenvError2 } from "@penvhq/core";
-var PENV_HOME_VAR = "PENV_HOME";
+import { join as join2 } from "path";
 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 resolve2(declared);
-  }
-  return join2(homedir(), ".penv");
-}
-function packageDir(home, kind, name, version) {
-  const bucket = resolve2(home, kind);
-  const dir = resolve2(bucket, ...name.split("/"), version);
-  if (!dir.startsWith(bucket + sep2)) {
-    throw new PenvError2(
-      "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 {
@@ -723,6 +724,7 @@ import {
   writeFileSync as writeFileSync2
 } from "fs";
 import { dirname as dirname2, join as join3 } from "path";
+import { packageDir } from "@penvhq/core";
 var DEFAULT_REGISTRY = "https://registry.npmjs.org";
 function tarballUrl(pin) {
   const registry = (pin.registry ?? DEFAULT_REGISTRY).replace(/\/+$/, "");
@@ -859,13 +861,16 @@ async function fetchRelease(query) {
 // src/add.ts
 import { mkdirSync as mkdirSync3, readFileSync as readFileSync4, writeFileSync as writeFileSync3 } from "fs";
 import { createRequire } from "module";
-import { dirname as dirname3, relative, resolve as resolve3, sep as sep3 } from "path";
+import { dirname as dirname3, relative, resolve as resolve2, sep as sep2 } from "path";
+import { pathToFileURL } from "url";
 import {
   findConfigFile,
+  isImportableEntry,
   LOCAL_EXTENSIONS_PATH as LOCAL_EXTENSIONS_PATH2,
   localExtensionsFile,
   MANIFEST_PATH as MANIFEST_PATH2,
   OFFICIAL_SCOPE as OFFICIAL_SCOPE2,
+  packageEntry,
   parseLocalExtensions,
   serializeLocalExtensions,
   serializeManifest
@@ -1066,7 +1071,7 @@ async function offerConfigEdit(options, name) {
     io.out(line);
     return;
   }
-  const shown = relative(root, configFile).split(sep3).join("/");
+  const shown = relative(root, configFile).split(sep2).join("/");
   let current = readFileSync4(configFile, "utf8");
   const entries = readProviderEntries(current);
   if (entries === void 0 || entries.length === 0) {
@@ -1113,7 +1118,7 @@ async function offerOnboarding(io, name, onboard) {
   return void 0;
 }
 function resolvePackageDir(name, root) {
-  const require2 = createRequire(resolve3(root, "noop.js"));
+  const require2 = createRequire(resolve2(root, "noop.js"));
   try {
     return dirname3(require2.resolve(`${name}/package.json`));
   } catch {
@@ -1132,6 +1137,26 @@ function resolvePackageDir(name, root) {
     return void 0;
   }
 }
+function resolveProjectEntry(name, root) {
+  let file;
+  try {
+    file = createRequire(resolve2(root, "noop.js")).resolve(name);
+  } catch {
+    return void 0;
+  }
+  return { file, importable: isImportableEntry(file) };
+}
+async function assertLoadable(name, entry, local) {
+  if (entry === void 0 || !entry.importable) {
+    throw new ExtensionNotImportableError(name, entry?.file, local);
+  }
+  try {
+    await import(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 = localExtensionsFile(root);
   let current;
@@ -1152,6 +1177,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,
@@ -1163,7 +1189,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 ${LOCAL_EXTENSIONS_PATH2} records it`);
   io.out(`\u2713 ${declaration} declares its config type`);
   await offerConfigEdit(options, request.name);
@@ -1208,6 +1234,7 @@ async function add(options) {
     },
     fetcher
   });
+  await assertLoadable(release.name, packageEntry(dir), false);
   const installed = readExtensionPackage(dir);
   const declaration = writeDeclaration({
     root,
@@ -1272,8 +1299,8 @@ function nodeSpawner() {
 // src/engine.ts
 import { existsSync as existsSync2, readFileSync as readFileSync5 } from "fs";
 import { createRequire as createRequire2 } from "module";
-import { dirname as dirname4, join as join5, resolve as resolve4, sep as sep4 } from "path";
-import { ENGINE_PACKAGE as ENGINE_PACKAGE2, PenvError as PenvError3 } from "@penvhq/core";
+import { dirname as dirname4, join as join5, resolve as resolve3, sep as sep3 } from "path";
+import { ENGINE_PACKAGE as ENGINE_PACKAGE2, PenvError as PenvError2 } from "@penvhq/core";
 var ENGINE_BIN = "penv-engine";
 function readPackageManifest(dir) {
   try {
@@ -1299,9 +1326,9 @@ function binPath(bin) {
 function engineAt(dir, name, version) {
   const manifest = readPackageManifest(dir);
   const bin = manifest === void 0 ? void 0 : binPath(manifest.bin);
-  const root = resolve4(dir);
-  const entry = bin === void 0 ? void 0 : resolve4(root, bin);
-  if (entry === void 0 || !entry.startsWith(root + sep4) || !existsSync2(entry)) {
+  const root = resolve3(dir);
+  const entry = bin === void 0 ? void 0 : resolve3(root, bin);
+  if (entry === void 0 || !entry.startsWith(root + sep3) || !existsSync2(entry)) {
     throw new EngineEntryError(name, version, dir);
   }
   return { name, version, dir, entry };
@@ -1312,7 +1339,7 @@ function bundledEngine() {
   try {
     manifestFile = require2.resolve(`${ENGINE_PACKAGE2}/package.json`);
   } catch {
-    throw new PenvError3(
+    throw new PenvError2(
       "PENV_NO_BUNDLED_ENGINE",
       `This penv installation is missing ${ENGINE_PACKAGE2}, the engine it runs \`init\` with`,
       "Reinstall the launcher with `npm install -g @penvhq/launcher`."
@@ -1342,8 +1369,8 @@ var DEV_PIN_INTEGRITY = "sha512-development-build-not-a-published-release";
 var DEV_PIN_VERSION = "0.0.0-dev";
 var BUNDLED_ENGINE_PIN = {
   package: ENGINE_PACKAGE3,
-  version: "0.9.5",
-  integrity: "sha512-cacsvynscs6G0NThpGaK1BfKy3POQSoogI/vvQNZ5sTZaftzwg4mPtUpT+i2GSc3KbYAHQu4Kq9MpYLOvSvulA=="
+  version: "0.10.0",
+  integrity: "sha512-b+U0c3xWbk1ILtMfPjJW8x5XBxSLAaw/IAOLMBmGvT2uuYv41JPED8PrenEj4s3ZJY5BxpWU9mQcJHEBouaw/Q=="
 };
 function assertReleasePin(pin) {
   if (pin.integrity === DEV_PIN_INTEGRITY || pin.version === DEV_PIN_VERSION) {
@@ -1360,11 +1387,11 @@ function releaseEnginePin(pin, ranVersion) {
 
 // src/project.ts
 import { existsSync as existsSync3 } from "fs";
-import { dirname as dirname5, join as join6, resolve as resolve5 } from "path";
+import { dirname as dirname5, join as join6, resolve as resolve4 } from "path";
 import { MANIFEST_PATH as MANIFEST_PATH3, stateDir } from "@penvhq/core";
 var MANIFEST_SEGMENTS = MANIFEST_PATH3.split("/");
 function findUp(cwd, matches) {
-  let dir = resolve5(cwd);
+  let dir = resolve4(cwd);
   for (; ; ) {
     if (matches(dir)) {
       return dir;
@@ -1389,12 +1416,48 @@ import { existsSync as existsSync4, readFileSync as readFileSync6, writeFileSync
 import { join as join7 } from "path";
 import {
   MANIFEST_FORMAT,
-  MANIFEST_PATH as MANIFEST_PATH4,
-  PenvError as PenvError4,
+  MANIFEST_PATH as MANIFEST_PATH5,
+  PENV_HOME_VAR,
+  PenvError as PenvError3,
   parseManifest as parseManifest2,
+  penvHome,
   serializeManifest as serializeManifest2,
   UnsupportedManifestFormatError
 } from "@penvhq/core";
+
+// src/help.ts
+import { EXTENSIONS_PATH as EXTENSIONS_PATH3, MANIFEST_PATH as MANIFEST_PATH4 } from "@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 ${MANIFEST_PATH4} 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 ${MANIFEST_PATH4} 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 ${MANIFEST_PATH4} and writes its type declaration to`);
+  io.out(`${EXTENSIONS_PATH3}/. Both are committed, so \`${INSTALL_COMMAND}\` gives every machine`);
+  io.out(`the bytes you reviewed. \`${LOCAL_FLAG}\` pins nothing and touches no manifest.`);
+}
+
+// src/launcher.ts
 var INSTALL = "install";
 var ADD = "add";
 var VERSION_FLAGS = /* @__PURE__ */ new Set(["--version", "-v"]);
@@ -1460,7 +1523,7 @@ function readManifestToRepair(manifestFile, home, argv) {
   }
 }
 function report(error, io) {
-  if (error instanceof PenvError4 && error.remedy !== void 0) {
+  if (error instanceof PenvError3 && error.remedy !== void 0) {
     const suffix = `
   ${error.remedy}`;
     const message = error.message.endsWith(suffix) ? error.message.slice(0, -suffix.length) : error.message;
@@ -1483,6 +1546,16 @@ async function launch(options) {
   const { noDownload, forwarded } = splitLauncherFlags(argv);
   const first = forwarded[0];
   const home = 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)) {
@@ -1527,7 +1600,7 @@ async function adopt(options, forwarded, home, cwd, noDownload) {
   if (root === void 0) {
     return 0;
   }
-  const manifestFile = join7(root, ...MANIFEST_PATH4.split("/"));
+  const manifestFile = join7(root, ...MANIFEST_PATH5.split("/"));
   if (existsSync4(manifestFile)) {
     return 0;
   }
@@ -1536,7 +1609,7 @@ async function adopt(options, forwarded, home, cwd, noDownload) {
     manifestFile,
     serializeManifest2({ format: MANIFEST_FORMAT, engine: pin, extensions: {} })
   );
-  options.io.out(`\u2713 ${MANIFEST_PATH4} pins ${pin.package} ${pin.version}`);
+  options.io.out(`\u2713 ${MANIFEST_PATH5} pins ${pin.package} ${pin.version}`);
   await ensureAdoptedEngine(
     options,
     { name: pin.package, version: pin.version, integrity: pin.integrity },
@@ -1615,13 +1688,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 }
   });
+  if (code === 0 && isRootHelp(forwarded)) {
+    printLauncherCommands(options.io);
+  }
+  return code;
 }
 
 export {
@@ -1642,6 +1723,8 @@ export {
   AddFlagError,
   LOCAL_FLAG,
   AddLocalFlagError,
+  ExtensionNotImportableError,
+  ExtensionUnloadableError,
   LocalExtensionUnresolvedError,
   AddLocalInCiError,
   AddRegistryError,
@@ -1665,12 +1748,9 @@ export {
   renderDeclaration,
   declarationPath,
   writeDeclaration,
-  PENV_HOME_VAR,
   HOME_META_FILE,
   INTEGRITY_FILE,
   NPM_UPDATE_COMMAND,
-  penvHome,
-  packageDir,
   launcherUpdateCommand,
   integrityOf,
   readTarball,
@@ -1695,4 +1775,4 @@ export {
   findAdoptedRoot,
   runLauncher
 };
-//# sourceMappingURL=chunk-4YZYBC5T.js.map
+//# sourceMappingURL=chunk-BNUZ52VN.js.map