neonctl 2.24.1 → 2.25.0

package/commands/dev.js

@@ -56,6 +56,7 @@ const runSingleSource = async (props) => {
         ...(props.projectId ? { projectId: props.projectId } : {}),
         ...(branchId ? { branchId } : {}),
         ...(props.apiKey ? { apiKey: props.apiKey } : {}),
+        ...(props.apiHost ? { apiHost: props.apiHost } : {}),
     });
     const unit = {
         slug: null,
@@ -93,6 +94,7 @@ const runFromConfig = async (props) => {
         ...(props.projectId ? { projectId: props.projectId } : {}),
         ...(branchId ? { branchId } : {}),
         ...(props.apiKey ? { apiKey: props.apiKey } : {}),
+        ...(props.apiHost ? { apiHost: props.apiHost } : {}),
     });
     const units = planFunctionsToUnits(functions, neonEnv, DEFAULT_PORT_BASE);
     // Re-derive the units from neon.ts on demand so the config watcher can hot-add/remove
@@ -114,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.
  */
@@ -122,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);
     });
@@ -160,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,
@@ -188,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 } } : {}),
     };
 };
 /**
@@ -210,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+)/;
@@ -219,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);
@@ -378,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".
@@ -434,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…'));
@@ -477,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 });
@@ -689,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,7 +55,9 @@ 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 } : {}),
     });
     const neonVars = pickNeonVars(vars);
@@ -57,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 };

package/commands/functions.js

@@ -21,6 +21,23 @@ const DEPLOYMENT_FIELDS = [
     'memory_mib',
     'created_at',
 ];
+// Deploy emits the resolved deployment plus the function's invocation_url, so a
+// successful `functions deploy` tells the user exactly where to call the function.
+const DEPLOY_RESULT_FIELDS = [
+    'id',
+    'status',
+    'invocation_url',
+    'runtime',
+    'memory_mib',
+    'created_at',
+];
+// In table mode a failed build's reason gets its own "deployment error"
+// section after the deployment table; json/yaml carry the raw `error` field.
+const writeDeploymentErrorSection = (out, dep) => {
+    if (dep.status === 'failed' && dep.error) {
+        out.write({ reason: dep.error }, { fields: ['reason'], title: 'deployment error' });
+    }
+};
 const SLUG_PATTERN = /^[a-z0-9]{1,20}$/;
 const SLUG_HELP = 'Use 1-20 lowercase letters and digits (no hyphens or other characters).';
 // Overridable so tests can poll fast; defaults to 2s in real use.
@@ -77,10 +94,19 @@ export const builder = (argv) => argv
     },
 }), (args) => deploy(args))
     .command('list', 'List functions on the branch', (yargs) => yargs, (args) => list(args))
-    .command('get <slug>', "Show a function's details", (yargs) => yargs.positional('slug', {
+    .command('get <slug>', "Show a function's details", (yargs) => yargs
+    .positional('slug', {
     describe: 'Function slug',
     type: 'string',
     demandOption: true,
+})
+    .options({
+    'list-env-variables': {
+        describe: 'List the environment variable names of the active deployment',
+        type: 'boolean',
+        alias: 'E',
+        default: false,
+    },
 }), (args) => get(args))
     .command('delete <slug>', 'Delete a function on the branch', (yargs) => yargs.positional('slug', {
     describe: 'Function slug',
@@ -104,6 +130,15 @@ const parseEnv = (entries) => {
     return JSON.stringify(map);
 };
 const statusHint = (slug, projectId, branchId) => `Check status with: neonctl functions get ${slug} --project-id ${projectId} --branch ${branchId}`;
+// Emit the resolved deployment together with the function's invocation_url, so the
+// deploy output shows where the function is reachable (not just the deployment id).
+const emitDeployResult = (props, deployment, fn) => {
+    const out = writer(props).write({ ...deployment, invocation_url: fn?.invocation_url }, { fields: DEPLOY_RESULT_FIELDS });
+    if (props.output !== 'json' && props.output !== 'yaml') {
+        writeDeploymentErrorSection(out, deployment);
+    }
+    out.end();
+};
 // A poll error worth retrying: a network error (no HTTP response), a 5xx, or a
 // 404 from eventual consistency. Anything else (e.g. 401/403) is surfaced.
 const isTransient = (err) => isAxiosError(err) &&
@@ -165,6 +200,9 @@ const deploy = async (props) => {
     // any version if there was none). --no-wait stops there; --wait stops at a
     // terminal status. Bounded by POLL_TIMEOUT_MS so it never hangs.
     let resolved;
+    // The function carries the invocation_url; keep the whole record (not just its
+    // active_deployment) so we can surface that URL on success.
+    let resolvedFn;
     const deadline = Date.now() + POLL_TIMEOUT_MS;
     try {
         while (!interrupted && Date.now() < deadline) {
@@ -173,18 +211,20 @@ const deploy = async (props) => {
                 break;
             // The deploy already succeeded server-side; tolerate transient poll
             // failures and retry on the next interval. Surface anything else.
-            let dep;
+            let fn;
             try {
-                dep = (await getFunction(props.apiClient, props.projectId, branchId, props.slug)).active_deployment;
+                fn = await getFunction(props.apiClient, props.projectId, branchId, props.slug);
             }
             catch (err) {
                 if (isTransient(err))
                     continue;
                 throw err;
             }
+            const dep = fn.active_deployment;
             const isNew = dep !== undefined && (before === undefined || dep.id > before);
             if (isNew && dep) {
                 resolved = dep;
+                resolvedFn = fn;
                 if (!props.wait)
                     break;
                 if (dep.status === 'completed' || dep.status === 'failed')
@@ -199,14 +239,14 @@ const deploy = async (props) => {
     if (interrupted) {
         log.info(statusHint(props.slug, props.projectId, branchId));
         if (resolved)
-            writer(props).end(resolved, { fields: DEPLOYMENT_FIELDS });
+            emitDeployResult(props, resolved, resolvedFn);
         return;
     }
     if (resolved === undefined) {
         log.info(statusHint(props.slug, props.projectId, branchId));
         throw new Error(`Timed out waiting for the deployment of ${props.slug} to start. It may still be in progress.`);
     }
-    writer(props).end(resolved, { fields: DEPLOYMENT_FIELDS });
+    emitDeployResult(props, resolved, resolvedFn);
     if (!props.wait) {
         log.info(statusHint(props.slug, props.projectId, branchId));
         return;
@@ -238,6 +278,14 @@ const get = async (props) => {
             fields: DEPLOYMENT_FIELDS,
             title: 'active deployment',
         });
+        writeDeploymentErrorSection(out, fn.active_deployment);
+    }
+    if (props.listEnvVariables) {
+        out.write((fn.active_deployment?.environment ?? []).map((name) => ({ name })), {
+            fields: ['name'],
+            title: 'environment',
+            emptyMessage: 'No environment variables on the active deployment.',
+        });
     }
     out.end();
 };

package/commands/index.js

@@ -22,6 +22,7 @@ import * as config from './config.js';
 import * as deploy from './deploy.js';
 import * as env from './env.js';
 import * as bucket from './bucket.js';
+import * as bootstrap from './bootstrap.js';
 export default [
     auth,
     users,
@@ -47,4 +48,5 @@ export default [
     deploy,
     env,
     bucket,
+    bootstrap,
 ];