neonctl 2.24.2 → 2.25.0

package/commands/projects.js

@@ -349,11 +349,11 @@ The organization ID has been saved in ${props.contextFile}
 
 If you'd like to change the default organization later, use
 
-    neonctl set-context --org-id <org_id>
+    neonctl link --org-id <org_id>
 
 Or to clear the context file and forget the default organization
 
-    neonctl set-context
+    neonctl link --clear
 
 `);
     }

package/commands/set_context.js

@@ -1,6 +1,7 @@
 import { applyContext } from '../context.js';
+import { log } from '../log.js';
 export const command = 'set-context';
-export const describe = 'Set the current context';
+export const describe = 'Deprecated: use `neonctl link`. Set the .neon context (raw write).';
 export const builder = (argv) => argv.usage('$0 set-context [options]').options({
     'project-id': {
         describe: 'Project ID',
@@ -16,6 +17,9 @@ export const builder = (argv) => argv.usage('$0 set-context [options]').options(
     },
 });
 export const handler = (props) => {
+    log.warning('`neonctl set-context` is deprecated and will be removed in a future release. ' +
+        'Use `neonctl link` instead — it verifies inputs and infers the org for you ' +
+        '(or `neonctl link --no-checks` for the same write-without-checks behavior).');
     const context = {
         projectId: props.projectId,
         orgId: props.orgId,

package/config_format.js

@@ -54,13 +54,19 @@ const toPreviewView = (preview) => {
     if (!preview)
         return undefined;
     const out = {};
-    if (preview.aiGatewayEnabled)
-        out.aiGateway = true;
     if (preview.functions.length > 0) {
         out.functions = Object.fromEntries(preview.functions.map((fn) => [fn.slug, { name: fn.name }]));
     }
     if (preview.buckets.length > 0) {
         out.buckets = Object.fromEntries(preview.buckets.map((b) => [b.name, { access: b.access }]));
     }
+    if (preview.credentials.length > 0) {
+        out.credentials = preview.credentials.map((c) => ({
+            id: c.tokenIdShort,
+            ...(c.name ? { name: c.name } : {}),
+            scopes: c.scopes,
+            ...(c.lastUsedAt ? { lastUsedAt: c.lastUsedAt } : {}),
+        }));
+    }
     return Object.keys(out).length > 0 ? out : undefined;
 };

package/context.js

@@ -2,6 +2,12 @@ import { accessSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, normalize, resolve } from 'node:path';
 import { log } from './log.js';
+/**
+ * The branch pinned in a context, reading the current `branch` field and
+ * falling back to the legacy `branchId` so pre-migration `.neon` files keep
+ * working.
+ */
+export const contextBranch = (context) => context.branch ?? context.branchId;
 const CONTEXT_FILE = '.neon';
 const GITIGNORE_FILE = '.gitignore';
 const wrapWithContextFile = (dir) => resolve(dir, CONTEXT_FILE);
@@ -48,7 +54,10 @@ export const readContextFile = (file) => {
     }
 };
 export const enrichFromContext = (args) => {
-    if (args._[0] === 'set-context' || args._[0] === 'link') {
+    // `link` and the deprecated `set-context` manage the context file themselves
+    // and must see the raw flags rather than values pre-filled from an existing
+    // `.neon`, so skip enrichment for both.
+    if (args._[0] === 'link' || args._[0] === 'set-context') {
         return;
     }
     const context = readContextFile(args.contextFile);
@@ -62,16 +71,17 @@ export const enrichFromContext = (args) => {
         !args.id &&
         !args.name &&
         context.projectId === args.projectId) {
-        args.branch = context.branchId;
+        args.branch = contextBranch(context);
     }
 };
 export const updateContextFile = (file, context) => {
     writeFileSync(file, JSON.stringify(context, null, 2));
 };
 /**
- * Shared primitive used by `set-context`, `link`, and `checkout` to persist
- * context. Mirrors the destructive write semantics of `updateContextFile` —
- * any field not present in `context` is dropped from the file.
+ * Shared primitive used by `link`, the deprecated `set-context`, and `checkout`
+ * to persist context. Mirrors the destructive write semantics of
+ * `updateContextFile` — any field not present in `context` is dropped from the
+ * file.
  *
  * `.gitignore` scaffolding only happens when the context file is being
  * *created* (it didn't exist before this write). On updates to an existing
@@ -86,6 +96,24 @@ export const applyContext = (file, context) => {
         ensureGitignored(file);
     }
 };
+/**
+ * Low-level writer for callers that already hold the resolved identifiers and
+ * just need to record them — e.g. `init` or `projects create`, which create a
+ * project and want to link it without the resolution, verification, prompting,
+ * or env-pull that `link` performs.
+ *
+ * Unlike the loose {@link applyContext}, this enforces at the type level that
+ * `orgId` and `projectId` are present, so the `.neon` file never ends up with a
+ * dangling project that has no org. The branch stays optional. It writes through
+ * {@link applyContext}, so the same `.gitignore` scaffolding applies.
+ */
+export const setContext = (file, context) => {
+    applyContext(file, {
+        orgId: context.orgId,
+        projectId: context.projectId,
+        branch: context.branch,
+    });
+};
 /**
  * Make sure the `.gitignore` next to `file` lists the file's basename
  * (currently always `.neon`). Creates the `.gitignore` if it doesn't exist,

package/dev/env.js

@@ -179,6 +179,7 @@ const fetchAndProject = async (config, ctx) => {
         projectId: ctx.projectId,
         branchId: ctx.branchId,
         ...apiOptions(ctx),
+        ...(ctx.env ? { env: ctx.env } : {}),
     });
     return toEntries(env);
 };
@@ -187,6 +188,35 @@ const fetchAndProject = async (config, ctx) => {
  * root. Returns `null` when there is none (the common "no config" case), and
  * surfaces real load errors (e.g. a syntax error in an existing file).
  */
+/**
+ * Substrings that mark a module-resolution failure while loading `neon.ts` —
+ * almost always because the project's dependencies aren't installed yet (the
+ * config imports `@neondatabase/config` & friends). Deliberately specific:
+ * the generic "…or a missing dependency…" hint the loader always appends is
+ * NOT in here, so a real syntax/runtime error doesn't get mislabeled.
+ */
+const MISSING_DEPENDENCY_HINTS = [
+    'cannot find module',
+    'cannot find package',
+    'err_module_not_found',
+    'failed to resolve',
+    'could not resolve',
+    'module not found',
+];
+/** Flatten an error and its `cause` chain to one lowercased string for matching. */
+const errorChainText = (err) => {
+    const parts = [];
+    let current = err;
+    for (let depth = 0; current instanceof Error && depth < 6; depth++) {
+        parts.push(current.message);
+        current = current.cause;
+    }
+    return parts.join('\n').toLowerCase();
+};
+const looksLikeMissingDependency = (err) => {
+    const text = errorChainText(err);
+    return MISSING_DEPENDENCY_HINTS.some((hint) => text.includes(hint));
+};
 const loadNeonConfig = async (cwd) => {
     try {
         const { config } = await loadConfigFromFile({ cwd });
@@ -197,6 +227,14 @@ const loadNeonConfig = async (cwd) => {
         if (/Could not find a Neon config file/i.test(message)) {
             return null;
         }
+        // A neon.ts that imports a package which isn't installed fails here with a
+        // cryptic "Cannot find module …". Turn that into the actionable thing to do.
+        if (looksLikeMissingDependency(err)) {
+            throw new Error('Could not load neon.ts: a package it imports is not installed. ' +
+                'Did you run `npm install`? Install your dependencies ' +
+                '(npm / pnpm / yarn / bun), then try again.\n' +
+                `Original error: ${message}`);
+        }
         throw err;
     }
 };

package/dev/functions.js

@@ -32,7 +32,6 @@ export const resolveFunctionsFromConfig = async (cwd, branchName) => {
             slug: fn.slug,
             name: fn.name,
             source,
-            portless: fn.dev?.portless === true,
             ...(devPort(fn.dev) !== undefined
                 ? { port: devPort(fn.dev) }
                 : {}),
@@ -42,9 +41,8 @@ export const resolveFunctionsFromConfig = async (cwd, branchName) => {
     return { configPath, functions: planned };
 };
 /**
- * Read the `port` off a {@link FunctionDevConfig}. The discriminated union guarantees a
- * `port` is present whenever `portless` is true, so this is `undefined` only for the
- * non-portless, port-omitted case (the supervisor then searches for a free port).
+ * Read the `port` off a {@link FunctionDevConfig}. `undefined` when no `dev.port` is set
+ * (the supervisor then searches for a free port).
  */
 const devPort = (dev) => dev?.port;
 /**

package/dev/runtime.js

@@ -100,8 +100,8 @@ export const startRuntime = async ({ source, port, hostname, }) => {
  * Build a {@link PortSelection} from the environment. Precedence:
  *   1. `NEON_DEV_PORT` -> explicit bind (crash if taken). Set by `neon dev` from an
  *      explicit `--port` / `dev.port`.
- *   2. `PORT`          -> explicit bind. This is what `portless` injects (and what a bare
- *      `PORT=3000 neon dev` sets), so the runtime binds the port chosen for it.
+ *   2. `PORT`          -> explicit bind. A bare `PORT=3000 neon dev` sets this, so the
+ *      runtime binds the port chosen for it.
  *   3. otherwise        -> search upward from `NEON_DEV_PORT_BASE` (or the default base).
  */
 export const portSelectionFromEnv = (env) => {

package/index.js

@@ -40,6 +40,7 @@ const NO_SUBCOMMANDS_VERBS = [
     'init',
     'dev',
     'deploy',
+    'bootstrap',
     // aliases
 ];
 let builder = yargs(hideBin(process.argv));

package/package.json

@@ -5,7 +5,7 @@
     "url": "git+ssh://git@github.com/neondatabase/neonctl.git"
   },
   "type": "module",
-  "version": "2.24.2",
+  "version": "2.25.0",
   "description": "CLI tool for NeonDB Cloud management",
   "main": "index.js",
   "author": "NeonDB",
@@ -59,9 +59,9 @@
   "dependencies": {
     "@hono/node-server": "2.0.4",
     "@neondatabase/api-client": "2.7.1",
-    "@neondatabase/config": "0.4.2",
-    "@neondatabase/config-runtime": "0.4.2",
-    "@neondatabase/env": "0.3.2",
+    "@neondatabase/config": "0.7.0",
+    "@neondatabase/config-runtime": "0.7.0",
+    "@neondatabase/env": "0.5.0",
     "@segment/analytics-node": "1.3.0",
     "axios": "1.7.2",
     "axios-debug-log": "1.0.0",
@@ -71,7 +71,7 @@
     "cliui": "8.0.1",
     "diff": "5.2.0",
     "fflate": "^0.8.3",
-    "neon-init": "0.14.0",
+    "neon-init": "0.15.0",
     "open": "10.1.0",
     "openid-client": "6.8.1",
     "pg-protocol": "^1.14.0",

package/storage_api.js

@@ -112,3 +112,37 @@ export const deleteProjectBranchBucketObjectsByPrefix = (apiClient, { projectId,
     format: 'json',
     secure: true,
 });
+/**
+ * Request a presigned PUT URL for uploading an object to a bucket on a branch.
+ *
+ * Returns the URL, the headers that must accompany the PUT for the signature to
+ * verify, and the expiry. The actual upload (a `PUT` to the returned `url` with
+ * the returned `headers` and the file stream) is performed by the caller, NOT
+ * through this api-client, since it targets the branch S3 data-plane endpoint
+ * rather than the console API. No SigV4 or credential handling happens here.
+ *
+ * The object key may contain `/`; it is percent-encoded into a single path
+ * segment so nested keys are routed to the `{object_key}` parameter.
+ *
+ * This targets the unified presign endpoint, passing `operation: "upload"` to
+ * request a presigned PUT. (The same endpoint also serves `download`, but that
+ * path is API-only and has no neonctl command.)
+ *
+ * @request POST /projects/{project_id}/branches/{branch_id}/buckets/{bucket_name}/objects/{object_key}/presign
+ */
+export const presignUpload = (apiClient, { projectId, branchId, bucketName, objectKey, contentType, expiresInSeconds, }) => {
+    const body = { operation: 'upload' };
+    if (contentType !== undefined) {
+        body.content_type = contentType;
+    }
+    if (expiresInSeconds !== undefined) {
+        body.expires_in_seconds = expiresInSeconds;
+    }
+    return apiClient.request({
+        path: `${bucketPath(projectId, branchId, bucketName)}/objects/${encodeURIComponent(objectKey)}/presign`,
+        method: 'POST',
+        body,
+        format: 'json',
+        secure: true,
+    });
+};

package/utils/bootstrap.js

@@ -0,0 +1,243 @@
+import axios, { isAxiosError } from 'axios';
+import YAML from 'yaml';
+import { log } from '../log.js';
+/** Hardcoded fallback used when the remote manifest cannot be fetched. */
+export const FALLBACK_TEMPLATES = [
+    {
+        id: 'hono',
+        title: 'Hono API (Drizzle, Neon Postgres) on Neon Functions',
+        description: 'A Hono API using Drizzle ORM and Neon Postgres, ready to deploy as a Neon Function.',
+        services: ['Postgres', 'Functions'],
+        source: {
+            owner: 'neondatabase',
+            repo: 'examples',
+            ref: 'main',
+            subdir: 'with-hono',
+        },
+    },
+];
+export const templateIds = (templates) => templates.map((t) => t.id).join(', ');
+export const findTemplate = (templates, id) => templates.find((t) => t.id === id);
+// Hosts are overridable so the e2e tests can point the downloader at a local
+// server (the same trick `--api-host` uses to redirect the Neon API in tests).
+// The defaults hit public GitHub; copying a public template needs no auth.
+const githubApiBase = () => process.env.NEON_BOOTSTRAP_GITHUB_API ?? 'https://api.github.com';
+const githubRawBase = () => process.env.NEON_BOOTSTRAP_GITHUB_RAW ?? 'https://raw.githubusercontent.com';
+const githubToken = () => process.env.GITHUB_TOKEN ?? process.env.GH_TOKEN ?? '';
+const apiHeaders = () => ({
+    Accept: 'application/vnd.github+json',
+    'X-GitHub-Api-Version': '2022-11-28',
+    'User-Agent': 'neonctl',
+    ...(githubToken() ? { Authorization: `Bearer ${githubToken()}` } : {}),
+});
+const rawHeaders = () => ({
+    'User-Agent': 'neonctl',
+    ...(githubToken() ? { Authorization: `Bearer ${githubToken()}` } : {}),
+});
+const isRecord = (value) => typeof value === 'object' && value !== null;
+/**
+ * Normalize a manifest entry's `services` into a clean string list. Tolerant by
+ * design: a missing or non-array value yields `undefined`, and non-string items
+ * are dropped, so a malformed `services` never sinks an otherwise-valid
+ * template (it just renders without its badge).
+ */
+const parseServices = (value) => {
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    const services = value.filter((item) => typeof item === 'string' && item.trim() !== '');
+    return services.length > 0 ? services : undefined;
+};
+// ---------------------------------------------------------------------------
+// Remote template manifest
+// ---------------------------------------------------------------------------
+const manifestUrl = () => process.env.NEON_BOOTSTRAP_MANIFEST_URL ??
+    `${githubRawBase()}/neondatabase/examples/main/bootstrap.yaml`;
+export const parseManifest = (text) => {
+    const data = YAML.parse(text);
+    if (!isRecord(data) || !Array.isArray(data.templates)) {
+        throw new Error('Invalid bootstrap manifest: missing "templates" array.');
+    }
+    const templates = [];
+    for (let i = 0; i < data.templates.length; i++) {
+        const item = data.templates[i];
+        if (!isRecord(item) ||
+            typeof item.id !== 'string' ||
+            typeof item.title !== 'string' ||
+            typeof item.description !== 'string' ||
+            !isRecord(item.source) ||
+            typeof item.source.owner !== 'string' ||
+            typeof item.source.repo !== 'string' ||
+            typeof item.source.ref !== 'string' ||
+            typeof item.source.subdir !== 'string') {
+            log.warning('bootstrap: skipping malformed template entry at index %d in manifest.', i);
+            continue;
+        }
+        const services = parseServices(item.services);
+        templates.push({
+            id: item.id,
+            title: item.title,
+            description: item.description,
+            ...(services ? { services } : {}),
+            source: {
+                owner: item.source.owner,
+                repo: item.source.repo,
+                ref: item.source.ref,
+                subdir: item.source.subdir,
+            },
+        });
+    }
+    return templates;
+};
+/**
+ * Fetch the template manifest from the remote `bootstrap.yaml` in the
+ * neondatabase/examples repo. Falls back to the hardcoded list on any error
+ * so the command never fails just because GitHub is unreachable.
+ */
+export const fetchTemplates = async () => {
+    const url = manifestUrl();
+    try {
+        const res = await axios.get(url, {
+            responseType: 'text',
+            headers: rawHeaders(),
+            timeout: 10000,
+        });
+        const templates = parseManifest(res.data);
+        if (templates.length === 0) {
+            log.warning('Remote bootstrap manifest at %s contained no templates; using built-in defaults.', url);
+            return FALLBACK_TEMPLATES;
+        }
+        return templates;
+    }
+    catch (err) {
+        log.debug('bootstrap: failed to fetch manifest from %s: %s — using built-in defaults.', url, err instanceof Error ? err.message : String(err));
+        return FALLBACK_TEMPLATES;
+    }
+};
+const malformed = (what) => new Error(`Unexpected GitHub API response while resolving ${what}.`);
+const parseCommit = (data) => {
+    if (!isRecord(data) || typeof data.sha !== 'string') {
+        throw malformed('the template commit');
+    }
+    const { commit } = data;
+    if (!isRecord(commit) ||
+        !isRecord(commit.tree) ||
+        typeof commit.tree.sha !== 'string') {
+        throw malformed('the template tree');
+    }
+    return { commitSha: data.sha, treeSha: commit.tree.sha };
+};
+const parseTree = (data) => {
+    if (!isRecord(data) || !Array.isArray(data.tree)) {
+        throw malformed('the template file tree');
+    }
+    const tree = [];
+    for (const item of data.tree) {
+        if (isRecord(item) &&
+            typeof item.path === 'string' &&
+            typeof item.mode === 'string' &&
+            typeof item.type === 'string') {
+            tree.push({ path: item.path, mode: item.mode, type: item.type });
+        }
+    }
+    return { truncated: data.truncated === true, tree };
+};
+const friendlyGithubError = (err, url) => {
+    if (isAxiosError(err)) {
+        const status = err.response?.status;
+        if (status === 404) {
+            return new Error(`GitHub returned 404 for ${url}. The template repo, ref, or subdirectory may have moved.`);
+        }
+        if (status === 403 &&
+            err.response?.headers['x-ratelimit-remaining'] === '0') {
+            return new Error('GitHub API rate limit exceeded. Set a GITHUB_TOKEN environment variable to raise the limit, then retry.');
+        }
+    }
+    return err instanceof Error ? err : new Error(String(err));
+};
+const getJson = async (url) => {
+    try {
+        const res = await axios.get(url, { headers: apiHeaders() });
+        return res.data;
+    }
+    catch (err) {
+        throw friendlyGithubError(err, url);
+    }
+};
+/**
+ * Map a flat (recursive) git tree to the entries under `subdir`, with the
+ * `subdir/` prefix stripped from each `path`. Pure so it can be unit tested
+ * without touching the network. Directory nodes are dropped — git never
+ * stores empty directories, and writing files re-creates their parents.
+ */
+export const selectSubtreeEntries = (tree, subdir) => {
+    const prefix = `${subdir.replace(/\/+$/, '')}/`;
+    const entries = [];
+    for (const node of tree) {
+        if (node.type !== 'blob') {
+            continue;
+        }
+        if (!node.path.startsWith(prefix)) {
+            continue;
+        }
+        const path = node.path.slice(prefix.length);
+        if (node.mode === '120000') {
+            entries.push({ kind: 'symlink', path, repoPath: node.path });
+        }
+        else {
+            entries.push({
+                kind: 'file',
+                path,
+                repoPath: node.path,
+                executable: node.mode === '100755',
+            });
+        }
+    }
+    return entries;
+};
+/**
+ * Resolve a template to the exact set of files to write. Pins everything to a
+ * single immutable commit: the ref is resolved to a commit sha, the tree is
+ * read from that commit's tree, and every blob is later fetched by that same
+ * commit — so a push to the template repo mid-copy can't produce a mismatched
+ * checkout.
+ */
+export const resolveTemplate = async (template) => {
+    const { owner, repo, ref, subdir } = template.source;
+    const api = githubApiBase();
+    const commit = parseCommit(await getJson(`${api}/repos/${owner}/${repo}/commits/${ref}`));
+    const { truncated, tree } = parseTree(await getJson(`${api}/repos/${owner}/${repo}/git/trees/${commit.treeSha}?recursive=1`));
+    if (truncated) {
+        throw new Error(`GitHub returned a truncated file tree for ${owner}/${repo}; cannot reliably copy template "${template.id}".`);
+    }
+    const entries = selectSubtreeEntries(tree, subdir);
+    if (entries.length === 0) {
+        throw new Error(`Template subdirectory "${subdir}" was not found in ${owner}/${repo}@${ref}.`);
+    }
+    log.debug('bootstrap: resolved %d files for template "%s" at %s', entries.length, template.id, commit.commitSha);
+    return { commitSha: commit.commitSha, entries };
+};
+const rawUrl = (template, commitSha, repoPath) => `${githubRawBase()}/${template.source.owner}/${template.source.repo}/${commitSha}/${repoPath}`;
+/** Download a file's raw bytes, pinned to the resolved commit. */
+export const fetchFileBytes = async (template, commitSha, repoPath) => {
+    const url = rawUrl(template, commitSha, repoPath);
+    try {
+        const res = await axios.get(url, {
+            responseType: 'arraybuffer',
+            headers: rawHeaders(),
+        });
+        return Buffer.from(res.data);
+    }
+    catch (err) {
+        throw friendlyGithubError(err, url);
+    }
+};
+/**
+ * Read a symlink's target. In a git blob a symlink is stored as a regular file
+ * whose contents are the (relative) link target, so the raw bytes are exactly
+ * the string we pass to `symlink(2)`.
+ */
+export const fetchSymlinkTarget = async (template, commitSha, repoPath) => {
+    const bytes = await fetchFileBytes(template, commitSha, repoPath);
+    return bytes.toString('utf8');
+};

package/utils/esbuild.js

@@ -6,6 +6,12 @@ import which from 'which';
 const NOT_FOUND = 'esbuild not found. neonctl ships esbuild for most platforms; if you see ' +
     'this, install esbuild and ensure it is on your PATH (e.g. `npm i -g ' +
     'esbuild`), or set NEON_ESBUILD_PATH to an esbuild binary.';
+// Prepended to the ESM bundle. Bundled dependencies are frequently CommonJS, but an ESM
+// output (`--format=esm`) has no `require` / `__filename` / `__dirname` in scope — so any
+// bundled CJS code that calls `require(...)` would fail at load with
+// `Dynamic require of "x" is not supported`. Re-create those globals via `createRequire`
+// so CJS and ESM dependencies coexist in the single `index.mjs`.
+const ESM_CJS_INTEROP_BANNER = "import{createRequire as ___cr}from'module';import{fileURLToPath as ___f}from'url';import{dirname as ___d}from'path';const require=___cr(import.meta.url);const __filename=___f(import.meta.url);const __dirname=___d(__filename);";
 const defaultDeps = {
     // @yao-pkg/pkg defines process.pkg inside the packaged binary.
     isPackaged: () => process.pkg !== undefined,
@@ -57,7 +63,10 @@ const bundleViaModule = async (source, loadEsbuild) => {
         minify: true,
         format: 'esm',
         platform: 'node',
-        packages: 'external',
+        // Bundle dependencies into the entry so the deployed archive is self-contained (the
+        // Functions runtime has no node_modules). Node built-ins stay external on
+        // platform:'node'. The banner re-creates require/__filename/__dirname for bundled CJS.
+        banner: { js: ESM_CJS_INTEROP_BANNER },
         logLevel: 'silent',
     })
         .catch((err) => {
@@ -118,7 +127,7 @@ const bundleViaBinary = async (source) => {
             '--minify',
             '--format=esm',
             '--platform=node',
-            '--packages=external',
+            `--banner:js=${ESM_CJS_INTEROP_BANNER}`,
             '--log-level=error',
         ]);
         if (code !== 0) {