libretto 0.5.3-experimental.2 → 0.5.3-experimental.4

package/dist/cli/commands/deploy.js

@@ -73,7 +73,7 @@ const deployInput = SimpleCLI.input({
         (value) => value?.split(",").map((entry) => entry.trim()).filter((entry) => entry.length > 0) ?? []
       ),
       {
-        help: "Comma-separated packages to externalize and install at runtime"
+        help: "Comma-separated packages to keep out of the bundle and install into the deployed package"
       }
     )
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libretto",
-  "version": "0.5.3-experimental.2",
+  "version": "0.5.3-experimental.4",
   "description": "AI-powered browser automation library and CLI built on Playwright",
   "license": "MIT",
   "repository": {

package/src/cli/commands/deploy.ts

@@ -113,7 +113,8 @@ export const deployInput = SimpleCLI.input({
             .filter((entry) => entry.length > 0) ?? [],
         ),
       {
-        help: "Comma-separated packages to externalize and install at runtime",
+        help:
+          "Comma-separated packages to keep out of the bundle and install into the deployed package",
       },
     ),
   },
@@ -127,6 +128,9 @@ export const deployCommand = SimpleCLI.command({
   .handle(async ({ input }) => {
     const { apiUrl, apiKey } = getConfig();
 
+    // Hosted deploy uploads a generated artifact with a deploy entrypoint and
+    // a minimal manifest. Bundled code is embedded in the generated files;
+    // external packages are listed in the manifest for installation.
     console.log("Bundling hosted deployment artifact...");
     const { entryPoint, source } = await buildHostedDeployTarball({
       additionalExternals: input.external,

package/src/cli/core/deploy-artifact.ts

@@ -441,6 +441,9 @@ function workspaceSourcePlugin(
         callback: (args: { path: string }) => { path: string } | null,
       ) => void;
     }) {
+      // Workspace imports are treated as bundle input, so their code is
+      // embedded into the generated implementation file. The deployed package
+      // does not depend on the original monorepo layout or workspace:* links.
       buildApi.onResolve({ filter: /^[^./].*/ }, (args) => {
         if (externalPackages.has(args.path)) {
           return null;
@@ -640,6 +643,10 @@ function createBootstrapSource(args: {
     ? 'export default createWorkflowProxy("default");'
     : "";
 
+  // The deploy entrypoint is tiny on purpose. Hosted build imports this module
+  // to discover workflow exports. The implementation bundle stays embedded in
+  // the file, while external packages are resolved from node_modules when the
+  // deployed code loads them.
   return `import { createRequire } from "node:module";
 import { existsSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -696,6 +703,9 @@ export async function createHostedDeployPackage(
   mkdirSync(outputDir, { recursive: true });
 
   const additionalExternals = [...new Set(args.additionalExternals ?? [])];
+  // These packages stay out of the implementation bundle. The generated
+  // package.json carries them into deploy-time installation, and the deployed
+  // code resolves them from node_modules.
   const externalPackages = new Set<string>([
     ...DEFAULT_RUNTIME_EXTERNALS,
     ...additionalExternals,
@@ -703,6 +713,9 @@ export async function createHostedDeployPackage(
   const workspacePackages = discoverWorkspacePackages(absSourceDir);
 
   try {
+    // The implementation bundle is CommonJS so the bootstrap can load it lazily
+    // with createRequire() after workflow discovery, while external packages
+    // continue to load through normal Node module resolution.
     const implementationBuild = await build({
       absWorkingDir: absSourceDir,
       bundle: true,
@@ -724,6 +737,9 @@ export async function createHostedDeployPackage(
       throw new Error("Bundler did not produce a deployment implementation file.");
     }
 
+    // A separate ESM bundle is used only to read the entry module's exported
+    // workflow names. Scanning the CommonJS bundle would also see exports from
+    // bundled dependencies, which is not the deploy surface.
     const exportBuild = await build({
       absWorkingDir: absSourceDir,
       bundle: true,
@@ -767,6 +783,9 @@ export async function createHostedDeployPackage(
     );
   }
 
+  // The generated manifest lists only packages that stay outside the
+  // implementation bundle. Hosted deploy installs them into the deployed
+  // package, and the deployed code loads them from node_modules.
   writeDeployManifest({
     additionalExternals,
     deploymentName: args.deploymentName,