insta 0.0.64 → 0.0.65

package/README.md

@@ -119,6 +119,14 @@ only. Provider-minted service credentials (`DATABASE_URL`, `BUCKET_NAME`,
 `insta secrets bind` rules, and the postgres connection string is read directly with
 `insta db url` (or `insta db connect` for a psql session).
 
+Secrets can be scoped per compute service, so several services may each define the same name — and
+a flat bundle cannot carry two values for one name. Such a name is **withheld** from the bundle and
+reported on stderr (which services define it, and how to read one). `insta run` then **refuses to
+start the command** rather than let it inherit a stale value for that name from your shell; re-run
+it as `insta run --service compute/<name>` to inject exactly what that one service receives, or
+`--ignore-collisions` to run with the name removed from the child environment altogether.
+`insta secrets --service compute/<name>` reads the same scoped env into `.env`.
+
 ### Destructive actions can require approval
 
 Agent requests are governed by the project's `agent-policy`; human requests use normal RBAC.

package/dist/commands/deploy.js

@@ -71,7 +71,8 @@ export async function deploy(dir, opts) {
     }
     const effOpts = { ...opts, port: port?.toString() };
     const image = dir ? await buildFromSource(api, p.projectId, dir, branch, effOpts) : opts.image;
-    const res = await api.rawRequest('POST', `/projects/${p.projectId}/deploy`, deployRequestBody(image, branch, effOpts));
+    const res = await api.rawRequest('POST', `/projects/${p.projectId}/deploy`, deployRequestBody(image, branch, effOpts))
+        .catch((e) => { throw e instanceof ApiError && e.status === 409 ? new ApiError(e.status, repoConnectedHint(e.message), e.body) : e; });
     if (handleApproval(res, opts.json))
         return;
     if (opts.json)
@@ -79,6 +80,11 @@ export async function deploy(dir, opts) {
     info(`deployed ${image} -> ${res.body.url} (branch ${res.body.branch}, group ${res.body.group})`);
     renderNextActions(res.body.nextActions);
 }
+// The platform refuses an image deploy onto a repo-connected service and names the body field it
+// wants; a CLI user can only pass the flag. Pure, so it's unit-tested.
+export function repoConnectedHint(message) {
+    return message.replace(/pass replaceSource: true/g, 'pass --replace-source');
+}
 // The local image tag a daemon-side deploy runs: unique per build so a redeploy replaces, and
 // legible in `docker images`. Pure, so it's unit-tested.
 export function localImageTag(projectId, group, now = Date.now()) {

package/dist/commands/run.js

@@ -4,16 +4,93 @@
 // as the process does.
 import { spawn } from 'node:child_process';
 import { ApiClient, requireProject } from '../api.js';
-import { CliExit, die, handleApproval, relayExitCode } from '../util.js';
+import { CliExit, die, refuse, relayExitCode } from '../util.js';
+import { assertServiceRef, branchHint, collisionLines, fetchSecretBundle } from './secrets.js';
+/** The bundle read, as run does it: the same GET as `insta secrets`, general or --service. */
+export function bundleFetcher(api, projectId, opts) {
+    return async () => {
+        const b = await fetchSecretBundle(api, projectId, opts);
+        if (!b)
+            throw new CliExit(); // gated (202): handleApproval already said how to unblock it
+        return b;
+    };
+}
+/** The child's environment: the parent's, plus the bundle, MINUS every colliding name.
+ *  Deleting is not belt-and-braces. A withheld name is simply ABSENT from the bundle, so the
+ *  spread would let the parent's own export stand in for it — the developer who once exported
+ *  codex's password would run hermes' command against it, with no sign anything was withheld.
+ *
+ *  Windows needs more than an exact-key delete, for both halves. Env names there are
+ *  case-insensitive; a plain JS object's keys are not, so this object can hold `Database_Url` from
+ *  the shell and `DATABASE_URL` from the bundle as two keys for one variable — and CreateProcess,
+ *  which does collapse them, picks. That makes a stale shell export able to beat the injected
+ *  credential, which is the whole point of `insta run`, not just a hazard for a colliding name.
+ *  So on win32 every name we DECIDE — injected or withheld — wins over whatever casings the parent
+ *  had: the parent's are removed, then the bundle's own casing is written back. Off win32 nothing
+ *  changes: POSIX names really are case-sensitive, so `Database_Url` there is a different variable
+ *  that is none of our business, and collapsing the two would itself be the bug. */
+export function childEnv(parent, bundle, collisions, platform = process.platform) {
+    const withheld = new Set(collisions.map((c) => c.name.toLowerCase()));
+    if (platform === 'win32') {
+        const env = { ...parent };
+        // Every name this run decides, whether it ends up injected or withheld.
+        const claimed = new Set([...Object.keys(bundle), ...collisions.map((c) => c.name)].map((n) => n.toLowerCase()));
+        for (const key of Object.keys(env))
+            if (claimed.has(key.toLowerCase()))
+                delete env[key];
+        // A withheld name stays gone in every casing — including one the bundle itself carried, which
+        // is a platform that answered `collisions` while still merging the values.
+        //
+        // defineProperty, not `env[k] = v`: a key of `__proto__` would otherwise set the prototype
+        // instead of creating an entry, and the secret would vanish silently. The platform's name rule
+        // (`^[A-Z][A-Z0-9_]{0,63}$`) makes that unreachable today — and that is exactly why it is worth
+        // one call rather than a trusted invariant: this CLI points at whatever `INSTA_API_URL` names,
+        // including a self-hosted insta-oss daemon whose validation is not this repo's to guarantee.
+        //
+        // The same rule is what makes two bundle keys differing ONLY by case impossible (case-differing
+        // needs a lowercase letter, which the rule forbids). If it ever loosens, this loop is where it
+        // bites: both variants would be written and Windows would resolve one of them arbitrarily.
+        for (const [k, v] of Object.entries(bundle)) {
+            if (withheld.has(k.toLowerCase()))
+                continue;
+            Object.defineProperty(env, k, { value: v, enumerable: true, configurable: true, writable: true });
+        }
+        return env;
+    }
+    const env = { ...parent, ...bundle };
+    for (const c of collisions)
+        delete env[c.name];
+    return env;
+}
+/** Pure: why run stopped, and the two ways forward. `branchHint` is the branch to name in the
+ *  suggested commands — set only when the run was NOT on the linked branch, since a hint that
+ *  drops an explicit --branch would send the user to read a different branch's secrets. */
+export function refusalLines(collisions, branchHint) {
+    const n = collisions.length;
+    const b = branchHint ? ` --branch ${branchHint}` : '';
+    return [
+        `refusing to run: ${n} secret name${n === 1 ? '' : 's'} ${n === 1 ? 'is' : 'are'} defined by more than one service, so the bundle cannot say which value the command should get:`,
+        ...collisionLines(collisions, branchHint),
+        `pick one service's env:   insta run --service ${collisions[0]?.services[0] ?? '<type>/<name>'}${b} -- <cmd>`,
+        `or run without the name:  insta run --ignore-collisions${b} -- <cmd>`,
+    ];
+}
 /** Core, dependency-injected for tests: spawn cmd with the bundle in env, return its exit code. */
 export async function runWithSecrets(cmd, args, deps) {
     const bundle = await deps.fetchBundle();
+    const collisions = bundle.collisions ?? [];
+    if (collisions.length) {
+        // Refuse rather than warn: with the name missing from the bundle the child would silently
+        // inherit the parent's value, and even clearing it isn't enough — the child may hold a
+        // compiled-in default or load its own .env, so a missing credential need not be observable.
+        if (!deps.ignoreCollisions)
+            refuse(refusalLines(collisions, deps.branchHint));
+        process.stderr.write(`warning: --ignore-collisions — ${collisions.map((c) => c.name).join(', ')} removed from the child environment (${collisions.length} name${collisions.length === 1 ? '' : 's'} defined by more than one service)\n`);
+    }
+    const env = childEnv(process.env, bundle.secrets, collisions);
+    deps.announce?.(bundle);
     return await new Promise((resolve, reject) => {
-        const child = (deps.spawnImpl ?? spawn)(cmd, args, {
-            stdio: 'inherit',
-            cwd: deps.cwd,
-            env: { ...process.env, ...bundle },
-        });
+        const child = (deps.spawnImpl ?? spawn)(cmd, args, { stdio: 'inherit', cwd: deps.cwd, env });
         child.on('error', reject);
         child.on('close', (code) => resolve(code ?? 1));
     });
@@ -21,20 +98,18 @@ export async function runWithSecrets(cmd, args, deps) {
 export async function run(cmdAndArgs, opts) {
     const [cmd, ...rest] = cmdAndArgs;
     if (!cmd)
-        die('usage: insta run [--branch <b>] -- <command> [args…]');
+        die('usage: insta run [--branch <b>] [--service <type/name>] -- <command> [args…]');
+    assertServiceRef(opts.service);
     const api = await ApiClient.load();
     const p = await requireProject();
     const branch = opts.branch ?? p.branch;
     const code = await runWithSecrets(cmd, rest, {
-        fetchBundle: async () => {
-            const res = await api.rawRequest('GET', `/projects/${p.projectId}/secrets?branch=${encodeURIComponent(branch)}`);
-            if (handleApproval(res))
-                throw new CliExit();
-            // stderr, not stdout: `insta run`'s stdout belongs entirely to the child command (that's why
-            // run has no --json — wrapping would break the child's own output contract).
-            process.stderr.write(`running with ${Object.keys(res.body.secrets).length} injected secrets (branch ${branch}) — nothing written to disk\n`);
-            return res.body.secrets;
-        },
+        fetchBundle: bundleFetcher(api, p.projectId, { branch, service: opts.service }),
+        ignoreCollisions: opts.ignoreCollisions,
+        branchHint: branchHint(branch, p.branch),
+        // stderr, not stdout: `insta run`'s stdout belongs entirely to the child command (that's why
+        // run has no --json — wrapping would break the child's own output contract).
+        announce: (b) => process.stderr.write(`running with ${Object.keys(b.secrets).length} injected secrets (${opts.service ? `${opts.service}, ` : ''}branch ${branch}) — nothing written to disk\n`),
     });
     relayExitCode(code);
 }

package/dist/commands/secrets.js

@@ -3,27 +3,99 @@ import { appendFileSync, existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { ApiClient, requireProject } from '../api.js';
 import { info, printJson, serializeEnv, handleApproval, die } from '../util.js';
-function q(branch) {
-    return branch ? `?branch=${encodeURIComponent(branch)}` : '';
-}
-// Fetch the credential bundle (the secret seam) and write it to .env (or print).
-export async function secrets(opts) {
+async function loadDeps() {
     const api = await ApiClient.load();
     const p = await requireProject();
-    const branch = opts.branch ?? p.branch;
-    const res = await api.rawRequest('GET', `/projects/${p.projectId}/secrets${q(branch)}`);
+    return { api, projectId: p.projectId, linkedBranch: p.branch };
+}
+/** A `--service` that arrived empty (`--service ""`, or an unset variable in a script) is a typo,
+ *  not a request: the platform 400s it, and silently falling back to the branch-wide read would
+ *  answer a different question than the one asked. Fail locally, naming the shape. */
+export function assertServiceRef(service) {
+    if (service !== undefined && service.trim() === '')
+        die('--service requires <type>/<name>, e.g. compute/api');
+}
+/** Query for a bundle read. `--service` asks for the env ONE compute service actually receives
+ *  (unambiguous by construction, so no collision can arise); a general read asks the platform to
+ *  WITHHOLD any name several services define rather than silently returning one of the values. */
+export function bundleQuery(opts) {
+    const parts = [];
+    if (opts.branch)
+        parts.push(`branch=${encodeURIComponent(opts.branch)}`);
+    // A bare/empty --service is a 400 on the platform; the flag is only ever sent with a value.
+    if (opts.service)
+        parts.push(`service=${encodeURIComponent(opts.service)}`);
+    else
+        parts.push('on_collision=withhold');
+    return `?${parts.join('&')}`;
+}
+/** GET the bundle. Returns null when the platform gated the read (202). A platform that doesn't
+ *  know `collisions` reads back as none.
+ *
+ *  That fallback FAILS OPEN and is deliberate: such a platform also ignores `on_collision`, so it
+ *  answers a colliding name with a merged value and no report, and `insta run` would spawn against
+ *  it believing nothing was withheld. It is safe only by shipping order — insta-platform#388 merges
+ *  before this CLI is released, so no released build ever talks to a platform without the field
+ *  (repo owner's call). Do not read the `?? []` as unconditionally safe: if that ordering ever
+ *  changes, this is where capability detection belongs. */
+export async function fetchSecretBundle(api, projectId, opts) {
+    const res = await api.rawRequest('GET', `/projects/${projectId}/secrets${bundleQuery(opts)}`);
     if (handleApproval(res, opts.json))
+        return null;
+    return { secrets: res.body.secrets, collisions: (res.body.collisions ?? []) };
+}
+/** The branch a remediation hint has to name: the one that was actually read, whenever that is not
+ *  the linked branch. A hint that silently dropped an explicit `--branch feat-x` would send the
+ *  user to read the linked branch instead — a different set of secrets, and no sign of the swap. */
+export function branchHint(read, linked) {
+    return read && read !== linked ? read : undefined;
+}
+/** Pure: the report for each withheld name — who defines it, and how to read one of them. */
+export function collisionLines(collisions, hintBranch) {
+    return collisions.flatMap((c) => [
+        `${c.name} omitted — ${c.services.length} services define it:`,
+        `  ${c.services.join(', ')}`,
+        `  read one with: insta secrets --service ${c.services[0] ?? '<type>/<name>'}${hintBranch ? ` --branch ${hintBranch}` : ''}`,
+    ]);
+}
+// STDERR, always: `secrets --print` writes the env to stdout and `insta run`'s stdout belongs to
+// the child command, so a collision report on stdout would corrupt both.
+export function warnCollisions(collisions, hintBranch) {
+    for (const line of collisionLines(collisions, hintBranch))
+        process.stderr.write(line + '\n');
+}
+// The same report for a machine reader, on stderr for the same reason: stdout carries the payload,
+// which under --json is the bare `{NAME: value}` map every existing consumer parses. Nothing is
+// written when there is nothing to choose between — a quiet stream is the signal, not `[]`.
+export function warnCollisionsJson(collisions) {
+    if (collisions.length)
+        process.stderr.write(JSON.stringify({ collisions }) + '\n');
+}
+// Fetch the credential bundle (the secret seam) and write it to .env (or print). --service reads
+// one compute service's own env instead of the branch-wide merge.
+export async function secrets(opts, deps) {
+    assertServiceRef(opts.service);
+    const d = deps ?? (await loadDeps());
+    const branch = opts.branch ?? d.linkedBranch;
+    const b = await fetchSecretBundle(d.api, d.projectId, { branch, service: opts.service, json: opts.json });
+    if (!b)
         return;
-    const bundle = res.body.secrets;
-    if (opts.json)
+    const bundle = b.secrets;
+    // --json's stdout stays the bare map it has always been; the collisions ride stderr as one JSON
+    // line, so a consumer that passes none of the new flags parses exactly what it parsed before.
+    if (opts.json) {
+        warnCollisionsJson(b.collisions);
         return printJson(bundle);
+    }
+    warnCollisions(b.collisions, branchHint(branch, d.linkedBranch));
     if (opts.print) {
         process.stdout.write(serializeEnv(bundle));
         return;
     }
     const out = opts.output ?? '.env';
     await writeFile(out, serializeEnv(bundle));
-    info(`wrote ${Object.keys(bundle).length} secrets to ${out} (branch ${branch})`);
+    const scope = opts.service ? `${opts.service}, branch ${branch}` : `branch ${branch}`;
+    info(`wrote ${Object.keys(bundle).length} secrets to ${out} (${scope})`);
     if (ensureIgnored(process.cwd(), out))
         info(`  .gitignore += ${out} (credentials must never be committed)`);
     info('  tip: `insta run -- <cmd>` injects these per-run with nothing written to disk');
@@ -94,6 +166,10 @@ async function readStdin() {
 // it to a branch service instead, which implies the current branch (binding requires one). Value
 // comes from the argument, or stdin when omitted (keeps secret values out of shell history).
 export async function secretsSet(name, value, opts) {
+    // An empty --service must not fall through to a project-wide WRITE. The scoping test below is a
+    // truthiness check, so `--service ''` (a client interpolating an absent variable) would have put
+    // the secret at a WIDER scope than the caller asked for, visible to every service on the branch.
+    assertServiceRef(opts.service);
     const api = await ApiClient.load();
     const p = await requireProject();
     const v = value ?? (await readStdin());
@@ -108,16 +184,29 @@ export async function secretsSet(name, value, opts) {
         return printJson({ ok: true, name, branch: branch ?? null, service: opts.service ?? null });
     info(`set ${name}${opts.service ? ` → ${opts.service}` : ''} (${branch ? `branch ${branch}` : 'project-wide'})`);
 }
-export async function secretsUnset(name, opts) {
-    const api = await ApiClient.load();
-    const p = await requireProject();
-    const qs = opts.branch ? `?branch=${encodeURIComponent(opts.branch)}` : '';
-    const res = await api.rawRequest('DELETE', `/projects/${p.projectId}/secrets/${encodeURIComponent(name)}${qs}`);
+// Remove a user secret. --service removes only THAT service's copy (the platform has always
+// honoured ?service= here; without the flag a name several services define stays defined).
+export async function secretsUnset(name, opts, deps) {
+    assertServiceRef(opts.service);
+    const d = deps ?? (await loadDeps());
+    // Service scoping REQUIRES a branch (a service exists on a branch, so the platform rejects the
+    // pair without one) — so --service defaults to the linked branch, exactly as `secrets set` does.
+    const branch = opts.service ? (opts.branch ?? d.linkedBranch) : opts.branch;
+    const parts = [];
+    if (branch)
+        parts.push(`branch=${encodeURIComponent(branch)}`);
+    if (opts.service)
+        parts.push(`service=${encodeURIComponent(opts.service)}`);
+    const qs = parts.length ? `?${parts.join('&')}` : '';
+    const res = await d.api.rawRequest('DELETE', `/projects/${d.projectId}/secrets/${encodeURIComponent(name)}${qs}`);
     if (handleApproval(res, opts.json))
         return;
+    // The EFFECTIVE branch, not the flag: with --service and no --branch the scope that was deleted
+    // is the linked branch's, and the output has to say which scope it actually touched.
     if (opts.json)
-        return printJson({ ok: true, name, branch: opts.branch ?? null });
-    info(`unset ${name} (${opts.branch ? `branch ${opts.branch}` : 'project-wide'})`);
+        return printJson({ ok: true, name, branch: branch ?? null, service: opts.service ?? null });
+    const scope = opts.service ? `${opts.service}, branch ${branch}` : branch ? `branch ${branch}` : 'project-wide';
+    info(`unset ${name} (${scope})`);
 }
 export async function secretsBind(envName, source, opts) {
     if (!opts.to)

package/dist/index.js

@@ -98,6 +98,8 @@ envCmd.command('use <name>').description(`Switch environment (${ENV_NAMES.join('
 // ---- 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)')
+    .option('--service <type/name>', "inject one compute service's own slice of the branch bundle, e.g. compute/api — the unambiguous read when several services define the same name (NOT the container's env: it also carries the branch's provider credentials, which a container gets only where bound)")
+    .option('--ignore-collisions', 'run even when several services define the same name; every such name is REMOVED from the child environment (never inherited from your shell)')
     .passThroughOptions().allowUnknownOption()
     .action(guard((cmd, args, o) => runCmd.run([cmd, ...(args ?? [])], o)));
 // ---- agent setup (the `curl … | sh --agents` target) ----
@@ -170,14 +172,18 @@ svc.command('secrets <type> <name>').description("List a service's secret names"
     .option('--branch <b>').option('--json').action(guard((type, name, o) => services.servicesSecrets(type, name, o)));
 // ---- secrets (seam) ----
 const sec = program.command('secrets').description('Fetch the credential bundle (secret seam) into .env')
-    .option('--branch <branch>').option('-o, --output <file>', 'output file (default .env)').option('--print', 'print instead of writing').option('--json')
+    .option('--branch <branch>')
+    .option('--service <type/name>', "read one compute service's own slice of the bundle instead of the branch-wide merge, e.g. compute/api")
+    .option('-o, --output <file>', 'output file (default .env)').option('--print', 'print instead of writing').option('--json')
     .action(guard((o) => secretsCmd.secrets(o)));
 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)')
     .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').option('--json').action(guard((n, o) => secretsCmd.secretsUnset(n, o)));
+    .option('--branch <branch>', 'scope to one branch')
+    .option('--service <type/name>', "remove only that service's copy, e.g. compute/api")
+    .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')

package/dist/util.js

@@ -81,6 +81,16 @@ export function die(msg) {
     fail(msg);
     throw new CliExit();
 }
+// The CLI declined to act and the caller must choose how to proceed — the same shape as the 202
+// approval gate below, so it takes the same exit code 2: not success (a redirected stdout must
+// never read the refusal as output), and not a plain failure either (die owns 1). Nothing ran,
+// and re-running with the flag the message names will work.
+export function refuse(lines) {
+    for (const line of lines)
+        process.stderr.write(line + '\n');
+    process.exitCode = 2;
+    throw new CliExit();
+}
 export function printJson(v) {
     process.stdout.write(JSON.stringify(v, null, 2) + '\n');
 }

package/package.json

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