insta 0.0.35 → 0.0.37

package/dist/commands/setup.js

@@ -6,12 +6,15 @@
 // Stack skills (tigris/better-auth) intentionally stay per-project: their presence in a
 // project doubles as its stack manifest — that install happens on `project create|link`.
 import { spawn } from 'node:child_process';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join } from 'node:path';
 import os from 'node:os';
 import { ApiClient } from '../api.js';
 import { resolveEnv } from '../config.js';
 import { DEFAULT_ENV, ENVS, mcpServerName } from '../env.js';
 import { info } from '../util.js';
 import { installAgentConfigs } from './mcp.js';
+import { detectChannel } from './upgrade.js';
 // The `skills` tool we shell out to prints a clack UI: a frame-by-frame clone spinner, an
 // "Installing to all N agents" banner, a full N-line install-path box, and a third-party
 // "Security Risk Assessment" that flags our OWN first-party skill as "Critical Risk". Streamed
@@ -76,13 +79,165 @@ export function summarizeInstall(output) {
         : `${count} agent${count === 1 ? '' : 's'}`;
     return `✓ Agent skills — ${list}`;
 }
+// ---- CLI self-install (makes `npx -y insta setup agent` a complete one-liner) ----
+// Under npx the CLI runs from the npm cache and vanishes when the process exits — but the skill
+// installed below tells every agent to run `insta …`, which then wouldn't exist. So when this
+// process came from the npm channel and no DURABLE `insta` is on PATH, install ourselves
+// globally first. The scan must ignore any PATH entry under a node_modules directory: npx
+// prepends its cache's node_modules/.bin (where this very process's `insta` shim lives), while
+// durable installs (npm -g bin, nvm/volta/fnm, the native binary's ~/.insta/bin) never sit
+// under one.
+// On POSIX a PATH hit only counts if it would actually run: a plain non-executable file (or a
+// directory) named `insta` must not suppress the self-install. Mode bits, not access(X_OK) —
+// access() answers "can THIS process exec it", which for root is always yes, so a root-run
+// setup would wrongly treat a non-executable file as a durable install. On Windows execute
+// permission is extension-driven, so existence of a regular file is the right check.
+const isRunnableFile = (p, win) => {
+    try {
+        const st = statSync(p);
+        if (!st.isFile())
+            return false;
+        return win || (st.mode & 0o111) !== 0;
+    }
+    catch {
+        return false;
+    }
+};
+/** Resolve a bare command name to its absolute PATH location (PATHEXT-aware on Windows).
+ *  cmd.exe searches the CURRENT DIRECTORY before PATH for bare names, so handing it a bare
+ *  `claude` would let a claude.cmd planted in the project directory shadow the real CLI —
+ *  the cmd.exe wrapper below only ever passes absolute paths. */
+export function whichOnPath(bin, env = process.env, platform = process.platform) {
+    const win = platform === 'win32';
+    const exts = win ? [...(env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';'), ''] : [''];
+    for (const dir of (env.PATH ?? '').split(win ? ';' : ':')) {
+        if (!dir)
+            continue;
+        for (const ext of exts) {
+            const p = join(dir, bin + ext);
+            if (isRunnableFile(p, win))
+                return p;
+        }
+    }
+    return null;
+}
+export function findDurableOnPath(bin, env = process.env, platform = process.platform) {
+    const win = platform === 'win32';
+    const dirs = (env.PATH ?? '').split(win ? ';' : ':');
+    // npm on Windows writes insta.cmd/insta.ps1 plus an extensionless sh shim; PATHEXT covers the
+    // former, the bare name the latter.
+    const exts = win ? [...(env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';'), ''] : [''];
+    for (const dir of dirs) {
+        // Case-insensitive: Windows paths (and the npx cache) may carry any casing.
+        if (!dir || dir.toLowerCase().includes('node_modules'))
+            continue;
+        for (const ext of exts)
+            if (isRunnableFile(join(dir, bin + ext), win))
+                return true;
+    }
+    return false;
+}
+const cliVersion = () => {
+    try {
+        return JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version;
+    }
+    catch {
+        return 'latest';
+    }
+};
+/** Best-effort: a failed global install must not block the skill/MCP setup below — the npx run
+ *  itself still completes the agent onboarding, and the manual fallback is one line. */
+export async function ensureCliInstalled(run, channel = detectChannel(), onPath = findDurableOnPath('insta'), recheck = () => findDurableOnPath('insta')) {
+    if (channel !== 'npm' || onPath)
+        return;
+    info('installing the insta CLI globally (npm) …');
+    // Pinned to THIS version so the one-liner installs exactly what it ran. The logical `npm` is
+    // resolved to a spawnable invocation ONCE, inside the default runner (resolveSpawnable) —
+    // handing it a pre-resolved node/npm-cli.js path here would make the runner resolve it a
+    // second time and, on Windows, wrap the real node.exe in cmd.exe.
+    const spec = `insta@${cliVersion()}`;
+    const res = await run('npm', ['install', '-g', spec]);
+    if (res.ok) {
+        // A clean `npm i -g` can still land in a bin dir that isn't on PATH (custom npm prefix) —
+        // exactly the machines this path exists for. Only claim success after re-finding the shim.
+        if (recheck()) {
+            info('✓ insta CLI — installed globally (`insta` now works in any shell)');
+        }
+        else {
+            info('✓ insta CLI — installed globally, but npm\'s global bin dir is not on PATH');
+            info('    add it to PATH (POSIX: `$(npm prefix -g)/bin`; Windows: the dir `npm prefix -g` prints), then verify with `insta --version`');
+        }
+        return;
+    }
+    info('  global CLI install failed — continuing with agent setup; install manually with:');
+    info(`    npm install -g ${spec}`);
+    if (/EACCES|permission denied/i.test(res.output ?? '')) {
+        info('    (permission error: the npm prefix is system-owned — use a Node version manager, or elevate that one command)');
+    }
+}
+// ---- Windows-safe spawning for npm/npx ----
+// On Windows `npm`/`npx` are .cmd shims, which spawn() without a shell refuses (Node docs:
+// spawning .bat/.cmd needs a shell or cmd.exe). Rather than a shell (argument-quoting hazards),
+// re-enter them as node scripts: the CLI script named by npm_execpath (swapped between
+// npm-cli.js and npx-cli.js as needed), else the one shipped beside the running node, else the
+// bare name (POSIX, where PATH shims resolve fine). Applied ONCE, inside the default runner,
+// so every `run('npm'|'npx', …)` call site benefits and nothing is ever resolved twice.
+export function resolveSpawnable(cmd, args, npmExecpath = process.env.npm_execpath, execPath = process.execPath, platform = process.platform, env = process.env) {
+    // Node re-entry is only valid when THIS process runs on node. On the native-binary channel
+    // execPath is the compiled `insta` executable — and npm scripts export npm_execpath to their
+    // children — so re-entering blindly would spawn `insta npx-cli.js …`. A non-node execPath
+    // sends npm/npx down the generic shim path below instead.
+    const execIsNode = /(^|[\\/])node(\.exe)?$/i.test(execPath);
+    if ((cmd === 'npm' || cmd === 'npx') && execIsNode) {
+        if (npmExecpath && /(^|[\\/])np[mx](-cli)?\.[cm]?js$/.test(npmExecpath)) {
+            const cli = npmExecpath.replace(/np[mx](-cli)?(\.[cm]?js)$/, `${cmd}$1$2`);
+            if (existsSync(cli))
+                return { cmd: execPath, args: [cli, ...args] };
+        }
+        const nodeDir = dirname(execPath);
+        const besideNode = platform === 'win32'
+            ? join(nodeDir, 'node_modules', 'npm', 'bin', `${cmd}-cli.js`)
+            : join(nodeDir, '..', 'lib', 'node_modules', 'npm', 'bin', `${cmd}-cli.js`);
+        if (existsSync(besideNode))
+            return { cmd: execPath, args: [besideNode, ...args] };
+    }
+    // Generic shim path — every non-npm CLI we shell out to (claude), plus npm/npx themselves
+    // when node isn't resolvable (native binary channel). On Windows these are .cmd shims, which
+    // spawn() refuses without a shell, so route them through cmd.exe. Guards, in order:
+    // - BARE names only: an absolute path or anything .exe (node.exe from a resolved npm/npx
+    //   invocation passing back through here) is directly spawnable and must NOT see cmd.exe.
+    // - The name is resolved to its ABSOLUTE PATH location first: cmd.exe searches the current
+    //   directory before PATH, so a bare name would let a shim planted in the project dir
+    //   shadow the real CLI. No PATH hit → pass through (spawn fails; callers degrade).
+    // - No manual quoting: libuv already wraps spaced args when building the child command
+    //   line — pre-quoting would be quoted AGAIN and arrive as literal quote characters.
+    // - That leaves cmd.exe metacharacters unprotectable, so an arg carrying one (e.g. a
+    //   custom INSTA_MCP_URL with `&`) skips the wrapper: the bare-shim spawn fails and every
+    //   caller degrades gracefully (probe → not-installed; registration → manual-add
+    //   fallback). Never hand metacharacters to a shell.
+    const bareShim = !/[\\/]/.test(cmd) && !/\.exe$/i.test(cmd);
+    if (platform === 'win32' && bareShim && !args.some((a) => /[&|<>^%"]/.test(a))) {
+        const abs = whichOnPath(cmd, env, platform);
+        if (abs)
+            return { cmd: 'cmd.exe', args: ['/d', '/s', '/c', abs, ...args] };
+    }
+    return { cmd, args };
+}
 // Capture stdout+stderr silently (don't stream) so we can print our own clean summary.
 // stdin is 'ignore', NOT 'inherit': under the canonical `curl … | sh` install, stdin is the
 // piped install script itself — a child that inherits it (npx/skills reads for keypresses even
 // with -y) consumes the rest of the script, so the shell never runs the trailing "Get started"
 // guidance. Ignoring stdin keeps the installer's own output intact. (-y means no prompt anyway.)
-const defaultRunner = (cmd, args) => new Promise((resolve) => {
+const defaultRunner = (cmdIn, argsIn) => new Promise((resolve) => {
+    const { cmd, args } = resolveSpawnable(cmdIn, argsIn);
     const env = { ...process.env, AI_AGENT: process.env.AI_AGENT || 'insta', FORCE_COLOR: '0' };
+    // When THIS process was launched by npx, npx exports its flags as npm_config_* env vars.
+    // npm_config_package pins package resolution for every nested npm/npx child — the inner
+    // `npx -y skills …` would then resolve `skills` against the insta package and degrade to
+    // `sh: skills: command not found`. Scrub the resolution-pinning vars; keep prefix/registry
+    // (deliberate user configuration).
+    delete env.npm_config_package;
+    delete env.npm_config_call;
     const p = spawn(cmd, args, { stdio: ['ignore', 'pipe', 'pipe'], env });
     let output = '';
     const grab = (chunk) => { output += chunk.toString(); };
@@ -91,11 +246,14 @@ const defaultRunner = (cmd, args) => new Promise((resolve) => {
     p.on('error', () => resolve({ ok: false, output }));
     p.on('close', (code) => resolve({ ok: code === 0, output }));
 });
+// Leading -y is npx's OWN flag: on a machine where the `skills` package isn't already in the
+// npx cache, non-TTY `npx skills …` refuses to auto-install and degrades to a shell lookup
+// (`sh: skills: command not found`) — the trailing -y only answers the skills TOOL's prompt.
 // -g = user-level (machine-global); -a '*' = every agent dir the skills tool supports
 // (Claude Code, Codex, Cursor, OpenCode, Copilot, …); --copy = real files, not cache symlinks.
 // `spec` is the skill source for the resolved environment (`owner/repo` or `owner/repo@ref`), so a
 // staging install reads the staging skill text rather than what's published on main.
-export const setupArgs = (spec) => ['skills', 'add', spec, '-s', 'insta', '-a', '*', '-g', '-y', '--copy'];
+export const setupArgs = (spec) => ['-y', 'skills', 'add', spec, '-s', 'insta', '-a', '*', '-g', '-y', '--copy'];
 /** Production's args. Kept as a named export because it is the installed-base default and is
  *  asserted directly by tests; runtime goes through `setupArgs(resolveEnv().skills)`. */
 export const SETUP_ARGS = setupArgs(ENVS[DEFAULT_ENV].skills);
@@ -158,10 +316,13 @@ export async function registerMcp(run = defaultRunner, mint = defaultMinter, use
         info(`  MCP registration failed — add manually:\n    claude mcp add --transport http ${name} ${url}`);
     }
 }
-export async function setupAgent(opts, run = defaultRunner, mint, installConfigs = installAgentConfigs) {
+export async function setupAgent(opts, run = defaultRunner, mint, installConfigs = installAgentConfigs, ensure = (r) => ensureCliInstalled(r)) {
     if (!opts.yes && !process.stdout.isTTY) {
         info('non-interactive shell — assuming -y');
     }
+    // BEFORE the skill install: the skill tells agents to run `insta …`, so a durable CLI must
+    // exist by the time it lands.
+    await ensure(run);
     // One resolve for the whole step, so the skills and the MCP registration below cannot disagree
     // about which environment this machine belongs to.
     const { env, skills } = await resolveEnv();

package/dist/commands/storage.js

@@ -50,7 +50,7 @@ export async function storageList(opts) {
     const branch = opts.branch ?? p.branch;
     const svc = await storageTarget(api, p.projectId, branch, opts.service);
     const res = await api.rawRequest('GET', objectsPath(p.projectId, svc.id, { branch, prefix: opts.prefix, cursor: opts.cursor, limit }));
-    if (handleApproval(res))
+    if (handleApproval(res, opts.json))
         return;
     if (opts.json)
         return printJson(res.body);
@@ -143,7 +143,7 @@ export async function storageGet(key, opts, deps = {}) {
     const branch = opts.branch ?? p.branch;
     const svc = await storageTarget(api, p.projectId, branch, opts.service);
     const res = await api.rawRequest('GET', objectDownloadPath(p.projectId, svc.id, { branch, key }));
-    if (handleApproval(res))
+    if (handleApproval(res, opts.json))
         return;
     // --json hands over the presigned URL instead of downloading, as `insta secrets --json` does.
     // Before outputPath, so a key with no filename still works when nothing is written to disk.
@@ -164,7 +164,7 @@ export async function storageDelete(key, opts) {
     const branch = opts.branch ?? p.branch;
     const svc = await storageTarget(api, p.projectId, branch, opts.service);
     const res = await api.rawRequest('DELETE', objectsPath(p.projectId, svc.id, { branch, key }));
-    if (handleApproval(res))
+    if (handleApproval(res, opts.json))
         return;
     if (opts.json)
         return printJson(res.body);

package/dist/ensure-skills.js

@@ -9,6 +9,7 @@ import { spawn } from 'node:child_process';
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { resolveEnv } from './config.js';
+import { resolveSpawnable } from './commands/setup.js';
 import { DEFAULT_ENV, ENVS } from './env.js';
 // Where `npx skills add` drops skills for the agents we pin below: Claude Code → .claude/skills/,
 // Codex → .agents/skills/ (.github/skills/ is the third well-known dir). These are regenerable
@@ -20,8 +21,15 @@ const SKILL_DIRS = ['.claude/skills/', '.agents/skills/', '.github/skills/'];
 // honest here (this IS programmatic, not an interactive prompt) and, because we already pin the
 // agents/skills/-y, has no effect on the install beyond quieting the banner. Preserve a caller's
 // existing AI_AGENT (e.g. running inside another agent) rather than clobbering it.
-const defaultRunner = (cmd, args, inherit = false) => new Promise((resolve) => {
+const defaultRunner = (cmdIn, argsIn, inherit = false) => new Promise((resolve) => {
+    // resolveSpawnable: on Windows `npx` is a .cmd shim spawn() refuses without a shell —
+    // re-enter npm's CLI script via node instead (same treatment as `insta setup agent`).
+    const { cmd, args } = resolveSpawnable(cmdIn, argsIn);
     const env = { ...process.env, AI_AGENT: process.env.AI_AGENT || 'insta' };
+    // npx exports its flags as npm_config_* to children; npm_config_package would pin the inner
+    // `npx -y skills …` to whatever package launched this CLI (see setup.ts defaultRunner).
+    delete env.npm_config_package;
+    delete env.npm_config_call;
     const p = spawn(cmd, args, { stdio: inherit ? 'inherit' : 'ignore', env });
     p.on('error', () => resolve({ ok: false })); // e.g. npx not on PATH
     p.on('close', (code) => resolve({ ok: code === 0 }));
@@ -31,17 +39,21 @@ const defaultRunner = (cmd, args, inherit = false) => new Promise((resolve) => {
 // name the exact skills (-s …) so there's no skill picker; -y to skip the scope/confirm prompt;
 // --copy to write real files (not symlinks into a transient npx cache).
 const AGENT_FLAGS = ['-a', 'claude-code', '-a', 'codex', '-y', '--copy'];
+// npx's OWN -y, distinct from the skills tool's -y above: without it, a machine whose npx cache
+// lacks the `skills` package refuses the auto-install in non-TTY runs and the whole command
+// degrades to `sh: skills: command not found`.
+const NPX_YES = ['-y'];
 // `instaSpec` is the insta skill source for the resolved environment (`owner/repo[@ref]`), so a
 // project created against staging gets the staging skill text. The third-party stack skills are
 // environment-independent — they document Tigris/Better Auth, not our control plane.
 const skillTargets = (instaSpec) => [
-    { label: 'insta', args: ['skills', 'add', instaSpec, '-s', 'insta', ...AGENT_FLAGS] },
-    { label: 'tigris', args: ['skills', 'add', 'tigrisdata/skills',
+    { label: 'insta', args: [...NPX_YES, 'skills', 'add', instaSpec, '-s', 'insta', ...AGENT_FLAGS] },
+    { label: 'tigris', args: [...NPX_YES, 'skills', 'add', 'tigrisdata/skills',
             '-s', 'tigris-object-operations', '-s', 'file-storage', '-s', 'tigris-sdk-guide',
             '-s', 'tigris-security-access-control', '-s', 'tigris-image-optimization',
             '-s', 'tigris-s3-migration', '-s', 'tigris-static-assets', '-s', 'tigris-agent-kit',
             ...AGENT_FLAGS] },
-    { label: 'better-auth', args: ['skills', 'add', 'better-auth/skills',
+    { label: 'better-auth', args: [...NPX_YES, 'skills', 'add', 'better-auth/skills',
             '-s', 'better-auth-best-practices', '-s', 'email-and-password-best-practices',
             '-s', 'better-auth-security-best-practices', ...AGENT_FLAGS] },
 ];

package/dist/flyctl-build.js

@@ -4,17 +4,21 @@
 import { spawn } from 'node:child_process';
 import { existsSync, writeFileSync, unlinkSync } from 'node:fs';
 import { join } from 'node:path';
-import { info } from './util.js';
 // Spawn flyctl, tee its output to the user (so they see buildkit progress) AND capture it for digest
-// parsing.
-export const defaultBuildRunner = (cmd, args, opts) => new Promise((resolve) => {
-    const child = spawn(cmd, args, { cwd: opts.cwd, env: opts.env, stdio: ['inherit', 'pipe', 'pipe'] });
-    let output = '';
-    child.stdout?.on('data', (b) => { const s = b.toString(); output += s; process.stdout.write(s); });
-    child.stderr?.on('data', (b) => { const s = b.toString(); output += s; process.stderr.write(s); });
-    child.on('error', (err) => resolve({ code: -1, output: `${output}\n${err.message}` }));
-    child.on('close', (code) => resolve({ code: code ?? -1, output }));
-});
+// parsing. `to` picks the tee destination for the child's stdout: `deploy --json` reserves the
+// process's stdout for the final JSON document, so it tees build progress to stderr instead.
+function teeRunner(to) {
+    return (cmd, args, opts) => new Promise((resolve) => {
+        const child = spawn(cmd, args, { cwd: opts.cwd, env: opts.env, stdio: ['inherit', 'pipe', 'pipe'] });
+        let output = '';
+        child.stdout?.on('data', (b) => { const s = b.toString(); output += s; to.write(s); });
+        child.stderr?.on('data', (b) => { const s = b.toString(); output += s; process.stderr.write(s); });
+        child.on('error', (err) => resolve({ code: -1, output: `${output}\n${err.message}` }));
+        child.on('close', (code) => resolve({ code: code ?? -1, output }));
+    });
+}
+export const defaultBuildRunner = teeRunner(process.stdout);
+export const stderrBuildRunner = teeRunner(process.stderr);
 // buildkit prints "pushing manifest for registry.fly.io/<app>:<label>@sha256:<digest>" on push.
 // Pin to the digest — the bare tag races on Fly's registry (MANIFEST_UNKNOWN); the digest always resolves.
 export function parseImageDigest(output, flyApp) {
@@ -57,10 +61,13 @@ export async function flyctlBuildAndPush(opts, run = defaultBuildRunner) {
     }
 }
 // Best-effort: ensure the fly CLI is available (needed for source-directory deploys). Never blocks —
-// if it can't be installed the subsequent build surfaces a clear error.
+// if it can't be installed the subsequent build surfaces a clear error. Everything here is one-time
+// bootstrap DIAGNOSTICS, so it all goes to stderr — including the installers' own stdout (fd 2 in
+// the stdio triple) — keeping stdout clean for `deploy --json`.
 export async function ensureFlyctl() {
+    const note = (m) => process.stderr.write(m + '\n');
     const ok = (cmd, args, inherit = false) => new Promise((resolve) => {
-        const p = spawn(cmd, args, { stdio: inherit ? 'inherit' : 'ignore' });
+        const p = spawn(cmd, args, { stdio: inherit ? ['inherit', 2, 2] : 'ignore' });
         p.on('error', () => resolve(false));
         p.on('close', (code) => resolve(code === 0));
     });
@@ -68,8 +75,8 @@ export async function ensureFlyctl() {
         if (await ok('flyctl', ['version']))
             return;
         if (process.platform === 'darwin' && (await ok('brew', ['--version']))) {
-            info('flyctl not found — installing with `brew install flyctl` (one-time)…');
-            info((await ok('brew', ['install', 'flyctl'], true)) ? 'flyctl installed ✓' : 'flyctl install failed — install manually: https://fly.io/docs/flyctl/install/');
+            note('flyctl not found — installing with `brew install flyctl` (one-time)…');
+            note((await ok('brew', ['install', 'flyctl'], true)) ? 'flyctl installed ✓' : 'flyctl install failed — install manually: https://fly.io/docs/flyctl/install/');
             return;
         }
         if (process.platform === 'linux') {
@@ -77,20 +84,20 @@ export async function ensureFlyctl() {
             // and no brew; without this branch `insta deploy <dir>` dead-ends on a hand-install of a
             // third-party CLI. Official installer, pinned into ~/.fly; the current process extends its
             // own PATH because the installer's shell-profile edit can't reach an already-running process.
-            info('flyctl not found — installing to ~/.fly (one-time)…');
+            note('flyctl not found — installing to ~/.fly (one-time)…');
             const flyHome = `${process.env.HOME ?? '~'}/.fly`;
             const installed = await ok('sh', ['-c', `curl -fsSL https://fly.io/install.sh | FLYCTL_INSTALL="${flyHome}" sh`], true);
             if (installed) {
                 process.env.PATH = `${process.env.PATH}:${flyHome}/bin`;
                 if (await ok('flyctl', ['version'])) {
-                    info('flyctl installed ✓');
+                    note('flyctl installed ✓');
                     return;
                 }
             }
-            info('flyctl install failed — install manually: https://fly.io/docs/flyctl/install/');
+            note('flyctl install failed — install manually: https://fly.io/docs/flyctl/install/');
             return;
         }
-        info('flyctl (fly CLI) not found — install it to deploy from source: https://fly.io/docs/flyctl/install/');
+        note('flyctl (fly CLI) not found — install it to deploy from source: https://fly.io/docs/flyctl/install/');
     }
     catch { /* best-effort convenience */ }
 }

package/dist/index.js

@@ -17,6 +17,7 @@ import { resolveServiceArgs, serviceArgsDeps } from './resolve-service.js';
 import * as regions from './commands/regions.js';
 import * as secretsCmd from './commands/secrets.js';
 import { deploy } from './commands/deploy.js';
+import { build } from './commands/build.js';
 import * as computeCmd from './commands/compute.js';
 import * as dbCmd from './commands/db.js';
 import * as storageCmd from './commands/storage.js';
@@ -73,7 +74,7 @@ const envCmd = program.command('env').description('Show or switch the deployment
 envCmd.command('show', { isDefault: true }).description('Show the current environment and its hosts')
     .option('--json').action(guard((o) => envCmd_.envShow(o)));
 envCmd.command('use <name>').description(`Switch environment (${ENV_NAMES.join(' | ')}) — drops the stored session, which is deployment-specific`)
-    .action(guard((name) => envCmd_.envUse(name)));
+    .option('--json').action(guard((name, o) => envCmd_.envUse(name, o)));
 // ---- run (per-request secret injection — nothing written to disk) ----
 program.command('run <cmd> [args...]').description('Run a command with the branch credential bundle injected into its environment (no .env written)')
     .option('--branch <b>', 'branch bundle to inject (default: linked branch)')
@@ -81,7 +82,7 @@ program.command('run <cmd> [args...]').description('Run a command with the branc
     .action(guard((cmd, args, o) => runCmd.run([cmd, ...(args ?? [])], o)));
 // ---- agent setup (the `curl … | sh --agents` target) ----
 const setupCmd = program.command('setup').description('Set up this machine for InstaCloud agent workflows');
-setupCmd.command('agent').description('Install the insta skill user-globally for all coding agents')
+setupCmd.command('agent').description('Install the insta CLI (if missing), the insta skill for all coding agents, and the MCP server')
     .option('-y, --yes', 'non-interactive')
     .option('--mcp-token', 'register the MCP server with a minted insta_ API token instead of OAuth (headless machines / CI)')
     .action(guard((o) => setup.setupAgent(o)));
@@ -94,29 +95,29 @@ mcpCmd.command('install').description('Register the remote MCP server with codin
 // ---- org ----
 const orgCmd = program.command('org').description('Manage organizations');
 orgCmd.command('list').option('--json').action(guard((o) => org.orgList(o)));
-orgCmd.command('create <name>').action(guard((name) => org.orgCreate(name)));
+orgCmd.command('create <name>').option('--json').action(guard((name, o) => org.orgCreate(name, o)));
 // ---- project ----
 const pj = program.command('project').description('Manage projects');
-pj.command('create [name]').option('--org <id>', 'org to create under (default: personal)').action(guard((name, o) => project.projectCreate(name, o)));
+pj.command('create [name]').option('--org <id>', 'org to create under (default: personal)').option('--json').action(guard((name, o) => project.projectCreate(name, o)));
 pj.command('list').option('--org <id>').option('--json').action(guard((o) => project.projectList(o)));
-pj.command('link <id>').description('Link a project to this directory').action(guard((id) => project.projectLink(id)));
-pj.command('delete').option('--project <id>').action(guard((o) => project.projectDelete(o)));
+pj.command('link <id>').description('Link a project to this directory').option('--json').action(guard((id, o) => project.projectLink(id, o)));
+pj.command('delete').option('--project <id>').option('--json').action(guard((o) => project.projectDelete(o)));
 // ---- branch ----
 const br = program.command('branch').description('Manage branch environments');
-br.command('create <name>').option('--from <branch>', 'parent branch (default: current)').action(guard((name, o) => branch.branchCreate(name, o)));
+br.command('create <name>').option('--from <branch>', 'parent branch (default: current)').option('--json').action(guard((name, o) => branch.branchCreate(name, o)));
 br.command('list').option('--json').action(guard((o) => branch.branchList(o)));
-br.command('switch <name>').action(guard((name) => branch.branchSwitch(name)));
-br.command('delete <name>').action(guard((name) => branch.branchDelete(name)));
+br.command('switch <name>').option('--json').action(guard((name, o) => branch.branchSwitch(name, o)));
+br.command('delete <name>').option('--json').action(guard((name, o) => branch.branchDelete(name, o)));
 br.command('merge <source>').description('Merge a branch service set into another (structural, no data)')
-    .option('--into <branch>', 'target branch (default: current)').action(guard((source, o) => branch.branchMerge(source, o)));
-// ---- services (opt-in postgres/storage/compute/redis) ----
-const svc = program.command('services').alias('svc').description('Manage project services (postgres|storage|compute|redis)');
+    .option('--into <branch>', 'target branch (default: current)').option('--json').action(guard((source, o) => branch.branchMerge(source, o)));
+// ---- services (opt-in postgres/storage/compute/redis/mysql/mongodb) ----
+const svc = program.command('services').alias('svc').description('Manage project services (postgres|storage|compute|redis|mysql|mongodb)');
 // [type] [name] are optional so the command can answer "what can I add?" — a terminal is walked
 // through the dashboard's Add Service kinds, anything else gets that list back as an error
 // (resolve-service.ts). Picking Docker Image also fills in --image/--port from the answers.
 svc.command('add [type] [name]').description('Provision a service on demand (assigns a default domain for postgres/compute); with no type/name, a terminal picks from the service kinds')
     .option('--branch <branch>', 'target branch (default: current)')
-    .option('--region <region>', 'region for postgres/compute/redis, e.g. us-east (see `insta regions`)')
+    .option('--region <region>', 'region for postgres/compute/managed databases, e.g. us-east (see `insta regions`)')
     .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)')
@@ -130,7 +131,7 @@ svc.command('add [type] [name]').description('Provision a service on demand (ass
 svc.command('list').option('--json').option('--branch <branch>', 'branch (default: current)')
     .action(guard((o) => services.servicesList(o)));
 svc.command('remove <type> <name>').description('Remove a service and destroy its resources')
-    .option('--branch <branch>', 'branch (default: current)')
+    .option('--branch <branch>', 'branch (default: current)').option('--json')
     .action(guard((type, name, o) => services.servicesRemove(type, name, o)));
 svc.command('rename <type> <name> <new-name>').description('Rename a service and re-key its managed secret names')
     .option('--json').option('--branch <branch>', 'branch (default: current)')
@@ -150,16 +151,47 @@ const sec = program.command('secrets').description('Fetch the credential bundle
 sec.command('list').description('List secret names, grouped by service').option('--branch <branch>').option('--json').action(guard((o) => secretsCmd.secretsList(o)));
 sec.command('set <name> [value]').description('Set a user secret (project-wide; value from stdin if omitted)')
     .option('--branch <branch>', 'scope to one branch').option('--service <type/name>', 'bind to a branch service (implies current branch)')
-    .action(guard((n, v, o) => secretsCmd.secretsSet(n, v, o)));
+    .option('--json').action(guard((n, v, o) => secretsCmd.secretsSet(n, v, o)));
 sec.command('unset <name>').description('Remove a user secret')
-    .option('--branch <branch>', 'scope to one branch').action(guard((n, o) => secretsCmd.secretsUnset(n, o)));
+    .option('--branch <branch>', 'scope to one branch').option('--json').action(guard((n, o) => secretsCmd.secretsUnset(n, o)));
+sec.command('bind <env-name> <source>').description('Bind a service credential into a compute env var')
+    .option('--branch <branch>', 'branch (default: current)')
+    .option('--to <compute-service>', 'target compute service, e.g. compute/api')
+    .option('--source-name <name>', 'source credential name when the source exposes more than one')
+    .option('--json')
+    .action(guard((n, source, o) => secretsCmd.secretsBind(n, source, o)));
+sec.command('unbind <env-name>').description('Remove a service credential binding from a compute env var')
+    .option('--branch <branch>', 'branch (default: current)')
+    .option('--from <compute-service>', 'target compute service, e.g. compute/api')
+    .option('--json')
+    .action(guard((n, o) => secretsCmd.secretsUnbind(n, o)));
+sec.command('bindings').description('List service credential bindings for a compute service')
+    .option('--branch <branch>', 'branch (default: current)')
+    .option('--target <compute-service>', 'target compute service, e.g. compute/api')
+    .option('--json')
+    .action(guard((o) => secretsCmd.secretsBindings(o)));
+sec.command('sources').description('List service credential sources available for binding')
+    .option('--branch <branch>', 'branch (default: current)')
+    .option('--json')
+    .action(guard((o) => secretsCmd.secretsSources(o)));
 sec.command('tree').description('Show secrets as project → branch → service → secrets').option('--json')
     .action(guard((o) => secretsCmd.secretsTree(o)));
+// ---- build (pre-push verification — local, offline, deploys nothing) ----
+program.command('build [dir]').description('Verify a source directory would build before deploying: detection plan + the Dockerfile that would be used (yours, or nixpacks-generated) + static checks. Local and offline — no login needed, nothing pushed. Exit 1 when the verdict is failed')
+    .option('--explain', 'include the Dockerfile content in the output')
+    .option('--port <p>', 'port the app listens on (else the Dockerfile EXPOSE)')
+    .option('--json')
+    .action(guard((dir, o) => build(dir, o)));
 // ---- deploy ----
 program.command('deploy [dir]').description('Deploy a source directory (built remotely on Fly) 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>')
     .option('--websocket', 'run a WebSocket app (larger guest + connection-based concurrency)')
+    .option('--json', 'print the deploy result as JSON (build progress goes to stderr)')
     .action(guard((dir, o) => deploy(dir, o)));
+// `insta compute exec` needs the command verbatim after a literal `--`; split it out of argv here,
+// before commander parses anything (see splitExecArgs's own comment for why `service` being
+// optional makes commander unable to hold that boundary itself).
+const { argv: computeArgv, command: execCommand } = computeCmd.splitExecArgs(process.argv);
 // ---- compute (lifecycle control + custom domains) ----
 const compute = program.command('compute').description('Control compute lifecycle (start/stop/suspend/status) + custom domains');
 compute.command('set-domain <host>').description('Attach a custom domain to a branch compute service (gated: deploy)')
@@ -167,7 +199,7 @@ compute.command('set-domain <host>').description('Attach a custom domain to a br
 compute.command('check-domain <host>').description("Show a custom domain's cert status + required DNS records")
     .option('--branch <b>').option('--group <g>').option('--json').action(guard((host, o) => computeCmd.checkDomain(host, o)));
 compute.command('remove-domain <host>').description('Detach a custom domain (gated: deploy)')
-    .option('--branch <b>').option('--group <g>').action(guard((host, o) => computeCmd.removeDomain(host, o)));
+    .option('--branch <b>').option('--group <g>').option('--json').action(guard((host, o) => computeCmd.removeDomain(host, o)));
 compute.command('start [service]').description('Bring a compute service online (persistent — re-enables auto-wake)')
     .option('--json').option('--branch <branch>', 'branch (default: current)').action(guard((service, o) => computeCmd.computeStart(service, o)));
 compute.command('stop [service]').description('Take a compute service offline; traffic will NOT wake it until `start`')
@@ -181,6 +213,9 @@ compute.command('limits [service]').description("Show or set a compute service's
     .option('--json').option('--branch <branch>', 'branch (default: current)').action(guard((service, o) => computeCmd.computeLimits(service, o)));
 compute.command('always-on <mode> [service]').description('Set a compute service always-on (mode: on|off). on = machines never scale to zero; off = default scale-to-zero. All plans; billing is actual usage either way')
     .option('--json').option('--branch <branch>', 'branch (default: current)').action(guard((mode, service, o) => computeCmd.computeAlwaysOn(mode, service, o)));
+compute.command('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)")
+    .option('--branch <b>').option('--timeout <sec>', 'command timeout in seconds, 1-180 (platform default: 30)').option('--json')
+    .action(guard((service, o) => computeCmd.computeExec(service, execCommand, o)));
 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")
     .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)')
@@ -225,11 +260,14 @@ program.command('manifest').description('Print an agent-legible view of the proj
 // ---- regions ----
 program.command('regions').description('List regions available for postgres/compute services').option('--json').action(guard((o) => regions.regionsList(o)));
 // ---- observability ----
-program.command('metrics <target> [group]').description('Service metrics (target: db|compute)')
+program.command('metrics <target> [group]').description('Service metrics (target: db|compute|redis|mysql|mongodb)')
     .option('--branch <b>').option('--from <unix>').option('--to <unix>').option('--step <s>').option('--json')
     .action(guard((target, group, o) => obs.metrics(target, group, o)));
-program.command('logs <target> [group]').description('Service logs (runtime by default; --deploy = compute deploy events; target: db|compute)')
-    .option('--branch <b>').option('--limit <n>').option('--region <r>').option('--instance <i>').option('--deploy', 'show compute deploy events (machine lifecycle) instead of runtime logs').option('--json')
+program.command('logs <target> [group]').description('Service logs (runtime by default; --deploy = machine lifecycle events; target: db|compute|redis|mysql|mongodb)')
+    .option('--branch <b>').option('--limit <n>').option('--region <r>').option('--instance <i>').option('--deploy', 'show deploy events (machine lifecycle) instead of runtime logs — Fly-backed targets only, not db').option('--json')
+    .option('--from <t>', 'window start: unix seconds or ISO-8601 — pages history (~7-day retention); without a window one recent provider page (~100 lines) is returned')
+    .option('--to <t>', 'window end: unix seconds or ISO-8601 (default: now)')
+    .option('--since <dur>', 'relative window start, e.g. 90s, 30m, 2h, 1d (shorthand for --from now-dur)')
     .action(guard((target, group, o) => obs.logs(target, group, o)));
 program.command('usage').description('Usage for the current billing cycle by billing dimension (org by default; --proj for one project)')
     .option('--from <unix>').option('--to <unix>').option('--proj [id]', 'show one project (the linked one, or a given id) instead of the whole org').option('--json')
@@ -248,8 +286,8 @@ program.command('events').description('Show the audit + agent-event timeline').o
 // ---- approvals ----
 const ap = program.command('approvals').description('Governance approvals (HITL)');
 ap.command('list').option('--status <s>', 'pending|granted|denied|consumed').option('--json').action(guard((o) => govern.approvalsList(o)));
-ap.command('approve <id>').option('--always', 'also set the policy to allow').action(guard((id, o) => govern.approvalsApprove(id, o)));
-ap.command('deny <id>').action(guard((id) => govern.approvalsDeny(id)));
+ap.command('approve <id>').option('--always', 'also set the policy to allow').option('--json').action(guard((id, o) => govern.approvalsApprove(id, o)));
+ap.command('deny <id>').option('--json').action(guard((id, o) => govern.approvalsDeny(id, o)));
 // ---- observe (local credential audit) ----
 const ob = program.command('observe').description('Local credential-audit hook');
 ob.command('install').description('Install the PostToolUse hook into this project').action(guard(() => observe.observeInstall()));
@@ -259,7 +297,7 @@ ob.command('sync').description('Upload findings into the project timeline').acti
 // ---- policy ----
 const pol = program.command('policy').description('Governance policy');
 pol.command('get').option('--json').action(guard((o) => govern.policyGet(o)));
-pol.command('set <action> <decision>').description('action: secrets.read|secrets.write|deploy|project.delete|branch.delete|service.add|service.remove|service.scale|service.upgrade|service.setAccess|storage.read|storage.write|storage.delete; decision: allow|deny|approve').action(guard((a, d) => govern.policySet(a, d)));
+pol.command('set <action> <decision>').description('action: secrets.read|secrets.write|deploy|project.delete|branch.delete|service.add|service.remove|service.scale|service.upgrade|service.setAccess|storage.read|storage.write|storage.delete; decision: allow|deny|approve').option('--json').action(guard((a, d, o) => govern.policySet(a, d, o)));
 // ---- feedback (agent + human hurdle reports → the InstaCloud team) ----
 program.command('feedback')
     .description('Report an InstaCloud-side hurdle (bug / missing feature / friction) to the InstaCloud team — about the insta toolkit itself, NEVER about the app you are building. Works logged-out and unlinked.')
@@ -284,5 +322,5 @@ program.command('autoupdate [mode]').description('Show or set auto-update: on |
     .action(guard((mode) => selfUpdate.autoupdate(mode)));
 program.command('__update-check', { hidden: true }).action(guard(() => selfUpdate.backgroundCheck()));
 selfUpdate.maybeUpdate(resolveVersion(), process.argv);
-program.parseAsync(process.argv);
+program.parseAsync(computeArgv);
 //# sourceMappingURL=index.js.map