@penvhq/launcher 0.9.4 → 0.10.0

package/dist/bin.cjs

@@ -59,6 +59,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) {
@@ -155,7 +158,58 @@ var AddFlagError = class extends import_core.PenvError {
     super(
       "PENV_ADD_FLAG",
       `\`penv add\` does not understand \`${flag}\``,
-      `Run \`penv add <package>\` with \`${TRUST_YOUNG_FLAG}\` or \`--registry <url>\` \u2014 those are the two it takes.`
+      `Run \`penv add <package>\` with \`${TRUST_YOUNG_FLAG}\`, \`--registry <url>\`, or \`${LOCAL_FLAG}\` \u2014 those are the three it takes.`
+    );
+  }
+};
+var LOCAL_FLAG = "--local";
+var AddLocalFlagError = class extends import_core.PenvError {
+  name = "AddLocalFlagError";
+  constructor(subject) {
+    super(
+      "PENV_ADD_LOCAL_FLAG",
+      `\`penv add ${LOCAL_FLAG}\` cannot take ${subject}`,
+      `${LOCAL_FLAG} adds the package this project already builds, so there is no release to name and nothing to pin. Publish it and run \`penv add <package>\` to pin one.`
+    );
+  }
+};
+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) {
+    super(
+      "PENV_LOCAL_EXTENSION_UNRESOLVED",
+      `${name} does not resolve from ${root}`,
+      `${LOCAL_FLAG} records that penv should read this package out of the project, so the project has to have it \u2014 add it as a dependency of the root (a workspace link is one), then run this again.`
+    );
+  }
+};
+var AddLocalInCiError = class extends import_core.PenvError {
+  name = "AddLocalInCiError";
+  constructor(name) {
+    super(
+      "PENV_ADD_LOCAL_IN_CI",
+      `Adding ${name} writes ${import_core.LOCAL_EXTENSIONS_PATH}, and CI does not decide what a project develops`,
+      `Run \`penv add ${LOCAL_FLAG} ${name}\` from a terminal and commit what it writes.`
     );
   }
 };
@@ -408,11 +462,13 @@ 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/add.ts
 var import_node_fs5 = require("fs");
+var import_node_module2 = require("module");
 var import_node_path5 = require("path");
+var import_node_url = require("url");
 var import_core6 = require("@penvhq/core");
 
 // src/config-edit.ts
@@ -594,14 +650,20 @@ function readExtensionPackage(dir) {
   try {
     parsed = JSON.parse((0, import_node_fs2.readFileSync)((0, import_node_path2.join)(dir, "package.json"), "utf8"));
   } catch {
-    return { types: void 0, onboard: void 0 };
+    return { name: void 0, version: void 0, types: void 0, onboard: void 0 };
   }
   const penv = field(parsed, "penv");
-  return { types: text(field(penv, "types")), onboard: text(field(penv, "onboard")) };
+  return {
+    name: text(field(parsed, "name")),
+    version: text(field(parsed, "version")),
+    types: text(field(penv, "types")),
+    onboard: text(field(penv, "onboard"))
+  };
 }
 function header(subject) {
-  const provenance = subject.attested ? "npm records a provenance attestation for it" : "npm records no provenance attestation for it";
-  return `// Written by \`penv add ${subject.name}\`, and committed.
+  const local = subject.local === true;
+  const provenance = local ? "resolved from this project, not from a published release" : subject.attested ? "npm records a provenance attestation for it" : "npm records no provenance attestation for it";
+  return `// Written by \`penv add ${local ? "--local " : ""}${subject.name}\`, and committed.
 // ${subject.name} ${subject.version} \u2014 ${provenance}.
 //
 // Types only: this declares the shape of the provider's \`penv.config.ts\`
@@ -676,35 +738,14 @@ function writeDeclaration(options) {
 // src/store.ts
 var import_node_fs4 = require("fs");
 var import_node_path4 = require("path");
+var import_core4 = require("@penvhq/core");
 
 // src/home.ts
 var import_node_fs3 = require("fs");
-var import_node_os2 = require("os");
 var import_node_path3 = require("path");
-var import_core4 = 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_path3.resolve)(declared);
-  }
-  return (0, import_node_path3.join)((0, import_node_os2.homedir)(), ".penv");
-}
-function packageDir(home, kind, name, version) {
-  const bucket = (0, import_node_path3.resolve)(home, kind);
-  const dir = (0, import_node_path3.resolve)(bucket, ...name.split("/"), version);
-  if (!dir.startsWith(bucket + import_node_path3.sep)) {
-    throw new import_core4.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 {
@@ -806,7 +847,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_core4.packageDir)(home, kind, pin.name, pin.version);
   if (!(0, import_node_fs4.existsSync)(dir)) {
     return { dir, state: "absent" };
   }
@@ -820,7 +861,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_core4.packageDir)(home, kind, pin.name, pin.version);
   const url = tarballUrl(pin);
   let bytes;
   try {
@@ -994,8 +1035,13 @@ function parseRequest(argv) {
   let spec;
   let registry;
   let trustYoung = false;
+  let local = false;
   for (let index = 0; index < argv.length; index += 1) {
     const token = argv[index] ?? "";
+    if (token === LOCAL_FLAG) {
+      local = true;
+      continue;
+    }
     if (token === TRUST_YOUNG_FLAG) {
       trustYoung = true;
       continue;
@@ -1024,7 +1070,18 @@ function parseRequest(argv) {
   if (!PACKAGE_NAME.test(name) || version === "") {
     throw new AddPackageNameError(spec);
   }
-  return { name, version, registry, trustYoung };
+  if (local) {
+    if (version !== void 0) {
+      throw new AddLocalFlagError("a version");
+    }
+    if (registry !== void 0) {
+      throw new AddLocalFlagError(`\`${REGISTRY_FLAG}\``);
+    }
+    if (trustYoung) {
+      throw new AddLocalFlagError(`\`${TRUST_YOUNG_FLAG}\``);
+    }
+  }
+  return { name, version, registry, trustYoung, local };
 }
 function tierOf(request) {
   if (request.name.startsWith(import_core6.OFFICIAL_SCOPE)) {
@@ -1157,9 +1214,90 @@ async function offerOnboarding(io2, name, onboard) {
   io2.out(`Run \`${command}\` to finish setting ${name} up.`);
   return void 0;
 }
+function resolvePackageDir(name, root) {
+  const require2 = (0, import_node_module2.createRequire)((0, import_node_path5.resolve)(root, "noop.js"));
+  try {
+    return (0, import_node_path5.dirname)(require2.resolve(`${name}/package.json`));
+  } catch {
+    let dir;
+    try {
+      dir = (0, import_node_path5.dirname)(require2.resolve(name));
+    } catch {
+      return void 0;
+    }
+    for (let current = dir, parent = (0, import_node_path5.dirname)(dir); current !== parent; parent = (0, import_node_path5.dirname)(current)) {
+      if (readExtensionPackage(current).name === name) {
+        return current;
+      }
+      current = parent;
+    }
+    return void 0;
+  }
+}
+function resolveProjectEntry(name, root) {
+  let file;
+  try {
+    file = (0, import_node_module2.createRequire)((0, import_node_path5.resolve)(root, "noop.js")).resolve(name);
+  } catch {
+    return void 0;
+  }
+  return { file, importable: (0, import_core6.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_core6.localExtensionsFile)(root);
+  let current;
+  try {
+    current = (0, import_node_fs5.readFileSync)(file, "utf8");
+  } catch {
+    current = "[]";
+  }
+  (0, import_node_fs5.mkdirSync)((0, import_node_path5.dirname)(file), { recursive: true });
+  (0, import_node_fs5.writeFileSync)(file, (0, import_core6.serializeLocalExtensions)([...(0, import_core6.parseLocalExtensions)(current), name]));
+}
+async function addLocal(options, request) {
+  const { io: io2, root } = options;
+  if (options.ci === true) {
+    throw new AddLocalInCiError(request.name);
+  }
+  const dir = resolvePackageDir(request.name, root);
+  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,
+    dir,
+    name: request.name,
+    version: installed.version ?? "unpublished",
+    attested: false,
+    local: true,
+    types: installed.types
+  });
+  recordLocalExtension(root, request.name);
+  io2.out(`\u2713 ${request.name} resolves from this project and imports \u2014 nothing is pinned`);
+  io2.out(`\u2713 ${import_core6.LOCAL_EXTENSIONS_PATH} records it`);
+  io2.out(`\u2713 ${declaration} declares its config type`);
+  await offerConfigEdit(options, request.name);
+  return { onboard: await offerOnboarding(io2, request.name, installed.onboard) };
+}
 async function add(options) {
   const { io: io2, fetcher, home, root, manifestFile } = options;
   const request = parseRequest(options.argv);
+  if (request.local) {
+    return addLocal(options, request);
+  }
   const tier = tierOf(request);
   const now = (options.now ?? (() => /* @__PURE__ */ new Date()))();
   if (options.noDownload === true) {
@@ -1193,6 +1331,7 @@ async function add(options) {
     },
     fetcher
   });
+  await assertLoadable(release.name, (0, import_core6.packageEntry)(dir), false);
   const installed = readExtensionPackage(dir);
   const declaration = writeDeclaration({
     root,
@@ -1211,14 +1350,46 @@ async function add(options) {
   return { onboard: await offerOnboarding(io2, release.name, installed.onboard) };
 }
 
-// src/pins.ts
+// src/help.ts
 var import_core7 = require("@penvhq/core");
+function printLauncherCommands(io2) {
+  io2.out("");
+  io2.out("LAUNCHER COMMANDS (penv itself, whatever engine a project pins)");
+  io2.out("");
+  io2.out(`  install                Installs everything ${import_core7.MANIFEST_PATH} pins`);
+  io2.out("  add <package>          Pins a provider extension, and commits the decision");
+  io2.out(`  add ${LOCAL_FLAG} <package>  Adds the one this repository builds \u2014 nothing is pinned`);
+  io2.out("");
+}
+function printInstallHelp(io2) {
+  io2.out(`${INSTALL_COMMAND}`);
+  io2.out("");
+  io2.out(`Downloads, verifies and installs every version ${import_core7.MANIFEST_PATH} pins \u2014 the engine and`);
+  io2.out("every extension \u2014 into $PENV_HOME. The one penv command CI and production run that");
+  io2.out("may reach the registry.");
+}
+function printAddHelp(io2) {
+  io2.out("penv add <package>[@<version>]");
+  io2.out("");
+  io2.out(`  ${LOCAL_FLAG}            Add the package this repository builds, resolved from it`);
+  io2.out("  --registry <url>   Take the release from a private registry instead of npmjs");
+  io2.out(
+    `  ${TRUST_YOUNG_FLAG}      Add a release published less than ${MIN_PACKAGE_AGE_DAYS} days ago`
+  );
+  io2.out("");
+  io2.out(`Pins the release in ${import_core7.MANIFEST_PATH} and writes its type declaration to`);
+  io2.out(`${import_core7.EXTENSIONS_PATH}/. Both are committed, so \`${INSTALL_COMMAND}\` gives every machine`);
+  io2.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.4",
-  integrity: "sha512-XnG+KlEAZyUaaKUfANPiyhY1dfYZ9KgnkF2R+5A0OskRgfYPSpBRN0i1UPtq8RnwMJaPxfSNDNdqfiiESz6kRw=="
+  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) {
@@ -1236,8 +1407,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 (; ; ) {
@@ -1256,7 +1427,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
@@ -1305,14 +1476,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);
   }
@@ -1325,7 +1496,7 @@ function readManifestToRepair(manifestFile, home, argv) {
   }
 }
 function report(error, io2) {
-  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;
@@ -1347,7 +1518,17 @@ async function launch(options) {
   const { argv, cwd, env, io: io2 } = 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(io2);
+      return 0;
+    }
+    if (first === ADD) {
+      printAddHelp(io2);
+      return 0;
+    }
+  }
   const project = findProject(cwd);
   if (project === void 0) {
     if (first !== void 0 && VERSION_FLAGS.has(first)) {
@@ -1392,16 +1573,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 },
@@ -1480,13 +1661,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;
 }
 
 // src/bin.ts