insta 0.0.60 → 0.0.62

package/dist/commands/compute.js

@@ -589,7 +589,7 @@ export async function computeAlwaysOn(mode, serviceName, opts) {
     if (opts.json)
         return printJson(res.body);
     const on = res.body.service?.always_on;
-    info(`compute ${res.body.service?.name ?? id}: always-on ${on ? 'ENABLED — machines stay warm (no cold starts; idle RAM bills at actual usage)' : 'disabled — scales to zero when idle (default)'}`);
+    info(`compute ${res.body.service?.name ?? id}: always-on ${on ? 'ENABLED — machines stay warm (no cold starts; idle RAM bills at actual usage)' : 'disabled — scales to zero when idle'}`);
 }
 // ---- limits (the resource ceiling; paid plans) ----
 // Parse a human memory value into MB: "512", "512mb", "1gb", "2g", "1.5gb".

package/dist/commands/services.js

@@ -85,7 +85,10 @@ export function servicesAddRequestBody(type, name, branch, opts) {
         type, name, ...(branch ? { branch } : {}), public: !!opts.public,
         ...(opts.image ? { image: opts.image } : {}), ...(opts.port ? { port: parsePort(opts.port) } : {}),
         ...(opts.region ? { region: opts.region } : {}),
-        ...(opts.alwaysOn ? { alwaysOn: true } : {}),
+        // Sent whenever the flag was given, false included: compute is born always-on by default
+        // (insta-platform #385, 2026-09-07), so `--no-always-on` must reach the API as an explicit
+        // false. Omitted means the platform default.
+        ...(opts.alwaysOn !== undefined ? { alwaysOn: opts.alwaysOn } : {}),
         ...(opts.volume !== undefined ? { volumeGib: parseVolumeGib(opts.volume) } : {}),
     };
 }
@@ -102,8 +105,9 @@ export async function servicesAdd(type, name, opts = {}) {
             throw new Error('--port is only valid for compute services');
         parsePort(opts.port); // junk fails here, before any config/network access
     }
-    if (opts.alwaysOn && type !== 'compute')
-        throw new Error('--always-on is only valid for compute services (for postgres, use `insta db always-on on` after creation)');
+    // 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('--always-on / --no-always-on is only valid for compute services (for postgres, use `insta db always-on on|off` after creation)');
     if (opts.volume !== undefined) {
         if (type !== 'compute')
             throw new Error('--volume is only valid for compute services (postgres has one by default — grow it with `insta db volume --size`)');

package/dist/commands/template.js

@@ -1,5 +1,6 @@
 // `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
+// code, from a local directory carrying insta.template.yaml, or from a github.com URL whose
+// manifest github-source.ts fetches with the user's own git credentials) 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';
@@ -9,6 +10,7 @@ import * as clack from '@clack/prompts';
 import { ApiClient, ApiError, requireProject } from '../api.js';
 import { info, printJson, handleApproval, renderNextActions, CliCancel } from '../util.js';
 import { MANIFEST_FILE, collectManifestVariables, loadTemplateManifest } from '../template-manifest.js';
+import { parseGitHubTemplateUrl, fetchGitHubTemplate } from '../github-source.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) {
@@ -172,12 +174,18 @@ export function looksLikePath(target) {
 // 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.
+ * Which deploy mode a target selects. A URL is classified FIRST — it contains `/`, which
+ * looksLikePath would otherwise claim as a directory, and a non-GitHub URL must be named as
+ * unsupported rather than reported as a missing manifest. Then: 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))) {
+    const github = parseGitHubTemplateUrl(target);
+    if (github)
+        return { kind: 'github', target: github };
     if (!looksLikePath(target))
         return { kind: 'registry', code: target };
     const dir = resolve(process.cwd(), expandHome(target));
@@ -314,8 +322,21 @@ export async function templateDeploy(target, opts = {}, deps = {}) {
     // code, so a same-named local directory can never shadow the registry template.
     const mode = deployMode(target);
     let manifest;
+    let source;
     let vars;
-    if (mode.kind === 'local') {
+    if (mode.kind === 'github') {
+        const fetched = await (deps.fetchGitHub ?? ((t) => fetchGitHubTemplate(t)))(mode.target);
+        manifest = fetched.manifest;
+        source = fetched.source;
+        vars = collectManifestVariables(manifest);
+        // Spec 4.4: exactly ONE line in front of today's output. A second "deploying template …" line
+        // would read as a duplicate of the "deploying template <code> to branch <branch>" line below,
+        // so the manifest's code@version rides on this one instead.
+        if (!quiet) {
+            info(`fetching template ${manifest.code}@${manifest.version} from github.com/${source.repo}@${source.ref}${source.path ? ` (${source.path})` : ''} at ${source.commit.slice(0, 7)}`);
+        }
+    }
+    else if (mode.kind === 'local') {
         manifest = loadTemplateManifest(mode.dir); // parse + local validation (pinned images, described vars)
         vars = collectManifestVariables(manifest);
         if (!quiet)
@@ -331,7 +352,7 @@ export async function templateDeploy(target, opts = {}, deps = {}) {
     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 };
+    const body = { ...(mode.kind === 'registry' ? { templateCode: mode.code } : { manifest }), branch: branchName, variables };
     let res;
     try {
         res = await api.rawRequest('POST', `/projects/${p.projectId}/template-deployments`, body);
@@ -355,7 +376,7 @@ export async function templateDeploy(target, opts = {}, deps = {}) {
         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);
+        return printJson(source ? { source, ...dep } : dep);
     info(`template ${codeLabel} deployed to branch ${branchName}`);
     for (const u of deploymentUrls(dep))
         info(`  ${u}`);

package/dist/github-source.js

@@ -0,0 +1,327 @@
+// Fetch a template manifest out of a GitHub repository, on this machine, with the user's own git
+// credentials. Parsing, ref resolution and the shallow clone live here; the deploy path stays in
+// commands/template.ts. See docs/superpowers/specs/2026-09-04-template-deploy-github-url-design.md.
+import { spawn as nodeSpawn } from 'node:child_process';
+import { mkdtempSync, rmSync, existsSync, realpathSync, statSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, sep } from 'node:path';
+import { parseManifestYaml, MANIFEST_FILE } from './template-manifest.js';
+const GITHUB_HOST = /^(?:https?:\/\/)?(?:www\.)?github\.com\//i;
+// An explicit address: a scheme, or an scp-style user@host:path. Never a local path.
+// A scheme (with or without its slashes) or an scp-style user@host:path. The slashes are optional
+// because `https:/github.com/o/r`, a URL that lost one, must be named as a bad address rather than
+// resolved as a directory called `https:`. Two or more scheme characters are required so a Windows
+// drive letter (`C:\src`, `C:/src`) stays a path.
+const EXPLICIT_ADDRESS = /^[a-z][a-z0-9+.-]+:|^[^/\\]+@[^/\\]+:/i;
+// Scheme-less first segments we still read as a host. A bare `<name>/<path>` is otherwise a LOCAL
+// PATH: `v1.0/templates` and `my.app/bot` are directories, and reading every dotted first segment
+// as a host broke them. Only names that unambiguously host code belong here.
+const KNOWN_GIT_HOSTS = new Set([
+    'gitlab.com', 'www.gitlab.com', 'bitbucket.org', 'www.bitbucket.org', 'gist.github.com',
+    'codeberg.org', 'git.sr.ht', 'dev.azure.com', 'ssh.dev.azure.com', 'gitea.com', 'sourceforge.net',
+]);
+const SEGMENT = /^[A-Za-z0-9_.-]+$/;
+/** Is this an address rather than a path? Only an explicit scheme/scp form, or a first segment
+ *  naming a host we recognise. A scheme-less name is far likelier to be someone's directory than
+ *  a git host, so everything else falls through to local and registry modes. */
+function isAddress(target) {
+    if (EXPLICIT_ADDRESS.test(target))
+        return true;
+    return KNOWN_GIT_HOSTS.has((target.split(/[/\\]/, 1)[0] ?? '').toLowerCase());
+}
+export function unsupportedSourceMessage(target) {
+    return `unsupported template source: ${target}. Use a registry code, a local directory, or https://github.com/<owner>/<repo>[/tree/<ref>[/<dir>]]`;
+}
+// Percent-decode first, so %2e%2e and %2f cannot smuggle a traversal past the segment check.
+function decodedSegments(parts, target) {
+    return parts.map((raw) => {
+        let seg;
+        try {
+            seg = decodeURIComponent(raw);
+        }
+        catch {
+            throw new Error(unsupportedSourceMessage(target));
+        }
+        if (!seg || seg === '.' || seg === '..' || /[/\\\0]/.test(seg))
+            throw new Error(unsupportedSourceMessage(target));
+        return seg;
+    });
+}
+/** Parse a github.com URL into owner, repo and the still-unsplit ref+path tail.
+ *  null = not URL-shaped, so the caller's local-directory and registry modes still get a look.
+ *  A URL-shaped target that is not a github.com repository URL throws (spec 4.1). */
+export function parseGitHubTemplateUrl(target) {
+    if (!GITHUB_HOST.test(target)) {
+        // Name a non-GitHub address for what it is; let everything else reach local/registry mode.
+        if (isAddress(target))
+            throw new Error(unsupportedSourceMessage(target));
+        return null;
+    }
+    // Links copied from GitHub's UI carry ?plain=1, #L1-L5 or ?tab=readme-ov-file, and none of that
+    // names a file. A `?` or `#` in a real path arrives percent-encoded, so a bare one is always the
+    // delimiter. Dropping it silently beats a "directory" called `bot?tab=readme-ov-file`.
+    const clean = target.replace(/[?#][\s\S]*$/, '');
+    const rest = clean.replace(GITHUB_HOST, '').replace(/\/+$/, '');
+    const parts = rest.split('/');
+    const owner = parts[0] ?? '';
+    const repo = (parts[1] ?? '').replace(/\.git$/i, '');
+    if (!SEGMENT.test(owner) || !SEGMENT.test(repo))
+        throw new Error(unsupportedSourceMessage(target));
+    const kind = parts[2];
+    if (kind === undefined)
+        return { owner, repo, refAndPath: '' };
+    if (kind !== 'tree' && kind !== 'blob')
+        throw new Error(unsupportedSourceMessage(target));
+    let tail = decodedSegments(parts.slice(3), target);
+    if (!tail.length)
+        throw new Error(unsupportedSourceMessage(target));
+    if (kind === 'blob') {
+        // A file link is read as its directory, and only for the manifest itself.
+        if (tail[tail.length - 1] !== MANIFEST_FILE)
+            throw new Error(unsupportedSourceMessage(target));
+        tail = tail.slice(0, -1);
+        if (!tail.length)
+            throw new Error(unsupportedSourceMessage(target));
+    }
+    return { owner, repo, refAndPath: tail.join('/') };
+}
+export const LS_REMOTE_TIMEOUT_MS = 30_000;
+export const CLONE_TIMEOUT_MS = 120_000;
+export function gitMissingMessage() {
+    return `git is required to deploy a template from a GitHub URL. Install git, or clone the repository yourself and run: insta template deploy ./<dir>`;
+}
+// git asks for nothing: no terminal credential prompt, no SSH host-key or passphrase prompt (an
+// insteadOf rewrite can send the clone over SSH). The environment stops it asking; only the
+// timeout stops it waiting.
+// GIT_SSH_COMMAND is EXTENDED, never replaced: a user's own `ssh -i <key>` IS how their private
+// repository authenticates, and overwriting it would drop the credentials this feature runs on.
+function nonInteractiveEnv(env = process.env) {
+    const ssh = env.GIT_SSH_COMMAND?.trim();
+    return {
+        GIT_TERMINAL_PROMPT: '0',
+        GIT_SSH_COMMAND: ssh ? `${ssh} -o BatchMode=yes` : 'ssh -o BatchMode=yes',
+        GCM_INTERACTIVE: 'never',
+    };
+}
+// git spawns helpers (ssh, a credential manager) that inherit its pipes, so a timeout has to take
+// the whole group. Windows has no process groups; taskkill /T walks the tree instead.
+function killTree(child) {
+    try {
+        if (process.platform === 'win32' && child.pid) {
+            // spawn reports a missing binary ASYNCHRONOUSLY: without this listener an absent taskkill
+            // becomes an uncaught ENOENT that kills the CLI, and try/catch never sees it.
+            nodeSpawn('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore' })
+                .on('error', () => { });
+        }
+        else if (child.pid) {
+            process.kill(-child.pid, 'SIGKILL'); // negative pid addresses the group
+        }
+    }
+    catch { /* already gone */ }
+    try {
+        child.kill('SIGKILL');
+    }
+    catch { /* already gone */ }
+}
+// A settled promise does not let the CLI exit. Node keeps its event loop alive for an open pipe,
+// and a grandchild that escaped the kill still holds the write end. Releasing our read ends and
+// unref-ing the child is what actually lets the process end.
+function releaseChild(child) {
+    try {
+        child.stdout?.destroy();
+    }
+    catch { /* already closed */ }
+    try {
+        child.stderr?.destroy();
+    }
+    catch { /* already closed */ }
+    try {
+        child.unref();
+    }
+    catch { /* already gone */ }
+}
+/** spawnFn is injected so the timeout path is testable without a network (spec FAQ 7.15). */
+export function makeGitRunner(spawnFn = nodeSpawn) {
+    return (args, opts) => new Promise((resolve) => {
+        // Spawned directly, NOT through resolveSpawnable: that wrapper exists for npm-installed
+        // `.cmd` shims, and its cmd.exe hop breaks any executable path containing a space —
+        // `cmd /s /c "C:\Program Files\Git\cmd\git.exe" --version` has its quotes stripped and
+        // dies with `'C:\Program' is not recognized`. git ships a real git.exe, which spawn finds
+        // through PATHEXT by itself; a `.cmd`-only git fails ENOENT, which reads as gitMissingMessage.
+        const child = spawnFn('git', args, {
+            env: { ...process.env, ...nonInteractiveEnv() },
+            stdio: ['ignore', 'pipe', 'pipe'],
+            // Own process group on POSIX, so killTree can reach git's helpers.
+            detached: process.platform !== 'win32',
+        });
+        let stdout = '';
+        let stderr = '';
+        let settled = false;
+        const finish = (r) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(r);
+        };
+        const timer = setTimeout(() => {
+            killTree(child);
+            // Then let go of the pipes. Killing can miss a grandchild that changed process group, and
+            // its inherited write end would keep BOTH 'close' and the CLI's event loop waiting
+            // (measured: promise settled at 203ms, process exited at 20094ms).
+            releaseChild(child);
+            // Settle NOW. 'close' waits for every inherited pipe; waiting would void the bound.
+            finish({ code: -1, stdout, stderr, timedOut: true });
+        }, opts.timeoutMs);
+        child.stdout?.on('data', (b) => { stdout += b.toString(); });
+        child.stderr?.on('data', (b) => { stderr += b.toString(); });
+        child.on('error', (err) => finish({ code: -1, stdout, stderr: `${stderr}${err.message}`, timedOut: false }));
+        child.on('close', (code) => finish({ code: code ?? -1, stdout, stderr, timedOut: false }));
+    });
+}
+export const defaultGitRunner = makeGitRunner();
+export function repoUrl(t) {
+    return `https://github.com/${t.owner}/${t.repo}.git`;
+}
+function repoLabel(t) {
+    return `https://github.com/${t.owner}/${t.repo}`;
+}
+export function unreadableRepoMessage(t, stderr) {
+    const tail = stderr.trim().split('\n').slice(-2).join('\n');
+    return [
+        `could not read ${repoLabel(t)}: repository not found or not accessible.`,
+        'If this is a private repository, configure git credentials and retry. With GitHub CLI:',
+        '  gh auth login',
+        '  gh auth setup-git',
+        ...(tail ? [`git said: ${tail}`] : []),
+    ].join('\n');
+}
+/** Read `git ls-remote --symref`: the HEAD symref names the default branch, and every other line
+ *  is `<sha>\t<refname>`. Keyed by FULL ref, so refs/heads/x and refs/tags/x stay distinct.
+ *  Peeled entries (`^{}`) are dropped: they name a commit, not a ref anyone can clone. */
+export function parseLsRemote(stdout) {
+    let head = null;
+    const refs = new Map();
+    for (const line of stdout.split('\n')) {
+        const symref = /^ref:\s+refs\/heads\/(\S+)\s+HEAD$/.exec(line);
+        if (symref) {
+            head = symref[1];
+            continue;
+        }
+        const m = /^([0-9a-f]{40})\s+(refs\/(?:heads|tags)\/.+)$/.exec(line);
+        if (!m || m[2].endsWith('^{}'))
+            continue;
+        refs.set(m[2], m[1]);
+    }
+    return { head, refs };
+}
+/** Longest-first, because a ref may contain `/` and only the real ref list can say where it ends.
+ *  A branch beats a tag of the same name, which is what `git clone --branch` does with the short
+ *  name; qualifiedRef records that choice for the reader, the clone still gets `ref`. */
+export function splitRefAndPath(refAndPath, refs) {
+    const segments = refAndPath.split('/');
+    for (let take = segments.length; take > 0; take--) {
+        const ref = segments.slice(0, take).join('/');
+        const qualifiedRef = refs.has(`refs/heads/${ref}`) ? `refs/heads/${ref}`
+            : refs.has(`refs/tags/${ref}`) ? `refs/tags/${ref}`
+                : null;
+        if (qualifiedRef)
+            return { ref, qualifiedRef, path: segments.slice(take).join('/') };
+    }
+    return null;
+}
+/** One round trip answers two questions: the default branch, and where the ref ends. The commit
+ *  is NOT taken from here — an annotated tag lists its tag object, and a branch can move before
+ *  the clone. fetchGitHubTemplate reads it from the checkout instead (spec FAQ 7.10). */
+export async function resolveGitHubRef(t, run) {
+    // HEAD is listed EXPLICITLY: adding refspecs otherwise drops the symref line that names the
+    // default branch (measured on this repo: 375 refs unfiltered, 188 with the filter, and no
+    // `ref: refs/heads/... HEAD` unless HEAD is asked for by name).
+    const res = await run(['ls-remote', '--symref', repoUrl(t), 'HEAD', 'refs/heads/*', 'refs/tags/*'], { timeoutMs: LS_REMOTE_TIMEOUT_MS });
+    if (res.timedOut)
+        throw new Error(`timed out after ${LS_REMOTE_TIMEOUT_MS / 1000}s resolving ${repoLabel(t)}`);
+    if (/\bENOENT\b/.test(res.stderr))
+        throw new Error(gitMissingMessage());
+    if (res.code !== 0)
+        throw new Error(unreadableRepoMessage(t, res.stderr));
+    const { head, refs } = parseLsRemote(res.stdout);
+    if (!t.refAndPath) {
+        if (!head)
+            throw new Error(unreadableRepoMessage(t, 'the remote named no default branch'));
+        return { ref: head, qualifiedRef: `refs/heads/${head}`, path: '' };
+    }
+    const split = splitRefAndPath(t.refAndPath, refs);
+    if (!split)
+        throw new Error(`no branch or tag ${t.refAndPath} in ${t.owner}/${t.repo}`);
+    return split;
+}
+/** What to call the manifest in a message: where the user pointed, never the temporary clone that
+ *  is deleted before they read it. */
+export function manifestLabel(t, r) {
+    return `${t.owner}/${t.repo}@${r.ref}:${r.path ? `${r.path}/` : ''}${MANIFEST_FILE}`;
+}
+export function missingManifestMessage(t, r) {
+    return [
+        `no ${MANIFEST_FILE} at ${t.owner}/${t.repo}@${r.ref}:${r.path || '/'}.`,
+        `Point the URL at the directory that contains it, for example https://github.com/${t.owner}/${t.repo}/tree/${r.ref}/templates/<name>`,
+    ].join(' ');
+}
+export function escapedManifestMessage(t, r) {
+    return `${MANIFEST_FILE} at ${t.owner}/${t.repo}@${r.ref}:${r.path || '/'} resolves outside the repository — refusing to read it`;
+}
+// The clone root, symlinks resolved, so containment is compared like with like.
+function containedRealPath(root, candidate) {
+    const realRoot = realpathSync(root);
+    const real = realpathSync(candidate);
+    if (real !== realRoot && !real.startsWith(realRoot + sep))
+        return null;
+    return real;
+}
+/** Resolve the ref, shallow-clone it, read the commit that was checked out, prove the manifest
+ *  sits inside the clone, parse it, delete the clone. Nothing on disk outlives this call: not the
+ *  variable prompt, not the POST, not the watcher. */
+export async function fetchGitHubTemplate(target, run = defaultGitRunner, parse = parseManifestYaml) {
+    const resolved = await resolveGitHubRef(target, run);
+    const dir = mkdtempSync(join(tmpdir(), 'insta-tpl-gh-'));
+    try {
+        // The short name, not resolved.qualifiedRef: `--branch` rejects a fully-qualified ref, and
+        // git's own short-name tie-break already agrees with splitRefAndPath (spec FAQ 7.14).
+        const cloned = await run(['clone', '--depth', '1', '--quiet', '--branch', resolved.ref, repoUrl(target), dir], { timeoutMs: CLONE_TIMEOUT_MS });
+        if (cloned.timedOut)
+            throw new Error(`timed out after ${CLONE_TIMEOUT_MS / 1000}s cloning https://github.com/${target.owner}/${target.repo}`);
+        if (/\bENOENT\b/.test(cloned.stderr))
+            throw new Error(gitMissingMessage());
+        if (cloned.code !== 0)
+            throw new Error(unreadableRepoMessage(target, cloned.stderr));
+        // The deployed commit is the one in the checkout: an annotated tag's listing entry is its tag
+        // object, and a branch can move between ls-remote and here (spec FAQ 7.10).
+        const head = await run(['-C', dir, 'rev-parse', 'HEAD'], { timeoutMs: LS_REMOTE_TIMEOUT_MS });
+        // Same three outcomes the other two calls distinguish, so a timeout or a missing git here is
+        // not reported as an unreadable repository.
+        if (head.timedOut)
+            throw new Error(`timed out after ${LS_REMOTE_TIMEOUT_MS / 1000}s reading the clone of ${repoLabel(target)}`);
+        if (/\bENOENT\b/.test(head.stderr))
+            throw new Error(gitMissingMessage());
+        if (head.code !== 0)
+            throw new Error(unreadableRepoMessage(target, head.stderr));
+        const commit = head.stdout.trim();
+        const manifestDir = resolved.path ? join(dir, resolved.path) : dir;
+        if (!existsSync(join(manifestDir, MANIFEST_FILE)))
+            throw new Error(missingManifestMessage(target, resolved));
+        // A committed symlink can point anywhere; only the resolved path proves what is being read.
+        const real = containedRealPath(dir, join(manifestDir, MANIFEST_FILE));
+        if (!real || !statSync(real).isFile())
+            throw new Error(escapedManifestMessage(target, resolved));
+        // Read and parse separately so a validation failure names where the user pointed. Handing the
+        // loader a directory makes it report the temp path, which is gone by the time they see it.
+        const manifest = parse(readFileSync(real, 'utf8'), manifestLabel(target, resolved));
+        return {
+            source: { repo: `${target.owner}/${target.repo}`, ref: resolved.ref, path: resolved.path, commit },
+            manifest,
+        };
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=github-source.js.map

package/dist/index.js

@@ -131,8 +131,9 @@ svc.command('add [type] [name]').description('Provision a service on demand (ass
     .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)')
-    .option('--always-on', 'compute only: create as always-on — never scales to zero (all plans; billing is actual usage either way)')
-    .option('--volume <gi>', 'compute only: attach a persistent /data volume of this many whole Gi (also attachable later: `insta compute volume <name> --size <gi>`; any plan may attach at the default 1; larger sizes are paid and plan-capped). Volume services keep 1 machine and stop (cold wake) instead of suspend when idle')
+    .option('--always-on', 'compute only: create as always-on — never scales to zero (the default for new compute services; all plans; billing is actual usage either way)')
+    .option('--no-always-on', 'compute only: create as scale-to-zero — idle machines suspend and wake on the next request')
+    .option('--volume <gi>', 'compute only: attach a persistent /data volume of this many whole Gi (also attachable later: `insta compute volume <name> --size <gi>`; any plan may attach at the default 10 (the free cap, on every plan); larger sizes are paid and plan-capped). Volume services keep 1 machine and stop (cold wake) instead of suspend when idle')
     .option('--json')
     .action(guard(async (type, name, o) => {
     const a = await resolveServiceArgs(type, name, serviceArgsDeps(o.json), o);
@@ -220,10 +221,10 @@ compute.command('restart [service]').description("Restart a compute service by r
     .option('--json').option('--branch <branch>', 'branch (default: current)').action(guard((service, o) => computeCmd.computeRestart(service, o)));
 compute.command('status [service]').description("Show a compute service's desired vs. live state")
     .option('--json').option('--branch <branch>', 'branch (default: current)').action(guard((service, o) => computeCmd.computeStatus(service, o)));
-compute.command('limits [service]').description("Show or set a compute service's resource ceiling (paid plans). --memory is the dial; cpu derives from it unless --cpu is given. Billing is actual usage — the ceiling caps what the app may burn, it is not a price")
+compute.command('limits [service]').description("Show or set a compute service's resource ceiling (any plan within the free cap; raising above it needs a paid plan). --memory is the dial; cpu derives from it unless --cpu is given. Billing is actual usage — the ceiling caps what the app may burn, it is not a price")
     .option('--memory <size>', 'memory ceiling, e.g. 512mb or 1gb').option('--cpu <n>', 'vCPU ceiling override (provider sizes: 1, 2, 4, 6, 8)')
     .option('--json').option('--branch <branch>', 'branch (default: current)').action(guard((service, o) => computeCmd.computeLimits(service, o)));
-compute.command('always-on <mode> [service]').description('Set a compute service always-on (mode: on|off). on = machines never scale to zero; off = default scale-to-zero. All plans; billing is actual usage either way')
+compute.command('always-on <mode> [service]').description('Set a compute service always-on (mode: on|off). on = machines never scale to zero (the default for new compute services); off = scale-to-zero. All plans; billing is actual usage either way')
     .option('--json').option('--branch <branch>', 'branch (default: current)').action(guard((mode, service, o) => computeCmd.computeAlwaysOn(mode, service, o)));
 const execCmd = compute.command('exec [service]').description("Run a one-shot command inside a compute service's machine (`insta compute exec [service] -- <command> [args…]`) — no interactive shell/PTY: `command` is argv, no shell is invoked (use [\"sh\", \"-c\", \"...\"] for shell features). Wakes the machine first if it's scaled to zero — expect a few seconds of latency, billed as uptime, not an error. Exits with the remote command's own exit code (agents rely on this)")
     .action(guard((service, o) => computeCmd.computeExec(service, execCommand, o, { windowsFallback: execWindowsFallback })));
@@ -231,7 +232,7 @@ const execCmd = compute.command('exec [service]').description("Run a one-shot co
 // new option cannot reach the CLI surface while the split still reads it as part of the command.
 for (const [flags, description] of computeCmd.EXEC_OPTIONS)
     execCmd.option(flags, description);
-compute.command('volume [service]').description("Show, attach, grow, or delete a compute service's persistent /data volume. No flag: print size, mount path, and the plan cap (any plan). --size on a volumeless service ATTACHES one (any plan at the default 1Gi; larger is paid and plan-capped; the disk mounts at /data on the next deploy); on a volume-bearing one it grows (paid plans; grow-only — a provisioned disk cannot shrink). --delete DESTROYS the disk and ALL its data immediately (no detach, no undo; billing stops now, and suspend fast-wake + scale-out return). Billing is actual data stored — the size is a cap, not a price")
+compute.command('volume [service]').description("Show, attach, grow, or delete a compute service's persistent /data volume. No flag: print size, mount path, and the plan cap (any plan). --size on a volumeless service ATTACHES one (any plan at the default 10Gi, the free cap; larger is paid and plan-capped; the disk mounts at /data on the next deploy); on a volume-bearing one it grows (paid plans; grow-only — a provisioned disk cannot shrink). --delete DESTROYS the disk and ALL its data immediately (no detach, no undo; billing stops now, and suspend fast-wake + scale-out return). Billing is actual data stored — the size is a cap, not a price")
     .option('--size <gi>', 'new size in whole Gi, e.g. 10 (must be ≥ the current size)')
     .option('--delete', 'destroy the volume and ALL its data (irreversible; download anything you need first)')
     .option('--json').option('--branch <branch>', 'branch (default: current)').action(guard((service, o) => computeCmd.computeVolume(service, o)));
@@ -243,7 +244,7 @@ db.command('url').description('Print the postgres connection string (DSN) — ba
 db.command('connect').description("Open an interactive psql session on the postgres service (needs psql on PATH; gated: secrets.read). A suspended instance wakes on connect — the first prompt can take a few seconds. Exits with psql's own exit code")
     .option('--branch <branch>', 'branch (default: current)').option('--group <g>', 'postgres service name (default: the sole/default one)')
     .action(guard((o) => dbCmd.dbConnect(o)));
-db.command('limits').description("Show or set a postgres service's resource ceiling (paid plans; insta-db-backed only). Moves both directions")
+db.command('limits').description("Show or set a postgres service's resource ceiling (any plan within the free cap, paid above it; insta-db-backed only). Moves both directions")
     .option('--cpu <n>', "vCPU ceiling, e.g. 2 or 2500m").option('--memory <size>', "memory ceiling, e.g. 4Gi")
     .option('--json').option('--branch <branch>', 'branch (default: current)').option('--group <g>', 'postgres service name (default: the sole/default one)')
     .action(guard((o) => dbCmd.dbLimits(o)));
@@ -281,12 +282,12 @@ 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)');
+// ---- templates (registry, local insta.template.yaml, or a GitHub URL) ----
+const tpl = program.command('template').description('Browse and deploy app templates (registry, a local dir, or a GitHub URL)');
 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')
+tpl.command('deploy <code-or-dir-or-url>').description('Deploy a template onto a branch — a registry code, a local directory containing insta.template.yaml (a path-looking target is always read as a directory), or a github.com URL (https://github.com/<owner>/<repo>[/tree/<ref>[/<dir>]]) whose manifest is fetched with your own git credentials. 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')

package/dist/template-manifest.js

@@ -78,8 +78,30 @@ export function validateManifest(m) {
     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.type !== 'web' && svc.type !== 'worker' && svc.type !== 'postgres') {
+            problems.push(`${where}.type must be web, worker or postgres`);
+        }
+        // A managed postgres service is BARE: the platform owns its image, port, sizing, credentials
+        // and env, so every other rule below would be asking about fields it must not carry. Mirrors
+        // the platform's own check (provisioning/templateManifest.ts) so an author hears it here.
+        if (svc.type === 'postgres') {
+            const bare = svc;
+            for (const field of ['image', 'build', 'port', 'healthcheck', 'volume', 'volumeGib', 'spec', 'alwaysOn']) {
+                if (bare[field] !== undefined) {
+                    problems.push(`${where}.${field}: a postgres service is platform-managed and carries no ${field} — declare it bare ({ type: postgres })`);
+                }
+            }
+            const groups = ['fixed', 'generated', 'platform', 'required', 'optional'];
+            const envShell = bare.env;
+            if (envShell !== undefined) {
+                const emptyShell = !!envShell && typeof envShell === 'object' && !Array.isArray(envShell)
+                    && Object.entries(envShell).every(([g, v]) => groups.includes(g) && !!v && typeof v === 'object' && !Array.isArray(v) && Object.keys(v).length === 0);
+                if (!emptyShell) {
+                    problems.push(`${where}.env: a postgres service is platform-managed and carries no env — declare it bare ({ type: postgres })`);
+                }
+            }
+            continue;
+        }
         if (svc.image && svc.build)
             problems.push(`${where}: image and build are mutually exclusive`);
         if (!svc.image && !svc.build)

package/package.json

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