insta 0.0.39 → 0.0.41

package/dist/api.js

@@ -5,9 +5,13 @@ import { autoResolveProject, promptChoice } from './resolve-project.js';
 import { die } from './util.js';
 export class ApiError extends Error {
     status;
-    constructor(status, msg) {
+    body;
+    // body carries the parsed error payload for callers that branch on machine-readable errors
+    // (e.g. template deploy's missing_variables); the message stays the human line.
+    constructor(status, msg, body) {
         super(msg);
         this.status = status;
+        this.body = body;
         this.name = 'ApiError';
     }
 }
@@ -47,14 +51,14 @@ export class ApiClient {
     async request(method, path, body, opts = {}) {
         const res = await this.raw(method, path, body, opts.auth ?? true);
         if (res.status >= 400)
-            throw new ApiError(res.status, res.body?.error ?? `HTTP ${res.status}`);
+            throw new ApiError(res.status, res.body?.error ?? `HTTP ${res.status}`, res.body);
         return res.body;
     }
     // Like request but returns {status, body} so callers can branch on 202 (approval_required).
     async rawRequest(method, path, body, opts = {}) {
         const res = await this.raw(method, path, body, opts.auth ?? true);
         if (res.status >= 400)
-            throw new ApiError(res.status, res.body?.error ?? `HTTP ${res.status}`);
+            throw new ApiError(res.status, res.body?.error ?? `HTTP ${res.status}`, res.body);
         return res;
     }
     async raw(method, path, body, auth) {

package/dist/commands/setup.js

@@ -285,39 +285,35 @@ const defaultMinter = async () => {
         return null;
     }
 };
-// Register the insta-cloud remote MCP server with Claude Code (user scope, so it follows the
-// machine like the skill install above). Default is OAuth: register with NO credential — the
-// platform's Better Auth MCP authorization server is discovered via RFC 9728 and Claude runs
-// the browser flow on first `/mcp` use, so no static token ever lands on disk. `--mcp-token`
-// is the headless fallback (CI, no browser): mint a durable token into the header instead.
-// Idempotent — an existing registration is left alone. Best-effort: the skill install is the
-// primary outcome; agents without an MCP registry are covered by the skill alone.
-export async function registerMcp(run = defaultRunner, mint = defaultMinter, useToken = false) {
+export async function registerMcp(run = defaultRunner, mint = defaultMinter, useToken = false, announce = true) {
     const { name, url } = await resolveMcpTarget();
     if (!(await run('claude', ['--version'])).ok)
-        return; // no Claude Code on this machine
+        return 'no-claude'; // no Claude Code on this machine
     if ((await run('claude', ['mcp', 'get', name])).ok) {
-        info(`✓ MCP — ${name} already registered with Claude Code`);
-        return;
+        if (announce)
+            info(`✓ MCP — ${name} already registered with Claude Code`);
+        return 'existing';
     }
     const args = ['mcp', 'add', '--transport', 'http', '--scope', 'user', name, url];
     if (useToken) {
         const token = await mint();
         if (!token) {
             info('  MCP not registered (--mcp-token needs a login) — run `insta login`, then `insta setup agent --mcp-token` again');
-            return;
+            return 'no-token';
         }
         args.push('--header', `Authorization: Bearer ${token}`);
     }
     const res = await run('claude', args);
-    if (res.ok) {
+    if (!res.ok) {
+        info(`  MCP registration failed — add manually:\n    claude mcp add --transport http ${name} ${url}`);
+        return 'failed';
+    }
+    if (announce) {
         info(`✓ MCP — ${name} registered with Claude Code (\`claude mcp list\` to verify)`);
         if (!useToken)
             info('  first use: run `/mcp` in Claude Code and authorize in the browser (headless machines: `insta setup agent --mcp-token`)');
     }
-    else {
-        info(`  MCP registration failed — add manually:\n    claude mcp add --transport http ${name} ${url}`);
-    }
+    return 'new';
 }
 /** The environment `setup agent` should target, and whether the machine must be switched to it
  *  first. Pure — decides only; the caller performs the switch.
@@ -414,31 +410,23 @@ export async function setupAgent(opts, run = defaultRunner, mint, installConfigs
         return;
     }
     info(summarizeInstall(res.output ?? ''));
-    info('  every coding agent on this machine now knows InstaCloud (review skills before use — they run with full permissions).');
-    await registerMcp(run, mint, !!opts.mcpToken);
+    // Register everything first, summarize ONCE below: Claude Code via `claude mcp add`, every other
+    // agent via a config-file entry — different mechanisms, one outcome, one line.
+    let claude = await registerMcp(run, mint, !!opts.mcpToken, false);
     const others = await installConfigs();
-    if (others.length)
-        info(`✓ MCP — also configured for ${others.join(', ')} (restart those tools to pick it up)`);
-    // The checkmarks end the install, but the user's next move shouldn't be guesswork. Local state
-    // only (no network): a config with a session means logged in — good enough for a hint.
-    // Deliberately prod-hosted prompt.md even on a staging setup: it is generic onboarding (the
-    // login/create commands in it are env-aware at runtime), and staging serves no equivalent.
-    const stored = await readStored();
-    const loggedIn = !!(stored.accessToken || stored.user);
-    const nextCreate = 'next: `insta project create <name>` in your app repo — or tell your agent: "Fetch https://instacloud.com/prompt.md and follow it"';
-    if (loggedIn)
-        return info(nextCreate);
-    // Default into login on an interactive terminal — see shouldOfferLogin. Best-effort: a declined
+    // Default into login on an interactive terminal (see shouldOfferLogin) BEFORE the MCP summary:
+    // a --mcp-token registration needs the session to mint, so a post-login retry must land in the
+    // same combined line instead of announcing Claude Code separately. Best-effort: a declined
     // prompt or a failed browser flow leaves a completed setup plus the manual hint, never an error.
+    const stored = await readStored();
+    let loggedIn = !!(stored.accessToken || stored.user);
     if (shouldOfferLogin(!!opts.yes, loggedIn, loginFlow.stdinTty, loginFlow.stdoutTty)) {
         if (await loginFlow.ask('log in now with GitHub? (Y/n) ')) {
             try {
                 await loginFlow.login();
-                // --mcp-token needs a session to mint: the registration above ran logged-out and skipped
-                // itself with the login hint — now that the session exists, do the token registration.
+                loggedIn = true;
                 if (opts.mcpToken)
-                    await registerMcp(run, mint, true);
-                return info(nextCreate);
+                    claude = await registerMcp(run, mint, true, false);
             }
             catch (e) {
                 info(`  login did not complete (${e instanceof Error ? e.message : String(e)}) — no problem, setup itself is done.`);
@@ -446,6 +434,18 @@ export async function setupAgent(opts, run = defaultRunner, mint, installConfigs
             }
         }
     }
-    info('next: `insta login --oauth github` (headless: `insta login --device`), then `insta project create <name>` — or tell your agent: "Fetch https://instacloud.com/prompt.md and follow it"');
+    // The one MCP line. The restart note exists because config-file agents only read their config
+    // at startup; Claude Code picks it up live.
+    const mcpTargets = [...(claude === 'new' || claude === 'existing' ? ['Claude Code'] : []), ...others];
+    if (mcpTargets.length) {
+        info(`✓ MCP — ${mcpTargets.join(', ')}${others.length ? ' (already-running tools load it on restart)' : ''}`);
+    }
+    if (claude === 'new' && !opts.mcpToken) {
+        info('  Claude Code first use: run `/mcp` and authorize in the browser (headless machines: `insta setup agent --mcp-token`)');
+    }
+    // The checkmarks end the install, but the user's next move shouldn't be guesswork.
+    info(loggedIn
+        ? 'next: run `insta project create` inside your app directory (existing project: `insta project link <id>`)'
+        : 'next: `insta login --oauth github` (headless: `insta login --device`), then `insta project create` inside your app directory');
 }
 //# sourceMappingURL=setup.js.map

package/dist/commands/template.js

@@ -0,0 +1,357 @@
+// `insta template` — browse the platform template registry and deploy a template (by registry
+// code, or from a local directory carrying insta.template.yaml) onto a branch. The deploy is a
+// platform-side pipeline (create services → write variables → deploy → health check); the CLI
+// submits it and renders progress by polling the deployment resource.
+import { join, resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import * as clack from '@clack/prompts';
+import { ApiClient, ApiError, requireProject } from '../api.js';
+import { info, printJson, handleApproval, renderNextActions } from '../util.js';
+import { MANIFEST_FILE, collectManifestVariables, loadTemplateManifest } from '../template-manifest.js';
+// One aligned row per template; numeric columns right-aligned. Plain padded columns, as the rest
+// of the CLI (storage list, compute check-domain) — no table library.
+export function templateListLines(templates) {
+    if (!templates.length)
+        return ['(no templates published yet)'];
+    const head = ['CODE', 'VERSION', 'CATEGORY', 'VARS', 'DEPLOYS', 'NAME'];
+    const numeric = [false, false, false, true, true, false];
+    const rows = templates.map((t) => [
+        t.code, t.version ?? '', t.category ?? '-',
+        String(t.requiredVarCount ?? 0), String(t.deployCount ?? 0),
+        t.tagline ? `${t.name} — ${t.tagline}` : (t.name ?? ''),
+    ]);
+    const widths = head.map((h, i) => Math.max(h.length, ...rows.map((r) => r[i].length)));
+    return [head, ...rows].map((r) => r.map((c, i) => (i === r.length - 1 ? c : numeric[i] ? c.padStart(widths[i]) : c.padEnd(widths[i]))).join('  ').trimEnd());
+}
+// The info endpoint may list services as an array or keep the manifest's map shape — render both.
+export function normalizeInfoServices(raw) {
+    if (Array.isArray(raw)) {
+        return raw.map((s) => ({ name: s.name ?? '?', type: s.type, port: s.port, volumeGib: s.volumeGib ?? s.volume?.size }));
+    }
+    if (raw && typeof raw === 'object') {
+        return Object.entries(raw).map(([name, s]) => ({ name, type: s?.type, port: s?.port, volumeGib: s?.volumeGib ?? s?.volume?.size }));
+    }
+    return [];
+}
+// Variables may arrive as one array with a `required` flag, or pre-grouped {required, optional}
+// (the registry detail endpoint's shape).
+export function normalizeInfoVariables(raw) {
+    const one = (v, required) => ({
+        name: v.name, required, description: v.description, default: v.default, generate: v.generate,
+    });
+    if (Array.isArray(raw))
+        return raw.map((v) => one(v, !!v.required));
+    if (raw && typeof raw === 'object') {
+        const g = raw;
+        return [...(g.required ?? []).map((v) => one(v, true)), ...(g.optional ?? []).map((v) => one(v, false))];
+    }
+    return [];
+}
+// `bold` is injected so the renderer stays pure (tests pass identity; the command passes ANSI
+// bold on a TTY).
+export function templateInfoLines(t, bold = (s) => s) {
+    const lines = [`${t.code}${t.name ? ` — ${t.name}` : ''}`];
+    if (t.tagline)
+        lines.push(`  ${t.tagline}`);
+    const field = (label, value) => { if (value)
+        lines.push(`  ${label.padEnd(11)} ${value}`); };
+    field('version', t.version);
+    field('maintainer', t.maintainer);
+    field('source', t.source);
+    field('license', t.license);
+    field('upstream', t.upstream?.pinned ?? t.upstream?.image ?? t.upstream?.repo);
+    const services = normalizeInfoServices(t.services);
+    if (services.length) {
+        const summary = services.map((s) => {
+            const bits = [s.type && s.type !== 'compute' ? s.type : undefined, s.port ? `port ${s.port}` : undefined, s.volumeGib ? `${s.volumeGib}Gi volume` : undefined].filter(Boolean);
+            return `${s.name}${bits.length ? ` (${bits.join(', ')})` : ''}`;
+        });
+        lines.push(`services (${services.length}): ${summary.join(', ')}`);
+    }
+    const vars = normalizeInfoVariables(t.variables);
+    if (vars.length) {
+        lines.push('variables:');
+        const render = (v, emph) => {
+            const extra = [v.generate ? `generated: ${v.generate}` : undefined, v.default !== undefined ? `default: ${v.default}` : undefined].filter(Boolean);
+            lines.push(`    ${emph(v.name.padEnd(24))} ${v.description ?? ''}${extra.length ? ` (${extra.join(', ')})` : ''}`.trimEnd());
+        };
+        const required = vars.filter((v) => v.required);
+        const optional = vars.filter((v) => !v.required);
+        if (required.length) {
+            lines.push('  required:');
+            for (const v of required)
+                render(v, bold);
+        }
+        if (optional.length) {
+            lines.push('  optional:');
+            for (const v of optional)
+                render(v, (s) => s);
+        }
+    }
+    return lines;
+}
+// Parse repeated --set K=V flags. Names must be platform env-var names (the same rule the
+// manifest's env maps live under), so a typo fails here instead of surviving to a server 400.
+// Later occurrences of a name win (shell-override semantics).
+export function parseSetFlags(pairs) {
+    const values = {};
+    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}`);
+        values[m[1]] = m[2];
+    }
+    return values;
+}
+export function missingVariablesMessage(missing) {
+    return [
+        'missing required template variables:',
+        ...missing.map((v) => `  ${v.name.padEnd(24)} ${v.description ?? ''}`.trimEnd()),
+        'supply them with --set NAME=value (repeatable)',
+    ].join('\n');
+}
+/**
+ * Decide which deploy-time variables to SEND. The platform's own resolution order is
+ * provided → generator → default (templateManifest.ts resolveVariables), so anything a generator
+ * or default answers is left OFF the wire — the executor generates secrets itself (they never
+ * transit) and applies defaults. What remains: --set wins; required vars with no machine answer
+ * are prompted on a TTY and are an error anywhere else. Unknown --set names pass through — the
+ * platform's variable set may be newer than local parsing.
+ */
+export async function resolveVariables(vars, given, opts = {}) {
+    const values = { ...given };
+    const missing = [];
+    for (const v of vars) {
+        if (values[v.name] !== undefined)
+            continue;
+        if (v.generate || v.default !== undefined) {
+            opts.onAutoResolved?.(v);
+            continue;
+        }
+        if (!v.required)
+            continue;
+        if (opts.tty && opts.ask) {
+            values[v.name] = await opts.ask(v);
+            continue;
+        }
+        missing.push(v);
+    }
+    if (missing.length)
+        throw new Error(missingVariablesMessage(missing));
+    return values;
+}
+// The platform's machine-readable "you forgot these" answer to the POST (error=missing_variables,
+// missing: [{name, key, description}] with a missingVariables alias) — turned back into promptable
+// variables. null = some other error, not ours to interpret.
+export function missingVariablesFrom(body) {
+    if ((body?.error ?? body?.code) !== 'missing_variables')
+        return null;
+    const list = body?.missing ?? body?.missingVariables ?? [];
+    if (!Array.isArray(list))
+        return [];
+    return list.map((v) => ({ name: String(v.name ?? v.key ?? v), required: true, description: v.description }));
+}
+// A deploy target that reads as a filesystem path must resolve as one — a typo'd directory should
+// not fall through to a registry lookup that 404s with a confusing "no such template".
+export function looksLikePath(target) {
+    return target.startsWith('.') || target.startsWith('/') || target.startsWith('~') || target.includes('/') || target.includes('\\');
+}
+// Expanding `~` is normally the shell's job, but it only does it unquoted — `deploy "~/tpl"`, or a
+// target assembled by an agent, arrives literally, and path.resolve() would then look for a
+// directory actually named "~". looksLikePath advertises `~` as a local path, so honour it here.
+// `~user` is left alone: resolving another user's home needs a passwd lookup, which no shell-less
+// tool should fake.
+const expandHome = (target) => target.replace(/^~(?=[/\\]|$)/, () => homedir());
+/**
+ * Which deploy mode a target selects. Local mode is OPTED INTO by a path-looking target (./dir,
+ * /abs, sub/dir); a bare word is ALWAYS a registry code — even when a same-named directory with a
+ * manifest sits in the working directory, deploying it must be explicit (./plausible), never a
+ * cwd coincidence. And a path-looking target with no manifest is a mistake, never a registry code.
+ */
+export function deployMode(target, hasManifest = (d) => existsSync(join(d, MANIFEST_FILE))) {
+    if (!looksLikePath(target))
+        return { kind: 'registry', code: target };
+    const dir = resolve(process.cwd(), expandHome(target));
+    if (!hasManifest(dir))
+        throw new Error(`no ${MANIFEST_FILE} at ${join(dir, MANIFEST_FILE)}`);
+    return { kind: 'local', dir };
+}
+// ---- deployment progress ----
+// The platform pipeline (insta-platform TemplateDeployment): status is running|succeeded|failed|
+// partial, and `step` names where the run is (or stopped) — create_services → write_variables →
+// deploy → health_check.
+export const DEPLOY_STEPS = ['create services', 'write variables', 'deploy', 'health check'];
+const STEP_KEYS = ['create_services', 'write_variables', 'deploy', 'health_check'];
+/** The index of the step a deployment is on, or null when it reports none (or one this CLI does
+ *  not know) — the watcher then holds progress instead of guessing. */
+export function stepIndexFor(step) {
+    const i = STEP_KEYS.indexOf(step ?? '');
+    return i >= 0 ? i : null;
+}
+/** Success URLs, one line each: per-service `name: url` (plus bare urls, defensively). */
+export function deploymentUrls(dep) {
+    const lines = [];
+    for (const u of dep?.urls ?? [])
+        lines.push(String(u));
+    for (const s of dep?.services ?? [])
+        if (s?.url)
+            lines.push(`${s.name ?? 'service'}: ${s.url}`);
+    return lines;
+}
+// One line per service with its terminal state — the anatomy of a partial/failed run.
+export function serviceStateLines(dep) {
+    return (dep?.services ?? []).map((s) => {
+        const mark = s?.state === 'healthy' ? '✓' : s?.state === 'failed' ? '✗' : '•';
+        return `  ${mark} ${s?.name ?? 'service'}${s?.url ? ` — ${s.url}` : ''}${s?.state && s.state !== 'healthy' ? ` [${s.state}]` : ''}`;
+    });
+}
+// `partial` is TERMINAL: some services came up healthy, others failed, and the created resources
+// are kept either way — so the message must say what stands and how to move (retry re-running the
+// 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;
+    return [
+        `template deployment finished partial: ${healthy}/${services.length} services healthy`,
+        ...serviceStateLines(dep),
+        ...(dep?.error ? [`  ${dep.error}`] : []),
+        ...(dep?.logsTail ? ['--- log tail ---', String(dep.logsTail).trimEnd()] : []),
+        'created services are kept — inspect with `insta logs compute <name>`, re-run the deploy to retry, or remove them with `insta services remove <type> <name>`',
+    ].join('\n');
+}
+export function failureMessage(dep, fallbackStep) {
+    const at = DEPLOY_STEPS[Math.min(stepIndexFor(dep?.step) ?? fallbackStep, DEPLOY_STEPS.length - 1)];
+    return [
+        `template deployment failed during ${at}${dep?.error ? `: ${dep.error}` : ''}`,
+        ...serviceStateLines(dep),
+        ...(dep?.logsTail ? ['--- log tail ---', String(dep.logsTail).trimEnd()] : []),
+    ].join('\n');
+}
+const sleepSeconds = (s) => new Promise((r) => setTimeout(r, s * 1000));
+/**
+ * Poll a template deployment until it settles, emitting each step exactly once as it completes
+ * (✓) or becomes active (…). Terminal states: succeeded (returns), failed and partial (throw —
+ * partial would otherwise poll forever, the platform never leaves it). Injectable getter/output/
+ * wait keep this testable without a network or real timers (the deviceGrant pattern in auth.ts).
+ */
+export async function watchDeployment(getDeployment, id, out = info, wait = sleepSeconds, timeoutMs = 15 * 60_000) {
+    let done = 0; // steps already reported ✓
+    let active = -1; // step already reported …
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const dep = await getDeployment(id);
+        const status = String(dep?.status ?? '');
+        const idx = stepIndexFor(dep?.step);
+        const completed = status === 'succeeded' ? DEPLOY_STEPS.length : (idx ?? done);
+        for (; done < completed; done++)
+            out(`  ✓ ${DEPLOY_STEPS[done]}`);
+        if (status === 'failed')
+            throw new Error(failureMessage(dep, done));
+        if (status === 'partial')
+            throw new Error(partialMessage(dep));
+        if (status === 'succeeded')
+            return dep;
+        // No step named (or one this CLI doesn't know): HOLD — announcing `create services` off a
+        // payload that never said so would be a guess, and the run may well be somewhere else.
+        if (idx !== null) {
+            const current = Math.min(idx, DEPLOY_STEPS.length - 1);
+            if (active !== current) {
+                out(`  … ${DEPLOY_STEPS[current]}`);
+                active = current;
+            }
+        }
+        await wait(2);
+    }
+    throw new Error(`timed out after ${Math.round(timeoutMs / 60_000)}m waiting for template deployment ${id} — check \`insta events\``);
+}
+// ---- commands ----
+export async function templateList(opts) {
+    const api = await ApiClient.load();
+    const { templates } = await api.request('GET', '/templates');
+    if (opts.json)
+        return printJson(templates);
+    for (const line of templateListLines(templates ?? []))
+        info(line);
+}
+export async function templateInfo(code, opts) {
+    const api = await ApiClient.load();
+    const tpl = await api.request('GET', `/templates/${encodeURIComponent(code)}`);
+    if (opts.json)
+        return printJson(tpl);
+    const bold = process.stdout.isTTY ? (s) => `\x1b[1m${s}\x1b[0m` : (s) => s;
+    for (const line of templateInfoLines(tpl.template ?? tpl, bold))
+        info(line);
+}
+/** Real prompt (clack, as feedback.ts); cancelling exits without deploying anything. */
+async function promptVariable(v) {
+    const answer = await clack.text({
+        message: `${v.name}${v.description ? ` — ${v.description}` : ''}:`,
+        validate: (s) => (s.trim() ? undefined : 'required'),
+    });
+    if (clack.isCancel(answer))
+        process.exit(0);
+    return answer.trim();
+}
+export async function templateDeploy(target, opts = {}, deps = {}) {
+    const given = parseSetFlags(opts.set ?? []); // a typo'd --set fails before any network access
+    // --json asked for parseable output: every human progress line is suppressed so stdout carries
+    // exactly one JSON document (the repo's --json convention).
+    const quiet = !!opts.json;
+    const api = deps.api ?? (await ApiClient.load());
+    const p = deps.project ?? (await requireProject());
+    const branchName = opts.branch ?? p.branch;
+    const ask = deps.ask ?? promptVariable;
+    // Local directory mode is opted into by a path-looking target; a bare word is always a registry
+    // code, so a same-named local directory can never shadow the registry template.
+    const mode = deployMode(target);
+    let manifest;
+    let vars;
+    if (mode.kind === 'local') {
+        manifest = loadTemplateManifest(mode.dir); // parse + local validation (pinned images, described vars)
+        vars = collectManifestVariables(manifest);
+        if (!quiet)
+            info(`deploying local template ${manifest.code}@${manifest.version}`);
+    }
+    else {
+        // Learn the variable set up front from the registry so prompting happens before the POST.
+        const tpl = await api.request('GET', `/templates/${encodeURIComponent(mode.code)}`);
+        vars = normalizeInfoVariables((tpl.template ?? tpl).variables);
+    }
+    // --json asked for parseable output, so a caller that happens to own a TTY still gets the error.
+    const tty = !opts.json && !opts.yes && !!process.stdin.isTTY && !!process.stdout.isTTY;
+    const onAutoResolved = quiet ? undefined : (v) => info(`  ${v.name}: ${v.generate ? `platform-generated (${v.generate})` : `default (${v.default})`}`);
+    const variables = await resolveVariables(vars, given, { tty, ask, onAutoResolved });
+    // The endpoint takes the branch NAME directly (branchId is its uuid alias) — no lookup needed.
+    const body = { ...(mode.kind === 'local' ? { manifest } : { templateCode: mode.code }), branch: branchName, variables };
+    let res;
+    try {
+        res = await api.rawRequest('POST', `/projects/${p.projectId}/template-deployments`, body);
+    }
+    catch (e) {
+        // The platform's own variable check is the authority; when it names what is missing in a
+        // machine-readable way, prompt from that and retry once instead of parroting an opaque 4xx.
+        const missing = e instanceof ApiError ? missingVariablesFrom(e.body) : null;
+        if (!missing?.length)
+            throw e;
+        Object.assign(variables, await resolveVariables(missing, {}, { tty, ask }));
+        res = await api.rawRequest('POST', `/projects/${p.projectId}/template-deployments`, { ...body, variables });
+    }
+    // handleApproval owns the whole 202 contract (hint on stderr, raw envelope on stdout under
+    // --json, exit code 2) — pass the flag through as every other gated command does.
+    if (handleApproval(res, opts.json))
+        return;
+    const deploymentId = res.body.deploymentId ?? (res.body.deployment ?? res.body).id;
+    const codeLabel = manifest?.code ?? target;
+    if (!quiet)
+        info(`deploying template ${codeLabel} to branch ${branchName} (${deploymentId})`);
+    const dep = await watchDeployment((id) => api.request('GET', `/template-deployments/${id}`), deploymentId, quiet ? () => { } : info, deps.wait);
+    if (opts.json)
+        return printJson(dep);
+    info(`template ${codeLabel} deployed to branch ${branchName}`);
+    for (const u of deploymentUrls(dep))
+        info(`  ${u}`);
+    info('next: run `insta secrets` to refresh .env with the new service credentials');
+    renderNextActions(dep.nextActions);
+}
+//# sourceMappingURL=template.js.map

package/dist/index.js

@@ -22,6 +22,7 @@ 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 template from './commands/template.js';
 import * as govern from './commands/govern.js';
 import * as observe from './commands/observe.js';
 import * as obs from './commands/metrics.js';
@@ -256,6 +257,17 @@ storage.command('delete <key>').description('DELETES one object from the bucket
     .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)));
+// ---- templates (registry + local insta.template.yaml deploys) ----
+const tpl = program.command('template').description('Browse and deploy app templates (registry, or a local dir with insta.template.yaml)');
+tpl.command('list').description('List templates in the platform registry').option('--json').action(guard((o) => template.templateList(o)));
+tpl.command('info <code>').description('Show a template: version, upstream pin, services, and its required/optional variables')
+    .option('--json').action(guard((code, o) => template.templateInfo(code, o)));
+tpl.command('deploy <code-or-dir>').description('Deploy a template onto a branch — a registry code, or a local directory containing insta.template.yaml (a path-looking target is always read as a directory). Missing required variables are prompted for on a terminal; generator-backed (secret:N) and defaulted ones are resolved by the platform')
+    .option('--branch <b>', 'target branch (default: current)')
+    .option('--set <NAME=value>', 'set a template variable (repeatable)', (v, prev) => [...prev, v], [])
+    .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)));
 // ---- manifest ----
 program.command('manifest').description('Print an agent-legible view of the project environments').option('--json').action(guard((o) => manifest(o)));
 // ---- regions ----

package/dist/template-manifest.js

@@ -0,0 +1,190 @@
+// Local insta.template.yaml parsing + validation for `insta template deploy ./dir` — the CLI
+// twin of the platform's src/provisioning/templateManifest.ts (THE authority; the executor
+// revalidates every manifest). Local checks exist to fail fast with a file the author can act
+// on, before anything travels, so the rules here mirror the server's exactly — plus two
+// authoring lints the server does not enforce: images must be pinned, and required variables
+// need a description unless a generator answers for the user. Everything here is pure over the
+// parsed document (unit-tested); only loadTemplateManifest touches disk.
+import { join, resolve } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import YAML from 'yaml';
+export const MANIFEST_FILE = 'insta.template.yaml';
+// The platform's own shapes (templateManifest.ts): codes and service names become branch/service
+// names; env vars are user-secret names; the one generator family is secret:N.
+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})$/;
+// What counts as a digest is the PLATFORM's call, not ours: registry.ts's DIGEST regex, verbatim.
+const DIGEST = /^sha256:[a-f0-9]{64}$/;
+// Why an image must carry a pin: a template is a reproducible deploy, and a tagless ref (implicit
+// :latest) or an explicit :latest re-resolves on every deploy — two runs of the same template
+// version would ship different bytes. Digest-pinned refs (…@sha256:…) are the strongest pin.
+//
+// The reference grammar mirrors the platform's parseImageRef (src/provisioning/registry.ts, THE
+// authority): everything after the LAST `@` is the reference, and `@` wins over `:` — so a `@`
+// reference is a pin only when it is a real digest, and a malformed one is never re-read as a tag.
+export function imageTagIssue(image) {
+    const at = image.lastIndexOf('@');
+    if (at !== -1) {
+        if (DIGEST.test(image.slice(at + 1)))
+            return null; // digest-pinned, the strongest pin
+        return `image ${image} carries an @ reference that is not a sha256 digest — use @sha256:<64 hex> (or a version tag)`;
+    }
+    const lastSegment = image.split('/').pop() ?? '';
+    const tag = lastSegment.includes(':') ? lastSegment.split(':').pop() : undefined;
+    if (!tag)
+        return `image ${image} has no tag — pin a version (or a @sha256 digest)`;
+    if (tag === 'latest')
+        return `image ${image} is pinned to :latest, which is not a pin — use a version tag (or a @sha256 digest)`;
+    return null;
+}
+// The platform runs every scalar manifest field through scalarString
+// (src/provisioning/templateManifest.ts): a string passes, a number/boolean coerces, anything else
+// is a manifest error naming the field. Same verdict here, so a YAML typo is reported rather than
+// crashing a lint that assumed a string.
+function scalarString(v) {
+    if (typeof v === 'string')
+        return v;
+    if (typeof v === 'number' || typeof v === 'boolean')
+        return String(v);
+    return null;
+}
+function asVarSpec(v) {
+    if (typeof v === 'string')
+        return { description: v };
+    return v ?? {};
+}
+/** All local validation problems, empty when the manifest is deployable. */
+export function validateManifest(m) {
+    const problems = [];
+    if (!m || typeof m !== 'object')
+        return ['manifest is not a YAML mapping'];
+    if (!m.code || typeof m.code !== 'string')
+        problems.push('code is required');
+    else if (!CODE_RE.test(m.code))
+        problems.push(`code must be lower-kebab (a-z, 0-9, -, max 39 chars), got: ${m.code}`);
+    if (m.version === undefined || m.version === null || m.version === '')
+        problems.push('version is required');
+    const generators = new Set();
+    for (const [name, spec] of Object.entries(m.generated ?? {})) {
+        if (!GENERATOR_RE.test(String(spec)))
+            problems.push(`generated.${name}: unknown generator '${spec}' (the platform knows secret:N, N 1-999)`);
+        generators.add(name);
+    }
+    const services = m.services ?? {};
+    const names = Object.keys(services);
+    if (names.length === 0)
+        problems.push('services: at least one service is required');
+    for (const name of names) {
+        const svc = services[name] ?? {};
+        const where = `services.${name}`;
+        if (svc.type !== 'web' && svc.type !== 'worker')
+            problems.push(`${where}.type must be web or worker`);
+        if (svc.image && svc.build)
+            problems.push(`${where}: image and build are mutually exclusive`);
+        if (!svc.image && !svc.build)
+            problems.push(`${where}: one of image or build is required`);
+        // A parsed YAML document holds whatever the author typed, so both scalars are type-checked the
+        // platform's way BEFORE any rule reads them as strings.
+        const image = svc.image !== undefined ? scalarString(svc.image) : undefined;
+        if (svc.image !== undefined && image === null)
+            problems.push(`${where}.image must be a string`);
+        if (svc.build !== undefined && scalarString(svc.build) === null)
+            problems.push(`${where}.build must be a string`);
+        if (image) {
+            const issue = imageTagIssue(image);
+            if (issue)
+                problems.push(`${where}: ${issue}`);
+        }
+        if (svc.port !== undefined && (!Number.isInteger(svc.port) || svc.port < 1 || svc.port > 65535)) {
+            problems.push(`${where}: port must be an integer between 1 and 65535, got: ${svc.port}`);
+        }
+        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 /)`);
+        if (svc.volume !== undefined && (!Number.isInteger(svc.volume?.size) || svc.volume.size < 1)) {
+            problems.push(`${where}: volume.size must be a whole Gi ≥ 1, got: ${svc.volume?.size}`);
+        }
+        const env = svc.env ?? {};
+        for (const group of ['fixed', 'generated', 'required', 'optional']) {
+            for (const varName of Object.keys(env[group] ?? {})) {
+                if (!ENV_NAME_RE.test(varName))
+                    problems.push(`${where}.env.${group}.${varName}: env names must match ^[A-Z][A-Z0-9_]{0,63}$`);
+            }
+        }
+        for (const [varName, ref] of Object.entries(env.generated ?? {})) {
+            const match = /^\$\{([a-zA-Z0-9_-]+)\}$/.exec(String(ref));
+            if (!match)
+                problems.push(`${where}.env.generated.${varName} must reference a declared generator like \${name}`);
+            else if (!generators.has(match[1]))
+                problems.push(`${where}.env.generated.${varName} references undeclared generator '${match[1]}'`);
+        }
+        // The generator rule is the server's, so it holds wherever a var declares one — an invalid
+        // generate on an OPTIONAL var is just as fatal at deploy time as on a required one.
+        for (const group of ['required', 'optional']) {
+            for (const [varName, raw] of Object.entries(env[group] ?? {})) {
+                const spec = asVarSpec(raw);
+                if (spec.generate && !GENERATOR_RE.test(spec.generate))
+                    problems.push(`${where}.env.${group}.${varName}: generate must be secret:N (1-999), got: ${spec.generate}`);
+                // A required var is a question put to the deployer — without a description (or a generator
+                // that answers it for them) there is nothing to ask with. Authoring lint, CLI-only.
+                if (group === 'required' && !spec.description && !spec.generate)
+                    problems.push(`${where}.env.required.${varName}: a description is required (unless generate is set)`);
+            }
+        }
+    }
+    return problems;
+}
+/**
+ * Flatten the manifest's prompt-relevant variables: every service's env.required and env.optional
+ * merged into the global variable namespace the POST's `variables` map addresses — the same name
+ * declared by two services is ONE variable, required if required anywhere, later mentions
+ * backfilling fields earlier ones left unset (the platform's collectVariables merge). env.fixed /
+ * env.generated (and top-level `generated`) are filled in by the executor, so they are not
+ * deploy-time questions.
+ */
+export function collectManifestVariables(m) {
+    const byName = new Map();
+    const add = (name, raw, required) => {
+        const spec = asVarSpec(raw);
+        const prev = byName.get(name);
+        byName.set(name, {
+            name,
+            description: prev?.description ?? spec.description,
+            required: (prev?.required ?? false) || required,
+            default: prev?.default ?? spec.default,
+            generate: prev?.generate ?? spec.generate,
+        });
+    };
+    for (const svc of Object.values(m.services ?? {})) {
+        for (const [name, spec] of Object.entries(svc.env?.required ?? {}))
+            add(name, spec, true);
+        for (const [name, spec] of Object.entries(svc.env?.optional ?? {}))
+            add(name, spec, false);
+    }
+    return [...byName.values()];
+}
+/** Parse manifest YAML text. Throws with every validation problem listed, not just the first. */
+export function parseManifestYaml(text, source = MANIFEST_FILE) {
+    let doc;
+    try {
+        doc = YAML.parse(text);
+    }
+    catch (e) {
+        throw new Error(`${source}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    const manifest = (doc ?? {});
+    const problems = validateManifest(manifest);
+    if (problems.length)
+        throw new Error(`${source} is not deployable:\n${problems.map((p) => `  - ${p}`).join('\n')}`);
+    return manifest;
+}
+/** Read + validate <dir>/insta.template.yaml. */
+export function loadTemplateManifest(dir) {
+    const path = join(resolve(process.cwd(), dir), MANIFEST_FILE);
+    if (!existsSync(path))
+        throw new Error(`no ${MANIFEST_FILE} at ${path}`);
+    return parseManifestYaml(readFileSync(path, 'utf8'), path);
+}
+//# sourceMappingURL=template-manifest.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "insta",
-  "version": "0.0.39",
+  "version": "0.0.41",
   "type": "module",
   "description": "InstaCloud CLI — a thin client of the platform control-plane API.",
   "keywords": [
@@ -43,7 +43,8 @@
   },
   "dependencies": {
     "@clack/prompts": "^0.9.1",
-    "commander": "^12.1.0"
+    "commander": "^12.1.0",
+    "yaml": "^2.9.0"
   },
   "devDependencies": {
     "@types/node": "^20.14.0",