insta 0.1.11 → 0.1.13

package/README.md

@@ -74,11 +74,12 @@ insta deploy .
 
 `project create` makes an empty project and links the current directory. Services are
 opt-in, so you add only what you need. `secrets` writes the current branch's user-defined
-secrets to `./.env` (the postgres connection string is read with `insta postgres url`). `deploy .`
+secrets plus the primary provider credentials of each service type to `./.env`. A service created with
+`insta service add compute` starts with no provider credential bindings; bind the sources it needs before deploying. `deploy .`
 builds the directory remotely and ships it to the branch's compute
 service, with no local Docker. Whether it needs a `Dockerfile` depends on where the
 service runs: on insta-compute it is optional, and a directory without one is built
-by nixpacks on the build gateway; on Fly-backed services one is still required.
+by nixpacks on the build gateway; on legacy-plane services one is still required.
 
 ## Authentication
 
@@ -116,12 +117,21 @@ the two branches diverge independently. A project is capped at 10 branches.
 
 ### Credentials come from the secret seam, not a file you maintain
 
-`insta secrets` fetches the current branch's **user-defined** secrets and writes `./.env`.
-`insta run <cmd>` does the same without touching disk, injecting them into the child process
-only. Provider-minted service credentials (`DATABASE_URL`, `BUCKET_NAME`,
-`AWS_ACCESS_KEY_ID`, …) are not in that bundle — they reach compute through explicit
-`insta secrets bind` rules, and the postgres connection string is read directly with
-`insta postgres url` (or `insta postgres connect` for a psql session).
+`insta secrets` writes the current branch's **user-defined secrets plus primary provider
+credentials** to `./.env`: one credential set per service type, from that type's primary service.
+`insta run <cmd>` injects the same bundle into a local child process without touching disk.
+Fetching this bundle does not bind credentials to compute. A compute service receives provider
+credentials only through explicit `insta secrets bind` rules; `insta service add compute` creates
+a service with no provider credential bindings inherited from other services. Bind each source it
+needs, then deploy or restart to apply the bindings. For a specific postgres service's connection string, use
+`insta postgres url <name>` (or `insta postgres connect <name>` for a psql session).
+
+A postgres database is reachable on its public endpoint (`DATABASE_URL`) by default.
+`insta postgres private-access on` adds `DATABASE_PRIVATE_URL` beside it, which resolves only inside
+InstaCloud compute; bind it into a compute with `insta secrets bind DATABASE_URL postgres/db
+--source-name DATABASE_PRIVATE_URL --to compute/api`. `insta postgres public-access off` then makes the
+database not reachable from the internet: it prints what will break and asks first (`--yes` when
+there is no terminal), and external clients, CI and local development can no longer connect.
 
 Secrets can be scoped per compute service, so several services may each define the same name — and
 a flat bundle cannot carry two values for one name. Such a name is **withheld** from the bundle and
@@ -221,7 +231,7 @@ build never reaches a production installer.
 | `insta secrets` | Write `.env`, plus `list` · `set` · `unset` · `bind` · `unbind` · `bindings` · `sources` · `tree` |
 | `insta domain` | Bought or bring-your-own: `attach` · `check` · `detach`; buy through InstaCloud: `search` · `buy` · `list` · `status` · `records …` |
 | `insta compute` | `start` · `stop` · `suspend` · `restart` · `status` · `scale` · `limits` · `volume` · `always-on` · `exec` · `ssh` · `repo` · `connect-repo` · `watch-paths` · `disconnect-repo` · `logs` · `metrics` |
-| `insta postgres` | `url` (print the DSN) · `connect` (psql) · `stats` · `limits` · `volume` · `always-on` · `logs` · `metrics` — every verb takes `[service]` |
+| `insta postgres` | `url` (print the DSN) · `connect` (psql) · `stats` · `limits` · `volume` · `always-on` · `private-access` · `public-access` · `logs` · `metrics` — every verb takes `[service]` |
 | `insta redis` · `mysql` · `mongodb` | `query` · `status` · `limits` · `volume` · `always-on` · `logs` · `metrics` |
 | `insta storage` | `list` · `get` · `delete` · `set-access` |
 | `insta build [dir]` · `deploy [dir]` | Verify a source dir would build; deploy a source directory (built remotely) or `--image <url>`. `insta build logs <id>` reads source-build output: `--source archive` (default) uses the deploy operation ID, `--source github` uses a GitHub build ID; `--follow` watches output, `--json` returns one snapshot |

package/dist/commands/billing.js

@@ -1,4 +1,4 @@
-import { ApiClient, requireProject } from '../api.js';
+import { ApiClient, ApiError, requireProject } from '../api.js';
 import { die, info, openUrl, printJson } from '../util.js';
 import { cycleLine, dimensionLines } from './metrics.js';
 // Resolve the target org: explicit --org, else the linked project's org.
@@ -100,6 +100,63 @@ export async function billingUpgrade(tier, opts) {
         return printJson({ url });
     presentUrl(url, `Subscribe to ${tier} — complete checkout in your browser:`, opts.open);
 }
+// The platform's contract (RedeemError#reason in billing/service.ts) — four literals, never
+// collapsed into one message, because the right next action differs per reason: `not_found` is
+// the only one worth retyping; `expired`/`revoked` both mean waiting never helps, but only
+// `revoked` has someone to go back to.
+//
+// `already_redeemed` deliberately does NOT say WHO redeemed it, because this CLI cannot know.
+// A sequential retry replays the receipt and never reaches here — but two requests from the same
+// org in flight at once both miss the replay read (it sees committed rows only), one wins the
+// claim and the other lands exactly here. That is the case a client resending a request it never
+// saw an answer to is IN. Telling that person "a different org took it" would be false about
+// their own money: the grant is on their wallet. So the message points them at their balance
+// instead of at a conclusion this side cannot support.
+const REDEEM_ERROR_MESSAGE = {
+    not_found: 'that code was not recognized — check it for typos and try again',
+    expired: 'that code has expired — ask whoever sent it for a new one',
+    already_redeemed: 'that code has already been redeemed — if it was your org, the credits are already there (check `insta billing`)',
+    revoked: 'that code was revoked — contact whoever sent it to you',
+};
+// Pure — the human line for a redeem failure. `reason` is the platform's literal (RedeemError's
+// four values); anything else (a platform version ahead of this CLI) falls back to relaying it
+// as-is rather than a message that would be wrong about which of the four cases this is.
+export function redeemErrorMessage(reason, fallback) {
+    return (reason && REDEEM_ERROR_MESSAGE[reason]) ?? fallback;
+}
+// Pure — the three facts the spec names, in the order it names them: what landed, when it stops
+// being spendable, and which org — by NAME — so someone who belongs to several orgs isn't left
+// reading a uuid to find out which one just got the money.
+export function redeemLines(r) {
+    return [
+        `credited:        $${(r.amountMicros / 1_000_000).toFixed(2)}`,
+        `expires:         ${r.creditsExpireAt ? r.creditsExpireAt.slice(0, 10) : 'never'}`,
+        `org:             ${r.orgName}`,
+    ];
+}
+// insta billing redeem <code> — apply a one-time credit code to the org's wallet.
+export async function billingRedeem(code, opts) {
+    const api = await ApiClient.load();
+    const orgId = await resolveOrgId(opts);
+    let res;
+    try {
+        res = await api.request('POST', `/orgs/${orgId}/billing/redeem`, { code });
+    }
+    catch (e) {
+        if (!(e instanceof ApiError) || e.status !== 400)
+            throw e;
+        // Under --json, stdout stays the one parseable document a script branches on (the platform's
+        // own `error` literal); the human line below is the diagnostic and belongs on stderr.
+        const reason = e.body?.error;
+        if (opts.json)
+            printJson({ error: reason ?? e.message });
+        die(redeemErrorMessage(reason, e.message));
+    }
+    if (opts.json)
+        return printJson(res);
+    for (const l of redeemLines(res))
+        info(l);
+}
 // insta billing portal — open the Stripe Customer Portal (change plan / card / cancel).
 export async function billingPortal(opts) {
     const api = await ApiClient.load();

package/dist/commands/build.js

@@ -123,11 +123,11 @@ export async function buildReport(dirArg, opts, deps) {
             severity: 'warning',
             status: 'fail',
             title: 'Dockerfile',
-            detail: `${dockerfileDetail} — \`insta deploy <dir>\` builds this on the gateway with nixpacks when the service runs on insta-compute, and needs your own Dockerfile on a Fly-backed one`,
+            detail: `${dockerfileDetail} — \`insta deploy <dir>\` builds this on the gateway with nixpacks when the service runs on insta-compute, and needs your own Dockerfile on a legacy-plane one`,
             // NOT "save the generated Dockerfile here": it is not standalone (it COPYs the
             // .nixpacks/nixpkgs-<hash>.nix support files nixpacks writes beside it, which this
             // directory does not have). The detected commands above are the reusable part.
-            nextAction: `on insta-compute this deploys as-is (nixpacks builds it on the gateway). On a Fly-backed service, write a Dockerfile at ${userDockerfilePath} — the detected install/start commands above are the starting point — or connect the GitHub repo (\`insta compute connect-repo <owner/repo>\`)`,
+            nextAction: `on insta-compute this deploys as-is (nixpacks builds it on the gateway). On a legacy-plane service, write a Dockerfile at ${userDockerfilePath} — the detected install/start commands above are the starting point — or connect the GitHub repo (\`insta compute connect-repo <owner/repo>\`)`,
         }
         : {
             id: 'dockerfile',
@@ -190,7 +190,7 @@ export function renderReport(r, explain) {
     // The builder line is the first thing read (and the thing an agent scrapes), so it carries the
     // lane caveat too — "builder: nixpacks" on its own reads as a promise that is only true on some
     // targets. It has to say the SAME thing the detail below it says, or a scrape sees both claims.
-    const lane = r.plan.builder === 'nixpacks' ? ' — server-side: insta-compute builds this as-is, a Fly-backed service needs your own Dockerfile' : '';
+    const lane = r.plan.builder === 'nixpacks' ? ' — server-side: insta-compute builds this as-is, a legacy-plane service needs your own Dockerfile' : '';
     lines.push(`  builder: ${r.plan.builder ?? 'none'}${r.plan.providers.length ? ` (providers: ${r.plan.providers.join(', ')})` : ''}${lane}`);
     if (r.plan.installCommand)
         lines.push(`  install: ${r.plan.installCommand}`);

package/dist/commands/postgres.js

@@ -1,7 +1,8 @@
 import { spawn } from 'node:child_process';
 import { constants as osConstants } from 'node:os';
 import { ApiClient, ApiError, requireProject } from '../api.js';
-import { info, printJson, handleApproval, relayExitCode } from '../util.js';
+import * as clack from '@clack/prompts';
+import { info, printJson, handleApproval, refuse, relayExitCode } from '../util.js';
 import { parseVolumeGib, q, resolveSoleService } from './services.js';
 export function alwaysOnArgs(first, second) {
     if (first === 'on' || first === 'off')
@@ -42,10 +43,34 @@ export async function dbAlwaysOn(first, second, opts) {
     const res = await api.rawRequest('PATCH', `/projects/${p.projectId}/database/settings${suffix}`, { scaleToZero: mode !== 'on' });
     if (handleApproval(res, opts.json))
         return;
+    const body = await settleScaleToZero(res.body, mode === 'off', async () => {
+        try {
+            return (await api.rawRequest('GET', `/projects/${p.projectId}/database/instance${suffix}`, undefined, { signal: AbortSignal.timeout(5000) })).body;
+        }
+        catch {
+            return undefined;
+        }
+    });
     if (opts.json)
-        return printJson(res.body);
-    const s2z = res.body?.scaleToZero;
-    info(`postgres ${service ?? 'default'}: always-on ${s2z === false ? 'ENABLED — instance stays warm (no cold starts; idle RAM bills at actual usage)' : 'disabled — scales to zero when idle (default; first connection after idle cold-starts)'}`);
+        return printJson(body);
+    info(alwaysOnSetLine(service, opts.branch, mode, body?.scaleToZero));
+}
+// insta-db applies the change asynchronously and answers with the value from before it, so re-read until they agree.
+export async function settleScaleToZero(body, want, read, wait = (ms) => new Promise((r) => setTimeout(r, ms))) {
+    for (let i = 0; i < 15 && typeof body?.scaleToZero === 'boolean' && body.scaleToZero !== want; i++) {
+        await wait(2000);
+        const next = await read();
+        if (next === undefined)
+            break;
+        body = next;
+    }
+    return body;
+}
+export function alwaysOnSetLine(service, branch, mode, scaleToZero) {
+    const group = service ?? 'default';
+    if (scaleToZero !== (mode === 'off'))
+        return `postgres ${group}: always-on ${mode} requested — the database has not applied it yet; confirm with \`insta postgres always-on${service ? ` ${service}` : ''}${branch ? ` --branch ${branch}` : ''}\``;
+    return `postgres ${group}: always-on ${mode === 'on' ? 'ENABLED — instance stays warm (no cold starts; idle RAM bills at actual usage)' : 'disabled — scales to zero when idle (default; first connection after idle cold-starts)'}`;
 }
 // Validated pass-throughs for the provider's quantity strings. The insta-db resize API takes
 // k8s-style quantities (cpu: "2", "2500m"; memory: "4Gi", "2048Mi"), so unlike the compute path
@@ -257,14 +282,6 @@ export async function dbVolume(service, opts) {
     const vg = res.body?.volumeGib;
     info(`postgres ${service ?? 'default'}: volume ${typeof vg === 'number' ? `grown to ${vg}Gi` : `set to ${sizeGib}Gi`}`);
 }
-// Resolve the postgres service (sole, or the named one) and its connection string. Two reads: the
-// branch's services list names the service; GET /services/:id/credentials (gated secrets.read)
-// carries the value. Provider-minted credentials are canonical within their source service
-// (DATABASE_URL) and deliberately absent from the general `insta secrets` bundle, so this is the
-// read that yields the DSN. The credentials call carries no branch param — the service id is
-// already branch-scoped by the list. Returns null when the read parked on an approval
-// (handleApproval already spoke). Takes the client as an argument so tests drive it with a stub,
-// per this repo's pure-seam convention.
 export async function resolveDbUrl(api, projectId, branch, service, json) {
     const { services } = await api.request('GET', `/projects/${projectId}/services${q(branch)}`);
     const svc = resolveSoleService(services, 'postgres', service);
@@ -350,4 +367,189 @@ export async function dbConnect(service, opts) {
     process.stderr.write(`psql → postgres/${r.serviceName}${branch ? ` (branch ${branch})` : ''} — a suspended instance wakes on connect, so the first prompt can take a few seconds\n`);
     relayExitCode(await connectWithPsql(r.url));
 }
+async function confirmOnTerminal(question) {
+    const answer = await clack.confirm({ message: question, initialValue: false });
+    if (clack.isCancel(answer))
+        return false;
+    return answer === true;
+}
+const onOff = (v) => (v === true ? 'on' : v === false ? 'off' : 'unknown');
+// The access block of a database/instance read. Pure, exported for tests. privateConnString in the
+// instance view carries NO password (the full URL is DATABASE_PRIVATE_URL in the credentials), so
+// printing it is safe.
+export function dbAccessLines(group, body) {
+    const pub = body?.publicAccess;
+    const lines = [
+        `postgres ${group}: public access ${onOff(pub)}${pub === false ? ' — not reachable from the internet; only the private network lane connects' : pub === true ? ' — reachable on the public endpoint (DATABASE_URL)' : ' — the provider did not report it'}`,
+        `postgres ${group}: private access ${onOff(body?.privateAccess)}${body?.privateAccess === true ? ' — DATABASE_PRIVATE_URL is in the service credentials (resolves only inside InstaCloud compute)' : ''}`,
+    ];
+    if (typeof body?.privateConnString === 'string' && body.privateConnString)
+        lines.push(`  private: ${body.privateConnString}`);
+    if (body?.privateLane?.enabled === false)
+        lines.push('  the private network lane is not yet available on this deployment — private access cannot be turned on, nor public access closed');
+    return lines;
+}
+// Human lines for what closing public access will break. The platform's warnings already name each
+// affected compute (and always end with the external-clients one), so the services array is left
+// to --json rather than repeated.
+export function impactLines(impact) {
+    const warnings = (impact?.warnings ?? []).filter((w) => typeof w === 'string' && w);
+    if (!warnings.length)
+        return [];
+    return ['closing public access will break:', ...warnings.map((w) => `  ! ${w}`)];
+}
+// Map an access-change refusal to a CLI-shaped message. Pure, exported for tests. The platform's
+// 400 texts name REST routes; the CLI names its own command instead, keeping the reason.
+export function accessErrorMessage(e, ctx) {
+    const code = e.body?.code;
+    const b = ctx.branch ? ` --branch ${ctx.branch}` : '';
+    if (code === 'private_lane_disabled') {
+        return `private network access for postgres is not yet available on this deployment — postgres ${ctx.service} stays reachable on its public endpoint (DATABASE_URL)`;
+    }
+    if (code === 'private_lane_unavailable_in_region') {
+        return `the region of postgres ${ctx.service} has no private network lane yet — private access was turned back off and nothing was minted; DATABASE_URL is unchanged`;
+    }
+    if (e.status === 400 && /private network access first/i.test(e.message)) {
+        return `turn on private access first: \`insta postgres private-access on ${ctx.service}${b}\` — closing public access without it would leave the database with no way to connect`;
+    }
+    if (e.status === 400 && /re-open public access first/i.test(e.message)) {
+        return `re-open public access first: \`insta postgres public-access on ${ctx.service}${b}\` — turning private access off while public access is closed would leave the database with no way to connect`;
+    }
+    return `${ctx.what} failed (${e.status}): ${e.message}`;
+}
+async function resolvePostgres(api, projectId, branch, service) {
+    const { services } = await api.request('GET', `/projects/${projectId}/services${q(branch)}`);
+    return resolveSoleService(services, 'postgres', service);
+}
+function settingsSuffix(branch, group) {
+    const qs = new URLSearchParams();
+    if (branch)
+        qs.set('branch', branch);
+    qs.set('group', group);
+    return `?${qs}`;
+}
+// `insta postgres public-access [on|off] [service]` — show, open, or close the public endpoint.
+// Reads GET /database/instance; writes PUT /services/:id/access {public} (gated: service.setAccess).
+// Closing previews GET /services/:id/access/impact?public=false first and asks before acting; a
+// non-interactive caller (agent, CI, --json) must pass --yes, having read the preview it printed.
+export async function dbPublicAccess(first, second, opts, deps = {}) {
+    const { mode, service } = alwaysOnArgs(first, second);
+    const api = await ApiClient.load();
+    const p = await requireProject();
+    const branch = opts.branch ?? p.branch;
+    const svc = await resolvePostgres(api, p.projectId, branch, service);
+    if (!mode)
+        return showAccess(api, p.projectId, branch, svc.name, opts);
+    const what = mode === 'off' ? 'closing public access' : 'opening public access';
+    const ctx = { service: svc.name, branch: opts.branch, what };
+    if (mode === 'off') {
+        let impact;
+        try {
+            impact = await api.request('GET', `/projects/${p.projectId}/services/${svc.id}/access/impact?public=false`);
+        }
+        catch (e) {
+            if (e instanceof ApiError)
+                throw new Error(`previewing the impact failed (${e.status}): ${e.message}`);
+            throw e;
+        }
+        const lines = impactLines(impact);
+        const tty = deps.tty ?? (!!process.stdin.isTTY && !!process.stdout.isTTY);
+        if (!opts.yes) {
+            if (opts.json || !tty) {
+                refuse([
+                    ...lines,
+                    `postgres ${svc.name}: closing public access makes the database not reachable from the internet — re-run with --yes to confirm`,
+                ]);
+            }
+            for (const l of lines)
+                info(l);
+            const ok = await (deps.confirm ?? confirmOnTerminal)(`Close public access to postgres ${svc.name}?`);
+            if (!ok) {
+                info(`postgres ${svc.name}: public access unchanged`);
+                return;
+            }
+        }
+        else if (!opts.json) {
+            for (const l of lines)
+                info(l);
+        }
+    }
+    let res;
+    try {
+        res = await api.rawRequest('PUT', `/projects/${p.projectId}/services/${svc.id}/access`, { public: mode === 'on' });
+    }
+    catch (e) {
+        if (e instanceof ApiError)
+            throw new Error(accessErrorMessage(e, ctx));
+        throw e;
+    }
+    if (handleApproval(res, opts.json))
+        return;
+    if (opts.json)
+        return printJson(res.body);
+    for (const l of publicAccessSetLines(svc.name, mode, res.body))
+        info(l);
+}
+export function publicAccessSetLines(group, mode, body) {
+    const notice = typeof body?.notice === 'string' && body.notice ? body.notice : undefined;
+    const head = mode === 'off'
+        ? `postgres ${group}: public access CLOSED — not reachable from the internet; external clients, CI and local development can no longer connect. Compute services on InstaCloud connect through DATABASE_PRIVATE_URL`
+        : `postgres ${group}: public access open — reachable on the public endpoint (DATABASE_URL)${notice ? '' : ' (it already was; nothing changed)'}`;
+    return notice ? [head, `  ${notice}`] : [head];
+}
+// `insta postgres private-access [on|off] [service]` — show or toggle the private network lane.
+// Writes PATCH /database/settings {privateAccess} (gated: service.setAccess). On mints
+// DATABASE_PRIVATE_URL beside DATABASE_URL (unchanged); off retracts it (refused while public
+// access is closed). No confirmation: neither direction takes a working connection away without
+// the platform refusing or warning (off answers `warnings` naming computes still bound to it).
+export async function dbPrivateAccess(first, second, opts) {
+    const { mode, service } = alwaysOnArgs(first, second);
+    const api = await ApiClient.load();
+    const p = await requireProject();
+    const branch = opts.branch ?? p.branch;
+    const svc = await resolvePostgres(api, p.projectId, branch, service);
+    if (!mode)
+        return showAccess(api, p.projectId, branch, svc.name, opts);
+    const ctx = { service: svc.name, branch: opts.branch, what: `turning private access ${mode}` };
+    let res;
+    try {
+        res = await api.rawRequest('PATCH', `/projects/${p.projectId}/database/settings${settingsSuffix(branch, svc.name)}`, { privateAccess: mode === 'on' });
+    }
+    catch (e) {
+        if (e instanceof ApiError)
+            throw new Error(accessErrorMessage(e, ctx));
+        throw e;
+    }
+    if (handleApproval(res, opts.json))
+        return;
+    if (opts.json)
+        return printJson(res.body);
+    for (const l of privateAccessSetLines(svc.name, mode, res.body))
+        info(l);
+}
+export function privateAccessSetLines(group, mode, body) {
+    const lines = mode === 'on'
+        ? [
+            `postgres ${group}: private access ON — DATABASE_PRIVATE_URL minted beside DATABASE_URL (unchanged)`,
+            '  it resolves only inside InstaCloud compute (insta-compute), not from a laptop or CI — keep DATABASE_URL for those',
+            `  switch a compute over: insta secrets bind DATABASE_URL postgres/${group} --source-name DATABASE_PRIVATE_URL --to compute/<name>, then \`insta compute restart <name>\``,
+            '  other workloads on the compute plane can reach the private endpoint too — the password is what authenticates',
+        ]
+        : [`postgres ${group}: private access off — DATABASE_PRIVATE_URL retracted; DATABASE_URL is unchanged`];
+    for (const w of Array.isArray(body?.warnings) ? body.warnings : [])
+        if (typeof w === 'string' && w)
+            lines.push(`  ! ${w}`);
+    return lines;
+}
+async function showAccess(api, projectId, branch, group, opts) {
+    const read = await fetchDbInstance(api, projectId, settingsSuffix(branch, group));
+    if (read.kind === 'no-instance') {
+        info(`postgres ${group}: no manageable instance (network access is not configurable for this service)`);
+        return;
+    }
+    if (opts.json)
+        return printJson(read.body);
+    for (const l of dbAccessLines(group, read.body))
+        info(l);
+}
 //# sourceMappingURL=postgres.js.map

package/dist/commands/services.js

@@ -70,6 +70,13 @@ export function parseVolumeGib(raw) {
         throw new Error(`invalid volume size: ${raw} (whole Gi — try 1 or 10)`);
     return n;
 }
+// Decimal digits only, as parsePort; which majors exist is the platform's answer (a 400 naming them).
+export function parsePgVersion(raw) {
+    const m = /^\s*(\d+)\s*$/.exec(raw);
+    if (!m)
+        throw new Error(`invalid Postgres major: ${raw} (a whole major version, e.g. 17)`);
+    return Number(m[1]);
+}
 // Resolve a service id from a `services list` result by (type, name).
 export function resolveServiceId(services, type, name) {
     const svc = services.find((s) => s.type === type && s.name === name);
@@ -112,6 +119,7 @@ export function servicesAddRequestBody(type, name, branch, opts) {
         ...(opts.alwaysOn !== undefined ? { alwaysOn: opts.alwaysOn } : {}),
         ...(opts.volume !== undefined ? { volumeGib: parseVolumeGib(opts.volume) } : {}),
         ...(opts.mountPath !== undefined ? { volumeMountPath: opts.mountPath } : {}),
+        ...(opts.pgVersion !== undefined ? { pgVersion: parsePgVersion(opts.pgVersion) } : {}),
     };
 }
 export async function servicesAdd(type, name, opts = {}) {
@@ -137,6 +145,11 @@ export async function servicesAdd(type, name, opts = {}) {
             throw new Error(volumeTypeError(type));
         parseVolumeGib(opts.volume); // junk fails here, before any config/network access
     }
+    if (opts.pgVersion !== undefined) {
+        if (type !== 'postgres')
+            throw new Error('--pg-version is only valid for postgres services');
+        parsePgVersion(opts.pgVersion);
+    }
     const api = await ApiClient.load();
     const p = await requireProject();
     const branch = opts.branch ?? p.branch;

package/dist/index.js

@@ -36,7 +36,7 @@ import * as template from './commands/template.js';
 import * as govern from './commands/govern.js';
 import * as observe from './commands/observe.js';
 import * as obs from './commands/metrics.js';
-import { billing, billingUpgrade, billingPortal } from './commands/billing.js';
+import { billing, billingUpgrade, billingPortal, billingRedeem } from './commands/billing.js';
 import * as domainCmd from './commands/domain.js';
 import * as selfUpdate from './commands/upgrade.js';
 import * as feedbackCmd from './commands/feedback.js';
@@ -158,6 +158,7 @@ svc.command('add [type] [name]').description('Provision a service on demand (com
     .option('--no-always-on', 'compute only: create as scale-to-zero — idle machines suspend and wake on the next request')
     .option('--mount-path <path>', 'compute only: container mount path for a new volume (requires --volume; default /data)')
     .option('--volume <gi>', 'compute only: attach a persistent volume of this many whole Gi (also attachable later: `insta compute volume <name> --size <gi>`). Any plan may attach up to its own plan cap (10Gi free, 50Gi paid by default; the bare `insta compute volume <name>` read prints it as plan max); a size above the free cap is paid. Volume services keep 1 machine and stop (cold wake) instead of suspend when idle')
+    .option('--pg-version <major>', 'postgres only: the Postgres major version to create the database on — 16, 17 or 18 (default 16). Fixed for the database\'s lifetime; branches keep it')
     .option('--json')
     .action(guard(async (type, name, o) => {
     const a = await resolveServiceArgs(type, name, serviceArgsDeps(o.json), o);
@@ -172,10 +173,11 @@ svc.command('rename <type> <name> <new-name>').description('Rename a service and
     .option('--json').option('--branch <branch>', 'branch (default: current)')
     .action(guard((type, name, newName, o) => services.servicesRename(type, name, newName, o)));
 // ---- secrets (seam) ----
-const sec = program.command('secrets').description('Fetch the credential bundle (secret seam) into .env')
+const sec = program.command('secrets').description('Write a local .env bundle: user secrets plus primary provider credentials; compute credentials require explicit bindings')
     .option('--branch <branch>')
     .option('--service <type/name>', "read one compute service's own slice of the bundle instead of the branch-wide merge, e.g. compute/api")
     .option('-o, --output <file>', 'output file (default .env)').option('--print', 'print instead of writing').option('--json')
+    .addHelpText('after', '\nFetching this bundle does not bind credentials to compute. A service created with `insta service add compute` starts with no provider credential bindings; bind each source it needs, then deploy.\n\nExample: insta secrets bind DATABASE_URL postgres/db --to compute/app')
     .action(guard((o) => secretsCmd.secrets(o)));
 // commander 12 defaults allowExcessArguments to true, so a mistyped/retired subcommand (e.g.
 // `secrets lst`) would otherwise run this group's own action instead of failing.
@@ -188,11 +190,12 @@ sec.command('unset <name>').description('Remove a user secret')
     .option('--branch <branch>', 'scope to one branch')
     .option('--service <type/name>', "remove only that service's copy, e.g. compute/api")
     .option('--json').action(guard((n, o) => secretsCmd.secretsUnset(n, o)));
-sec.command('bind <env-name> <source>').description('Bind a service credential into a compute env var')
+sec.command('bind <env-name> <source>').description('Bind one provider credential to a compute service (applied on next deploy or restart)')
     .option('--branch <branch>', 'branch (default: current)')
     .option('--to <compute-service>', 'target compute service, e.g. compute/api')
     .option('--source-name <name>', 'source credential name when the source exposes more than one')
     .option('--json')
+    .addHelpText('after', '\nThe local .env bundle includes primary provider credentials without bindings. Compute services require their own explicit bindings: `insta service add compute` creates a service with no provider credential bindings inherited from other services.\n\nExample: insta secrets bind DATABASE_URL postgres/db --to compute/app')
     .action(guard((n, source, o) => secretsCmd.secretsBind(n, source, o)));
 sec.command('unbind <env-name>').description('Remove a service credential binding from a compute env var')
     .option('--branch <branch>', 'branch (default: current)')
@@ -420,8 +423,8 @@ compute.command('volume [service]').description("Show, attach, grow, remount, or
     .option('--json').option('--branch <branch>', 'branch (default: current)').action(guard((service, o) => computeCmd.computeVolume(service, o)));
 addObservability(compute, 'compute', 'compute');
 // ---- postgres ----
-const pg = program.command('postgres').description('Postgres services: connection string, psql, stats, resource ceiling, volume, always-on, logs, metrics');
-pg.command('url [service]').description('Print the postgres connection string (DSN) — bare on stdout for piping, e.g. `psql "$(insta postgres url)"` (gated: secrets.read). Provider credentials are not in `insta secrets` — this is the command that yields the DSN')
+const pg = program.command('postgres').description('Postgres services: connection string, psql, stats, resource ceiling, volume, always-on, network access, logs, metrics');
+pg.command('url [service]').description('Print the postgres connection string (DSN) — bare on stdout for piping, e.g. `psql "$(insta postgres url)"` (gated: secrets.read). `insta secrets` includes the primary postgres service\'s DATABASE_URL; use this command to select a specific postgres service')
     .option('--json').option('--branch <branch>', 'branch (default: current)')
     .action(guard((service, o) => pgCmd.dbUrl(service, o)));
 pg.command('connect [service]').description("Open an interactive psql session on the postgres service (needs psql on PATH; gated: secrets.read). A suspended instance wakes on connect — the first prompt can take a few seconds. Exits with psql's own exit code")
@@ -441,8 +444,15 @@ pg.command('volume [service]').description("Show or grow a postgres service's pr
 pg.command('always-on [mode] [service]').description('Show or set a postgres service always-on (mode: on|off; no mode = print the current setting). on = instance stays warm, no cold starts; off = default scale-to-zero (idle instance suspends; first connection cold-starts). insta-db-backed services only')
     .option('--json').option('--branch <branch>', 'branch (default: current)')
     .action(guard((mode, service, o) => pgCmd.dbAlwaysOn(mode, service, o)));
+pg.command('private-access [mode] [service]').description('Show or set private network access (mode: on|off; no mode = print public and private access). on = mint DATABASE_PRIVATE_URL beside DATABASE_URL (unchanged) — it resolves only inside InstaCloud compute, not from a laptop or CI; bind it into a compute with `insta secrets bind … --source-name DATABASE_PRIVATE_URL`. off = retract it (refused while public access is closed). insta-db-backed only (gated: service.setAccess)')
+    .option('--json').option('--branch <branch>', 'branch (default: current)')
+    .action(guard((mode, service, o) => pgCmd.dbPrivateAccess(mode, service, o)));
+pg.command('public-access [mode] [service]').description("Show, close or re-open the public endpoint (mode: on|off; no mode = print public and private access). off = the database is not reachable from the internet: external clients, CI and local development can no longer connect, only InstaCloud compute via DATABASE_PRIVATE_URL. Needs private access on first. Prints what will break and asks first; takes effect within about 30 seconds. insta-db-backed only (gated: service.setAccess)")
+    .option('-y, --yes', 'close without asking (required when there is no terminal, or with --json) — read the printed impact first')
+    .option('--json').option('--branch <branch>', 'branch (default: current)')
+    .action(guard((mode, service, o) => pgCmd.dbPublicAccess(mode, service, o)));
 addObservability(pg, 'db', 'postgres');
-// ---- redis / mysql / mongodb (managed Fly databases) ----
+// ---- redis / mysql / mongodb (managed databases) ----
 for (const type of ['redis', 'mysql', 'mongodb']) {
     const g = program.command(type).description(`Managed ${type} services: query, status, resource ceiling, volume, always-on, logs, metrics`);
     const query = g.command('query <service> [args...]').description(type === 'redis'
@@ -530,7 +540,7 @@ tpl.command('deploy <code-or-dir-or-url>').description('Deploy a template onto a
     .option('--json')
     .action(guard((target, o) => template.templateDeploy(target, o)));
 // ---- billing ----
-const bill = program.command('billing').description('Billing: current cycle overview (bare), subscribe to a tier, Stripe portal, usage by dimension')
+const bill = program.command('billing').description('Billing: current cycle overview (bare), subscribe to a tier, redeem a credit code, Stripe portal, usage by dimension')
     .option('--org <id>', 'target org (default: linked project\'s org)').option('--json')
     .action(guard((o) => billing(o)));
 // commander 12 defaults allowExcessArguments to true, so a mistyped/retired subcommand (e.g.
@@ -539,6 +549,9 @@ bill.allowExcessArguments(false);
 bill.command('subscribe <tier>').description('Subscribe the org to a paid tier (pro|team) via Stripe Checkout')
     .option('--org <id>').option('--no-open', 'print the URL instead of opening a browser').option('--json')
     .action(guard((tier, o) => billingUpgrade(tier, o)));
+bill.command('redeem <code>').description("Redeem a one-time credit code into the org's wallet")
+    .option('--org <id>').option('--json')
+    .action(guard((code, o) => billingRedeem(code, o)));
 bill.command('portal').description('Open the Stripe Customer Portal (change plan / card / cancel)')
     .option('--org <id>').option('--no-open', 'print the URL instead of opening a browser').option('--json')
     .action(guard((o) => billingPortal(o)));

package/dist/telemetry.js

@@ -36,6 +36,7 @@ const SAFE_ARGS = {
     'storage set-access': { 0: oneOf(['public', 'private']) },
     'compute scale': { 0: (v) => /^\d+$/.test(v) },
     'compute always-on': { 0: ON_OFF }, 'postgres always-on': { 0: ON_OFF },
+    'postgres private-access': { 0: ON_OFF }, 'postgres public-access': { 0: ON_OFF },
     'redis always-on': { 0: ON_OFF }, 'mysql always-on': { 0: ON_OFF }, 'mongodb always-on': { 0: ON_OFF },
     'template info': { 0: SLUG }, 'billing subscribe': { 0: oneOf(['pro', 'team']) },
     'agent approvals approve': { 0: ID }, 'agent approvals deny': { 0: ID },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "insta",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "type": "module",
   "description": "InstaCloud CLI — a thin client of the platform control-plane API.",
   "keywords": [