insta 0.0.45 → 0.0.48

package/README.md

@@ -65,13 +65,15 @@ insta login --oauth github
 insta project create my-app
 insta services add postgres db
 insta services add compute api
+insta secrets bind DATABASE_URL postgres/db --to compute/api
 insta secrets
 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 credentials to
-`./.env`. `deploy .` builds the directory remotely and ships it to the branch's compute
+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 db url`). `deploy .`
+builds the directory remotely and ships it to the branch's compute
 service; it needs a `Dockerfile`, but no local Docker.
 
 ## Authentication
@@ -104,10 +106,12 @@ 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 bundle and writes `./.env`. `insta run <cmd>`
-does the same without touching disk, injecting the bundle into the child process only.
-Credential names are per service — `DATABASE_URL`, `BUCKET_NAME`, `AWS_ACCESS_KEY_ID` —
-suffixed with the service name when a project has more than one service of a type.
+`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 db url` (or `insta db connect` for a psql session).
 
 ### Destructive actions can require approval
 
@@ -197,6 +201,7 @@ build never reaches a production installer.
 | `insta run <cmd>` | Run a command with the branch bundle injected, nothing written to disk |
 | `insta deploy [dir]` | Deploy a source directory (built remotely) or `--image <url>` |
 | `insta compute` | `start` · `stop` · `suspend` · `status` · `set-domain` · `check-domain` · `remove-domain` |
+| `insta db` | `url` (print the postgres DSN) · `connect` (psql session) · `limits` · `stats` · `always-on` · `volume` |
 | `insta regions` | Regions available for postgres and compute |
 | `insta manifest` | Agent-legible view of every branch and its URLs |
 | `insta metrics` · `logs` · `events` | Service metrics; runtime logs (`--deploy` for deploy events); audit timeline |

package/dist/commands/auth.js

@@ -194,8 +194,12 @@ function browserOauth(apiUrl, provider) {
             const redirect = `http://127.0.0.1:${port}/callback`;
             const authorizeUrl = `${apiUrl}/auth/cli/authorize?provider=${encodeURIComponent(provider)}&redirect=${encodeURIComponent(redirect)}&state=${state}`;
             info(`opening browser to authorize with ${provider}…`);
-            if (!openUrl(authorizeUrl))
-                info(`open this URL to continue:\n  ${authorizeUrl}`);
+            // Always print the URL: a launcher that fails to start reports it on spawn's ASYNC error
+            // event, so openUrl's return value cannot see it (e.g. powershell.exe blocked by AppLocker
+            // on hardened fleets) — and the silent variant of that failure looks exactly like a hang.
+            info(`if nothing opens, use this URL:\n  ${authorizeUrl}`);
+            openUrl(authorizeUrl);
+            info('waiting for you to finish in the browser… (times out in 2m; ctrl-c to abort)');
             timer = setTimeout(() => { server.close(); reject(new Error('timed out waiting for browser login (2m)')); }, 120_000);
         });
     });

package/dist/commands/billing.js

@@ -67,11 +67,14 @@ export async function billingPortal(opts) {
         return printJson({ url });
     presentUrl(url, 'Manage billing in your browser:', opts.open);
 }
-// Print the URL and, unless --no-open, try to open it in the browser.
+// Print the URL and, unless --no-open, try to open it in the browser. The message says
+// "opening", not "opened": a launcher that starts and then fails reports it asynchronously,
+// so openUrl's true return is an attempt, not a confirmation (see util.ts) — and the URL is
+// already printed above for exactly that case.
 function presentUrl(url, label, open) {
     info(label);
     info(`  ${url}`);
     if (open !== false && openUrl(url))
-        info('(opened in your default browser)');
+        info('(opening in your default browser…)');
 }
 //# sourceMappingURL=billing.js.map

package/dist/commands/db.js

@@ -1,6 +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 } from '../util.js';
-import { parseVolumeGib } from './services.js';
+import { parseVolumeGib, q, resolveSoleService } from './services.js';
 // Toggle a postgres service between scale-to-zero (the default: instance suspends when idle,
 // cold-starts on the next connection) and always-on (instance stays warm; idle RAM bills at
 // actual usage). Thin wrapper over PATCH /database/settings {scaleToZero} — insta-db-backed
@@ -237,4 +239,97 @@ export async function dbVolume(opts) {
     const vg = res.body?.volumeGib;
     info(`postgres ${opts.group ?? 'default'}: volume ${typeof vg === 'number' ? `grown to ${vg}Gi` : `set to ${sizeGib}Gi`}`);
 }
+// Resolve the postgres service (sole, or --group) 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, group, json) {
+    const { services } = await api.request('GET', `/projects/${projectId}/services${q(branch)}`);
+    const svc = resolveSoleService(services, 'postgres', group);
+    const res = await api.rawRequest('GET', `/projects/${projectId}/services/${svc.id}/credentials`);
+    if (handleApproval(res, json))
+        return null;
+    const url = res.body?.credentials?.DATABASE_URL;
+    if (typeof url !== 'string' || !url) {
+        throw new Error(`postgres ${svc.name} has no DATABASE_URL credential yet — still provisioning? (\`insta services list\` shows status)`);
+    }
+    return { serviceName: svc.name, url };
+}
+// Print the postgres connection string: the bare DSN on stdout, nothing else — pipe-friendly
+// (`psql "$(insta db url)"`), like `storage get --json` keeps stdout parseable.
+export async function dbUrl(opts) {
+    const api = await ApiClient.load();
+    const p = await requireProject();
+    const branch = opts.branch ?? p.branch;
+    const r = await resolveDbUrl(api, p.projectId, branch, opts.group, opts.json);
+    if (!r)
+        return;
+    if (opts.json)
+        return printJson({ service: r.serviceName, branch: branch ?? null, url: r.url });
+    process.stdout.write(r.url + '\n');
+}
+// Decompose a postgres DSN into libpq PG* environment variables. Pure, exported for tests.
+// The credential must NOT ride in psql's argv — process arguments are visible to every local
+// user via `ps`, so a secrets.read-gated value would leak the moment the session starts. Child
+// environment is not (the `insta run` model), and PG* env is a libpq-supported mechanism, so
+// psql runs with an empty argv. `sslmode` is the only query param the platform's DSNs carry;
+// anything else would be a platform-side change this mapping should then learn about.
+export function psqlEnvFromUrl(url) {
+    const u = new URL(url);
+    const env = {};
+    if (u.hostname)
+        env.PGHOST = decodeURIComponent(u.hostname);
+    if (u.port)
+        env.PGPORT = u.port;
+    if (u.username)
+        env.PGUSER = decodeURIComponent(u.username);
+    if (u.password)
+        env.PGPASSWORD = decodeURIComponent(u.password);
+    const db = u.pathname.replace(/^\//, '');
+    if (db)
+        env.PGDATABASE = decodeURIComponent(db);
+    const sslmode = u.searchParams.get('sslmode');
+    if (sslmode)
+        env.PGSSLMODE = sslmode;
+    return env;
+}
+/** Core, dependency-injected for tests: spawn psql against the DSN (via PG* env, never argv), return its exit code. */
+export async function connectWithPsql(url, spawnImpl = spawn) {
+    // Strip ambient PG* first: parent-env PGHOSTADDR/PGSERVICE/PGOPTIONS/PGSSL* would silently
+    // redirect or reshape the connection away from the service this command just resolved.
+    const env = { ...process.env };
+    // Case-insensitive: Windows env names are case-insensitive, so ambient `pgservice` redirects
+    // psql just as PGSERVICE does.
+    for (const k of Object.keys(env))
+        if (k.slice(0, 2).toUpperCase() === 'PG')
+            delete env[k];
+    Object.assign(env, psqlEnvFromUrl(url));
+    return await new Promise((resolve, reject) => {
+        const child = spawnImpl('psql', [], { stdio: 'inherit', env });
+        child.on('error', (e) => reject(e.code === 'ENOENT'
+            ? new Error('psql not found on PATH — install the postgres client, or print the DSN with `insta db url`')
+            : e));
+        // Signal death reports code null — map to the conventional 128+signo (full table from
+        // os.constants) so the advertised exit-status passthrough holds for Ctrl-C'd/killed sessions.
+        child.on('close', (code, signal) => resolve(code ?? (signal ? 128 + (osConstants.signals[signal] ?? 0) : 1)));
+    });
+}
+// Open an interactive psql session on the postgres service. The DSN never touches disk or argv
+// history beyond the child process. Exits with psql's own exit code (agents rely on this, as
+// with `compute exec`).
+export async function dbConnect(opts) {
+    const api = await ApiClient.load();
+    const p = await requireProject();
+    const branch = opts.branch ?? p.branch;
+    const r = await resolveDbUrl(api, p.projectId, branch, opts.group, opts.json);
+    if (!r)
+        return;
+    // stderr: stdout belongs to psql (the `insta run` rule).
+    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`);
+    process.exit(await connectWithPsql(r.url));
+}
 //# sourceMappingURL=db.js.map

package/dist/commands/manifest.js

@@ -1,5 +1,28 @@
 import { ApiClient, requireProject } from '../api.js';
 import { info, printJson } from '../util.js';
+/**
+ * The label that names WHERE a resource runs.
+ *
+ * `kind` is the platform's internal resource kind, and for compute it is always 'fly' — 'fly' is
+ * the compute SEAT, occupied by the microvm plane on any environment that has cut over. Printing
+ * it is how `insta manifest` came to tell users and agents that a microvm-backed service ran on
+ * Fly (staging, 2026-08-25: `fly(api)` for a row serving from warm pod insta-warm-00178a-16).
+ *
+ * So for compute rows the label is the platform's explicit `provider`, and when that is absent --
+ * an older platform, or a row whose provider the platform itself could not determine -- we fall
+ * back to the neutral 'compute'. That names the resource without asserting a plane: no provider
+ * beats a wrong one. Non-compute kinds keep printing their kind.
+ */
+export function resourceLabel(r) {
+    const kind = r.kind ?? 'resource';
+    const label = kind === 'fly' ? (r.provider === 'fly' || r.provider === 'microvm' ? r.provider : 'compute') : kind;
+    return `${label}${r.name ? `(${r.name})` : ''}`;
+}
+// One `manifest` resource line. Pure, so the label is unit-tested without a network mock.
+export function resourceLine(r) {
+    const where = r.ref?.url ?? r.ref?.bucket ?? r.ref?.neonProjectId ?? '';
+    return `    - ${resourceLabel(r)}  ${where}  [${r.status}]`;
+}
 // Agent-legible view of each environment's databases / storage / compute.
 export async function manifest(opts) {
     const api = await ApiClient.load();
@@ -11,10 +34,8 @@ export async function manifest(opts) {
     for (const b of detail.branches) {
         info(`  branch ${b.name}${b.is_default ? ' *' : ''} [${b.status}]`);
         const rs = detail.resources.filter((r) => r.branchId === b.id || (b.is_default && r.branchId === null));
-        for (const r of rs) {
-            const where = r.ref?.url ?? r.ref?.bucket ?? r.ref?.neonProjectId ?? '';
-            info(`    - ${r.kind}${r.name ? `(${r.name})` : ''}  ${where}  [${r.status}]`);
-        }
+        for (const r of rs)
+            info(resourceLine(r));
     }
 }
 //# sourceMappingURL=manifest.js.map

package/dist/commands/services.js

@@ -120,6 +120,14 @@ export async function servicesAdd(type, name, opts = {}) {
     const img = svc.image ? `  running ${svc.image}${svc.port ? `:${svc.port}` : ''}` : '';
     const vol = svc.volume_gib ? `  vol ${svc.volume_gib}Gi at /data` : '';
     info(`added ${type} service ${name} on ${branch ?? 'default'} (${svc.id})${access}${svc.region ? `  ${svc.region}` : ''}${img}${vol}${svc.domain ? ` — ${svc.domain}` : ''}`);
+    // Discoverability: the DB is directly dialable, but its DSN is deliberately absent from the
+    // general `insta secrets` bundle — without this line nothing in the product says how to reach it.
+    if (type === 'postgres') {
+        // The hint must be runnable as printed: carry --branch when the service was created on a
+        // branch other than the linked one, and --group so it survives multiple postgres services.
+        const flags = `${opts.branch ? ` --branch ${opts.branch}` : ''} --group ${name}`;
+        info(`  connect: \`insta db url${flags}\` prints the connection string, \`insta db connect${flags}\` opens psql (--group optional with a single postgres service)`);
+    }
     renderNextActions(res.body.nextActions);
 }
 // Render one `services list` row. Pure, so it's unit-tested without a network mock (mirrors

package/dist/commands/setup.js

@@ -15,6 +15,7 @@ import { readPersistedGlobal, resolveEnv } from '../config.js';
 import { DEFAULT_ENV, ENVS, ENV_NAMES, envForApiUrl, envFromEnvVar, isEnvName, mcpServerName } from '../env.js';
 import { info } from '../util.js';
 import { loginOauth } from './auth.js';
+import { projectLink } from './project.js';
 import { envUse } from './env.js';
 import { installAgentConfigs } from './mcp.js';
 import { detectChannel } from './upgrade.js';
@@ -424,7 +425,7 @@ export async function setupAgent(opts, run = defaultRunner, mint, installConfigs
     login: () => loginOauth('github', {}),
     stdinTty: canPromptViaTty(),
     stdoutTty: !!process.stdout.isTTY,
-}) {
+}, link = projectLink) {
     if (!opts.yes && !process.stdout.isTTY) {
         info('non-interactive shell — assuming -y');
     }
@@ -485,6 +486,31 @@ export async function setupAgent(opts, run = defaultRunner, mint, installConfigs
             }
         }
     }
+    // --project: link this directory inside the SAME process. The console's connect panel used to
+    // print `setup agent && insta project link <id>` as one paste — but no shell joiner survives
+    // every Windows shell, and in shells without bracketed paste the queued link line is eaten as
+    // the answer to the login prompt above (console PR #290). Carrying the id as a flag is the one
+    // form where "one line" is safe. Linking needs the session: without one the manual command is
+    // the hint, never a hang; a failed link (bad id, no access) is a REAL error — the link is the
+    // entire point of the flag — so it sets the exit code instead of pretending setup succeeded.
+    if (opts.project) {
+        if (!loggedIn) {
+            info(`  not logged in — project not linked; run \`insta login\`, then \`insta project link ${opts.project}\``);
+        }
+        else {
+            try {
+                await link(opts.project);
+            }
+            catch (e) {
+                // Stop here — like the skill-install failure above, finishing with the success summary
+                // and a cheerful `next:` after an error is mixed messaging. Setup itself did succeed,
+                // so say exactly that alongside the retry command.
+                info(`  project link failed (${e instanceof Error ? e.message : String(e)}) — agent setup itself is done; run \`insta project link ${opts.project}\` to retry the link`);
+                process.exitCode = 1;
+                return;
+            }
+        }
+    }
     // THE summary line. The restart note exists because config-file agents only read their MCP
     // config at startup; the skill files need no restart.
     const mcpOk = claude === 'new' || claude === 'existing' || others.length > 0;

package/dist/commands/template.js

@@ -351,7 +351,8 @@ export async function templateDeploy(target, opts = {}, deps = {}) {
     info(`template ${codeLabel} deployed to branch ${branchName}`);
     for (const u of deploymentUrls(dep))
         info(`  ${u}`);
-    info('next: run `insta secrets` to refresh .env with the new service credentials');
+    // Provider credentials are not in the `insta secrets` bundle — point at the paths that exist.
+    info('next: `insta db url` prints the postgres DSN; bind service credentials into compute with `insta secrets bind`; `insta secrets` refreshes user-defined secrets in .env');
     renderNextActions(dep.nextActions);
 }
 //# sourceMappingURL=template.js.map

package/dist/index.js

@@ -87,6 +87,7 @@ setupCmd.command('agent').description('Install the insta CLI (if missing), the i
     .option('-y, --yes', 'non-interactive')
     .option('--env <prod|staging>', 'deployment to set this machine up for (default: prod — switches and persists, like `insta env use`)')
     .option('--mcp-token', 'register the MCP server with a minted insta_ API token instead of OAuth (headless machines / CI)')
+    .option('--project <id>', 'also link this directory to an existing project after setup (flows through login first if needed)')
     .action(guard((o) => setup.setupAgent(o)));
 // ---- MCP server integration ----
 const mcpCmd = program.command('mcp').description('insta-cloud remote MCP server integration');
@@ -223,7 +224,13 @@ compute.command('volume [service]').description("Show, attach, grow, or delete a
     .option('--delete', 'destroy the volume and ALL its data (irreversible; download anything you need first)')
     .option('--json').option('--branch <branch>', 'branch (default: current)').action(guard((service, o) => computeCmd.computeVolume(service, o)));
 // ---- db (postgres service controls) ----
-const db = program.command('db').description('Postgres service controls (limits / volume / always-on / scale-to-zero)');
+const db = program.command('db').description('Postgres service controls (url / connect / limits / volume / always-on / scale-to-zero)');
+db.command('url').description('Print the postgres connection string (DSN) — bare on stdout for piping, e.g. `psql "$(insta db url)"` (gated: secrets.read). Provider credentials are not in `insta secrets` — this is the command that yields the DSN')
+    .option('--json').option('--branch <branch>', 'branch (default: current)').option('--group <g>', 'postgres service name (default: the sole/default one)')
+    .action(guard((o) => dbCmd.dbUrl(o)));
+db.command('connect').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")
+    .option('--branch <branch>', 'branch (default: current)').option('--group <g>', 'postgres service name (default: the sole/default one)')
+    .action(guard((o) => dbCmd.dbConnect(o)));
 db.command('limits').description("Show or set a postgres service's resource ceiling (paid plans; insta-db-backed only). Moves both directions")
     .option('--cpu <n>', "vCPU ceiling, e.g. 2 or 2500m").option('--memory <size>', "memory ceiling, e.g. 4Gi")
     .option('--json').option('--branch <branch>', 'branch (default: current)').option('--group <g>', 'postgres service name (default: the sole/default one)')

package/dist/util.js

@@ -1,10 +1,43 @@
 // Output + small pure helpers (env serialization is unit-tested).
 import { createInterface } from 'node:readline';
 import { spawn } from 'node:child_process';
-// Best-effort: open a URL in the user's default browser. Returns false if we couldn't launch.
+/** How to launch the default browser for `url` on `platform`. Pure so the Windows encoding is
+ *  testable. On Windows NO shell may ever parse the URL: cmd.exe splits at bare `&` (which #138
+ *  fixed by quoting) but ALSO expands `%…%` sequences even inside quotes, and a percent-encoded
+ *  OAuth redirect (`http%3A%2F%2F127.0.0.1…`) is nothing but such sequences. So the launch goes
+ *  through PowerShell's -EncodedCommand: a pure-ASCII script travels as base64(UTF-16LE) — no
+ *  argument parsing anywhere — and the URL itself rides as a second base64 payload INSIDE that
+ *  script, decoded by .NET at runtime, so no URL byte ever appears in PowerShell source (see the
+ *  win32 branch). Start-Process on a URL is ShellExecute, i.e. the default browser. */
+export function openUrlSpawn(url, platform = process.platform, 
+// Absolute path, not bare `powershell`: CreateProcess-style lookup searches the current
+// directory before PATH, so a planted powershell.exe beside the user's shell would win.
+systemRoot = process.env.SYSTEMROOT ?? process.env.windir ?? 'C:\\Windows') {
+    if (platform === 'win32') {
+        // The URL never appears in PowerShell SOURCE at all: it travels as base64 inside the script
+        // and is decoded by .NET at runtime. Interpolating it into a quoted literal is not enough —
+        // PowerShell honors smart quotes (U+2018–U+201B) as string delimiters too, so ASCII-only
+        // escaping still leaves a breakout. The script below is pure ASCII by construction (the
+        // base64 alphabet), so no byte of any URL can terminate anything.
+        const urlB64 = Buffer.from(url, 'utf8').toString('base64');
+        const script = `Start-Process ([Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('${urlB64}')))`;
+        return {
+            cmd: `${systemRoot}\\System32\\WindowsPowerShell\\v1.0\\powershell.exe`,
+            args: ['-NoProfile', '-NonInteractive', '-EncodedCommand', Buffer.from(script, 'utf16le').toString('base64')],
+        };
+    }
+    return { cmd: platform === 'darwin' ? 'open' : 'xdg-open', args: [url] };
+}
+// ShellExecute-family launchers (Start-Process/open/xdg-open) run ANY target they're handed —
+// a UNC path is an execution, not a navigation — so only web URLs may reach them.
+export const isWebUrl = (url) => /^https?:\/\//i.test(url);
+// Best-effort: open a URL in the user's default browser. Returns false if we couldn't launch —
+// but a launcher that starts and THEN fails (ENOENT arrives on the async 'error' event) still
+// reads as true, so callers must not treat true as proof the browser opened.
 export function openUrl(url) {
-    const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'cmd' : 'xdg-open';
-    const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url];
+    if (!isWebUrl(url))
+        return false;
+    const { cmd, args } = openUrlSpawn(url);
     try {
         const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
         child.on('error', () => { });

package/package.json

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