insta 0.1.22 → 0.1.24

package/dist/commands/compute.js

@@ -1723,11 +1723,30 @@ export function acquireLockFile(path, now, staleMs) {
     // ask whether the holder still exists.
     const token = `${process.pid}:${randomUUID()}`;
     const release = () => {
+        // The claim a takeover of this token takes, so a release and a takeover never interleave.
+        const claim = takeoverClaim(path, token);
+        let claimed = false;
+        try {
+            linkSync(path, claim);
+            claimed = true;
+        }
+        catch (e) {
+            // Leave the lock unless the disk has no hardlinks, where no takeover can claim it either.
+            if (!LINK_UNSUPPORTED.has(String(e?.code)))
+                return;
+        }
         try {
             if (readFileSync(path, 'utf8') === token)
                 unlinkSync(path);
         }
         catch { /* already gone, or taken over by someone else */ }
+        finally {
+            if (claimed)
+                try {
+                    unlinkSync(claim);
+                }
+                catch { /* the inode keeps its other name */ }
+        }
     };
     const take = () => {
         try {
@@ -1859,21 +1878,22 @@ function processAlive(pid) {
  *  `path` keeps its inode throughout, so there is no moment at which the lock
  *  at `path` can have become somebody else's between the check and the act:
  *  the holder judged dead cannot release, every other breaker is behind the
- *  claim, and a release by anyone else checks for its own token first. Should
- *  the old holder's release ever run, it reads a foreign token and leaves the
- *  file alone.
+ *  claim, and a release by anyone else checks for its own token first.
+ *  The old holder's release takes this same claim, so it never lands inside a takeover.
+ *  A release that cannot take it leaves the lock, to be broken like an abandoned one.
  *
  *  Residual, and deliberately not "fixed": a breaker killed between the link
- *  and its write leaves the claim behind, and that one token can then no
- *  longer be broken (removing the claim by hand is the way out, and the busy
- *  message names the lock). Every scheme for reaping an abandoned claim needs
+ *  and its write, or a release killed before its unlink, leaves the claim
+ *  behind, and that one token can then no longer be broken or released
+ *  (removing the claim by hand is the way out, and the busy message names
+ *  the lock). Every scheme for reaping an abandoned claim needs
  *  to decide the claim is dead and then remove it -- the same check-then-act
  *  this function exists to eliminate, one level up. A claim left behind AFTER
  *  the write is inert: the lock now carries the breaker's token, and the next
  *  breaker keys its claim on that. A wedged lock is recoverable and says so;
  *  two writers in the same section silently lose the user's config. */
 function breakStaleLock(path, stale, mine) {
-    const claim = `${path}.stale.${createHash('sha256').update(stale).digest('hex').slice(0, 32)}`;
+    const claim = takeoverClaim(path, stale);
     try {
         linkSync(path, claim);
     }
@@ -1906,6 +1926,12 @@ function breakStaleLock(path, stale, mine) {
         catch { /* the inode keeps its other name */ }
     }
 }
+/** link() errors from a disk without hardlinks, where a release may skip its claim. */
+const LINK_UNSUPPORTED = new Set(['EPERM', 'ENOTSUP', 'EOPNOTSUPP', 'ENOSYS']);
+/** The hardlink that arbitrates breaking or releasing the lock `token` names. */
+function takeoverClaim(path, token) {
+    return `${path}.stale.${createHash('sha256').update(token).digest('hex').slice(0, 32)}`;
+}
 export async function computeSSH(serviceName, opts, deps = {}) {
     if (opts.ensureCert !== undefined)
         return ensureCertForAlias(opts.ensureCert);

package/dist/commands/cron.js

@@ -16,7 +16,7 @@
 //      forward because it can (see buildRequest).
 import { randomUUID } from 'node:crypto';
 import { ApiClient, ApiError, requireProject } from '../api.js';
-import { die, handleApproval, info, printJson, refuse } from '../util.js';
+import { die, handleApproval, info, isWebUrl, printJson, refuse } from '../util.js';
 import { q, resolveSoleService } from './services.js';
 // ---- pure, unit-tested helpers (throw plain Errors; the CLI guard turns them into clean output) ----
 // The API's own bounds (openapi/schemas/cron.ts), enforced here so junk fails before any network or
@@ -245,7 +245,7 @@ export function assertTargetFlags(o, partial = false) {
         throw new Error('--path applies to --service (an external target carries its path in the --url)');
     if (!partial && !o.url && !o.service)
         throw new Error('name a target: --url <https://…> or --service <name> [--path /api/cron]');
-    if (o.url !== undefined && !/^https?:\/\//i.test(o.url))
+    if (o.url !== undefined && !isWebUrl(o.url))
         throw new Error(`--url must be an absolute http(s) URL, got: ${o.url}`);
     if (o.path !== undefined && !o.path.startsWith('/'))
         throw new Error(`--path must start with /, got: ${o.path}`);

package/dist/commands/deploy.js

@@ -6,7 +6,7 @@ import { info, die, printJson, handleApproval, renderNextActions, CliExit } from
 import { flyctlBuildAndPush, ensureFlyctl, defaultBuildRunner, stderrBuildRunner } from '../flyctl-build.js';
 import { packDirectory, windowsModeCaveat } from '../pack.js';
 import { deployArchive, uploadArchive } from '../deploy-archive.js';
-import { parsePort } from './services.js';
+import { parseEndpoint, parsePort } from './services.js';
 // With --json, stdout must carry exactly one JSON document (the deploy result), so every progress
 // line moves to stderr.
 const note = (opts) => (opts.json ? (m) => void process.stderr.write(m + '\n') : info);
@@ -19,9 +19,17 @@ export function deployRequestBody(source, branch, opts) {
         group: opts.group,
         port: opts.port ? Number(opts.port) : undefined,
         websocket: opts.websocket ? true : undefined,
+        endpoint: opts.endpoint !== undefined ? parseEndpoint(opts.endpoint) : undefined,
         replaceSource: opts.replaceSource ? true : undefined,
     };
 }
+// Where the deploy answers: the HTTPS URL, or for an endpoint tcp service its tcp address (the
+// platform reports no URL for one). Pure, so it's unit-tested.
+export function deployedTarget(r, port) {
+    if (r.endpointHost)
+        return `tcp://${r.endpointHost}:${port ?? '?'}`;
+    return r.url || '(no URL: a worker)';
+}
 // Ask the platform which lane serves this target, so the CLI stops knowing which provider backs
 // its service. A 404 means the platform predates the contract — and because this is a GET, it
 // 404s the same way for a human and an agent, which a POST would not.
@@ -143,6 +151,19 @@ export async function deploy(dir, opts) {
         die('pick one: a source <dir> OR --image <url>, not both');
     if (!dir && !opts.image)
         die('usage: insta deploy <dir> | --image <url>  [--branch <b>] [--group <g>] [--port <n>]');
+    // Normalized here, once, so both lanes get the same validated value: the archive lane's body
+    // (deployArchive) otherwise silently drops anything that isn't exactly 'http'/'tcp' to
+    // undefined, which let a typo like --endpoint tpc build and deploy using the service's existing
+    // endpoint instead of failing locally. Checked before ApiClient.load()/requireProject(): those
+    // can resolve a project and persist an automatic link for an unlinked directory, so a typo must
+    // die before either runs, not after.
+    let endpoint;
+    try {
+        endpoint = opts.endpoint === undefined ? undefined : parseEndpoint(opts.endpoint);
+    }
+    catch (e) {
+        die(e.message);
+    }
     const api = await ApiClient.load();
     const p = await requireProject();
     const branch = opts.branch ?? p.branch;
@@ -162,7 +183,7 @@ export async function deploy(dir, opts) {
             log(`using port ${exposed} (Dockerfile EXPOSE) — override with --port`);
         }
     }
-    const effOpts = { ...opts, port: port?.toString() };
+    const effOpts = { ...opts, port: port?.toString(), endpoint };
     const source = dir ? await prepareSource(api, p.projectId, dir, branch, effOpts) : { image: opts.image };
     if (!source)
         return; // an approval is pending; the user approves and re-runs
@@ -171,8 +192,8 @@ export async function deploy(dir, opts) {
         // nextActions, which the operation read does not carry.
         const d = source.deployed;
         if (opts.json)
-            return printJson({ image: d.image, url: d.url, branch: d.branch, group: d.group, machineId: d.machineId });
-        info(`deployed ${d.image} -> ${d.url} (branch ${d.branch}, group ${d.group})`);
+            return printJson({ image: d.image, url: d.url, ...(d.endpointHost ? { endpointHost: d.endpointHost } : {}), branch: d.branch, group: d.group, machineId: d.machineId });
+        info(`deployed ${d.image} -> ${deployedTarget(d, effOpts.port)} (branch ${d.branch}, group ${d.group})`);
         return;
     }
     const res = await api.rawRequest('POST', `/projects/${p.projectId}/deploy`, deployRequestBody(source, branch, effOpts))
@@ -182,7 +203,7 @@ export async function deploy(dir, opts) {
     const what = source.image;
     if (opts.json)
         return printJson({ image: source.image, ...res.body });
-    info(`deployed ${what} -> ${res.body.url} (branch ${res.body.branch}, group ${res.body.group})`);
+    info(`deployed ${what} -> ${deployedTarget(res.body, effOpts.port)} (branch ${res.body.branch}, group ${res.body.group})`);
     renderNextActions(res.body.nextActions);
 }
 // The platform refuses an image deploy onto a repo-connected service and names the body field it

package/dist/commands/postgres.js

@@ -14,9 +14,9 @@ export function alwaysOnArgs(first, second) {
 export function alwaysOnLine(group, scaleToZero) {
     return `postgres ${group}: always-on ${scaleToZero === false ? 'on — instance stays warm' : scaleToZero === true ? 'off — scales to zero when idle' : 'unknown — the provider did not report it'}`;
 }
-// Show or set a postgres service's idle mode: scale-to-zero (the default: instance suspends when
-// idle, cold-starts on the next connection) or always-on (instance stays warm; idle RAM bills at
-// actual usage). Reads GET /database/instance, sets PATCH /database/settings {scaleToZero} —
+// Show or set a postgres service's idle mode: always-on (the default for databases since platform
+// #666: instance stays warm; idle RAM bills at actual usage) or scale-to-zero (instance suspends
+// when idle, cold-starts on the next connection). Reads GET /database/instance, sets PATCH /database/settings {scaleToZero} —
 // insta-db-backed postgres only.
 export async function dbAlwaysOn(first, second, opts) {
     const { mode, service } = alwaysOnArgs(first, second);
@@ -70,7 +70,7 @@ export function alwaysOnSetLine(service, branch, mode, scaleToZero) {
     const group = service ?? 'default';
     if (scaleToZero !== (mode === 'off'))
         return `postgres ${group}: always-on ${mode} requested — the database has not applied it yet; confirm with \`insta postgres always-on${service ? ` ${service}` : ''}${branch ? ` --branch ${branch}` : ''}\``;
-    return `postgres ${group}: always-on ${mode === 'on' ? 'ENABLED — instance stays warm (no cold starts; idle RAM bills at actual usage)' : 'disabled — scales to zero when idle (default; first connection after idle cold-starts)'}`;
+    return `postgres ${group}: always-on ${mode === 'on' ? 'ENABLED — instance stays warm (no cold starts; idle RAM bills at actual usage; the default for databases)' : 'disabled — scales to zero when idle (first connection after idle cold-starts)'}`;
 }
 // Validated pass-throughs for the provider's quantity strings. The insta-db resize API takes
 // k8s-style quantities (cpu: "2", "2500m"; memory: "4Gi", "2048Mi"), so unlike the compute path
@@ -160,9 +160,20 @@ export async function dbLimits(service, opts) {
         return;
     if (opts.json)
         return printJson(res.body);
-    const cpu = typeof res.body?.cpuMilli === 'number' ? `${res.body.cpuMilli / 1000} vCPU` : (opts.cpu ?? 'unchanged');
-    const mem = typeof res.body?.memoryMib === 'number' ? fmtMib(res.body.memoryMib) : (opts.memory ?? 'unchanged');
-    info(`postgres ${service ?? 'default'}: ceiling set to ${cpu} / ${mem}`);
+    info(limitsSetLine(service, opts.branch, { cpu: body.cpu, memory: body.memory }, res));
+}
+// insta-db queues the resize and answers 202 (the platform adds pending: true) with the row from
+// BEFORE the patch, so on pending the body's cpuMilli/memoryMib are the old ceiling: print what was
+// asked for and point at the read-back, the way alwaysOnSetLine does.
+export function limitsSetLine(service, branch, requested, res) {
+    const group = service ?? 'default';
+    if (res.status === 202 || res.body?.pending === true) {
+        const asked = [requested.cpu && `${requested.cpu} vCPU`, requested.memory].filter(Boolean).join(' / ');
+        return `postgres ${group}: ceiling ${asked} requested, not applied yet — confirm with \`insta postgres limits${service ? ` ${service}` : ''}${branch ? ` --branch ${branch}` : ''}\``;
+    }
+    const cpu = typeof res.body?.cpuMilli === 'number' ? `${res.body.cpuMilli / 1000} vCPU` : (requested.cpu ?? 'unchanged');
+    const mem = typeof res.body?.memoryMib === 'number' ? fmtMib(res.body.memoryMib) : (requested.memory ?? 'unchanged');
+    return `postgres ${group}: ceiling set to ${cpu} / ${mem}`;
 }
 // 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).
@@ -204,12 +215,8 @@ 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. 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.
+// hit rate, database size. Read-only. A suspended instance answers from the provider's control
+// plane (shown as "(suspended)" with structural zeros), never dialed.
 export async function dbStats(service, opts) {
     const api = await ApiClient.load();
     const p = await requireProject();

package/dist/commands/secrets.js

@@ -190,6 +190,23 @@ export function applyServiceLines(services) {
         return `  = ${s.serviceId}${s.reason ? ` (${s.reason})` : ''}`;
     });
 }
+// POST one entry to /apply and settle what `secrets set` and `secrets unset` share: the approval
+// gate, the exit code, and the --json document. Returns null when the caller has nothing left to
+// print — the platform gated the write, or --json already carried the outcome.
+async function applyEntry(d, name, branch, entry, opts) {
+    const res = await d.api.rawRequest('POST', `/projects/${d.projectId}/apply`, { branch: branch ?? d.linkedBranch, entries: [entry] });
+    if (handleApproval(res, opts.json))
+        return null;
+    const entries = res.body.entries ?? [];
+    const services = res.body.services ?? [];
+    const verdict = applyVerdict(entries, services);
+    process.exitCode = applyExitCode(verdict);
+    if (opts.json) {
+        printJson({ ok: verdict === 'ok', verdict, name, branch: branch ?? null, service: opts.service ?? null, entries, services });
+        return null;
+    }
+    return { verdict, services };
+}
 // Set a user secret. Project-wide by default; --branch scopes it to one branch. --service binds
 // it to a branch service instead, which implies the current branch (binding requires one). Value
 // comes from the argument, or stdin when omitted (keeps secret values out of shell history).
@@ -205,15 +222,10 @@ export async function secretsSet(name, value, opts, deps) {
     const branch = opts.service ? (opts.branch ?? d.linkedBranch) : opts.branch;
     // The batch always deploys on ONE branch, so the top level falls back to the linked one even when the entry itself is project-wide.
     const entry = { kind: 'set', name, value: v, ...(branch ? { branch } : {}), ...(opts.service ? { service: opts.service } : {}) };
-    const res = await d.api.rawRequest('POST', `/projects/${d.projectId}/apply`, { branch: branch ?? d.linkedBranch, entries: [entry] });
-    if (handleApproval(res, opts.json))
+    const outcome = await applyEntry(d, name, branch, entry, opts);
+    if (!outcome)
         return;
-    const entries = res.body.entries ?? [];
-    const services = res.body.services ?? [];
-    const verdict = applyVerdict(entries, services);
-    process.exitCode = applyExitCode(verdict);
-    if (opts.json)
-        return printJson({ ok: verdict === 'ok', verdict, name, branch: branch ?? null, service: opts.service ?? null, entries, services });
+    const { verdict, services } = outcome;
     info(`set ${name}${opts.service ? ` → ${opts.service}` : ''} (${branch ? `branch ${branch}` : 'project-wide'})`);
     for (const line of applyServiceLines(services))
         info(line);
@@ -232,17 +244,12 @@ export async function secretsUnset(name, opts, deps) {
     // pair without one) — so --service defaults to the linked branch, exactly as `secrets set` does.
     const branch = opts.service ? (opts.branch ?? d.linkedBranch) : opts.branch;
     const entry = { kind: 'delete', name, ...(branch ? { branch } : {}), ...(opts.service ? { service: opts.service } : {}) };
-    const res = await d.api.rawRequest('POST', `/projects/${d.projectId}/apply`, { branch: branch ?? d.linkedBranch, entries: [entry] });
-    if (handleApproval(res, opts.json))
-        return;
-    const entries = res.body.entries ?? [];
-    const services = res.body.services ?? [];
-    const verdict = applyVerdict(entries, services);
-    process.exitCode = applyExitCode(verdict);
     // The EFFECTIVE branch, not the flag: with --service and no --branch the scope that was deleted
     // is the linked branch's, and the output has to say which scope it actually touched.
-    if (opts.json)
-        return printJson({ ok: verdict === 'ok', verdict, name, branch: branch ?? null, service: opts.service ?? null, entries, services });
+    const outcome = await applyEntry(d, name, branch, entry, opts);
+    if (!outcome)
+        return;
+    const { verdict, services } = outcome;
     const scope = opts.service ? `${opts.service}, branch ${branch}` : branch ? `branch ${branch}` : 'project-wide';
     info(`unset ${name} (${scope})`);
     for (const line of applyServiceLines(services))

package/dist/commands/services.js

@@ -105,6 +105,20 @@ export function resolveComputeServiceId(services, name) {
 function defaultDatabasePort(type) {
     return type === 'mysql' ? 3306 : type === 'mongodb' ? 27017 : 6379;
 }
+// How a compute service is reached: http (the default HTTPS domain) or tcp (raw TCP on its port at
+// its own IPv6 address). Checked locally so a typo fails before any network call; which ports tcp
+// accepts is the platform's answer, not repeated here.
+export function parseEndpoint(raw) {
+    const v = raw.trim().toLowerCase();
+    if (v !== 'http' && v !== 'tcp')
+        throw new Error(`--endpoint must be http or tcp, got: ${raw}`);
+    return v;
+}
+// Where a tcp service is dialed. The host is set once a deploy has confirmed it; before that the
+// row only knows its port.
+export function tcpAddress(s) {
+    return s.endpoint_host ? `tcp://${s.endpoint_host}:${s.port}` : `tcp/${s.port ?? '?'} (address after the first deploy)`;
+}
 // 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
 // type) stays in servicesAdd, ahead of any network/config access.
@@ -112,6 +126,7 @@ export function servicesAddRequestBody(type, name, branch, opts) {
     return {
         type, name, ...(branch ? { branch } : {}), public: !!opts.public,
         ...(opts.image ? { image: opts.image } : {}), ...(opts.port !== undefined ? { port: parsePort(opts.port, { allowZero: type === 'compute' }) } : {}),
+        ...(opts.endpoint !== undefined ? { endpoint: parseEndpoint(opts.endpoint) } : {}),
         ...(opts.region ? { region: opts.region } : {}),
         // Sent whenever the flag was given, false included: the birth default is platform config
         // (INSTA_COMPUTE_ALWAYS_ON_DEFAULT, scale-to-zero unless set), so an explicit --no-always-on
@@ -135,6 +150,11 @@ export async function servicesAdd(type, name, opts = {}) {
             throw new Error('--port is only valid for compute services');
         parsePort(opts.port, { allowZero: true });
     }
+    if (opts.endpoint !== undefined) {
+        if (type !== 'compute')
+            throw new Error('--endpoint is only valid for compute services');
+        parseEndpoint(opts.endpoint);
+    }
     // Presence, not truthiness: `--no-always-on` is an explicit false and is just as compute-only.
     if (opts.alwaysOn !== undefined && type !== 'compute')
         throw new Error(alwaysOnTypeError(type));
@@ -179,7 +199,8 @@ export function serviceAddedLine(type, name, branch, svc) {
     const vol = svc.volume_gib ? `  vol ${svc.volume_gib}Gi at ${svc.volume_mount_path ?? "/data"}` : '';
     // The major belongs next to the connect hint: it decides which psql/pg_dump to reach for.
     const pg = svc.type === 'postgres' ? pgBadge(svc.pg_version) : '';
-    return `added ${type} service ${name} on ${branch ?? 'default'} (${svc.id})${access}${svc.region ? `  ${svc.region}` : ''}${img}${vol}${pg}${svc.domain ? ` — ${svc.domain}` : ''}`;
+    const where = svc.endpoint === 'tcp' ? ` — ${tcpAddress(svc)}` : svc.domain ? ` — ${svc.domain}` : '';
+    return `added ${type} service ${name} on ${branch ?? 'default'} (${svc.id})${access}${svc.region ? `  ${svc.region}` : ''}${img}${vol}${pg}${where}`;
 }
 // `  pg <major>` for a postgres row, or '' when the platform sent nothing usable. The field arrives
 // as untyped API JSON: only a positive integer renders, so a malformed or nonsense value (true,
@@ -197,7 +218,9 @@ export function serviceListLine(s) {
                 // Postgres major, so the reader picks matching pg_dump/psql BEFORE connecting (a newer client
                 // dumps statements an older server cannot restore). Older platforms send no pg_version.
                 : s.type === 'postgres' ? pgBadge(s.pg_version) : '';
-    return `${s.type}/${s.name}  [${s.status}]${extra}${s.domain ? `  ${s.domain}` : ''}  ${s.id}`;
+    // A tcp compute service has no HTTP domain; its address is the tcp one.
+    const where = s.type === 'compute' && s.endpoint === 'tcp' ? `  ${tcpAddress(s)}` : s.domain ? `  ${s.domain}` : '';
+    return `${s.type}/${s.name}  [${s.status}]${extra}${where}  ${s.id}`;
 }
 export async function servicesList(opts) {
     const api = await ApiClient.load();

package/dist/commands/template-author.js

@@ -65,6 +65,8 @@ function serviceText(s) {
     const bits = [
         kind,
         s.port != null ? `port ${s.port}` : undefined,
+        // Only a web service has one, and a platform that does not serve the field says nothing.
+        s.type === 'web' && s.healthcheck !== undefined ? (s.healthcheck ? `health check ${s.healthcheck}` : 'no health check') : undefined,
         s.image ? `image ${s.image}` : undefined,
         // A null mount path on a volume is the default /data.
         s.volume ? `volume at ${s.mountPath ?? '/data'}` : undefined,

package/dist/commands/template.js

@@ -32,6 +32,7 @@ export function templateListLines(templates) {
 export function normalizeInfoServices(raw) {
     const one = (name, s) => ({
         name, type: s?.type, port: s?.port,
+        healthcheck: typeof s?.healthcheck === 'string' ? s.healthcheck : undefined,
         volumeGib: s?.volumeGib ?? s?.volume?.size,
         volume: s?.volume === true || s?.volumeGib != null || s?.volume?.size != null,
         mountPath: typeof s?.mountPath === 'string' ? s.mountPath : undefined,
@@ -91,7 +92,9 @@ export function templateInfoLines(t, bold = (s) => s) {
             // A size only when the registry still carries one: a manifest names no size any more, so
             // "persistent /data" is all there is to say until the service exists.
             const disk = s.volumeGib ? `${s.volumeGib}Gi volume` : s.volume ? `persistent ${s.mountPath ?? '/data'}` : undefined;
-            const bits = [infoKind(s), s.port ? `port ${s.port}` : undefined, disk].filter(Boolean);
+            // Only a web service has a path to probe, and a manifest that names none has no health check.
+            const health = s.type === 'web' ? (s.healthcheck ? `health check ${s.healthcheck}` : 'no health check') : undefined;
+            const bits = [infoKind(s), s.port ? `port ${s.port}` : undefined, health, disk].filter(Boolean);
             return `${s.name}${bits.length ? ` (${bits.join(', ')})` : ''}`;
         });
         lines.push(`services (${services.length}): ${summary.join(', ')}`);
@@ -126,11 +129,17 @@ export function parseSetFlags(pairs) {
     for (const pair of pairs) {
         const m = /^([A-Z][A-Z0-9_]{0,63})=([\s\S]*)$/.exec(pair);
         if (!m)
-            throw new Error(`--set expects NAME=value (NAME matching ^[A-Z][A-Z0-9_]{0,63}$), got: ${pair}`);
+            throw new Error(`--set expects NAME=value (NAME matching ^[A-Z][A-Z0-9_]{0,63}$), got: ${redactSetPair(pair)}`);
         values[m[1]] = m[2];
     }
     return values;
 }
+// --set carries secrets and this error reaches stderr and CI logs, so only the name is ever shown.
+function redactSetPair(pair) {
+    const eq = pair.indexOf('=');
+    // Nothing of a pair with no `=`: it was never split, so the whole token may be the value itself.
+    return eq >= 0 ? `${pair.slice(0, eq)}=<value hidden>` : '<value hidden: no NAME= in front of it>';
+}
 export function missingVariablesMessage(missing) {
     return [
         'missing required template variables:',
@@ -233,8 +242,13 @@ export function deploymentUrls(dep) {
     return lines;
 }
 // One line per service with its terminal state — the anatomy of a partial/failed run.
+// `skipped` is the platform saying the user deleted that service and the run stepped over it. Its
+// `state` stays `pending`, which under the marks below would read as "not reached yet" — a run that
+// is still going — so it gets its own mark and names the reason instead.
 export function serviceStateLines(dep) {
     return (dep?.services ?? []).map((s) => {
+        if (s?.skipped)
+            return `  - ${s?.name ?? 'service'} [skipped: it no longer exists, so the run stepped over it]`;
         const mark = s?.state === 'healthy' ? '✓' : s?.state === 'failed' ? '✗' : '•';
         return `  ${mark} ${s?.name ?? 'service'}${s?.url ? ` — ${s.url}` : ''}${s?.state && s.state !== 'healthy' ? ` [${s.state}]` : ''}`;
     });
@@ -244,9 +258,13 @@ export function serviceStateLines(dep) {
 // deploy, or clean up), not just that something went wrong.
 export function partialMessage(dep) {
     const services = dep?.services ?? [];
-    const healthy = services.filter((s) => s?.state === 'healthy').length;
+    // A skipped service was never part of this run — the user had deleted it — so counting it in the
+    // denominator would report a run that did everything it could as having left something behind.
+    // It is still LISTED below, because "where did it go" is the question the count then raises.
+    const ran = services.filter((s) => !s?.skipped);
+    const healthy = ran.filter((s) => s?.state === 'healthy').length;
     return [
-        `template deployment finished partial: ${healthy}/${services.length} services healthy`,
+        `template deployment finished partial: ${healthy}/${ran.length} services healthy`,
         ...serviceStateLines(dep),
         ...(dep?.error ? [`  ${dep.error}`] : []),
         ...(dep?.logsTail ? ['--- log tail ---', String(dep.logsTail).trimEnd()] : []),
@@ -418,4 +436,209 @@ export async function templateDeploy(target, opts = {}, deps = {}) {
     info('next: `insta postgres 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);
 }
+/** The review, as lines. Current is the LIVE value: what the upgrade will overwrite. */
+export function upgradePlanLines(plan) {
+    if (plan.refusals.length) {
+        return ['This upgrade cannot run:', ...plan.refusals.map((r) => `  ${r}`)];
+    }
+    const lines = [`${plan.from_version} → ${plan.to_version}`];
+    for (const s of plan.services) {
+        const who = s.service_name ?? s.key;
+        if (s.gone) {
+            lines.push(`  ${who}  no longer exists, skipped`);
+            continue;
+        }
+        // Created, not reconciled: there is no live value to compare, so its rows follow below as they come.
+        if (s.added)
+            lines.push(`  ${who}  added by ${plan.to_version}, created by this upgrade`);
+        for (const f of s.fields) {
+            const drift = f.drifted ? '  (you changed this, the upgrade will overwrite it)' : '';
+            lines.push(`  ${who}  ${f.label}  ${f.live ?? '(none)'} → ${f.next}${drift}`);
+        }
+        for (const name of s.missing_variables) {
+            lines.push(`  ${who}  ${name} is required by ${plan.to_version} and has no value, pass --set ${name}=...`);
+        }
+    }
+    for (const key of plan.removed)
+        lines.push(`  ${key}  dropped by ${plan.to_version}, left running`);
+    return lines;
+}
+// The 409 codes a user will actually hit, in a sentence that says what to do next.
+const UPGRADE_409 = {
+    template_version_changed: 'The template was republished since the plan was shown. Nothing was changed. Run the command again to review the new version.',
+};
+const ROLLBACK_409 = {
+    template_version_not_recorded: 'The earlier version of this template is no longer recorded, so it cannot be restored. Nothing was changed.',
+};
+/**
+ * Codes whose platform sentence names the deployment or the version to act on. Replacing it with
+ * wording of our own would drop the one name that makes it actionable, so the platform's sentence
+ * is printed as given and only the next step is appended.
+ */
+const KEEP_PLATFORM_SENTENCE = {
+    // "this deployment was already replaced by <code>@<version> — act on that deployment instead".
+    // Reachable here only for a service a NEWER version dropped: it keeps pointing at the deployment
+    // the instance has moved off, which is the one this CLI resolves from the service name.
+    template_superseded: 'Nothing was changed. This command addresses a service, so name one that the newer deployment carries.',
+    // "<code>@<version> was republished with different content after this instance ran it …".
+    template_version_content_changed: 'Nothing was changed.',
+    // Two causes now, and the second one names the version: "this instance was already rolled back
+    // to <version> … upgrade it to move forward", beside the original "was not upgraded from
+    // anything". Our own wording could only say one of them, and said the wrong one for a rollback.
+    template_no_step_back: 'Nothing was changed.',
+};
+/** The sentence to raise for a coded 409, or undefined when this is not one we explain. */
+function coded409(e, advice) {
+    if (!(e instanceof ApiError) || e.status !== 409)
+        return undefined;
+    const code = typeof e.body?.code === 'string' ? e.body.code : '';
+    if (advice[code])
+        return new Error(advice[code]);
+    const next = KEEP_PLATFORM_SENTENCE[code];
+    return next ? new Error(`${e.message}. ${next}`) : undefined;
+}
+async function postWithAdvice(api, path, body, advice) {
+    try {
+        return await api.rawRequest('POST', path, body);
+    }
+    catch (e) {
+        throw coded409(e, advice) ?? e;
+    }
+}
+/**
+ * A service name is what a person has; a deployment uuid is not. The services list already carries
+ * the attribution, so the lookup lives here rather than in the user's head.
+ */
+async function deploymentOfService(api, projectId, branch, service, verb) {
+    const body = await api.request('GET', `/projects/${projectId}/services?branch=${encodeURIComponent(branch)}`);
+    const row = (body.services ?? []).find((s) => s.name === service);
+    if (!row)
+        throw new Error(`no service named ${service} on branch ${branch}`);
+    // Named by the caller: the same sentence under `rollback` would send the user to upgrade instead.
+    if (!row.template_deployment_id)
+        throw new Error(`${service} was not deployed from a template, so there is nothing to ${verb}`);
+    return { deploymentId: row.template_deployment_id };
+}
+export async function templateUpgrade(service, opts = {}, deps = {}) {
+    const given = parseSetFlags(opts.set ?? []); // a typo'd --set fails before any network access
+    const api = deps.api ?? (await ApiClient.load());
+    const p = deps.project ?? (await requireProject());
+    const branchName = opts.branch ?? p.branch;
+    const ask = deps.ask ?? promptVariable;
+    const target = await deploymentOfService(api, p.projectId, branchName, service, 'upgrade');
+    // The poll and preview routes are keyed by deployment id, not project: name the project so agent
+    // mode signs with the project-bound session, exactly as templateDeploy does.
+    // The preview is a GET and raises coded 409s of its own (template_superseded among them), so it
+    // gets the same reading as the POST rather than the raw "<sentence> (HTTP 409)" the guard prints.
+    let plan;
+    try {
+        ;
+        ({ plan } = await api.request('GET', `/template-deployments/${target.deploymentId}/upgrade`, undefined, { projectId: p.projectId }));
+    }
+    catch (e) {
+        throw coded409(e, UPGRADE_409) ?? e;
+    }
+    // --json alone is "tell me" (the plan, no upgrade); --json --yes is "do it and tell me".
+    const quiet = !!opts.json;
+    if (opts.json && (!opts.yes || plan.refusals.length)) {
+        printJson(plan);
+        if (plan.refusals.length)
+            process.exitCode = 1;
+        return;
+    }
+    if (!quiet)
+        for (const line of upgradePlanLines(plan))
+            info(line);
+    // A refusal is not a prompt to confirm past: there is nothing to confirm.
+    if (plan.refusals.length) {
+        process.exitCode = 1;
+        return;
+    }
+    // Only what the new version ADDS is ever asked for: the platform recovers every value the
+    // instance already holds, so re-prompting would invite the user to overwrite a live credential.
+    const missing = plan.services.flatMap((s) => s.missing_variables.map((name) => ({ name, required: true })));
+    const tty = !opts.yes && !!process.stdin.isTTY && !!process.stdout.isTTY;
+    const variables = missing.length ? await resolveVariables(missing, given, { tty, ask }) : given;
+    if (!opts.yes && tty) {
+        const go = await clack.confirm({ message: `Upgrade ${service} from ${plan.from_version} to ${plan.to_version}?` });
+        if (clack.isCancel(go))
+            throw new CliCancel();
+        if (!go)
+            return;
+    }
+    // The version and digest the user just read. A republish in between answers 409 rather than
+    // running something they never saw.
+    const res = await postWithAdvice(api, `/projects/${p.projectId}/template-deployments/${target.deploymentId}/upgrade`, {
+        variables, expectedVersion: plan.to_version, expectedDigest: plan.to_digest,
+    }, UPGRADE_409);
+    if (handleApproval(res, opts.json))
+        return;
+    const deploymentId = res.body.deploymentId ?? (res.body.deployment ?? res.body).id;
+    if (!quiet)
+        info(`upgrading ${service} to ${plan.to_version} (${deploymentId})`);
+    const dep = await watchDeployment((id) => api.request('GET', `/template-deployments/${id}`, undefined, { projectId: p.projectId }), deploymentId, quiet ? () => { } : info, deps.wait);
+    if (quiet)
+        return printJson(dep);
+    info(`${service} is on ${plan.to_version}`);
+    info(`next: \`insta template rollback ${service}\` returns it to ${plan.from_version}`);
+    renderNextActions(dep.nextActions);
+}
+export async function templateRollback(service, opts = {}, deps = {}) {
+    const given = parseSetFlags(opts.set ?? []); // a typo'd --set fails before any network access
+    const quiet = !!opts.json;
+    const out = quiet ? () => { } : info;
+    // Destructive, and its two warnings are load-bearing: a machine-readable run must say --yes out
+    // loud rather than roll back unseen through a pipe.
+    // Same rule as `template publish`: ask on a terminal, anywhere else (a pipe, --json) say --yes.
+    const tty = !opts.json && !opts.yes && !!process.stdin.isTTY && !!process.stdout.isTTY;
+    if (!opts.yes && !tty)
+        throw new Error('rollback needs --yes without a terminal to confirm on: it does not restore data the app migrated, so nothing was rolled back');
+    const api = deps.api ?? (await ApiClient.load());
+    const p = deps.project ?? (await requireProject());
+    const branchName = opts.branch ?? p.branch;
+    const ask = deps.ask ?? promptVariable;
+    const target = await deploymentOfService(api, p.projectId, branchName, service, 'roll back');
+    // Said BEFORE the confirmation, not after the fact: rollback prints no plan, so these lines are
+    // the whole disclosure, and what they warn of is not recoverable by running the command again.
+    out('Going back restores every setting that version declares: the image, the start command, the port, always-on, public access, the volume mount path and the recorded variables.');
+    out('A setting the older version does not declare keeps its current value.');
+    out('Public access on a storage bucket reaches that bucket on every branch that has a copy, not only this one.');
+    out('It does not restore data the app migrated under the newer version, and a volume only grows.');
+    if (tty) {
+        const go = await clack.confirm({ message: `Return ${service} to the version it was upgraded from?` });
+        if (clack.isCancel(go))
+            throw new CliCancel();
+        if (!go)
+            return;
+    }
+    // The platform recovers every value the services still hold, so a rollback normally sends
+    // nothing. What it cannot recover is a variable the NEWER version stopped declaring: the upgrade
+    // deleted that value and the older manifest still requires it. Rollback prints no plan, so the
+    // platform's 400 naming them is the only place those names exist — prompt from it and retry
+    // once, exactly as templateDeploy does with its own missing_variables.
+    const rollbackPath = `/projects/${p.projectId}/template-deployments/${target.deploymentId}/rollback`;
+    const variables = { ...given };
+    let res;
+    try {
+        res = await postWithAdvice(api, rollbackPath, { variables }, ROLLBACK_409);
+    }
+    catch (e) {
+        const missing = e instanceof ApiError ? missingVariablesFrom(e.body) : null;
+        if (!missing?.length)
+            throw e;
+        // No TTY (or --yes) fails here with the `--set NAME=value` list, the same rule the deploy and
+        // upgrade paths follow — nothing has been rolled back at this point.
+        Object.assign(variables, await resolveVariables(missing, {}, { tty, ask }));
+        res = await postWithAdvice(api, rollbackPath, { variables }, ROLLBACK_409);
+    }
+    if (handleApproval(res, opts.json))
+        return;
+    const deploymentId = res.body.deploymentId ?? (res.body.deployment ?? res.body).id;
+    out(`rolling ${service} back (${deploymentId})`);
+    const dep = await watchDeployment((id) => api.request('GET', `/template-deployments/${id}`, undefined, { projectId: p.projectId }), deploymentId, out, deps.wait);
+    if (quiet)
+        return printJson(dep);
+    info(`${service} is back on ${(dep.deployment ?? dep).template_version ?? 'its previous version'}`);
+    renderNextActions(dep.nextActions);
+}
 //# sourceMappingURL=template.js.map

package/dist/commands/upgrade.js

@@ -346,8 +346,6 @@ export async function autoupdate(mode) {
     const enabled = cfg.autoUpdate !== false && !process.env.INSTA_NO_AUTOUPDATE;
     info(`autoupdate: ${enabled ? 'on' : 'off'} (default on while the CLI is pre-1.0 — \`insta config autoupdate off\` to disable)`);
 }
-// Called once at CLI start-up. Never blocks: reads the cache synchronously, prints at most one
-// stderr line, and (when due) spawns detached children for the registry check / quiet upgrade.
 /** Commands that must never nudge about an update or spawn a background one.
  *
  *  `upgrade`/`autoupdate` are the update machinery itself. Every `__` command
@@ -368,6 +366,8 @@ export function skipsUpdateCheck(cmd, sub) {
         return true;
     return cmd === 'upgrade' || cmd === 'autoupdate' || !!cmd?.startsWith('__');
 }
+// Called once at CLI start-up. Never blocks: reads the cache synchronously, prints at most one
+// stderr line, and (when due) spawns detached children for the registry check / quiet upgrade.
 export function maybeUpdate(current, argv) {
     if (skipsUpdateCheck(argv[2], argv[3]))
         return;

package/dist/deploy-archive.js

@@ -72,6 +72,7 @@ export async function deployArchive(api, projectId, ref, branch, opts, now = Dat
         archive: ref,
         port: opts.port ? Number(opts.port) : undefined,
         websocket: typeof opts.websocket === 'boolean' ? opts.websocket : undefined,
+        endpoint: opts.endpoint === 'http' || opts.endpoint === 'tcp' ? opts.endpoint : undefined,
         replaceSource: opts.replaceSource === true ? true : undefined,
     });
     // An approval is a 202 too, told apart by its status word; anything else here is our operation.
@@ -121,7 +122,9 @@ export async function deployArchive(api, projectId, ref, branch, opts, now = Dat
             if (state === 'live') {
                 const image = res.body?.imageRef;
                 const url = res.body?.url;
-                if (typeof image !== 'string' || !image || typeof url !== 'string' || (!url && opts.port !== '0')) {
+                // An endpoint tcp service has no URL: its answer is the tcp host instead. A worker has neither.
+                const endpointHost = typeof res.body?.endpointHost === 'string' && res.body.endpointHost ? res.body.endpointHost : undefined;
+                if (typeof image !== 'string' || !image || typeof url !== 'string' || (!url && opts.port !== '0' && !endpointHost)) {
                     throw new Error('the deploy finished but the platform returned no image or URL for it — check `insta status`');
                 }
                 const optionalString = (field, v) => {
@@ -132,7 +135,7 @@ export async function deployArchive(api, projectId, ref, branch, opts, now = Dat
                     return v;
                 };
                 return {
-                    image, url,
+                    image, url, ...(endpointHost ? { endpointHost } : {}),
                     branch: optionalString('branch', res.body.branch) ?? branch,
                     group: optionalString('group', res.body.group) ?? opts.group ?? '',
                     machineId: optionalString('machineId', res.body.machineId),

package/dist/index.js

@@ -155,6 +155,7 @@ svc.command('add [type] [name]').description('Provision a service on demand (com
     .option('--public', 'storage only: serve the bucket with anonymous public-read (default private)')
     .option('--image <url>', 'compute only: run this container image at creation')
     .option('--port <n>', 'compute only: port the image listens on (default 8080; 0 for a worker without a routed port)')
+    .option('--endpoint <http|tcp>', 'compute only: how the service is reached — http (default: HTTPS at its domain) or tcp (raw TCP on --port at its own public IPv6 address; IPv6 clients only, no platform TLS, no custom domain). tcp needs --port and refuses commonly scanned, web (80/443) and platform-reserved ports')
     .option('--always-on', 'compute only: create as always-on — never scales to zero (all plans; billing is actual usage either way). A worker (--port 0) is always-on regardless')
     .option('--no-always-on', 'compute only: create as scale-to-zero — idle machines suspend and wake on the next request (the default for new compute services; refused with --port 0, a worker cannot scale to zero)')
     .option('--mount-path <path>', 'compute only: container mount path for a new volume (requires --volume; default /data)')
@@ -449,7 +450,7 @@ pg.command('volume [service]').description("Show or grow a postgres service's pr
     .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) => pgCmd.dbVolume(service, o)));
-pg.command('always-on [mode] [service]').description('Show or set a postgres service always-on (mode: on|off; no mode = print the current setting). on = instance stays warm, no cold starts; off = default scale-to-zero (idle instance suspends; first connection cold-starts). insta-db-backed services only')
+pg.command('always-on [mode] [service]').description('Show or set a postgres service always-on (mode: on|off; no mode = print the current setting). on = instance stays warm, no cold starts (the default for databases); off = scale-to-zero (idle instance suspends; first connection cold-starts). insta-db-backed services only')
     .option('--json').option('--branch <branch>', 'branch (default: current)')
     .action(guard((mode, service, o) => pgCmd.dbAlwaysOn(mode, service, o)));
 pg.command('private-access [mode] [service]').description('Show or set private network access (mode: on|off; no mode = print public and private access). on = mint DATABASE_PRIVATE_URL beside DATABASE_URL (unchanged) — it resolves only inside InstaCloud compute, not from a laptop or CI; bind it into a compute with `insta secrets bind … --source-name DATABASE_PRIVATE_URL`. off = retract it (refused while public access is closed). insta-db-backed only (gated: service.setAccess)')
@@ -525,6 +526,7 @@ buildCmd.command('logs <build-id>').description('Read source-build output for a
 program.command('deploy [dir]').description('Deploy a source directory (built remotely; on insta-compute a Dockerfile is optional and nixpacks detects the runtime) or a prebuilt --image to a branch compute group')
     .option('--image <url>', 'prebuilt container image to deploy (instead of a source dir)').option('--branch <b>').option('--group <g>').option('--port <p>', 'port the app listens on (0 for a worker without a routed port)')
     .option('--websocket', 'run a WebSocket app (larger guest + connection-based concurrency)')
+    .option('--endpoint <http|tcp>', 'switch how the service is reached from this deploy on: tcp (raw TCP on --port at its own public IPv6 address; IPv6 clients only) or http (back to its HTTPS domain). Omitted: keep the current endpoint')
     .option('--replace-source', 'the service deploys from a connected GitHub repo: switch it to this image and remove the repo connection (admin); without it such a deploy is refused')
     .option('--json', 'print the deploy result as JSON (build progress goes to stderr)')
     .action(guard((dir, o) => deploy(dir, o)));
@@ -547,6 +549,18 @@ tpl.command('deploy <code-or-dir-or-url>').description('Deploy a template onto a
     .option('-y, --yes', 'non-interactive: missing required variables fail with a --set list instead of prompting')
     .option('--json')
     .action(guard((target, o) => template.templateDeploy(target, o)));
+tpl.command('upgrade <service>').description('Move a service deployed from a template to the version the registry serves now. Shows what will change and asks before it runs. A service that already exists is reused, and every setting the new version declares is applied: image, start command, port, always-on, public access, the volume and its mount path, and the variables, each of them listed in the plan first. A service the new version ADDS is created by the upgrade: the plan names it as added and then lists every setting it will be created with, each written `(none) -> <new value>` because there is no live service to compare against, followed by the variables it requires. A service the new version no longer declares is left running, named in the plan as dropped. A volume the new version adds is attached at your plan\'s size and mounted where the manifest says; an existing one is never resized. For a storage bucket, a public-access change reaches that bucket on every branch that has a copy. Refused with a 409 when the template was republished since the plan, or when this instance has already moved off this deployment')
+    .option('--branch <b>', 'branch the service is on (default: current)')
+    .option('--set <NAME=value>', 'set a template variable the new version requires (repeatable)', (v, prev) => [...prev, v], [])
+    .option('-y, --yes', 'do not ask for confirmation')
+    .option('--json', 'machine-readable output: alone it prints the plan and does not upgrade; with --yes it upgrades and prints the finished deployment')
+    .action(guard((service, o) => template.templateUpgrade(service, o)));
+tpl.command('rollback <service>').description('Return a service to the template version it was upgraded from, one step. Restores every setting that version declares: image, start command, port, always-on, public access, the volume mount path and the recorded variables, while a setting it does not declare keeps its current value. For a storage bucket, a public-access change reaches that bucket on every branch that has a copy. It does not restore data the app migrated, and a volume only grows. Refused with a 409 when the service was never upgraded, when that version\'s manifest is no longer recorded, or when that version was republished with different content after this instance ran it')
+    .option('--branch <b>', 'branch the service is on (default: current)')
+    .option('--set <NAME=value>', "set a template variable the older version requires that the instance no longer holds — an upgrade to a version that stopped declaring it deleted the value (repeatable)", (v, prev) => [...prev, v], [])
+    .option('-y, --yes', 'do not ask for confirmation')
+    .option('--json', 'print the finished deployment as JSON and suppress progress lines; requires --yes')
+    .action(guard((service, o) => template.templateRollback(service, o)));
 // Authoring: the org's community templates, the same drafts the console editor changes.
 tpl.command('create').description("Create a community template draft from the linked project (or --project), or an empty one with --blank. Prints its code, status and the console editor link")
     .option('--project <id>', 'project to generate the draft from (default: the linked project)')
@@ -556,7 +570,8 @@ tpl.command('create').description("Create a community template draft from the li
     .option('--json')
     .action(guard((o) => templateAuthor.templateCreate(o)));
 tpl.command('drafts').description("List your org's community templates, drafts and published, with their status")
-    .option('--org <id>', "target org (default: linked project's org)").option('--json')
+    .option('--org <id>', "target org (default: linked project's org)")
+    .option('--json', 'print one summary per template as the platform serves it, with no services, variables or publish requirements. insta template draft <code> --json prints one draft in full')
     .action(guard((o) => templateAuthor.templateDrafts(o)));
 tpl.command('draft <code>').description('Show one community template draft: its services, every variable with its choice, and the publish requirements')
     .option('--org <id>', "target org (default: linked project's org)").option('--json')

package/dist/template-manifest.js

@@ -14,6 +14,8 @@ export const MANIFEST_FILE = 'insta.template.yaml';
 const CODE_RE = /^[a-z0-9][a-z0-9-]{0,38}$/;
 export const ENV_NAME_RE = /^[A-Z][A-Z0-9_]{0,63}$/;
 const GENERATOR_RE = /^secret:([1-9]\d{0,2})$/;
+// The platform's HEALTHCHECK_RE (src/provisioning/templateManifest.ts), verbatim.
+const HEALTHCHECK_RE = /^\/(?!\/)[A-Za-z0-9\-._~!$&'()*+,;=:@%/?]*$/;
 // The compute vocabulary every CLI has known. Any other type is the platform's to accept or refuse.
 const COMPUTE_TYPES = ['web', 'worker'];
 // Datastores that never gain a url or host. Storage is left off because a public bucket may get an address.
@@ -116,10 +118,16 @@ export function validateManifest(m) {
             if (svc.alwaysOn === false)
                 problems.push(`${where}.alwaysOn: a worker cannot scale to zero — nothing is routed to it, so nothing would wake it; remove alwaysOn or set it true`);
         }
-        if (svc.type === 'web' && !svc.healthcheck)
-            problems.push(`${where}: web services must declare a healthcheck path`);
-        if (svc.healthcheck && !String(svc.healthcheck).startsWith('/'))
-            problems.push(`${where}: healthcheck must be an absolute path (start with /)`);
+        // Optional on a web service, and a given path must pass the platform's grammar.
+        if (svc.type !== 'worker' && svc.healthcheck !== undefined) {
+            const healthcheck = scalarString(svc.healthcheck);
+            if (healthcheck === null)
+                problems.push(`${where}.healthcheck must be a string`);
+            else if (!healthcheck.startsWith('/'))
+                problems.push(`${where}: healthcheck must be an absolute path (start with /)`);
+            else if (!HEALTHCHECK_RE.test(healthcheck))
+                problems.push(`${where}: healthcheck must be a single-slash absolute path on the service itself (no '//host', scheme, backslash or control characters), got: ${healthcheck}`);
+        }
         // Sizing is the platform's, capped for the org's plan. Same answers the
         // publish endpoint gives, said here so an author does not upload to find out. Read as unknown:
         // the type above admits only what is SUPPORTED, and the document is a cast over YAML.parse, so
@@ -131,7 +139,6 @@ export function validateManifest(m) {
         if (authored.spec !== undefined) {
             problems.push(`${where}: compute size is the platform's to choose — remove spec`);
         }
-        // Validate runtime fields: command and mountPath
         if (svc.command !== undefined && (typeof svc.command !== 'string' || !svc.command.trim())) {
             problems.push(`${where}.command must be a non-empty string`);
         }

package/package.json

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