insta 0.0.31 → 0.0.33

package/dist/commands/db.js

@@ -4,8 +4,9 @@ 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
-// postgres only; Neon-backed services manage their own autosuspend and the platform returns an
-// error for them.
+// postgres only. Legacy Neon path: Neon is no longer used by any environment (postgres is 100%
+// insta-db) and this code is retained, not live — Neon-backed services managed their own
+// autosuspend and the platform returned an error for them.
 export async function dbAlwaysOn(mode, opts) {
     if (mode !== 'on' && mode !== 'off')
         throw new Error('mode must be on|off');
@@ -53,7 +54,8 @@ export async function fetchDbInstance(api, projectId, suffix) {
     }
     catch (e) {
         // The platform answers a provider-shaped 502 for services with no manageable instance
-        // (Neon-backed): a soft case, not a failure. Everything else stays an error — an expired
+        // (the legacy Neon path — Neon is no longer used by any environment; this branch is retained,
+        // not live): a soft case, not a failure. Everything else stays an error — an expired
         // token must not render as "no ceiling set" — but wrapped so the user sees what failed.
         if (e instanceof ApiError && e.status === 502)
             return { kind: 'no-instance' };
@@ -78,7 +80,7 @@ export async function dbLimits(opts) {
     if (!opts.cpu && !opts.memory) {
         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 resources)`);
+            info(`postgres ${opts.group ?? 'default'}: no manageable instance (this service manages its own resources)`);
             return;
         }
         if (opts.json)
@@ -161,9 +163,11 @@ export function dbStatsLines(group, body) {
 }
 // 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.
+// provider's control plane (shown as "(suspended)" with structural zeros), never dialed. That is
+// every environment today — the Neon-backed contrast below is historical: Neon is no longer used
+// anywhere, and the code that handled it is retained, not live. Neon-backed: the platform read
+// over a direct SQL connection, so a one-shot call could 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();
@@ -207,7 +211,7 @@ export async function dbVolume(opts) {
     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)`);
+            info(`postgres ${opts.group ?? 'default'}: no manageable instance (this service manages its own storage)`);
             return;
         }
         if (opts.json)

package/dist/commands/metrics.js

@@ -97,7 +97,9 @@ function printDimensions(dims) {
 }
 // insta usage — usage across the 5 billing dimensions (cpu/memory/volume/egress/storage) for the
 // current billing cycle. Shows the whole ORG by default (with a per-project breakdown); pass --proj
-// [id] for a single project (the linked one, or a given id). Billed dimensions, not raw fly/neon meters.
+// [id] for a single project (the linked one, or a given id). Billed dimensions, not raw provider
+// meters. (Historical: those were fly/neon meters — Neon is no longer used by any environment,
+// though the adapter code is retained, not live.)
 export async function usage(opts) {
     const api = await ApiClient.load();
     const p = await requireProject();

package/dist/commands/services.js

@@ -23,6 +23,16 @@ export function parseCount(raw) {
         throw new Error(`count must be a positive integer, got: ${raw}`);
     return n;
 }
+// Parse a TCP port. Junk fails here rather than reaching the API as NaN (the parseCpu lesson).
+// Decimal digits only, as parseVolumeGib: `Number()` alone would quietly read 0x1f90 as 8080 and
+// 1e3 as 1000, and a port written in hex is a typo worth reporting, not one worth honouring.
+export function parsePort(raw) {
+    const m = /^\s*(\d+)\s*$/.exec(raw);
+    const n = m ? Number(m[1]) : NaN;
+    if (!Number.isInteger(n) || n < 1 || n > 65535)
+        throw new Error(`port must be an integer between 1 and 65535, 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
@@ -43,20 +53,24 @@ export function resolveServiceId(services, type, name) {
         throw new Error(`service not found: ${type} ${name}`);
     return svc.id;
 }
-// Resolve a compute service id: by name, or the sole compute service when name is omitted.
-export function resolveComputeServiceId(services, name) {
-    const compute = services.filter((s) => s.type === 'compute');
+// Resolve one service of a type: by name, or the sole one of that type when name is omitted.
+export function resolveSoleService(services, type, name) {
+    const of = services.filter((s) => s.type === type);
     if (name) {
-        const svc = compute.find((s) => s.name === name);
+        const svc = of.find((s) => s.name === name);
         if (!svc)
-            throw new Error(`compute service not found: ${name}`);
-        return svc.id;
+            throw new Error(`${type} service not found: ${name}`);
+        return svc;
     }
-    if (compute.length === 0)
-        throw new Error('no compute service in this project (add one with `insta services add compute <name>`)');
-    if (compute.length > 1)
-        throw new Error(`multiple compute services — specify one: ${compute.map((s) => s.name).join(', ')}`);
-    return compute[0].id;
+    if (of.length === 0)
+        throw new Error(`no ${type} service in this project (add one with \`insta services add ${type} <name>\`)`);
+    if (of.length > 1)
+        throw new Error(`multiple ${type} services — specify one: ${of.map((s) => s.name).join(', ')}`);
+    return of[0];
+}
+// Resolve a compute service id: by name, or the sole compute service when name is omitted.
+export function resolveComputeServiceId(services, name) {
+    return resolveSoleService(services, 'compute', name).id;
 }
 // Map service-add options to the platform POST body. Pure, so it's unit-tested without a network
 // mock (mirrors deployRequestBody in deploy.ts). Validation (which options are valid for which
@@ -64,7 +78,7 @@ export function resolveComputeServiceId(services, name) {
 export function servicesAddRequestBody(type, name, branch, opts) {
     return {
         type, name, ...(branch ? { branch } : {}), public: !!opts.public,
-        ...(opts.image ? { image: opts.image } : {}), ...(opts.port ? { port: Number(opts.port) } : {}),
+        ...(opts.image ? { image: opts.image } : {}), ...(opts.port ? { port: parsePort(opts.port) } : {}),
         ...(opts.region ? { region: opts.region } : {}),
         ...(opts.alwaysOn ? { alwaysOn: true } : {}),
         ...(opts.volume !== undefined ? { volumeGib: parseVolumeGib(opts.volume) } : {}),
@@ -78,8 +92,11 @@ export async function servicesAdd(type, name, opts = {}) {
         throw new Error('--region is not valid for storage services');
     if (opts.image && type !== 'compute')
         throw new Error('--image is only valid for compute services');
-    if (opts.port && type !== 'compute')
-        throw new Error('--port is only valid for compute services');
+    if (opts.port) {
+        if (type !== 'compute')
+            throw new Error('--port is only valid for compute services');
+        parsePort(opts.port); // junk fails here, before any config/network access
+    }
     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) {
@@ -93,6 +110,8 @@ export async function servicesAdd(type, name, opts = {}) {
     const res = await api.rawRequest('POST', `/projects/${p.projectId}/services`, servicesAddRequestBody(type, name, branch, opts));
     if (handleApproval(res))
         return;
+    if (opts.json)
+        return printJson(res.body.service);
     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}` : ''}` : '';

package/dist/commands/storage.js

@@ -0,0 +1,173 @@
+// `insta storage` — browse, download, and delete the objects in a storage service's bucket.
+import { chmod, rename, rm, stat } from 'node:fs/promises';
+import { createWriteStream, rmSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { ApiClient, requireProject } from '../api.js';
+import { info, printJson, handleApproval } from '../util.js';
+import { q, resolveSoleService } from './services.js';
+import { fmtBytes } from './db.js'; // the repo's tested bytes formatter — don't grow a third copy
+function qs(params) {
+    const u = new URLSearchParams();
+    for (const [k, v] of Object.entries(params))
+        if (v !== undefined && v !== '')
+            u.set(k, String(v));
+    const s = u.toString();
+    return s ? `?${s}` : '';
+}
+// Page size the listing route accepts. Junk must fail here, not travel as `limit=NaN`.
+export function parseObjectLimit(raw) {
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n < 1 || n > 1000)
+        throw new Error(`--limit must be an integer 1..1000, got: ${raw}`);
+    return n;
+}
+// pure: platform path for the objects collection — GET lists it, DELETE removes one `key`.
+export function objectsPath(projectId, serviceId, params) {
+    const { limit, ...rest } = params;
+    return `/projects/${projectId}/services/${serviceId}/objects${qs({ ...rest, limit: limit === undefined ? undefined : String(limit) })}`;
+}
+// pure: the presign route — a static subpath, so keys containing `/` stay in the query.
+export function objectDownloadPath(projectId, serviceId, params) {
+    return `/projects/${projectId}/services/${serviceId}/objects/download${qs(params)}`;
+}
+// pure: one `storage list` row, size-first so the columns line up over variable-length keys.
+export function objectListLine(o) {
+    const size = typeof o.size === 'number' ? fmtBytes(o.size) : '—';
+    return `${size.padStart(10)}  ${(o.lastModified ?? '—').padEnd(24)}  ${o.key}`;
+}
+// Resolve the branch's storage service (named, or the sole one) — its bucket is what we browse.
+async function storageTarget(api, projectId, branch, name) {
+    const { services } = await api.request('GET', `/projects/${projectId}/services${q(branch)}`);
+    return resolveSoleService(services, 'storage', name);
+}
+// S3 filters by prefix only — there is no substring search, so `--prefix` is the query surface.
+export async function storageList(opts) {
+    const limit = opts.limit === undefined ? undefined : parseObjectLimit(opts.limit);
+    const api = await ApiClient.load();
+    const p = await requireProject();
+    const branch = opts.branch ?? p.branch;
+    const svc = await storageTarget(api, p.projectId, branch, opts.service);
+    const res = await api.rawRequest('GET', objectsPath(p.projectId, svc.id, { branch, prefix: opts.prefix, cursor: opts.cursor, limit }));
+    if (handleApproval(res))
+        return;
+    if (opts.json)
+        return printJson(res.body);
+    const objects = res.body?.objects ?? [];
+    if (!objects.length) {
+        return info(opts.prefix ? `(no objects under prefix ${opts.prefix} in storage/${svc.name})` : `(storage/${svc.name} is empty)`);
+    }
+    for (const o of objects)
+        info(objectListLine(o));
+    const next = res.body?.nextCursor;
+    if (next)
+        info(`  (more — next page: ${nextPageCommand({ ...opts, limit }, next)})`);
+}
+// Safe unquoted in every shell we care about — no spaces, quotes, or expansion characters.
+const SHELL_SAFE = /^[\w./:@=+-]+$/;
+// The continuation must repeat the filters, or following it lists a different set. Quoting rules
+// differ between sh and PowerShell, so rather than guess the shell, a value that would need quotes
+// gets a sentence instead of syntax that is broken somewhere.
+export function nextPageCommand(opts, cursor) {
+    const values = [opts.service, opts.branch, opts.prefix, cursor].filter((v) => !!v);
+    if (!values.every((v) => SHELL_SAFE.test(v))) {
+        return `re-run this command with --cursor set to ${cursor}`;
+    }
+    const flags = [
+        opts.service ? `--service ${opts.service}` : '',
+        opts.branch ? `--branch ${opts.branch}` : '',
+        opts.prefix ? `--prefix ${opts.prefix}` : '',
+        opts.limit === undefined ? '' : `--limit ${opts.limit}`,
+        `--cursor ${cursor}`,
+    ].filter(Boolean);
+    return `insta storage list ${flags.join(' ')}`;
+}
+// pure: where the bytes land. Only the last segment is used, so no key can escape cwd.
+export function outputPath(key, output) {
+    if (output)
+        return output;
+    // Split on `\` too: a key may contain one, and on Windows that is also a separator.
+    const base = key.split(/[\\/]/).pop() ?? '';
+    if (!base)
+        throw new Error(`cannot infer a filename from key "${key}" — pass -o <file>`);
+    return base;
+}
+// Stream from the provider (never through the platform, which only signs) straight to disk, so a
+// multi-gigabyte object never has to fit in memory. Returns the byte count written.
+export async function streamPresignedTo(url, out, fetchImpl = fetch) {
+    const res = await fetchImpl(url);
+    if (!res.ok || !res.body)
+        throw new Error(`download failed: HTTP ${res.status} (a presigned URL lives ~60s — re-run to mint a fresh one)`);
+    let written = 0;
+    const counting = new TransformStream({
+        transform(chunk, controller) { written += chunk.byteLength; controller.enqueue(chunk); },
+    });
+    // Write beside the target, then rename: opening `out` directly would truncate an existing file
+    // that a failed download then deletes. Same directory keeps the rename atomic.
+    const part = `${out}.insta-part-${randomBytes(4).toString('hex')}`;
+    // A signal kills the process without unwinding, so the part file needs a synchronous sweep.
+    // Exit 128+signo, so a supervisor still reads interrupted (130) apart from terminated (143).
+    const sweep = (signo) => () => { rmSync(part, { force: true }); process.exit(128 + signo); };
+    const onInt = sweep(2);
+    const onTerm = sweep(15);
+    process.once('SIGINT', onInt);
+    process.once('SIGTERM', onTerm);
+    try {
+        await pipeline(Readable.fromWeb(res.body.pipeThrough(counting)), createWriteStream(part));
+        // Replacing a 0600 file must not widen it to the umask default the part was created with.
+        const mode = await stat(out).then((s) => s.mode, () => undefined);
+        if (mode !== undefined)
+            await chmod(part, mode);
+        await rename(part, out);
+    }
+    catch (e) {
+        await rm(part, { force: true });
+        throw e;
+    }
+    finally {
+        process.off('SIGINT', onInt);
+        process.off('SIGTERM', onTerm);
+    }
+    return written;
+}
+// Core, dependency-injected for tests (mirrors runWithSecrets): stream → disk, return byte count.
+export async function saveObject(url, out, deps = {}) {
+    return (deps.streamTo ?? streamPresignedTo)(url, out);
+}
+export async function storageGet(key, opts, deps = {}) {
+    if (!key)
+        throw new Error('key is required');
+    const api = await ApiClient.load();
+    const p = await requireProject();
+    const branch = opts.branch ?? p.branch;
+    const svc = await storageTarget(api, p.projectId, branch, opts.service);
+    const res = await api.rawRequest('GET', objectDownloadPath(p.projectId, svc.id, { branch, key }));
+    if (handleApproval(res))
+        return;
+    // --json hands over the presigned URL instead of downloading, as `insta secrets --json` does.
+    // Before outputPath, so a key with no filename still works when nothing is written to disk.
+    if (opts.json)
+        return printJson(res.body);
+    const out = outputPath(key, opts.output);
+    if (!res.body?.url)
+        throw new Error('the platform returned no download URL');
+    const bytes = await saveObject(res.body.url, out, deps);
+    info(`wrote ${fmtBytes(bytes)} to ${out} (${key} from storage/${svc.name}, branch ${branch})`);
+}
+// No prompt, matching every other destructive command here — the governance gate is the guard.
+export async function storageDelete(key, opts) {
+    if (!key)
+        throw new Error('key is required');
+    const api = await ApiClient.load();
+    const p = await requireProject();
+    const branch = opts.branch ?? p.branch;
+    const svc = await storageTarget(api, p.projectId, branch, opts.service);
+    const res = await api.rawRequest('DELETE', objectsPath(p.projectId, svc.id, { branch, key }));
+    if (handleApproval(res))
+        return;
+    if (opts.json)
+        return printJson(res.body);
+    info(`deleted ${key} from storage/${svc.name} (branch ${branch})`);
+}
+//# sourceMappingURL=storage.js.map

package/dist/index.js

@@ -13,11 +13,13 @@ import * as org from './commands/org.js';
 import * as project from './commands/project.js';
 import * as branch from './commands/branch.js';
 import * as services from './commands/services.js';
+import { resolveServiceArgs, serviceArgsDeps } from './resolve-service.js';
 import * as regions from './commands/regions.js';
 import * as secretsCmd from './commands/secrets.js';
 import { deploy } from './commands/deploy.js';
 import * as computeCmd from './commands/compute.js';
 import * as dbCmd from './commands/db.js';
+import * as storageCmd from './commands/storage.js';
 import { manifest } from './commands/manifest.js';
 import * as govern from './commands/govern.js';
 import * as observe from './commands/observe.js';
@@ -108,7 +110,10 @@ br.command('merge <source>').description('Merge a branch service set into anothe
     .option('--into <branch>', 'target branch (default: current)').action(guard((source, o) => branch.branchMerge(source, o)));
 // ---- services (opt-in postgres/storage/compute) ----
 const svc = program.command('services').alias('svc').description('Manage project services (postgres|storage|compute)');
-svc.command('add <type> <name>').description('Provision a service on demand (assigns a default domain for postgres/compute)')
+// [type] [name] are optional so the command can answer "what can I add?" — a terminal is walked
+// through the dashboard's Add Service kinds, anything else gets that list back as an error
+// (resolve-service.ts). Picking Docker Image also fills in --image/--port from the answers.
+svc.command('add [type] [name]').description('Provision a service on demand (assigns a default domain for postgres/compute); with no type/name, a terminal picks from the service kinds')
     .option('--branch <branch>', 'target branch (default: current)')
     .option('--region <region>', 'region for postgres/compute, e.g. us-east (see `insta regions`)')
     .option('--public', 'storage only: serve the bucket with anonymous public-read (default private)')
@@ -116,7 +121,11 @@ svc.command('add <type> <name>').description('Provision a service on demand (ass
     .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 (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)));
+    .option('--json')
+    .action(guard(async (type, name, o) => {
+    const a = await resolveServiceArgs(type, name, serviceArgsDeps(o.json), o);
+    return services.servicesAdd(a.type, a.name, { ...o, image: a.image ?? o.image, port: a.port ?? o.port });
+}));
 svc.command('list').option('--json').option('--branch <branch>', 'branch (default: current)')
     .action(guard((o) => services.servicesList(o)));
 svc.command('remove <type> <name>').description('Remove a service and destroy its resources')
@@ -129,7 +138,7 @@ svc.command('set-access <type> <name> <access>').description('Set a storage serv
     .option('--json').action(guard((type, name, access, o) => services.servicesSetAccess(type, name, access, o)));
 svc.command('scale <type> <name> <number> [region]').description('Set a compute service machine count (paid plans only)')
     .option('--json').option('--branch <branch>', 'branch (default: current)').action(guard((type, name, number, region, o) => services.servicesScale(type, name, number, region, o)));
-svc.command('upgrade <type> <name> <spec>').description('Change a compute/postgres service spec (paid plans only)')
+svc.command('upgrade <type> <name> <spec>').description('Change a compute service spec (paid plans only). Postgres upgrades are rejected by the platform — use `insta db limits` instead')
     .option('--json').option('--branch <branch>', 'branch (default: current)').action(guard((type, name, spec, o) => services.servicesUpgrade(type, name, spec, o)));
 svc.command('secrets <type> <name>').description("List a service's secret names")
     .option('--branch <b>').option('--json').action(guard((type, name, o) => services.servicesSecrets(type, name, o)));
@@ -191,6 +200,25 @@ db.command('volume').description("Show or grow a postgres service's provisioned
     .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)));
+// ---- storage (bucket objects) ----
+const storage = program.command('storage').description("Browse, download, and delete a storage service's bucket objects");
+storage.command('list').description("List the bucket's objects. S3 filters by prefix only — there is no substring search")
+    .option('--prefix <p>', 'only keys starting with this prefix (applied server-side)')
+    .option('--cursor <c>', 'continue from the nextCursor a previous page printed')
+    .option('--limit <n>', 'page size, 1..1000 (default 100)')
+    .option('--service <name>', 'storage service (default: the sole one on the branch)')
+    .option('--branch <b>', 'branch (default: current)').option('--json')
+    .action(guard((o) => storageCmd.storageList(o)));
+storage.command('get <key>').description('Download one object to disk through a short-lived presigned URL (bytes come straight from the provider)')
+    .option('-o, --output <file>', "output file (default: the key's last segment)")
+    .option('--service <name>', 'storage service (default: the sole one on the branch)')
+    .option('--branch <b>', 'branch (default: current)')
+    .option('--json', 'print the presigned URL + expiry instead of downloading')
+    .action(guard((key, o) => storageCmd.storageGet(key, o)));
+storage.command('delete <key>').description('DELETES one object from the bucket immediately — no undo, and an already-gone key still reports success (gated: storage.delete)')
+    .option('--service <name>', 'storage service (default: the sole one on the branch)')
+    .option('--branch <b>', 'branch (default: current)').option('--json')
+    .action(guard((key, o) => storageCmd.storageDelete(key, o)));
 // ---- manifest ----
 program.command('manifest').description('Print an agent-legible view of the project environments').option('--json').action(guard((o) => manifest(o)));
 // ---- regions ----
@@ -230,7 +258,7 @@ ob.command('sync').description('Upload findings into the project timeline').acti
 // ---- policy ----
 const pol = program.command('policy').description('Governance policy');
 pol.command('get').option('--json').action(guard((o) => govern.policyGet(o)));
-pol.command('set <action> <decision>').description('action: secrets.read|secrets.write|deploy|project.delete|branch.delete|service.add|service.remove|service.scale|service.upgrade|service.setAccess; decision: allow|deny|approve').action(guard((a, d) => govern.policySet(a, d)));
+pol.command('set <action> <decision>').description('action: secrets.read|secrets.write|deploy|project.delete|branch.delete|service.add|service.remove|service.scale|service.upgrade|service.setAccess|storage.read|storage.write|storage.delete; decision: allow|deny|approve').action(guard((a, d) => govern.policySet(a, d)));
 // ---- self-update ----
 program.command('upgrade').description('Update the insta CLI to the latest release (binary or npm install)')
     .action(guard(() => selfUpdate.upgrade()));

package/dist/resolve-service.js

@@ -0,0 +1,161 @@
+// `insta services add` with no type (or no name): the kinds are otherwise only discoverable by
+// guessing wrong and reading `type must be postgres|storage|compute`, so missing arguments answer
+// "what can I add?" instead. The list mirrors the dashboard's Add Service menu (frontend
+// `add-service-button.tsx`) — Docker Image sits BESIDE Empty Service, not under it, because
+// picking an image is a different intent rather than a compute flag. An agent gets the same list
+// as an error, because nothing was created and a silent exit 0 would read as success.
+import * as clack from '@clack/prompts';
+import { SERVICE_TYPES, assertServiceName, parsePort } from './commands/services.js';
+// Same order, labels and default names as the dashboard's Add Service menu. Github Repo is left
+// out: the platform has no repo path yet, so a CLI entry could only say "coming soon".
+export const SERVICE_KINDS = [
+    { id: 'image', label: 'Docker Image', type: 'compute', hint: 'run an existing container image', needsImage: true },
+    { id: 'postgres', label: 'Postgres', type: 'postgres', hint: 'relational DB, usable as soon as it is added', defaultName: 'main-db' },
+    { id: 'storage', label: 'Storage', type: 'storage', hint: 'S3-compatible bucket, private by default', defaultName: 'assets' },
+    { id: 'compute', label: 'Empty Service', type: 'compute', hint: 'an app to deploy code to (empty until `insta deploy`)', defaultName: 'compute' },
+];
+// The platform's own default; the dialog prefills the same number.
+export const DEFAULT_IMAGE_PORT = '8080';
+/** Registry refs aren't URLs — quietly strip a pasted scheme prefix (mirrors the dashboard). */
+export function normalizeImageRef(raw) {
+    return raw.trim().replace(/^https?:\/\//, '');
+}
+/**
+ * Name from an image ref: last path segment, sans tag/digest, kebab-safe (the dashboard's rule).
+ * Also capped at the 39 chars `assertServiceName` allows — a suggestion the user cannot accept
+ * unchanged is worse than none.
+ */
+export function suggestServiceName(ref) {
+    const last = ref.split('@')[0].split('/').pop() ?? '';
+    return last
+        .split(':')[0]
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 39)
+        .replace(/-+$/g, '');
+}
+/** The non-interactive command for a kind — what an agent should run instead of being asked. */
+export function kindCommand(k) {
+    if (k.needsImage)
+        return `insta services add compute <name> --image <ref> --port <n>`;
+    return `insta services add ${k.type} ${k.defaultName}`;
+}
+/** The kind list, one line each — what a terminal picks from and an agent reads. */
+export function serviceKindLines() {
+    return SERVICE_KINDS.map((k) => `  ${k.label.padEnd(14)} ${kindCommand(k)}`);
+}
+/** What to say when there is no terminal to ask: the missing half, and how to supply it. */
+export function missingArgsMessage(type) {
+    // A bare type names the plain kind, never Docker Image — that one is reached with --image.
+    const known = SERVICE_KINDS.find((k) => k.type === type && !k.needsImage);
+    if (known)
+        return `name the service:  ${kindCommand(known)}`;
+    return ['what to add:', ...serviceKindLines()].join('\n');
+}
+/**
+ * Fill in whatever `insta services add` was not given. An unknown type passes straight through so
+ * `assertType` — not this — reports it, keeping one wording for a bad type everywhere. Flags that
+ * were already supplied are never asked for again.
+ */
+export async function resolveServiceArgs(type, name, deps, given = {}) {
+    if (type && name)
+        return { type, name };
+    if (type && !SERVICE_TYPES.includes(type))
+        return { type, name: name ?? '' };
+    if (!deps.tty)
+        throw new Error(missingArgsMessage(type));
+    // A bad --port is a typo in the command, not an answer: fail before asking anything.
+    if (given.port !== undefined)
+        parsePort(given.port);
+    const kind = type
+        ? SERVICE_KINDS.find((k) => k.type === type && !k.needsImage)
+        : await deps.selectKind(SERVICE_KINDS);
+    if (!kind)
+        return { type: type, name: name ?? '' };
+    if (!kind.needsImage) {
+        return { type: kind.type, name: name ?? (await deps.askName(kind, kind.defaultName ?? '')) };
+    }
+    // The prompt validates a typed ref; a --image that normalizes away would slip past it and
+    // provision a plain empty compute instead (servicesAddRequestBody drops a falsy image).
+    const image = normalizeImageRef(given.image ?? (await deps.askImage()));
+    if (!image)
+        throw new Error('an image reference is required');
+    return {
+        type: kind.type,
+        name: name ?? (await deps.askName(kind, suggestServiceName(image))),
+        image,
+        port: given.port ?? (await deps.askPort(DEFAULT_IMAGE_PORT)),
+    };
+}
+/** Real prompts (clack, as the InsForge CLI's `create`); cancelling exits without provisioning. */
+export async function promptServiceKind(kinds) {
+    const picked = await clack.select({
+        message: 'What do you want to add?',
+        options: kinds.map((k) => ({ value: k.id, label: k.label, hint: k.hint })),
+    });
+    if (clack.isCancel(picked))
+        process.exit(0);
+    // Resolve against the list that was displayed — a subset must not fall through to the registry.
+    return kinds.find((k) => k.id === picked);
+}
+export async function promptImageRef() {
+    const answer = await clack.text({
+        message: 'Image reference:',
+        placeholder: 'nginx:latest',
+        validate: (v) => (normalizeImageRef(v) ? undefined : 'an image reference is required'),
+    });
+    if (clack.isCancel(answer))
+        process.exit(0);
+    return answer;
+}
+export async function promptServiceName(kind, suggested) {
+    const answer = await clack.text({
+        message: `Name this ${kind.type} service:`,
+        initialValue: suggested,
+        // The same rule the command enforces, reported before Enter rather than after a round trip.
+        validate: (v) => {
+            try {
+                assertServiceName(v.trim());
+                return undefined;
+            }
+            catch (e) {
+                return e.message;
+            }
+        },
+    });
+    if (clack.isCancel(answer))
+        process.exit(0);
+    return answer.trim();
+}
+export async function promptPort(fallback) {
+    const answer = await clack.text({
+        message: 'Port the image listens on:',
+        initialValue: fallback,
+        // The rule the command enforces, so the prompt and a --port can never disagree.
+        validate: (v) => {
+            try {
+                parsePort(v.trim());
+                return undefined;
+            }
+            catch (e) {
+                return e.message;
+            }
+        },
+    });
+    if (clack.isCancel(answer))
+        process.exit(0);
+    return answer.trim();
+}
+/** Prompts on a real terminal only — an agent's stdin is not one, and must never block. */
+export function serviceArgsDeps(json) {
+    return {
+        selectKind: promptServiceKind,
+        askImage: promptImageRef,
+        askName: promptServiceName,
+        askPort: promptPort,
+        // --json asked for parseable output, so a caller that happens to own a TTY still gets the error.
+        tty: !json && !!process.stdin.isTTY && !!process.stdout.isTTY,
+    };
+}
+//# sourceMappingURL=resolve-service.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "insta",
-  "version": "0.0.31",
+  "version": "0.0.33",
   "type": "module",
   "description": "InstaCloud CLI — a thin client of the platform control-plane API.",
   "keywords": [
@@ -42,6 +42,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
+    "@clack/prompts": "^0.9.1",
     "commander": "^12.1.0"
   },
   "devDependencies": {