neonctl 2.24.2 → 2.25.0

package/commands/bucket.js

@@ -1,16 +1,21 @@
-import { createWriteStream } from 'node:fs';
-import { unlink } from 'node:fs/promises';
+import { createReadStream, createWriteStream } from 'node:fs';
+import { stat, unlink } from 'node:fs/promises';
 import { basename } from 'node:path';
 import { pipeline } from 'node:stream/promises';
-import { isAxiosError } from 'axios';
+import axios, { isAxiosError } from 'axios';
 import { retryOnLock } from '../api.js';
 import { branchIdFromProps, fillSingleProject } from '../utils/enrichers.js';
 import { log } from '../log.js';
 import { writer } from '../writer.js';
-import { createProjectBranchBucket, listProjectBranchBuckets, deleteProjectBranchBucket, listProjectBranchBucketObjects, getProjectBranchBucketObject, deleteProjectBranchBucketObject, deleteProjectBranchBucketObjectsByPrefix, } from '../storage_api.js';
+import { createProjectBranchBucket, listProjectBranchBuckets, deleteProjectBranchBucket, listProjectBranchBucketObjects, getProjectBranchBucketObject, deleteProjectBranchBucketObject, deleteProjectBranchBucketObjectsByPrefix, presignUpload, } from '../storage_api.js';
 const OBJECT_FIELDS = ['key', 'size', 'last_modified', 'etag'];
 const BUCKET_FIELDS = ['name', 'access_level'];
 const ACCESS_LEVELS = ['private', 'public_read'];
+// Single-PUT upload cap. Objects larger than this must use multipart upload,
+// which is out of scope for v1; we reject them client-side before any HTTP so
+// the user gets an immediate, clear error rather than a server-side rejection
+// part-way through a large transfer.
+const MAX_OBJECT_BYTES = 100 * 1024 * 1024; // 100 MB
 // Ambient scope shared by every bucket sub-command. The bucket name (and the
 // object key/prefix) is always a positional, never a flag.
 const scopeOptions = {
@@ -85,7 +90,7 @@ export const builder = (argv) => argv
         .options(scopeOptions),
     handler: (args) => deleteBucket(args),
 })
-    .command('object <sub-command>', 'List, download or delete objects in a bucket', (yargs) => yargs
+    .command('object <sub-command>', 'List, download, upload or delete objects in a bucket', (yargs) => yargs
     .usage('$0 bucket object <sub-command> [options]')
     .command({
     command: 'list <target>',
@@ -129,6 +134,25 @@ export const builder = (argv) => argv
         type: 'string',
     },
 }), (args) => getObject(args))
+    .command('put <target>', 'Upload a local file to a bucket as an object', (yargs) => yargs
+    .usage('$0 bucket object put <bucket>/<key> [options]')
+    .positional('target', {
+    describe: 'The object to upload to: <bucket>/<key>',
+    type: 'string',
+    demandOption: true,
+})
+    .options({
+    ...scopeOptions,
+    file: {
+        describe: 'Path to the local file to upload',
+        type: 'string',
+        demandOption: true,
+    },
+    'content-type': {
+        describe: 'Content-Type to store the object with (e.g. text/plain)',
+        type: 'string',
+    },
+}), (args) => putObject(args))
     .command({
     command: 'delete <target>',
     aliases: ['rm'],
@@ -328,6 +352,95 @@ const getObject = async (props) => {
     }
     log.info(`Object "${key}" downloaded from bucket "${bucket}" on branch ${branchId} to ${destination}`);
 };
+const putObject = async (props) => {
+    const branchId = await branchIdFromProps(props);
+    const { bucket, rest: key } = splitBucketTarget(props.target);
+    if (bucket === '' || key === '') {
+        throw new Error('Object target must be in the form <bucket>/<key>.');
+    }
+    // Stat the file first so we fail fast on a missing/unreadable file and can
+    // enforce the single-PUT size cap BEFORE any network round-trip. We also
+    // reuse the byte count as the PUT Content-Length so the stream is uploaded
+    // without buffering the whole file in memory.
+    let fileSize;
+    try {
+        const fileStat = await stat(props.file);
+        if (!fileStat.isFile()) {
+            throw new Error(`"${props.file}" is not a regular file.`);
+        }
+        fileSize = fileStat.size;
+    }
+    catch (err) {
+        if (err?.code === 'ENOENT') {
+            throw new Error(`File "${props.file}" does not exist.`);
+        }
+        throw err;
+    }
+    if (fileSize > MAX_OBJECT_BYTES) {
+        throw new Error(`File "${props.file}" is ${fileSize} bytes, which exceeds the ${MAX_OBJECT_BYTES}-byte (100 MB) single-upload limit. Larger objects are not supported yet.`);
+    }
+    // Ask the console for a presigned PUT URL plus the headers that must travel
+    // with the upload for the signature to verify. No SigV4 happens in neonctl.
+    let presign;
+    try {
+        ({ data: presign } = await presignUpload(props.apiClient, {
+            projectId: props.projectId,
+            branchId,
+            bucketName: bucket,
+            objectKey: key,
+            contentType: props.contentType,
+        }));
+    }
+    catch (err) {
+        if (isAxiosError(err)) {
+            const status = err.response?.status;
+            if (status === 404) {
+                throw new Error(objectNotFoundMessage(err, key, bucket, branchId));
+            }
+            // Any other HTTP error from the console (e.g. 403 when the caller lacks
+            // write permission on the bucket) carries the same JSON `{ message }`
+            // body, so surface that rather than a bare axios message. When the body
+            // has no usable message, fall back to a clean status-bearing error.
+            const serverMessage = serverErrorMessage(err.response?.data);
+            throw new Error(serverMessage ??
+                `Failed to presign upload for "${key}" in bucket "${bucket}" on branch ${branchId}${status !== undefined ? ` (HTTP ${status})` : ''}: ${err.message}`);
+        }
+        throw err;
+    }
+    // Stream the file straight into the PUT body; never buffer the whole file.
+    // The presigned URL targets the branch S3 data-plane endpoint directly, so
+    // this PUT goes through a plain axios call rather than the console api-client.
+    //
+    // `presign.headers` carries the signature-relevant headers (e.g. host,
+    // content-type); the server does not sign Content-Length, so we set it
+    // ourselves from the stat'd size to keep the upload streamed, not chunked.
+    // `maxRedirects: 0` ensures we never resend the file bytes and signed headers
+    // to a different host if the data-plane endpoint were to answer with a
+    // redirect.
+    try {
+        await axios.put(presign.url, createReadStream(props.file), {
+            headers: {
+                ...presign.headers,
+                'Content-Length': fileSize,
+            },
+            maxBodyLength: Infinity,
+            maxContentLength: Infinity,
+            maxRedirects: 0,
+        });
+    }
+    catch (err) {
+        // The upload targets the S3 data plane, whose error bodies are XML rather
+        // than the JSON `{ message }` the console returns, so surface the status
+        // (and axios message) rather than leaking a raw error. Never include the
+        // presigned URL, which carries the signature.
+        if (isAxiosError(err)) {
+            const status = err.response?.status;
+            throw new Error(`Failed to upload "${props.file}" to "${key}" in bucket "${bucket}" on branch ${branchId}${status !== undefined ? ` (HTTP ${status})` : ''}: ${err.message}`);
+        }
+        throw err;
+    }
+    log.info(`File "${props.file}" uploaded to "${key}" in bucket "${bucket}" on branch ${branchId}`);
+};
 const deleteObject = async (props) => {
     const branchId = await branchIdFromProps(props);
     const { bucket, rest } = splitBucketTarget(props.target);

package/commands/checkout.js

@@ -52,16 +52,17 @@ export const handler = async (props) => {
     // (--project-id flag > .neon file > single-project auto-detect); when
     // nothing resolves, fall back to an interactive `neonctl link`.
     const projectId = await resolveProjectId(props);
-    const { branchId, created, policyApplied } = await resolveBranchId(props, projectId);
+    const { branchId, branchName, created, policyApplied } = await resolveBranchId(props, projectId);
     const orgId = await resolveOrgId(props, projectId);
-    // `checkout` is a thin helper over `set-context`. It fully "heals" the
-    // context file: it always (re)writes `projectId`, `branchId`, and `orgId`
-    // (when the project has one) so a `.neon` that drifted or was missing fields
-    // ends up complete and consistent after checkout.
+    // `checkout` is a thin helper over `link`. It fully "heals" the context file:
+    // it always (re)writes `projectId`, `branch`, and `orgId` (when the project
+    // has one) so a `.neon` that drifted or was missing fields ends up complete
+    // and consistent after checkout. The branch is stored as its name when known
+    // (see `link`'s `branch` field), matching what `link` writes.
     applyContext(props.contextFile, {
         projectId,
         ...(orgId ? { orgId } : {}),
-        branchId,
+        branch: branchName,
     });
     log.info('Checked out branch %s on project %s%s. Updated %s.', branchId, projectId, orgId ? ` (org ${orgId})` : '', props.contextFile);
     // When checkout *created* the branch and a neon.ts exists, the branch was created straight
@@ -96,8 +97,10 @@ const resolveBranchId = async (props, projectId) => {
                 'or run interactively to pick one from a list.',
         });
         if (picked.kind === 'existing') {
+            const existing = branches.find((b) => b.id === picked.branchId);
             return {
                 branchId: picked.branchId,
+                branchName: existing?.name ?? picked.branchId,
                 created: false,
                 policyApplied: false,
             };
@@ -110,13 +113,23 @@ const resolveBranchId = async (props, projectId) => {
     if (looksLikeBranchId(ref)) {
         const byId = branches.find((b) => b.id === ref);
         if (byId) {
-            return { branchId: byId.id, created: false, policyApplied: false };
+            return {
+                branchId: byId.id,
+                branchName: byId.name ?? byId.id,
+                created: false,
+                policyApplied: false,
+            };
         }
         throw new Error(notFoundMessage(ref, branches));
     }
     const byName = branches.find((b) => b.name === ref);
     if (byName) {
-        return { branchId: byName.id, created: false, policyApplied: false };
+        return {
+            branchId: byName.id,
+            branchName: byName.name ?? byName.id,
+            created: false,
+            policyApplied: false,
+        };
     }
     // Name not found: offer to create it interactively, mirroring `branch create`.
     if (isCi() || !process.stdout.isTTY) {
@@ -151,12 +164,14 @@ const createCheckoutBranch = async (props, projectId, name, branches) => {
     if (fromPolicy) {
         return {
             branchId: fromPolicy.branchId,
+            branchName: name,
             created: true,
             policyApplied: true,
         };
     }
     return {
         branchId: await createBranch(props.apiClient, projectId, name, branches),
+        branchName: name,
         created: true,
         policyApplied: false,
     };
@@ -229,6 +244,8 @@ const resolveProjectId = async (props) => {
         ...props,
         agent: false,
         yes: false,
+        clear: false,
+        checks: true,
     });
     const linked = readContextFile(props.contextFile);
     if (!linked.projectId) {

package/commands/config.js

@@ -7,6 +7,7 @@ import { branchIdFromProps, fillSingleProject } from '../utils/enrichers.js';
 import { bundleEntry } from '../utils/esbuild.js';
 import { zipBundle } from '../utils/zip.js';
 import { writer } from '../writer.js';
+import { autoPullEnvAfterPin } from './env.js';
 /**
  * Bundle a function with neonctl's OWN bundler (the shared esbuild helper) so the
  * config-runtime never has to import esbuild itself. Injecting this keeps esbuild
@@ -16,6 +17,7 @@ import { writer } from '../writer.js';
 const neonctlBundler = async (fn) => zipBundle(await bundleEntry(fn.source));
 const INSPECT_FIELDS = ['project', 'branch', 'config'];
 const APPLIED_FIELDS = ['action', 'kind', 'identifier', 'details'];
+const FUNCTION_FIELDS = ['slug', 'invocation_url'];
 const CONFLICT_FIELDS = [
     'identifier',
     'field',
@@ -47,6 +49,20 @@ export const applyFlags = {
         default: false,
     },
 };
+/**
+ * `--env-pull` for `config apply` / `deploy` (shared so both expose the identical surface).
+ * After a successful apply, the branch's Neon env vars are written to a local `.env` — the
+ * same bundled convenience as `link` / `checkout`. On by default; `--no-env-pull` opts out.
+ */
+export const envPullFlag = {
+    'env-pull': {
+        describe: "Pull the branch's Neon env vars (DATABASE_URL, …) into a local .env after a " +
+            'successful apply. On by default; use --no-env-pull to skip (e.g. when injecting ' +
+            'env at runtime with `neon-env run` / `neon dev`).',
+        type: 'boolean',
+        default: true,
+    },
+};
 export const command = 'config';
 export const describe = 'Manage a branch with a neon.ts policy';
 export const builder = (argv) => argv
@@ -85,6 +101,7 @@ export const builder = (argv) => argv
     },
     ...envFlag,
     ...applyFlags,
+    ...envPullFlag,
 }), (args) => applyCmd(args));
 export const handler = (args) => {
     return args;
@@ -145,7 +162,7 @@ export const planCmd = async (props) => {
         ...(props.apiHost ? { apiHost: props.apiHost } : {}),
         ...(props.runtimeApi ? { api: props.runtimeApi } : {}),
     });
-    reportPushResult(props, result, 'plan');
+    reportPushResult(props, result, 'plan', utilizedServices(config));
 };
 export const applyCmd = async (props) => {
     const config = await loadConfig(props);
@@ -160,16 +177,62 @@ export const applyCmd = async (props) => {
         ...(props.allowProtected ? { allowProtectedBranch: true } : {}),
         bundleFunction: neonctlBundler,
     });
-    reportPushResult(props, result, 'apply');
+    reportPushResult(props, result, 'apply', utilizedServices(config));
+    // After a successful apply/deploy, write the branch's Neon env vars to a local .env —
+    // the same bundled convenience as `link` / `checkout`, so the branch is immediately
+    // usable for local dev. `--no-env-pull` opts out; a pull failure degrades to a warning
+    // (the apply already succeeded). See autoPullEnvAfterPin.
+    await autoPullEnvAfterPin({ ...props, envPull: props.envPull !== false });
+};
+/**
+ * A static service toggle (`auth` / `dataApi` / `preview.aiGateway`) is "on" unless
+ * explicitly disabled: `true` / `{}` / `{ enabled: true }` enable it; `false` /
+ * `{ enabled: false }` / absent leave it off. Mirrors the runtime's `isServiceEnabled`
+ * (which isn't exported), kept tiny and pure so it can be read straight off the policy.
+ */
+const isToggleEnabled = (toggle) => {
+    if (toggle === undefined)
+        return false;
+    if (typeof toggle === 'boolean')
+        return toggle;
+    return toggle.enabled !== false;
+};
+/**
+ * Human-readable list of the services a `neon.ts` policy utilizes on the branch, shown under
+ * the plan/apply table. Postgres is always present (every branch has it); the rest are listed
+ * only when the policy declares them. This deliberately surfaces services that produce **no**
+ * plan step — notably the AI Gateway, which is always available and only needs a scoped branch
+ * credential (not a provisioning step) — so adding `preview.aiGateway` to a neon.ts isn't
+ * mistaken for being silently dropped. Service enablement is static top-level config (it never
+ * lives in the per-branch closure), so reading it straight off `config` is accurate.
+ */
+const utilizedServices = (config) => {
+    const services = ['Postgres'];
+    if (isToggleEnabled(config.auth))
+        services.push('Neon Auth');
+    if (isToggleEnabled(config.dataApi))
+        services.push('Data API');
+    if (Object.keys(config.preview?.buckets ?? {}).length > 0) {
+        services.push('Object Storage');
+    }
+    if (Object.keys(config.preview?.functions ?? {}).length > 0) {
+        services.push('Functions');
+    }
+    if (isToggleEnabled(config.preview?.aiGateway))
+        services.push('AI Gateway');
+    return services;
 };
 /**
- * Render a {@link PushResult}. JSON/YAML output emits the raw result verbatim so it
- * can be piped; the human-readable path renders the actual changes (dropping noops)
- * and any blocking conflicts as tables, or a "nothing to do" line when both are empty.
+ * Render a {@link PushResult}. JSON/YAML output emits the raw result (plus a `services`
+ * summary) verbatim so it can be piped; the human-readable path renders the actual changes
+ * (dropping noops) and any blocking conflicts as tables, or a "nothing to do" line when both
+ * are empty — and always closes with the list of services the policy utilizes so a service
+ * that produces no plan step (Postgres, or the credential-gated AI Gateway) isn't mistaken
+ * for being missing from the plan above.
  */
-const reportPushResult = (props, result, mode) => {
+const reportPushResult = (props, result, mode, services) => {
     if (props.output === 'json' || props.output === 'yaml') {
-        writer(props).end(result, { fields: [] });
+        writer(props).end({ ...result, services }, { fields: [] });
         return;
     }
     const changes = result.applied
@@ -187,21 +250,46 @@ const reportPushResult = (props, result, mode) => {
         desired: stringify(conflict.desired),
         reason: conflict.reason,
     }));
-    if (changes.length === 0 && conflicts.length === 0) {
-        log.info(`No changes — branch ${result.branchName} already matches the policy.`);
-        return;
+    // Deployed functions carry their invocation URL in the change details — pull them into a
+    // dedicated table so users can see where to call each function without digging through the
+    // raw details blob. Keyed by slug so a function never shows twice.
+    const functionUrlBySlug = new Map();
+    for (const change of result.applied) {
+        if (change.action === 'noop')
+            continue;
+        const slug = change.details?.slug;
+        const invocationUrl = change.details?.invocationUrl;
+        if (typeof slug === 'string' && typeof invocationUrl === 'string') {
+            functionUrlBySlug.set(slug, invocationUrl);
+        }
     }
+    const functions = [...functionUrlBySlug].map(([slug, invocation_url]) => ({
+        slug,
+        invocation_url,
+    }));
     const out = writer(props);
+    const noChanges = changes.length === 0 && conflicts.length === 0;
     if (changes.length > 0) {
         out.write(changes, {
             fields: APPLIED_FIELDS,
             title: mode === 'plan' ? 'Planned changes' : 'Applied changes',
         });
     }
+    if (functions.length > 0) {
+        out.write(functions, {
+            fields: FUNCTION_FIELDS,
+            title: mode === 'plan' ? 'Function URLs (after apply)' : 'Function URLs',
+        });
+    }
     if (conflicts.length > 0) {
         out.write(conflicts, { fields: CONFLICT_FIELDS, title: 'Conflicts' });
     }
+    // Flush any tables, then append the summary so it reads directly below them.
     out.end();
+    if (noChanges) {
+        log.info(`No changes — branch ${result.branchName} already matches the policy.`);
+    }
+    out.text(`\nUtilized services: ${services.join(', ')}\n`);
     if (conflicts.length > 0) {
         log.info('Resolve the conflicts above, or re-run with --update-existing to override the current remote settings.');
     }

package/commands/deploy.js

@@ -1,5 +1,5 @@
 import { fillSingleProject } from '../utils/enrichers.js';
-import { applyCmd, applyFlags, envFlag } from './config.js';
+import { applyCmd, applyFlags, envFlag, envPullFlag, } from './config.js';
 export const command = 'deploy';
 export const describe = 'Apply a neon.ts policy to a branch (alias for `config apply`)';
 export const builder = (argv) => argv
@@ -19,6 +19,7 @@ export const builder = (argv) => argv
     },
     ...envFlag,
     ...applyFlags,
+    ...envPullFlag,
 })
     .middleware(fillSingleProject)
     .strict();

package/commands/dev.js

@@ -116,7 +116,7 @@ const runFromConfig = async (props) => {
  * Map a list of {@link PlannedFunction}s to {@link ServedUnit}s, coordinating the search
  * base across them so search-mode functions don't all probe the same starting port.
  *
- * Each search-mode (no `dev.port`, non-portless) function gets a distinct base starting at
+ * Each search-mode (no `dev.port`) function gets a distinct base starting at
  * `searchBase`; the runtime still walks upward from its base, so an occupied base
  * self-resolves and this never fails — the offset just makes startup deterministic.
  */
@@ -124,7 +124,7 @@ const planFunctionsToUnits = (functions, neonEnv, searchBase) => {
     let searchOffset = 0;
     return functions.map((fn) => {
         const base = searchBase + searchOffset;
-        if (!fn.portless && fn.port === undefined)
+        if (fn.port === undefined)
             searchOffset += 1;
         return plannedToUnit(fn, neonEnv, base);
     });
@@ -162,19 +162,14 @@ const portFromProps = (port) => {
 };
 /**
  * Translate a {@link PlannedFunction} into a {@link ServedUnit}. Port rules:
- *   - portless: portless assigns the port and injects PORT, which the runtime honors — so
- *     we set no port env (`inherit`) and `dev.port` is ignored. Wrapped with
- *     `portless <slug>` for a stable `slug.localhost` URL.
  *   - explicit `dev.port`: bind exactly, fail if taken.
  *   - no `dev.port`: search for a free port (base coordinated by the caller).
  * Per-function neon.ts env layers over the shared branch env.
  */
 const plannedToUnit = (fn, branchEnv, searchBase) => {
-    const port = fn.portless
-        ? { mode: 'inherit' }
-        : fn.port !== undefined
-            ? { mode: 'explicit', port: fn.port }
-            : { mode: 'search', from: searchBase };
+    const port = fn.port !== undefined
+        ? { mode: 'explicit', port: fn.port }
+        : { mode: 'search', from: searchBase };
     const childEnv = buildChildEnv({ ...branchEnv, ...fn.env }, port);
     return {
         slug: fn.slug,
@@ -190,10 +185,8 @@ const plannedToUnit = (fn, branchEnv, searchBase) => {
         configKey: JSON.stringify({
             source: fn.source,
             port: fn.port ?? null,
-            portless: fn.portless,
             env: fn.env,
         }),
-        ...(fn.portless ? { portless: { slug: fn.slug } } : {}),
     };
 };
 /**
@@ -212,7 +205,6 @@ const buildChildEnv = (neonEnv, port) => {
     else if (port.mode === 'search') {
         env.NEON_DEV_PORT_BASE = String(port.from);
     }
-    // 'inherit': set neither, so an injected PORT (portless) drives the runtime.
     return env;
 };
 const READY_PATTERN = /neon-dev:ready (\d+)/;
@@ -221,20 +213,16 @@ const READY_PATTERN = /neon-dev:ready (\d+)/;
  * its inputs for hot reload, and tear everything down cleanly on shutdown. Units are
  * independent — one crashing or failing to start does not stop the others (it is shown
  * as errored and recovered on the next edit). A single SIGINT/SIGTERM shuts all of them
- * down, tree-killing each child so no descendant (e.g. a portless-wrapped runtime) is
- * orphaned.
+ * down, tree-killing each child so no descendant it spawned is orphaned.
  *
  * In config mode, `reload` lets the supervisor watch `neon.ts` and reconcile the live set
  * of units when it changes: a newly-declared function is hot-added (its own child, watcher,
  * and port) and a removed one is torn down — all without disturbing the functions that
- * stayed the same. A function whose config (env/port/portless/source) changed is restarted
+ * stayed the same. A function whose config (env/port/source) changed is restarted
  * in place; siblings are untouched.
  */
 const runSupervisor = async (units, options = {}) => {
     const { reload, envNote } = options;
-    if (hasPortlessUnit(units)) {
-        assertPortlessAvailable();
-    }
     const runtimePath = resolveRuntimePath();
     let shuttingDown = false;
     const running = units.map(makeRunningUnit);
@@ -380,7 +368,7 @@ const makeRunningUnit = (unit) => ({
  * Pure slug-keyed diff of the live units against the freshly-resolved desired set:
  *   - a slug present now but not before → **add** (new child + watcher + port),
  *   - a slug gone from neon.ts → **remove** (torn down),
- *   - a slug whose config (source/port/portless/env) changed → **restart** in place,
+ *   - a slug whose config (source/port/env) changed → **restart** in place,
  *   - an unchanged slug → left out of the plan entirely (never touched).
  * Functions that stayed the same never die, so an edit that only adds a function is
  * non-disruptive. `desired === null` (neon.ts deleted) is treated as "no functions".
@@ -436,8 +424,6 @@ const reconcileOnce = async (running, replan, ops) => {
     }
     if (ops.isShuttingDown())
         return;
-    if (hasPortlessUnit(desired ?? []))
-        assertPortlessAvailable();
     const plan = diffUnits(running, desired);
     for (const r of plan.remove) {
         logUnit(r.unit, chalk.dim('removed from neon.ts, stopping…'));
@@ -479,50 +465,18 @@ const nextSearchBase = (running) => {
     }
     return max + 1;
 };
-const hasPortlessUnit = (units) => units.some((u) => u.portless !== undefined);
 /**
- * Spawn the child for a unit. A portless unit is wrapped as `portless <slug> node
- * <runtime> <bundle>`: portless assigns a port, injects it as PORT (which the runtime
- * honors), and exposes the server at `slug.localhost`. A plain unit runs the bundled
- * output directly under `node`.
+ * Spawn the child for a unit: the bundled output run directly under `node`.
  *
- * Spawned detached (own process group) so killTree can reap the whole group — important
- * for the portless case, where the tree is portless -> node runtime.
+ * Spawned detached (own process group) so killTree can reap the whole group.
  */
 const spawnChild = (unit, runtimePath, bundlePath) => {
-    if (unit.portless) {
-        return spawn('portless', [unit.portless.slug, process.execPath, runtimePath, bundlePath], {
-            stdio: ['ignore', 'pipe', 'pipe'],
-            env: unit.childEnv,
-            detached: true,
-        });
-    }
     return spawn(process.execPath, [runtimePath, bundlePath], {
         stdio: ['ignore', 'pipe', 'pipe'],
         env: unit.childEnv,
         detached: true,
     });
 };
-/** Fail early with an actionable message if a portless unit is requested but the binary is missing. */
-const assertPortlessAvailable = () => {
-    const result = spawnSyncCheck('portless');
-    if (!result) {
-        throw new Error('A function sets `dev.portless: true`, but the `portless` command was not ' +
-            'found on your PATH. Install it globally (e.g. `npm i -g portless`) or ' +
-            'remove `dev.portless` from the function in neon.ts.');
-    }
-};
-const spawnSyncCheck = (bin) => {
-    try {
-        // Synchronous, no-side-effect probe: `which`/`where` resolves the binary.
-        const probe = process.platform === 'win32' ? 'where' : 'which';
-        const { status } = spawnSync(probe, [bin]);
-        return status === 0;
-    }
-    catch {
-        return false;
-    }
-};
 const writeBundle = async (source, bundleDir) => {
     const files = await bundleEntry(source);
     mkdirSync(bundleDir, { recursive: true });
@@ -691,7 +645,7 @@ const startDirectoryWatcher = async (chokidar, source, restart) => {
 /**
  * Terminate a child and every descendant it spawned. The child is started `detached`, so
  * on POSIX it leads its own process group and a negative-PID signal reaps the group
- * (covering portless -> neonctl -> node). On Windows there are no POSIX groups, so we
+ * (covering the runtime and anything it spawned). On Windows there are no POSIX groups, so we
  * shell out to `taskkill /T` to kill the tree. Escalates SIGTERM -> SIGKILL after 2s.
  */
 const killTree = (child) => {

package/commands/env.js

@@ -1,8 +1,9 @@
 import chalk from 'chalk';
 import { NEON_ENV_VAR_KEYS } from '@neondatabase/env';
+import { existsSync } from 'node:fs';
 import { log } from '../log.js';
 import { resolveNeonEnvVars } from '../dev/env.js';
-import { mergeEnvFile, resolveEnvFilePath } from '../env_file.js';
+import { mergeEnvFile, readEnvFile, resolveEnvFilePath } from '../env_file.js';
 import { branchIdFromProps, fillSingleProject } from '../utils/enrichers.js';
 export const command = 'env';
 export const describe = "Manage a branch's Neon env variables locally";
@@ -41,6 +42,12 @@ const NEON_VAR_NAMES = Object.values(NEON_ENV_VAR_KEYS).flatMap((group) => Objec
 export const pull = async (props) => {
     const cwd = props.cwd ?? process.cwd();
     const branchId = await branchIdFromProps(props);
+    // Resolve the target file first and layer its current contents under the resolver's env
+    // source. This lets `fetchEnv` reuse one-time secrets that are already on disk — Neon Auth
+    // keys and the unified branch credential's `api_token` / `s3_secret_access_key`, which the
+    // API returns exactly once — instead of minting a fresh credential on every pull.
+    const targetPath = resolveEnvFilePath(cwd, props.file);
+    const existingEnv = existsSync(targetPath) ? readEnvFile(targetPath) : {};
     // Reuse `neon dev`'s tiered resolver (neon.ts policy -> plan gate -> fetchEnv, else
     // pullConfig -> fetchEnv). Unlike dev, an unresolved context or failure is surfaced —
     // `env pull` is an explicit action, so it should error rather than write nothing.
@@ -48,6 +55,7 @@ export const pull = async (props) => {
         cwd,
         projectId: props.projectId,
         branchId,
+        env: { ...process.env, ...existingEnv },
         ...(props.apiKey ? { apiKey: props.apiKey } : {}),
         ...(props.apiHost ? { apiHost: props.apiHost } : {}),
         ...(props.runtimeApi ? { api: props.runtimeApi } : {}),
@@ -58,7 +66,6 @@ export const pull = async (props) => {
             'enabled Auth / Data API).');
         return { status: 'empty' };
     }
-    const targetPath = resolveEnvFilePath(cwd, props.file);
     const { written } = mergeEnvFile(targetPath, neonVars);
     log.info('Pulled %d Neon variable%s into %s: %s', written.length, written.length === 1 ? '' : 's', targetPath, written.join(', '));
     return { status: 'written', written, file: targetPath };