insta 0.0.69 → 0.0.70

package/README.md

@@ -240,6 +240,7 @@ build never reaches a production installer.
 |---|---|
 | `~/.insta/config.json` | API URL, access and refresh tokens, user, auto-update preference |
 | `./.insta/project.json` | Project id, org id, current branch |
+| `./.insta/link-plane.json` | The control-plane URL this machine linked against. Gitignored and per machine; a link made against a different control plane is refused rather than reused. The home directory is never a project |
 
 | Variable | Effect |
 |---|---|

package/dist/api.js

@@ -1,6 +1,6 @@
 // Thin API client over the platform control-plane. Handles bearer auth + one-shot refresh on 401.
 // 2xx (including 202 approval_required) returns the parsed body; >=400 throws ApiError.
-import { readGlobal, writeGlobal, readProject, writeProject } from './config.js';
+import { readGlobal, writeGlobal, readProject, persistAutoLink, resolveProjectLink, foreignLinkMessage } from './config.js';
 import { autoResolveProject, promptChoice } from './resolve-project.js';
 import { die } from './util.js';
 import { USER_AGENT } from './version.js';
@@ -127,12 +127,20 @@ export class ApiClient {
 // Resolve the linked project (./.insta/project.json), or null.
 export async function linkedProject() { return readProject(); }
 // Resolve the linked project or exit with guidance.
-export async function requireProject() {
-    const p = await readProject();
-    if (p)
-        return p;
+export async function requireProject(deps = {}) {
+    const r = await resolveProjectLink(deps.cwd);
+    // Fail CLOSED on a link made against another control plane. Treating it as "unlinked" sent this
+    // into auto-resolve, which with exactly one project on the new plane picks it without a prompt
+    // and SAVES — so a read-only command replaced the committed team binding, and pointing back
+    // flipped it again. Only an explicit `insta project link` may replace a link.
+    if (r?.foreign)
+        die(foreignLinkMessage(r.foreign));
+    if (r)
+        return r.link;
     if (agentMode())
         die('agent mode requires a linked project — run `insta setup agent --project <id>`');
+    if (deps.autoResolve)
+        return deps.autoResolve();
     // One command, just works: unlinked ≠ error. Resolve the project (auto when there's one,
     // one-keystroke picker when several) and persist the choice so this happens once per dir.
     const api = await ApiClient.load();
@@ -143,10 +151,16 @@ export async function requireProject() {
             listProjects: async () => (await api.request('GET', `/orgs/${orgId}/projects`)).projects,
             promptChoice,
             save: async (c) => {
-                await writeProject(c);
                 // stderr: this is a diagnostic that can precede ANY command's output — under --json,
                 // stdout must stay one parseable document.
-                process.stderr.write(`auto-linked project ${c.projectId} → ./.insta/project.json\n`);
+                if (await persistAutoLink(c, deps.cwd)) {
+                    process.stderr.write(`auto-linked project ${c.projectId} → ./.insta/project.json\n`);
+                }
+                else {
+                    // The home directory never holds a link (~/.insta is the global config): use the choice
+                    // for this command instead of failing it after the picker has already run.
+                    process.stderr.write(`using project ${c.projectId} for this command — not saving a link in the home directory; run inside a project directory to remember it\n`);
+                }
             },
             tty: !!process.stdin.isTTY && !!process.stderr.isTTY,
         });

package/dist/commands/billing.js

@@ -14,17 +14,20 @@ export async function resolveOrgId(opts) {
 export function billingLines(s, org) {
     const t = s.totals;
     const lines = [
-        `tier:      ${s.tier}`,
-        `status:    ${s.billingStatus}`,
+        `tier:            ${s.tier}`,
+        `status:          ${s.billingStatus}`,
         cycleLine(s.window),
-        `included:  $${Number(t.includedUsd).toFixed(2)}`,
-        `used:      $${Number(t.usedUsd).toFixed(4)}`,
-        `overage:   $${Number(t.overageUsd).toFixed(4)}`,
-        `credits:   $${Number(t.creditsUsd).toFixed(2)}`,
-        `forecast:  $${Number(t.forecastUsd).toFixed(4)}  (predicted full cycle)`,
+        // Two separate figures, never added together: the plan's allowance for this cycle, and the
+        // org's wallet. "included usage" is the name the console and the pricing page use for the
+        // former; "credits" now means the wallet alone.
+        `included usage:  $${Number(t.includedUsd).toFixed(2)}`,
+        `used:            $${Number(t.usedUsd).toFixed(4)}`,
+        `overage:         $${Number(t.overageUsd).toFixed(4)}`,
+        `credits:         $${Number(t.creditBalanceUsd).toFixed(2)}`,
+        `forecast:        $${Number(t.forecastUsd).toFixed(4)}  (predicted full cycle)`,
     ];
     if (s.subscriptionStatus)
-        lines.push(`subscription: ${s.subscriptionStatus}`);
+        lines.push(`subscription:    ${s.subscriptionStatus}`);
     if (s.billingStatus === 'suspended') {
         // Four causes, five messages, and every one is a dead end for the others. Tier first: only a
         // free org can spend a prepaid wallet, and waiting for the next cycle genuinely fixes that one.

package/dist/commands/branch.js

@@ -1,5 +1,5 @@
 import { ApiClient, requireProject } from '../api.js';
-import { writeProject } from '../config.js';
+import { isHomeLinkTarget, writeProject } from '../config.js';
 import { info, die, printJson, handleApproval, renderNextActions } from '../util.js';
 export async function branchCreate(name, opts) {
     const api = await ApiClient.load();
@@ -20,6 +20,11 @@ export async function branchList(opts) {
         info(`${b.is_default ? '*' : ' '} ${b.name}  [${b.status}]  ${b.id}`);
 }
 export async function branchSwitch(name, opts = {}) {
+    // A switch is remembered in ./.insta/project.json, which never lives in the home directory. Say so
+    // up front, instead of auto-resolving a project "for this command" and then refusing to save.
+    if (await isHomeLinkTarget()) {
+        die('can\'t switch branches in the home directory — the branch is remembered in ./.insta/project.json, and ~/.insta is the insta CLI\'s global config. Run this inside a project directory');
+    }
     const api = await ApiClient.load();
     const p = await requireProject();
     const { branches } = await api.request('GET', `/projects/${p.projectId}/branches`);

package/dist/commands/project.js

@@ -1,7 +1,7 @@
 import { homedir } from 'node:os';
 import { agentMode, setupProjectAgentSession } from '../agent.js';
 import { ApiClient, requireProject } from '../api.js';
-import { writeProject } from '../config.js';
+import { HOME_LINK_REFUSAL, isHomeLinkTarget, writeProject } from '../config.js';
 import { info, die, printJson, handleApproval, renderNextActions } from '../util.js';
 import { installObserve } from '../observe/install.js';
 import { installRoot } from './observe.js';
@@ -73,6 +73,10 @@ export async function projectCreate(name, opts) {
         info('  (or just ask your coding agent — it has the insta skill and will do this for you)');
         return;
     }
+    // Refuse the home directory BEFORE provisioning: refusing only inside writeProject created the
+    // project on the control plane and then failed, with no id printed under --json.
+    if (await isHomeLinkTarget())
+        die(HOME_LINK_REFUSAL);
     const api = await ApiClient.load();
     const orgId = await resolveOrg(api, opts.org);
     const out = await api.request('POST', `/orgs/${orgId}/projects`, { name: resolved });
@@ -103,6 +107,11 @@ export async function projectList(opts) {
         info(`${p.id}  ${p.name}  [${p.status}]`);
 }
 export async function projectLink(id, opts = {}) {
+    // Refuse the home directory BEFORE anything with side effects. In agent mode the session below is
+    // saved, and .gitignore edited, at the link root; refusing only inside writeProject left both
+    // behind in ~ after the command had already failed.
+    if (await isHomeLinkTarget())
+        die(HOME_LINK_REFUSAL);
     const api = await ApiClient.load();
     if (agentMode())
         await setupProjectAgentSession(api, id);

package/dist/config.js

@@ -1,13 +1,21 @@
 // CLI config: global (~/.insta/config.json: api url + tokens) and per-project (./.insta/project.json).
 import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { realpathSync } from 'node:fs';
+import { chmod, mkdir, readFile, writeFile } from 'node:fs/promises';
 import { ensureGitignore } from './gitignore.js';
+import { die } from './util.js';
 import { DEFAULT_ENV, ENVS, envForApiUrl, envFromEnvVar, normalizeUrl } from './env.js';
 const GLOBAL_DIR = join(homedir(), '.insta');
 const GLOBAL_FILE = join(GLOBAL_DIR, 'config.json');
 const PROJECT_DIR = '.insta';
 const PROJECT_FILE = 'project.json';
+// Machine-local, gitignored: which project this machine linked here, and on which control plane.
+// It is NOT in project.json because that file is the team's committed binding — a URL chosen by one
+// machine (a staging switch, a local box, a transient INSTA_API_URL) would make every teammate's
+// CLI treat the shared link as foreign. It records the project id too, because project.json is
+// committed and this file is not: a pull or checkout can replace the project underneath it.
+const LINK_PLANE_FILE = 'link-plane.json';
 // The cloud API default. Uses the instacloud.com brand domain (matches the agents.instacloud.com
 // onboarding), NOT the legacy beta-api.insta.insforge.dev host — same backend, branded domain.
 // Only affects fresh installs: a persisted apiUrl (from a prior login) or INSTA_API_URL wins below.
@@ -85,11 +93,46 @@ export async function writeGlobal(c) {
     await mkdir(GLOBAL_DIR, { recursive: true });
     await writeFile(GLOBAL_FILE, JSON.stringify(c, null, 2));
 }
+/** The home directory is never a project root. `~/.insta/` is this CLI's GLOBAL config directory,
+ *  so a project.json there is not a project link: honouring one made every directory under the home
+ *  dir inherit it, and `insta project link` run anywhere below home silently overwrote it. */
+function isHomeDir(dir) {
+    return canonicalDir(dir) === canonicalDir(homedir());
+}
+/** A directory's filesystem identity rather than its spelling: the native real path, which resolves
+ *  symlinks and returns the on-disk case on case-insensitive filesystems (macOS, Windows). Comparing
+ *  spellings let a symlinked or differently-cased path to home through the home check. A path that
+ *  doesn't exist has no identity to resolve, so it falls back to its resolved spelling. */
+function canonicalDir(dir) {
+    try {
+        return realpathSync.native(resolve(dir));
+    }
+    catch {
+        return resolve(dir);
+    }
+}
+export const HOME_LINK_REFUSAL = 'refusing to link the home directory — ~/.insta is the insta CLI\'s global config, not a project. Run this inside a project directory';
+/** Where a link written from `cwd` lands: the existing project root, or `cwd` itself. */
+async function linkTarget(cwd) {
+    return (await findProjectRoot(cwd)) ?? resolve(cwd);
+}
+/** True when a link written from `cwd` would land in the home directory, which never holds one.
+ *  Lets a caller refuse BEFORE it does anything else with side effects. */
+export async function isHomeLinkTarget(cwd = process.cwd()) {
+    return isHomeDir(await linkTarget(cwd));
+}
 /** Git-style ancestor lookup: the nearest directory at-or-above `cwd` containing
- *  .insta/project.json — so "link once" works from any subdirectory of the project. */
+ *  .insta/project.json — so "link once" works from any subdirectory of the project. The search
+ *  stops at the home directory (see isHomeDir): neither home nor anything above it is a project
+ *  root for a directory inside home. */
 export async function findProjectRoot(cwd = process.cwd()) {
     let dir = resolve(cwd);
     for (;;) {
+        // Stop AT the home directory rather than skipping it: a link above home is not a project for
+        // home or anything below it, and climbing past home let `insta project link` run in ~ resolve
+        // to, and overwrite, an ancestor's link after the home-directory check had passed.
+        if (isHomeDir(dir))
+            return null;
         try {
             await readFile(join(dir, PROJECT_DIR, PROJECT_FILE), 'utf8');
             return dir;
@@ -101,32 +144,157 @@ export async function findProjectRoot(cwd = process.cwd()) {
         dir = parent;
     }
 }
-export async function readProject(cwd = process.cwd()) {
+/** The link that applies to `cwd`, and whether it was made against a DIFFERENT control plane. A
+ *  project id means nothing on another control plane (cloud, staging and every insta-oss box each
+ *  have their own), and the CLI used to reuse a link against whatever API it was pointed at. */
+export async function resolveProjectLink(cwd = process.cwd()) {
     // Linkless targeting (CI / one-offs / agents): INSTA_PROJECT_ID resolves the project with no
     // link file, and beats one when both exist — an explicit parameter outranks ambient state.
     if (process.env.INSTA_PROJECT_ID) {
         return {
-            projectId: process.env.INSTA_PROJECT_ID,
-            orgId: process.env.INSTA_ORG_ID ?? '',
-            branch: process.env.INSTA_BRANCH ?? 'main',
+            link: {
+                projectId: process.env.INSTA_PROJECT_ID,
+                orgId: process.env.INSTA_ORG_ID ?? '',
+                branch: process.env.INSTA_BRANCH ?? 'main',
+            },
         };
     }
     const root = await findProjectRoot(cwd);
     if (!root)
         return null;
+    let link;
+    try {
+        link = JSON.parse(await readFile(join(root, PROJECT_DIR, PROJECT_FILE), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+    // No sidecar — a link from before this existed, or a teammate who just cloned — resolves as it
+    // always did: there is nothing to say which control plane it belongs to.
+    const record = await readLinkPlane(root);
+    if (record) {
+        const current = safeUrl((await readGlobal()).apiUrl);
+        const base = {
+            file: join(root, PROJECT_DIR, PROJECT_FILE), projectId: String(link.projectId),
+            linkedProjectId: record.projectId, linkedApiUrl: record.apiUrl, currentApiUrl: current,
+        };
+        // The record vouches for the project it was written for, and only that one. A record for
+        // another project says nothing about this one: trusting it would send this project to the
+        // control plane of the project it replaced, or refuse it for a reason that is not true. Fail
+        // closed with the real reason instead.
+        if (record.projectId !== base.projectId)
+            return { link, foreign: { reason: 'changed', ...base } };
+        if (normalizeUrl(record.apiUrl) !== normalizeUrl(current))
+            return { link, foreign: { reason: 'plane', ...base } };
+    }
+    return { link };
+}
+/** The link for this control plane, or null. A foreign link is NOT returned (it names a project
+ *  that does not exist here); callers that must act on a project use requireProject, which stops
+ *  with guidance instead of treating a foreign link as "unlinked". */
+export async function readProject(cwd = process.cwd()) {
+    const r = await resolveProjectLink(cwd);
+    if (!r)
+        return null;
+    if (r.foreign) {
+        if (!warnedForeignLinks.has(r.foreign.file)) {
+            warnedForeignLinks.add(r.foreign.file);
+            process.stderr.write(`note: ${foreignLinkMessage(r.foreign)}\n`);
+        }
+        return null;
+    }
+    return r.link;
+}
+const warnedForeignLinks = new Set();
+export function foreignLinkMessage(f) {
+    // Every field can come from a file (a committed project.json, a copied or hand-edited record),
+    // so all of it is stripped of control characters before it reaches a terminal.
+    const file = safeText(f.file);
+    const id = safeText(f.projectId);
+    const linked = safeUrl(f.linkedApiUrl);
+    const current = safeUrl(f.currentApiUrl);
+    if (f.reason === 'changed') {
+        return `${file} now links project ${id}, but this machine linked project ${safeText(f.linkedProjectId)} there, on ${linked}. `
+            + `The link changed since (a pull or checkout), so its control plane is unknown. `
+            + `Confirm it for ${current} with \`insta project link ${id}\`.`;
+    }
+    return `${file} links project ${id} on ${linked}, but the CLI is pointed at ${current}. `
+        + `Link this directory for ${current} with \`insta project link <id>\`, or point the CLI back at ${linked}.`;
+}
+async function readLinkPlane(root) {
     try {
-        return JSON.parse(await readFile(join(root, PROJECT_DIR, PROJECT_FILE), 'utf8'));
+        const raw = JSON.parse(await readFile(join(root, PROJECT_DIR, LINK_PLANE_FILE), 'utf8'));
+        // Validated, not cast: a malformed record is ignored rather than crashing every command. A
+        // record with no project id cannot say which project it vouches for, so it is ignored too.
+        if (!raw || typeof raw.projectId !== 'string' || !raw.projectId || typeof raw.apiUrl !== 'string' || !raw.apiUrl)
+            return null;
+        // Untrusted input (it may have been copied or edited), so sanitized before it is compared or printed.
+        return { projectId: raw.projectId, apiUrl: safeUrl(raw.apiUrl) };
     }
     catch {
         return null;
     }
 }
+/** Text safe to echo to a terminal: C0 and C1 control characters and DEL removed — ESC and the
+ *  single-byte C1 introducers (U+009B CSI among them) alike, so no escape sequence survives. */
+function safeText(text) {
+    return String(text).replace(/[\u0000-\u001f\u007f-\u009f]/g, '');
+}
+/** A control-plane URL safe to persist and to print: control characters removed, surrounding
+ *  whitespace trimmed, and any userinfo (INSTA_API_URL may carry credentials) removed.
+ *
+ *  Userinfo is removed with the same WHATWG parser fetch uses, not with a pattern. That parser is
+ *  lenient in ways a pattern keeps missing: it accepts leading whitespace, `\` for `/`, and a
+ *  missing `//` on special schemes, and each of those defeated an anchored pattern while fetch
+ *  would still have sent the credentials. A value the parser rejects is never requested, but it can
+ *  still be stored or printed, so everything up to its last `@` is dropped. The same goes for a
+ *  value that parses under any other scheme: `user:token@host` parses as scheme `user:` with the
+ *  credentials in its path, where clearing username and password removes nothing. */
+export function safeUrl(url) {
+    const text = safeText(url).trim();
+    const pastLastAt = () => (text.includes('@') ? text.slice(text.lastIndexOf('@') + 1) : text);
+    let parsed;
+    try {
+        parsed = new URL(text);
+    }
+    catch {
+        return pastLastAt();
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')
+        return pastLastAt();
+    if (!parsed.username && !parsed.password)
+        return text;
+    parsed.username = '';
+    parsed.password = '';
+    return parsed.href;
+}
 /** Writes to the existing project root when inside a linked project (branch switches from a
- *  subdirectory must not mint a nested link); a fresh `link` in an unlinked tree writes to cwd. */
+ *  subdirectory must not mint a nested link); a fresh `link` in an unlinked tree writes to cwd.
+ *  Records the control plane in the machine-local sidecar beside it. Never writes into the home
+ *  directory: `~/.insta/` is the global config, not a project. */
 export async function writeProject(c, cwd = process.cwd()) {
-    const target = (await findProjectRoot(cwd)) ?? cwd;
+    const target = await linkTarget(cwd);
+    if (isHomeDir(target))
+        die(HOME_LINK_REFUSAL);
+    const { apiUrl } = await readGlobal();
     await mkdir(join(target, PROJECT_DIR), { recursive: true });
     ensureGitignore(target, ['.insta/agent-session.json'], '# Local agent credentials');
+    ensureGitignore(target, [`.insta/${LINK_PLANE_FILE}`], '# Local: the control plane this machine linked against');
     await writeFile(join(target, PROJECT_DIR, PROJECT_FILE), JSON.stringify(c, null, 2));
+    // Owner-only, like agent-session.json: it can name a private self-hosted box. writeFile's mode
+    // applies only when it creates the file, so an existing record is chmod-ed too.
+    const record = join(target, PROJECT_DIR, LINK_PLANE_FILE);
+    await writeFile(record, JSON.stringify({ projectId: c.projectId, apiUrl: safeUrl(apiUrl) }, null, 2), { mode: 0o600 });
+    await chmod(record, 0o600);
+}
+/** Save a link that auto-resolution chose. Unlike an explicit `insta project link`, the command it
+ *  was resolved for must still run: in the home directory the choice is used for this command and
+ *  simply not remembered, rather than showing the picker and then failing the command. Returns
+ *  whether the link was saved. */
+export async function persistAutoLink(c, cwd = process.cwd()) {
+    if (await isHomeLinkTarget(cwd))
+        return false;
+    await writeProject(c, cwd);
+    return true;
 }
 //# sourceMappingURL=config.js.map

package/dist/index.js

@@ -149,7 +149,7 @@ svc.command('add [type] [name]').description('Provision a service on demand (ass
     .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 (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('--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 up to its own plan cap (10Gi free, 50Gi paid by default; the bare `insta compute volume <name>` read prints it as plan max); a size above the free cap is paid. 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);
@@ -270,7 +270,7 @@ compute.command('watch-paths [service]').description("Show or change which paths
     .option('--json').option('--branch <branch>', 'branch (default: current)').action(guard((service, o) => githubCmd.computeWatchPaths(service, o)));
 compute.command('disconnect-repo [service]').description('Disconnect the GitHub repository from a compute service. The service keeps running its current image; pushes no longer deploy it, and its build history stays')
     .option('--json').option('--branch <branch>', 'branch (default: current)').action(guard((service, o) => githubCmd.computeDisconnectRepo(service, 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 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")
+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 up to its own plan cap — 10Gi free, 50Gi paid by default — which is also what a disk with no size named is born at; a size above the free cap is paid; 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)));

package/package.json

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