insta 0.0.26 → 0.0.28

package/README.md

@@ -79,8 +79,8 @@ plane's address, not the CLI's loopback address.
 ### Services are branch-scoped
 
 A project holds services (`postgres`, `storage`, `compute`) and each branch owns its own
-set. `insta branch create feature-x` forks the parent's services: a Neon branch per
-Postgres, a copy-on-write bucket per storage, a clone of every compute service. From there
+set. `insta branch create feature-x` forks the parent's services: a copy-on-write database
+branch per Postgres, a copy-on-write bucket per storage, a clone of every compute service. From there
 the two branches diverge independently. A project is capped at 10 branches.
 
 ### Credentials come from the secret seam, not a file you maintain
@@ -207,8 +207,9 @@ build never reaches a production installer.
 The `insta` skill and its task guides live in
 [InsForge/insta-skills](https://github.com/InsForge/insta-skills). `insta setup agent`
 installs it user-globally for every coding agent on the machine. `insta project create` and
-`insta project link` additionally install the stack skills (Neon Postgres, Tigris, Better
-Auth) into the project, along with the `insta observe` credential-audit hook.
+`insta project link` additionally install the stack skills (Tigris, Better Auth) into the
+project, along with the `insta observe` credential-audit hook. Postgres needs no stack
+skill — it's plain Postgres, reached directly via `DATABASE_URL`.
 
 ## Contributing
 

package/dist/api.js

@@ -11,6 +11,13 @@ export class ApiError extends Error {
         this.name = 'ApiError';
     }
 }
+// Store a durable insta_ key as the credential: set it as the bearer and drop any refresh token (an insta_ key never rotates; a stale one would leak to /auth/refresh on a 401).
+export function storeApiKeyCredential(cfg, token, user) {
+    cfg.accessToken = token;
+    delete cfg.refreshToken;
+    if (user)
+        cfg.user = user;
+}
 export class ApiClient {
     cfg;
     constructor(cfg) {
@@ -27,6 +34,10 @@ export class ApiClient {
         if (user)
             this.cfg.user = user;
     }
+    // Adopt a durable insta_ key as the credential (non-interactive `login --api-key`).
+    setApiKey(token, user) {
+        storeApiKeyCredential(this.cfg, token, user);
+    }
     clearSession() {
         delete this.cfg.accessToken;
         delete this.cfg.refreshToken;

package/dist/commands/auth.js

@@ -17,6 +17,13 @@ function targetApiUrl(opts) {
     return ENVS[want].api;
 }
 export async function login(opts) {
+    // Login modes are exclusive — pick one. Check presence (not truthiness) so an explicit
+    // empty --api-key= is rejected by validation rather than silently falling through.
+    if (opts.apiKey !== undefined) {
+        if (opts.device || opts.oauth || opts.email)
+            die('choose one login mode: --api-key, --device, --oauth, or --email');
+        return loginApiKey(opts.apiKey, opts);
+    }
     if (opts.device)
         return loginDevice(opts);
     if (opts.oauth)
@@ -65,6 +72,36 @@ export async function loginDevice(opts) {
     await api.persist();
     info(`logged in as ${me.user.email ?? me.user.id} @ ${api.apiUrl}`);
 }
+// Non-interactive login with a durable insta_ key (minted via POST /tokens): store it and confirm against /me. No browser, no polling.
+export async function loginApiKey(key, opts) {
+    const api = await ApiClient.load();
+    const target = targetApiUrl(opts);
+    if (target)
+        api.setApiUrl(target);
+    const user = await applyApiKeyLogin(api, key);
+    await api.persist();
+    info(`logged in as ${user.email ?? user.id} @ ${api.apiUrl}`);
+}
+// Verify an insta_ key and store it: set it first so the /me probe is authed with the key itself, then re-store with the resolved user (401 → bad/revoked).
+export async function applyApiKeyLogin(client, key) {
+    key = key.trim(); // tolerate a trailing newline / stray whitespace from `--api-key "$(cat token)"`
+    if (!key.startsWith('insta_'))
+        throw new Error('--api-key expects an insta_ token (mint one with POST /tokens)');
+    client.setApiKey(key);
+    let me;
+    try {
+        me = await client.request('GET', '/me');
+    }
+    catch (e) {
+        if (e instanceof ApiError && e.status === 401)
+            throw new Error('that insta_ API key was rejected (invalid or revoked) — check it or mint a new one');
+        throw e;
+    }
+    if (!me?.user)
+        throw new Error('unexpected response while verifying the API key');
+    client.setApiKey(key, me.user);
+    return me.user;
+}
 const sleepSeconds = (s) => new Promise((r) => setTimeout(r, s * 1000));
 // Drives the device grant against the platform's Better Auth mount (/api/auth/device*) and
 // returns the approved session token. Injectable poster + wait keep this testable without a

package/dist/commands/compute.js

@@ -1,6 +1,6 @@
 import { ApiClient, requireProject } from '../api.js';
 import { info, printJson, handleApproval } from '../util.js';
-import { resolveComputeServiceId, q } from './services.js';
+import { resolveComputeServiceId, q, parseVolumeGib } from './services.js';
 // Attach a developer-owned custom domain to a branch's compute service. Fly issues the cert + routes
 // it; the platform returns the DNS records to set in your OWN zone.
 export async function setDomain(host, opts) {
@@ -116,6 +116,46 @@ export function parseCpu(raw) {
         throw new Error(`invalid cpu: ${raw} (provider sizes: ${CPU_SIZES.join(', ')})`);
     return n;
 }
+// ---- volume (the persistent /data disk; attach is create-time only) ----
+// Render the volume read. Pure, exported for tests (mirrors serviceListLine). Every plan may view;
+// only growth is paid — that gate is the backend's to enforce, so nothing here pre-blocks.
+export function volumeLines(name, volume, cap) {
+    if (!volume)
+        return [
+            `compute ${name}: no volume attached (attach is create-time only: \`insta services add compute <name> --volume <gi>\`)`,
+        ];
+    return [
+        `compute ${name}: volume ${volume.sizeGib}Gi at ${volume.mountPath}  (plan max ${cap.volumeGib}Gi)`,
+        '  billing is actual data stored — the size is a cap, not a price; grow with --size (grow-only)',
+    ];
+}
+// Show or grow a compute service's /data volume. No --size: a safe read (size + mount path + the
+// plan cap). --size: grow via PUT .../volume — paid and grow-only, but both gates belong to the
+// backend, whose 403/400 messages carry the upgrade hints and must reach the user verbatim (the
+// guard prints ApiError messages as-is).
+export async function computeVolume(serviceName, opts) {
+    const api = await ApiClient.load();
+    const p = await requireProject();
+    const branch = opts.branch ?? p.branch;
+    const { services } = await api.request('GET', `/projects/${p.projectId}/services${q(branch)}`);
+    const id = resolveComputeServiceId(services, serviceName);
+    if (!opts.size) {
+        const r = await api.request('GET', `/projects/${p.projectId}/services/${id}/volume`);
+        if (opts.json)
+            return printJson(r);
+        for (const line of volumeLines(serviceName ?? id, r.volume, r.cap))
+            info(line);
+        return;
+    }
+    const sizeGib = parseVolumeGib(opts.size);
+    const res = await api.rawRequest('PUT', `/projects/${p.projectId}/services/${id}/volume`, { sizeGib });
+    if (handleApproval(res))
+        return;
+    if (opts.json)
+        return printJson(res.body);
+    const v = res.body.volume;
+    info(`compute ${res.body.service?.name ?? serviceName ?? id}: volume grown to ${v.sizeGib}Gi at ${v.mountPath}  (plan max ${res.body.cap.volumeGib}Gi)`);
+}
 // Show or set a compute service's ceiling. With no --memory it PRINTS the current limits and the
 // plan cap (so `insta compute limits` is a safe read), which is also what a UI renders as a slider
 // with its plan-limit marker.

package/dist/commands/db.js

@@ -1,5 +1,6 @@
 import { ApiClient, ApiError, requireProject } from '../api.js';
 import { info, printJson, handleApproval } from '../util.js';
+import { parseVolumeGib } 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
@@ -116,4 +117,61 @@ export async function dbLimits(opts) {
     const mem = typeof res.body?.memoryMib === 'number' ? fmtMib(res.body.memoryMib) : (opts.memory ?? 'unchanged');
     info(`postgres ${opts.group ?? 'default'}: ceiling set to ${cpu} / ${mem}`);
 }
+// Render the instance's volume from a database/instance read. Pure, exported for tests. Reads the
+// CANONICAL volume* names only — storageSize/storageGiB are deprecated aliases the platform drops
+// next release, so depending on them here would be a scheduled breakage.
+export function dbVolumeLines(group, body) {
+    const gib = typeof body?.volumeGib === 'number' ? `${body.volumeGib}Gi` : (typeof body?.volumeSize === 'string' ? body.volumeSize : undefined);
+    if (gib === undefined)
+        return [`postgres ${group}: provider reported no volume size`];
+    const cap = body?.cap?.volumeGib;
+    const region = typeof body?.region === 'string' ? `  ${body.region}` : '';
+    return [
+        `postgres ${group}: volume ${gib}${typeof cap === 'number' ? `  (plan max ${cap}Gi)` : ''}${region}`,
+        '  billing is actual data stored — the size is a cap, not a price; grow with --size (grow-only)',
+    ];
+}
+// Show or grow a postgres service's provisioned volume (block disk; insta-db-backed only). Viewing
+// is available on every plan; growth is paid and grow-only — both gates are the backend's to
+// enforce, so nothing here pre-blocks: its 403/400 messages carry the upgrade hints and are wrapped
+// with context but kept verbatim.
+export async function dbVolume(opts) {
+    const api = await ApiClient.load();
+    const p = await requireProject();
+    const qs = new URLSearchParams();
+    const branch = opts.branch ?? p.branch;
+    if (branch)
+        qs.set('branch', branch);
+    if (opts.group)
+        qs.set('group', opts.group);
+    const suffix = qs.toString() ? `?${qs}` : '';
+    if (!opts.size) {
+        const read = await fetchDbInstance(api, p.projectId, suffix);
+        if (read.kind === 'no-instance') {
+            info(`postgres ${opts.group ?? 'default'}: no manageable instance (Neon-backed services manage their own storage)`);
+            return;
+        }
+        if (opts.json)
+            return printJson(read.body);
+        for (const line of dbVolumeLines(opts.group ?? 'default', read.body))
+            info(line);
+        return;
+    }
+    const sizeGib = parseVolumeGib(opts.size);
+    let res;
+    try {
+        res = await api.rawRequest('PATCH', `/projects/${p.projectId}/database/settings${suffix}`, { volumeSize: `${sizeGib}Gi` });
+    }
+    catch (e) {
+        if (e instanceof ApiError)
+            throw new Error(`growing the volume failed (${e.status}): ${e.message}`);
+        throw e;
+    }
+    if (handleApproval(res))
+        return;
+    if (opts.json)
+        return printJson(res.body);
+    const vg = res.body?.volumeGib;
+    info(`postgres ${opts.group ?? 'default'}: volume ${typeof vg === 'number' ? `grown to ${vg}Gi` : `set to ${sizeGib}Gi`}`);
+}
 //# sourceMappingURL=db.js.map

package/dist/commands/services.js

@@ -23,6 +23,19 @@ export function parseCount(raw) {
         throw new Error(`count must be a positive integer, got: ${raw}`);
     return n;
 }
+// Parse a volume size in whole Gi: "10" or "10Gi" (suffix case-insensitive — unlike the db
+// quantity strings this is not a provider pass-through; the wire value is an integer). Volumes
+// are provisioned block disks, so fractional and Mi values are rejected locally with an example
+// rather than travelling to the server as junk (the parseCpu lesson: NaN serializes to null).
+export function parseVolumeGib(raw) {
+    const m = /^\s*(\d+)\s*(gi|gib|g)?\s*$/i.exec(raw);
+    if (!m)
+        throw new Error(`invalid volume size: ${raw} (whole Gi — try 1 or 10)`);
+    const n = Number(m[1]);
+    if (n < 1)
+        throw new Error(`invalid volume size: ${raw} (whole Gi — try 1 or 10)`);
+    return n;
+}
 // 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);
@@ -54,6 +67,7 @@ export function servicesAddRequestBody(type, name, branch, opts) {
         ...(opts.image ? { image: opts.image } : {}), ...(opts.port ? { port: Number(opts.port) } : {}),
         ...(opts.region ? { region: opts.region } : {}),
         ...(opts.alwaysOn ? { alwaysOn: true } : {}),
+        ...(opts.volume !== undefined ? { volumeGib: parseVolumeGib(opts.volume) } : {}),
     };
 }
 export async function servicesAdd(type, name, opts = {}) {
@@ -68,6 +82,11 @@ export async function servicesAdd(type, name, opts = {}) {
         throw new Error('--port is only valid for compute services');
     if (opts.alwaysOn && type !== 'compute')
         throw new Error('--always-on is only valid for compute services (for postgres, use `insta db always-on on` after creation)');
+    if (opts.volume !== undefined) {
+        if (type !== 'compute')
+            throw new Error('--volume is only valid for compute services (postgres has one by default — grow it with `insta db volume --size`)');
+        parseVolumeGib(opts.volume); // junk fails here, before any config/network access
+    }
     const api = await ApiClient.load();
     const p = await requireProject();
     const branch = opts.branch ?? p.branch;
@@ -77,14 +96,15 @@ export async function servicesAdd(type, name, opts = {}) {
     const svc = res.body.service;
     const access = svc.type === 'storage' ? `  [${svc.public ? 'public' : 'private'}]` : '';
     const img = svc.image ? `  running ${svc.image}${svc.port ? `:${svc.port}` : ''}` : '';
-    info(`added ${type} service ${name} on ${branch ?? 'default'} (${svc.id})${access}${svc.region ? `  ${svc.region}` : ''}${img}${svc.domain ? ` — ${svc.domain}` : ''}`);
+    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}` : ''}`);
     renderNextActions(res.body.nextActions);
 }
 // Render one `services list` row. Pure, so it's unit-tested without a network mock (mirrors
 // billingLines in billing.ts). Compute rows show the running image when the platform reports one.
 export function serviceListLine(s) {
     const extra = s.type === 'compute'
-        ? `  x${s.machine_count}${s.image ? `  running ${s.image}${s.port ? `:${s.port}` : ''}` : ''}`
+        ? `  x${s.machine_count}${s.volume_gib ? `  vol ${s.volume_gib}Gi` : ''}${s.image ? `  running ${s.image}${s.port ? `:${s.port}` : ''}` : ''}`
         : s.type === 'storage' ? `  ${s.public ? 'public' : 'private'}` : '';
     return `${s.type}/${s.name}  [${s.status}]${extra}${s.domain ? `  ${s.domain}` : ''}  ${s.id}`;
 }

package/dist/commands/setup.js

@@ -3,7 +3,7 @@
 // every agent the skills tool knows: the skill is pure product knowledge with brand-gated
 // triggers — no project state in it (the project binding is carried by ./.insta/project.json
 // at command time), so one machine-level copy is strictly better than per-project copies.
-// Stack skills (neon/tigris/better-auth) intentionally stay per-project: their presence in a
+// Stack skills (tigris/better-auth) intentionally stay per-project: their presence in a
 // project doubles as its stack manifest — that install happens on `project create|link`.
 import { spawn } from 'node:child_process';
 import os from 'node:os';

package/dist/ensure-skills.js

@@ -1,6 +1,7 @@
 // Install the related agent skills into a linked project so the developer's coding agent has
-// context for what InstaCloud provisions — the `insta` CLI itself plus the three services you build
-// directly against (Neon Postgres, Tigris storage, Better Auth). Runs `npx skills add`
+// context for what InstaCloud provisions — the `insta` CLI itself plus the services you build
+// directly against (Tigris storage, Better Auth). Postgres gets no vendor skill: instadb is
+// plain Postgres, and agents talk to it directly via DATABASE_URL. Runs `npx skills add`
 // (vercel-labs/skills) fully non-interactively. Best-effort: a failure (offline, npx missing, a
 // repo moved) prints a manual fallback and never blocks or fails the host command — same contract
 // as the observe-hook install.
@@ -13,8 +14,8 @@ import { DEFAULT_ENV, ENVS } from './env.js';
 // Codex → .agents/skills/ (.github/skills/ is the third well-known dir). These are regenerable
 // agent context, not the developer's source — keep them out of git.
 const SKILL_DIRS = ['.claude/skills/', '.agents/skills/', '.github/skills/'];
-// `skills` prints a full-screen ASCII banner at the top of every `add`, so our 4 invocations
-// would stack 4 banners. It skips the banner when it detects an agent driving it rather than a
+// `skills` prints a full-screen ASCII banner at the top of every `add`, so our 3 invocations
+// would stack 3 banners. It skips the banner when it detects an agent driving it rather than a
 // human — AI_AGENT is its first-checked signal (any non-empty value ⇒ agent mode). Setting it is
 // honest here (this IS programmatic, not an interactive prompt) and, because we already pin the
 // agents/skills/-y, has no effect on the install beyond quieting the banner. Preserve a caller's
@@ -32,10 +33,9 @@ const defaultRunner = (cmd, args, inherit = false) => new Promise((resolve) => {
 const AGENT_FLAGS = ['-a', 'claude-code', '-a', 'codex', '-y', '--copy'];
 // `instaSpec` is the insta skill source for the resolved environment (`owner/repo[@ref]`), so a
 // project created against staging gets the staging skill text. The third-party stack skills are
-// environment-independent — they document Neon/Tigris/Better Auth, not our control plane.
+// environment-independent — they document Tigris/Better Auth, not our control plane.
 const skillTargets = (instaSpec) => [
     { label: 'insta', args: ['skills', 'add', instaSpec, '-s', 'insta', ...AGENT_FLAGS] },
-    { label: 'neon-postgres', args: ['skills', 'add', 'neondatabase/agent-skills', '-s', 'neon-postgres', ...AGENT_FLAGS] },
     { label: 'tigris', args: ['skills', 'add', 'tigrisdata/skills',
             '-s', 'tigris-object-operations', '-s', 'file-storage', '-s', 'tigris-sdk-guide',
             '-s', 'tigris-security-access-control', '-s', 'tigris-image-optimization',
@@ -63,7 +63,7 @@ export async function installSkills(deps) {
             targets = skillTargets(skills);
         }
         catch { /* keep production defaults */ }
-        print('  installing related agent skills (insta, neon-postgres, tigris, better-auth) …');
+        print('  installing related agent skills (insta, tigris, better-auth) …');
         for (const s of targets) {
             // Don't stream: the `skills` tool's clack UI (clone spinner, banners) is noise. Run it
             // silent (stdio 'ignore') and let the per-skill ✓/failed line below be the clean output —

package/dist/index.js

@@ -54,11 +54,12 @@ function resolveVersion() {
 }
 program.name('insta').description('InstaCloud CLI — manage projects, branches, secrets, deploys').version(resolveVersion());
 // ---- auth ----
-program.command('login').description('Log in with email + password, --oauth <github|google> (browser), or --device (headless)')
+program.command('login').description('Log in with email + password, --oauth <github|google> (browser), --device (headless), or --api-key <insta_…> (headless, durable token)')
     .option('--email <email>', 'account email')
     .option('--password <password>', 'account password (else $INSTA_PASSWORD or prompt)')
     .option('--oauth <provider>', 'browser OAuth login: github | google')
     .option('--device', 'device-code login: approve from a browser on any other machine (VMs, SSH, CI)')
+    .option('--api-key <key>', 'non-interactive login with a durable insta_ API token (headless agents / CI)')
     .option('--api-url <url>', 'control-plane API base URL')
     .option('--env <name>', `deployment environment: ${ENV_NAMES.join(' | ')}`)
     .action(guard((o) => auth.login(o)));
@@ -114,6 +115,7 @@ svc.command('add <type> <name>').description('Provision a service on demand (ass
     .option('--image <url>', 'compute only: run this container image at creation')
     .option('--port <n>', 'compute only: port the image listens on (default 8080)')
     .option('--always-on', 'compute only: create as always-on — never scales to zero (all plans; billing is actual usage either way)')
+    .option('--volume <gi>', 'compute only: attach a persistent /data volume of this many whole Gi (create-time only; any plan may attach at the default 1; larger sizes are paid and plan-capped). Volume services keep 1 machine and stop (cold wake) instead of suspend when idle')
     .action(guard((type, name, o) => services.servicesAdd(type, name, o)));
 svc.command('list').option('--json').option('--branch <branch>', 'branch (default: current)')
     .action(guard((o) => services.servicesList(o)));
@@ -169,8 +171,11 @@ compute.command('limits [service]').description("Show or set a compute service's
     .option('--json').option('--branch <branch>', 'branch (default: current)').action(guard((service, o) => computeCmd.computeLimits(service, o)));
 compute.command('always-on <mode> [service]').description('Set a compute service always-on (mode: on|off). on = machines never scale to zero; off = default scale-to-zero. All plans; billing is actual usage either way')
     .option('--json').option('--branch <branch>', 'branch (default: current)').action(guard((mode, service, o) => computeCmd.computeAlwaysOn(mode, service, o)));
+compute.command('volume [service]').description("Show or grow a compute service's persistent /data volume. No --size: print size, mount path, and the plan cap (any plan). --size grows it (paid plans; grow-only — a provisioned disk cannot shrink). Attach is create-time only: `insta services add compute <name> --volume <gi>`. Billing is actual data stored — the size is a cap, not a price")
+    .option('--size <gi>', 'new size in whole Gi, e.g. 10 (must be ≥ the current size)')
+    .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 / always-on / scale-to-zero)');
+const db = program.command('db').description('Postgres service controls (limits / volume / always-on / scale-to-zero)');
 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)')
@@ -178,6 +183,10 @@ db.command('limits').description("Show or set a postgres service's resource ceil
 db.command('always-on <mode>').description('Set a postgres service always-on (mode: on|off). 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)').option('--group <g>', 'postgres service name (default: the sole/default one)')
     .action(guard((mode, o) => dbCmd.dbAlwaysOn(mode, o)));
+db.command('volume').description("Show or grow a postgres service's provisioned volume (block disk; insta-db-backed only). No --size: print size and the plan cap (any plan). --size grows it (paid plans; grow-only — a provisioned disk cannot shrink). Billing is actual data stored — the size is a cap, not a price")
+    .option('--size <gi>', 'new size in whole Gi, e.g. 10 (must be ≥ the current size)')
+    .option('--json').option('--branch <branch>', 'branch (default: current)').option('--group <g>', 'postgres service name (default: the sole/default one)')
+    .action(guard((o) => dbCmd.dbVolume(o)));
 // ---- manifest ----
 program.command('manifest').description('Print an agent-legible view of the project environments').option('--json').action(guard((o) => manifest(o)));
 // ---- regions ----

package/package.json

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