insta 0.0.28 → 0.0.30

package/dist/commands/compute.js

@@ -116,23 +116,32 @@ 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) ----
+// ---- volume (the persistent /data disk; attach any time, grow-only, never detach) ----
 // 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>\`)`,
+            `compute ${name}: no volume attached (attach one: \`insta compute volume ${name} --size <gi>\` — it mounts at /data on the next deploy)`,
         ];
     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).
+// Render the PUT result. Pure, exported for tests. `attached` comes from the backend and is what
+// tells a FIRST attach (no disk yet — it mounts on the next deploy) apart from a grow (the live
+// disk was already extended); the wire size is authoritative in both cases.
+export function volumeWriteLine(name, body) {
+    if (body.attached) {
+        return `compute ${name}: volume ${body.volume.sizeGib}Gi attached — mounts at ${body.volume.mountPath} on the next deploy  (plan max ${body.cap.volumeGib}Gi)`;
+    }
+    return `compute ${name}: volume grown to ${body.volume.sizeGib}Gi at ${body.volume.mountPath}  (plan max ${body.cap.volumeGib}Gi)`;
+}
+// Show, attach, or grow a compute service's /data volume. No --size: a safe read (size + mount
+// path + the plan cap). --size: PUT .../volume — attaches when no volume exists, grows otherwise.
+// The paid/cap/machine-count gates all 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();
@@ -153,8 +162,7 @@ export async function computeVolume(serviceName, opts) {
         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)`);
+    info(volumeWriteLine(res.body.service?.name ?? serviceName ?? id, res.body));
 }
 // 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

package/dist/commands/db.js

@@ -120,6 +120,65 @@ export async function dbLimits(opts) {
 // 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.
+// Bytes → human units, one decimal above KiB. Local because the metrics payload is the only
+// bytes-denominated read in this file (fmtMib serves the MiB-denominated resize path).
+export function fmtBytes(n) {
+    if (n < 1024)
+        return `${n} B`;
+    const units = ['KiB', 'MiB', 'GiB', 'TiB'];
+    let v = n / 1024;
+    let i = 0;
+    while (v >= 1024 && i < units.length - 1) {
+        v /= 1024;
+        i++;
+    }
+    return `${v.toFixed(1)} ${units[i]}`;
+}
+// Human-readable stats lines from GET /database/metrics. Pure seam for tests. "—" for anything
+// unmeasured (old platform, suspended instance, no cache traffic yet) — never a fake 0: the
+// platform omits cacheHitRatio and sends max 0 in exactly those cases.
+export function dbStatsLines(group, body) {
+    const c = body?.connections ?? {};
+    const max = typeof c.max === 'number' && c.max > 0 ? c.max : null;
+    const total = typeof c.total === 'number' ? c.total : null;
+    const conn = total === null ? '—'
+        : (max === null ? String(total) : `${total} / ${max}`)
+            + (typeof c.active === 'number' && max !== null ? ` (${c.active} active)` : '');
+    const ratio = body?.cacheHitRatio;
+    const cache = typeof ratio === 'number' ? `${(ratio * 100).toFixed(1)}%` : '—';
+    const size = typeof body?.dbSizeBytes === 'number' ? fmtBytes(body.dbSizeBytes) : '—';
+    const bits = [
+        typeof body?.state === 'string' ? body.state : null,
+        typeof body?.serverVersion === 'string' && body.serverVersion ? `PG ${body.serverVersion}` : null,
+    ].filter(Boolean);
+    const state = bits.length ? ` (${bits.join(' · ')})` : '';
+    return [
+        `postgres ${group}${state}`,
+        `  connections  ${conn}`,
+        `  cache hit    ${cache}`,
+        `  size         ${size}`,
+    ];
+}
+// Point-in-time stats snapshot for a postgres service: connections vs the server's ceiling, cache
+// hit rate, database size. Read-only. insta-db-backed: a suspended instance answers from the
+// provider's control plane (shown as "(suspended)" with structural zeros), never dialed.
+// Neon-backed: the platform reads over a direct SQL connection, so a one-shot call may wake a
+// suspended endpoint — acceptable for an explicit command, which is why nothing here polls.
+export async function dbStats(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 res = await api.rawRequest('GET', `/projects/${p.projectId}/database/metrics${qs.toString() ? `?${qs}` : ''}`);
+    if (opts.json)
+        return printJson(res.body);
+    for (const line of dbStatsLines(opts.group ?? 'default', res.body))
+        info(line);
+}
 export function dbVolumeLines(group, body) {
     const gib = typeof body?.volumeGib === 'number' ? `${body.volumeGib}Gi` : (typeof body?.volumeSize === 'string' ? body.volumeSize : undefined);
     if (gib === undefined)

package/dist/commands/metrics.js

@@ -8,6 +8,58 @@ function qs(params) {
     const s = u.toString();
     return s ? `?${s}` : '';
 }
+// One printed series line. Pure seam so the formatting is testable without a backend.
+//
+// Byte-rate series (compute's egress/ingress) arrive as raw bytes per second, which is unreadable at
+// real traffic volumes — 20480031 bytes/s is 20 MB/s. Percent and vCPU units are already
+// human-sized, so only bytes and byte rates get scaled.
+export function metricLine(s) {
+    const last = s.points?.[s.points.length - 1];
+    const value = last ? formatMetricValue(last[1], s.unit) : 'n/a';
+    const unit = s.unit && !isScaled(s.unit) ? ` (${s.unit})` : '';
+    return `${s.name}${unit}: ${value}  [${s.points?.length ?? 0} points]`;
+}
+// The platform's unit strings are the contract here (`bytes` for memory/storage, `bytes/s` for
+// egress/ingress — src/adapters/fly.ts and insta-db.ts). Matching them loosely is deliberate: an
+// unrecognised unit fails SILENTLY back to the raw 8-digit number this scaling exists to fix, so a
+// casing or spacing change on the platform side must not be enough to regress it.
+function scaleOf(unit) {
+    const u = unit?.trim().toLowerCase();
+    if (u === 'bytes' || u === 'byte' || u === 'b')
+        return 'bytes';
+    if (u === 'bytes/s' || u === 'byte/s' || u === 'b/s' || u === 'bytes/sec')
+        return 'bytes/s';
+    return undefined;
+}
+function isScaled(unit) {
+    return scaleOf(unit) !== undefined;
+}
+function formatMetricValue(v, unit) {
+    if (!Number.isFinite(v))
+        return 'n/a';
+    const scale = scaleOf(unit);
+    // Traffic scales by 1000 because egress is BILLED per decimal GB (`bytes / 1e9`, platform
+    // src/adapters/fly.ts) — a 1024-based "GB/s" would sit ~7% off the invoice. Memory and storage
+    // stay binary: those ceilings are provisioned in GiB. Same split as the console.
+    if (scale === 'bytes')
+        return humanBytes(v, 1024);
+    if (scale === 'bytes/s')
+        return `${humanBytes(v, 1000)}/s`;
+    return String(v);
+}
+function humanBytes(v, base) {
+    const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+    let value = v;
+    let i = 0;
+    while (Math.abs(value) >= base && i < units.length - 1) {
+        value /= base;
+        i += 1;
+    }
+    // Sub-KB values keep their integer form (`512 B`, not `512.0 B`), but a RATE is fractional —
+    // PromQL rate() of a byte counter yields things like 342.857142, which must not print in full.
+    const shown = i === 0 && Number.isInteger(value) ? String(value) : value.toFixed(1);
+    return `${shown} ${units[i]}`;
+}
 // insta metrics <db|compute> [group]
 export async function metrics(component, group, opts) {
     const api = await ApiClient.load();
@@ -19,10 +71,8 @@ export async function metrics(component, group, opts) {
         info(`note: ${res.note}`);
     if (!res.series?.length)
         return info('(no series)');
-    for (const s of res.series) {
-        const last = s.points?.[s.points.length - 1];
-        info(`${s.name}${s.unit ? ` (${s.unit})` : ''}: ${last ? last[1] : 'n/a'}  [${s.points?.length ?? 0} points]`);
-    }
+    for (const s of res.series)
+        info(metricLine(s));
 }
 // Customer-facing name for each internal billing dimension (the platform stores RAM as `ram`).
 const DIMENSION_LABEL = { ram: 'memory' };

package/dist/index.js

@@ -115,7 +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')
+    .option('--volume <gi>', 'compute only: attach a persistent /data volume of this many whole Gi (also attachable later: `insta compute volume <name> --size <gi>`; 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)));
@@ -171,7 +171,7 @@ 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")
+compute.command('volume [service]').description("Show, attach, or grow a compute service's persistent /data volume. No --size: print size, mount path, and the plan cap (any plan). --size on a volumeless service ATTACHES one (any plan at the default 1Gi; larger is paid and plan-capped; the disk mounts at /data on the next deploy); on a volume-bearing one it grows (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)').action(guard((service, o) => computeCmd.computeVolume(service, o)));
 // ---- db (postgres service controls) ----
@@ -180,6 +180,9 @@ db.command('limits').description("Show or set a postgres service's resource ceil
     .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)')
     .action(guard((o) => dbCmd.dbLimits(o)));
+db.command('stats').description("Postgres stats snapshot: connections vs the server's max (active count), cache hit rate, database size. insta-db-backed services answer without waking a suspended instance")
+    .option('--json').option('--branch <branch>', 'branch (default: current)').option('--group <g>', 'postgres service name (default: the sole/default one)')
+    .action(guard((o) => dbCmd.dbStats(o)));
 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)));

package/package.json

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