insta 0.0.76 → 0.0.78

package/dist/commands/compute.js

@@ -750,7 +750,7 @@ import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { createHash, randomUUID } from 'node:crypto';
-import { aliasFor, certifiesPublicKey, hasOwnedBlock, isSafeAlias, isSafeConfigValue, isSafeSSHHost, isSafeSSHUsername, isSafeTimestamp, isSSHCertificateRecord, mayWidenCAHost, parseCAPublicKey, planCertAuthority, renderConfigBlock, revertCertAuthority, upsertConfigBlock, } from './ssh-config.js';
+import { aliasFor, certifiesPublicKey, hasOwnedBlock, isSafeAlias, isSafeConfigValue, isSafeSSHHost, isSafeSSHUsername, isSafeTimestamp, isSSHCertificateRecord, mayWidenCAHost, parseCAPublicKey, planCertAuthority, renderConfigBlock, revertCertAuthority, upsertConfigBlock, ownedBlock, ownedBlockIsFirst } from './ssh-config.js';
 /** Where this CLI keeps its own SSH material. Deliberately NOT ~/.ssh: we never
  *  touch a key the user already had, and a dedicated key pairs with
  *  IdentitiesOnly to avoid being identified by the wrong one. */
@@ -769,6 +769,15 @@ export const instaAliasStorePath = () => join(instaSSHDir(), 'aliases.json');
 export const userKnownHostsPath = () => join(homedir(), '.ssh', 'known_hosts');
 /** The renewal-hook command prefix. ssh-config.ts appends the validated alias. */
 export const ENSURE_CERT_COMMAND = 'insta __ssh-ensure-cert';
+/** The gateway's public port when the plane does not say: :2222, the port the
+ *  lane shipped on (:22 waits for a compliance exception). The plane's answer
+ *  in a mint response ALWAYS wins over this; it exists for stores and planes
+ *  that predate the `port` field, so a working alias does not stop working. */
+export const DEFAULT_SSH_PORT = 2222;
+/** A TCP port as the plane returns it: an integer, 1..65535. */
+export function isValidPort(v) {
+    return typeof v === 'number' && Number.isInteger(v) && v >= 1 && v <= 65535;
+}
 /** Never throws: a missing or hand-mangled store must degrade to "nothing is
  *  set up", not break `ssh` for every alias. */
 export function readAliasStore(path = instaAliasStorePath()) {
@@ -800,6 +809,7 @@ export function isValidAliasRecord(r) {
     return typeof v.projectId === 'string' && v.projectId !== ''
         && typeof v.serviceId === 'string' && v.serviceId !== ''
         && (v.branch === undefined || typeof v.branch === 'string')
+        && (v.port === undefined || isValidPort(v.port))
         && isSafeConfigValue(v.host) && isSafeConfigValue(v.username);
 }
 /** Refuse to point an existing alias at a different service.
@@ -839,7 +849,7 @@ export function hostEntries(store) {
         // sit where the rendering does.
         .filter(([alias, r]) => isSafeAlias(alias) && isValidAliasRecord(r))
         .sort(([a], [b]) => a.localeCompare(b))
-        .map(([alias, r]) => ({ alias, hostName: r.host, user: r.username, certificateFile: instaCertPath(alias) }));
+        .map(([alias, r]) => ({ alias, hostName: r.host, user: r.username, port: r.port ?? DEFAULT_SSH_PORT, certificateFile: instaCertPath(alias) }));
 }
 /**
  * When `ssh-keygen -L` output says the certificate stops being valid, or
@@ -969,6 +979,11 @@ export function validateCertResponse(body) {
     // are refused rather than rendered.
     if (!isSafeTimestamp(b.expiresAt))
         throw new Error('the platform returned an unusable certificate expiry');
+    // Optional only because planes predating the field exist; PRESENT and wrong
+    // is refused, never coerced -- a port we made up is a connection that hangs.
+    if (b.port !== undefined && !isValidPort(b.port)) {
+        throw new Error(`the platform returned an unusable ssh port: ${JSON.stringify(String(b.port).slice(0, 16))}`);
+    }
     // Parsed here rather than at install time so a malformed key fails before
     // anything is written, instead of after the alias is already recorded.
     if (b.caPublicKey !== undefined)
@@ -1235,6 +1250,40 @@ function withLockedFile(name, fn, { waitMs, staleMs, sleep, busy }) {
         sleep(LOCK_POLL_MS);
     }
 }
+/** The block ssh_config SHOULD carry for this store, rendered the one way. */
+function renderInstalledBlock(store) {
+    return renderConfigBlock({
+        entries: hostEntries(store),
+        identityFile: instaKeyPath(),
+        knownHostsFile: userKnownHostsPath(),
+        ensureCertCommand: ENSURE_CERT_COMMAND,
+    });
+}
+/** Whether the installed block differs from what the store renders -- the ONE
+ *  predicate for "rewrite ssh_config". A host move, a port the plane changed,
+ *  and a stanza written before the Port line existed all show up here; a
+ *  renewal whose response changed nothing does not, which matters because
+ *  OpenSSH is reading the file while the hook runs and a rename over an open
+ *  file fails on Windows. No installed block = nothing to repair (setup owns
+ *  the first write). */
+function configBlockStale(store) {
+    let existing;
+    try {
+        existing = readFileSync(join(homedir(), '.ssh', 'config'), 'utf8');
+    }
+    catch {
+        return false;
+    }
+    const installed = ownedBlock(existing);
+    if (installed === undefined)
+        return false;
+    // Position is content too: a block that has slid below other configuration
+    // is shadowed keyword by keyword (first obtained value wins), whatever its
+    // text says. The rewrite puts it back where setup wrote it, at the top.
+    if (!ownedBlockIsFirst(existing))
+        return true;
+    return installed.replace(/\n+$/, '') !== renderInstalledBlock(store).replace(/\n+$/, '');
+}
 function installConfigBlock(store) {
     const cfg = join(homedir(), '.ssh', 'config');
     mkdirSync(dirname(cfg), { recursive: true, mode: 0o700 });
@@ -1246,12 +1295,7 @@ function installConfigBlock(store) {
     // target says.
     const existedBefore = pathExists(cfg);
     const existing = readUserText(cfg);
-    const block = renderConfigBlock({
-        entries: hostEntries(store),
-        identityFile: instaKeyPath(),
-        knownHostsFile: userKnownHostsPath(),
-        ensureCertCommand: ENSURE_CERT_COMMAND,
-    });
+    const block = renderInstalledBlock(store);
     // Backed up: this is the file that decides whether the user can ssh anywhere
     // at all, and our block goes at the TOP of it.
     writeFileAtomicSync(cfg, upsertConfigBlock(existing, block), { mode: 0o600, backup: true });
@@ -1370,6 +1414,20 @@ export async function ensureCertForAlias(alias, timeoutMs = RENEWAL_REQUEST_TIME
     try {
         if (!isSafeAlias(alias))
             return;
+        // Repair BEFORE the renewal gate, because the stanza can lag the store
+        // with no certificate due: an alias set up before the Port line existed
+        // dials :22 on every connection, and waiting for its certificate to age
+        // would leave it failing for up to the certificate's lifetime. The
+        // predicate is content drift, so the common case -- an up-to-date stanza --
+        // is one file read and a string compare, with no lock taken; only a stale
+        // stanza takes the alias-store lock, re-checks under it and rewrites.
+        if (configBlockStale(readAliasStore())) {
+            withAliasStoreLock(() => {
+                const store = readAliasStore();
+                if (store[alias] && configBlockStale(store))
+                    installConfigBlock(store);
+            }, { waitMs: KNOWN_HOSTS_LOCK_WAIT_MS });
+        }
         if (!certNeedsRenewal(instaCertPath(alias)))
             return;
         // An IDE opens several connections at once and `scp` adds more, so the
@@ -1433,9 +1491,16 @@ export async function ensureCertForAlias(alias, timeoutMs = RENEWAL_REQUEST_TIME
                     return;
                 if (!certNeedsRenewal(instaCertPath(alias)))
                     return;
+                // The plane's answer wins, on every field it answers. `moved` is the
+                // host/user half and keeps its CA requirement below (a new host needs
+                // an anchor); the port has no such requirement but is part of the
+                // record all the same, and a legacy record without one gains it here
+                // so the stanza can carry the line.
+                const port = out.port ?? held.port ?? DEFAULT_SSH_PORT;
                 const moved = held.host !== out.host || held.username !== out.username;
-                const store = moved
-                    ? { ...before, [alias]: { ...held, host: out.host, username: out.username } }
+                const recordChanged = moved || held.port !== port;
+                const store = recordChanged
+                    ? { ...before, [alias]: { ...held, host: out.host, username: out.username, port } }
                     : before;
                 const installed = configBlockInstalled();
                 const ca = out.caPublicKey;
@@ -1463,11 +1528,13 @@ export async function ensureCertForAlias(alias, timeoutMs = RENEWAL_REQUEST_TIME
                 // host into a renewal that gives up -- one failed renewal and a
                 // `--setup` to repair it, never a half-moved alias.
                 const steps = [];
-                if (moved)
+                if (recordChanged)
                     steps.push(() => { const back = snapshotForUndo(instaAliasStorePath()); writeAliasStore(store); return back; });
                 if (ca !== undefined)
                     steps.push(() => installCertAuthority(hostPatternFor(out.host), ca));
-                if (moved && installed)
+                // Drift, not "moved": a changed port rewrites the stanza; an unchanged
+                // response leaves the file alone (see configBlockStale).
+                if (installed && configBlockStale(store))
                     steps.push(() => installConfigBlock(store));
                 steps.push(() => out.staged.commit());
                 // ONE section from reading the anchor to committing the certificate
@@ -1752,7 +1819,7 @@ export async function computeSSH(serviceName, opts, deps = {}) {
             assertAliasFree(before, alias, { projectId: p.projectId, serviceId: svc.id, branch });
             const store = {
                 ...before,
-                [alias]: { projectId: p.projectId, ...(branch ? { branch } : {}), serviceId: svc.id, host: out.host, username: out.username },
+                [alias]: { projectId: p.projectId, ...(branch ? { branch } : {}), serviceId: svc.id, host: out.host, username: out.username, port: out.port ?? DEFAULT_SSH_PORT },
             };
             // Whether ~/.ssh is BACKING this store, not merely whether --setup was
             // passed. The store and the certificate are rewritten by every issuance,
@@ -1811,9 +1878,9 @@ export async function computeSSH(serviceName, opts, deps = {}) {
         out.staged.discard();
     }
     if (opts.json)
-        return printJson({ alias, host: out.host, username: out.username, expiresAt: out.expiresAt, configured: installed });
+        return printJson({ alias, host: out.host, username: out.username, port: out.port ?? DEFAULT_SSH_PORT, expiresAt: out.expiresAt, configured: installed });
     for (const line of sshAdvice({
-        alias, host: out.host, username: out.username, expiresAt: out.expiresAt, serviceName: svc.name,
+        alias, host: out.host, username: out.username, port: out.port ?? DEFAULT_SSH_PORT, expiresAt: out.expiresAt, serviceName: svc.name,
         configured: installed, identityFile: instaKeyPath(), certificateFile: instaCertPath(alias),
     }))
         emit(line);
@@ -1830,7 +1897,7 @@ export async function computeSSH(serviceName, opts, deps = {}) {
  */
 export function sshAdvice(r) {
     const head = r.configured
-        ? [`ssh ${r.alias}  →  ${r.username}@${r.host}`]
+        ? [`ssh ${r.alias}  →  ${r.username}@${r.host} (port ${r.port})`]
         : [
             // Every option here is load-bearing. The key lives at
             // ~/.insta/ssh/id_ed25519 and the certificate at <alias>-cert.pub;
@@ -1839,7 +1906,9 @@ export function sshAdvice(r) {
             // this command just issued -- it fails, having printed success.
             // IdentitiesOnly stops a loaded agent from spending the server's
             // MaxAuthTries on unrelated keys before ours is ever tried.
-            `ssh -i ${shQuote(r.identityFile)} -o CertificateFile=${shQuote(r.certificateFile)} -o IdentitiesOnly=yes ${shQuote(`${r.username}@${r.host}`)}`,
+            // -p is not optional: the gateway is on :2222 and :22 is closed, so a
+            // pasted command without it fails before the credential is ever tried.
+            `ssh -p ${r.port} -i ${shQuote(r.identityFile)} -o CertificateFile=${shQuote(r.certificateFile)} -o IdentitiesOnly=yes ${shQuote(`${r.username}@${r.host}`)}`,
             `  run \`insta compute ssh ${r.serviceName} --setup\` once for the shorter \`ssh ${r.alias}\`, automatic renewal, and scp/-L support`,
         ];
     return [...head, `  certificate valid until ${r.expiresAt}`];

package/dist/commands/domain.js

@@ -34,15 +34,8 @@ export async function domainSearch(keyword, opts, deps) {
         info(`buy one: insta domain buy ${buyable.domainName}`);
 }
 export async function domainBuy(name, opts, deps) {
+    const years = whole('--years', opts.years);
     const { api, project: p } = await domainDeps(deps);
-    // JSON.stringify drops undefined but keeps NaN as null, which the platform rejects as a type
-    // error rather than a bad term — so a malformed --years is refused here, with the reason.
-    let years;
-    if (opts.years !== undefined) {
-        years = Number(opts.years);
-        if (!Number.isInteger(years))
-            die(`--years must be a whole number of years, not ${opts.years}`);
-    }
     const res = await api.rawRequest('POST', `/projects/${p.projectId}/domains/orders`, { domainName: name, years });
     if (handleApproval(res, opts.json))
         return;
@@ -138,4 +131,61 @@ export async function domainStatus(name, opts, deps) {
     for (const line of domain ? domainLines(domain) : orderStatusLines(order))
         info(line);
 }
+export function recordLines(records) {
+    const w = (pick) => Math.max(...records.map((r) => pick(r).length));
+    const idW = w((r) => String(r.id)), typeW = w((r) => r.type), nameW = w((r) => r.fqdn), answerW = w((r) => r.answer), ttlW = w((r) => String(r.ttl));
+    return records.map((r) => {
+        const line = `  ${String(r.id).padEnd(idW)}  ${r.type.padEnd(typeW)}  ${r.fqdn.padEnd(nameW)}  ${r.answer.padEnd(answerW)}  ${String(r.ttl).padEnd(ttlW)}  ${r.priority === undefined ? '' : String(r.priority)}`.trimEnd();
+        if (r.managed)
+            return `${line}  (managed${r.hostname ? ` — published for ${r.hostname}` : ' — no hostname claims it; remove drops it'})`;
+        return line;
+    });
+}
+const recordPath = (orgId, domainName) => `/orgs/${orgId}/domains/${encodeURIComponent(domainName)}/records`;
+// Number() reads "" as 0 and "1e3" as 1000, and keeps NaN, which the platform refuses as a type error naming no flag.
+function whole(flag, value) {
+    if (value === undefined)
+        return undefined;
+    const digits = value.trim();
+    if (!/^\d+$/.test(digits))
+        die(`${flag} must be a whole number, not ${JSON.stringify(value)}`);
+    return Number(digits);
+}
+export async function domainRecordsList(domainName, opts, deps) {
+    const { api, orgId } = await orgDeps(opts, deps);
+    const r = await api.request('GET', recordPath(orgId, domainName));
+    if (opts.json)
+        return printJson(r);
+    if (!r.items.length)
+        return info(`no records in ${domainName} — add one: insta domain records add ${domainName} A @ <ip>`);
+    for (const line of recordLines(r.items))
+        info(line);
+}
+export async function domainRecordsAdd(domainName, type, name, content, opts, deps) {
+    const body = { type: type.toUpperCase(), host: name, answer: content, ttl: whole('--ttl', opts.ttl), priority: whole('--priority', opts.priority) };
+    const { api, orgId } = await orgDeps(opts, deps);
+    const r = await api.request('POST', recordPath(orgId, domainName), body);
+    if (opts.json)
+        return printJson(r);
+    for (const line of recordLines([r]))
+        info(line);
+}
+export async function domainRecordsSet(domainName, id, opts, deps) {
+    const body = { type: opts.type?.toUpperCase(), host: opts.name, answer: opts.content, ttl: whole('--ttl', opts.ttl), priority: whole('--priority', opts.priority) };
+    if (Object.values(body).every((v) => v === undefined))
+        die('nothing to change — pass --type, --name, --content, --ttl or --priority');
+    const { api, orgId } = await orgDeps(opts, deps);
+    const r = await api.request('PATCH', `${recordPath(orgId, domainName)}/${encodeURIComponent(id)}`, body);
+    if (opts.json)
+        return printJson(r);
+    for (const line of recordLines([r]))
+        info(line);
+}
+export async function domainRecordsRemove(domainName, id, opts, deps) {
+    const { api, orgId } = await orgDeps(opts, deps);
+    const r = await api.request('DELETE', `${recordPath(orgId, domainName)}/${encodeURIComponent(id)}`);
+    if (opts.json)
+        return printJson(r);
+    info(`removed record ${id} from ${domainName}`);
+}
 //# sourceMappingURL=domain.js.map

package/dist/commands/secrets.js

@@ -162,27 +162,66 @@ async function readStdin() {
         data += chunk;
     return data.trim();
 }
+// Every platform SkipReason (applyTargets.ts) except 'unknown-service', which means the plan
+// could not resolve the service, not that it correctly chose to skip it.
+const BENIGN_SKIP_REASONS = new Set(['no-image', 'other-branch', 'caller-deploying', 'skip-deploy']);
+// Design doc §5's three outcomes: an unwritten entry is a hard failure; a written entry with a
+// failed or unexplained-skip service is durable but not fully live; anything else is success.
+export function applyVerdict(entries, services) {
+    if (entries.some((e) => !e.written))
+        return 'not-written';
+    const degraded = services.some((s) => s.result === 'failed' || (s.result === 'skipped' && !BENIGN_SKIP_REASONS.has(s.reason ?? '')));
+    return degraded ? 'degraded' : 'ok';
+}
+// util.ts already claims 1 (plain failure) and 2 (nothing ran, re-run is safe); this state fits
+// neither, so it takes the next code rather than overload one of theirs.
+export function applyExitCode(verdict) {
+    return verdict === 'ok' ? 0 : verdict === 'not-written' ? 1 : 3;
+}
+// Pure — one line per service, extending `branch.ts`'s create/skip convention; `started` matters most, it means new billing.
+export function applyServiceLines(services) {
+    return services.map((s) => {
+        if (s.result === 'started')
+            return `  + ${s.serviceId} started (was stopped — this now bills)`;
+        if (s.result === 'deployed')
+            return `  ~ ${s.serviceId} redeployed`;
+        if (s.result === 'failed')
+            return `  ! ${s.serviceId} failed${s.reason ? `: ${s.reason}` : ''}`;
+        return `  = ${s.serviceId}${s.reason ? ` (${s.reason})` : ''}`;
+    });
+}
 // Set a user secret. Project-wide by default; --branch scopes it to one branch. --service binds
 // 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) {
+export async function secretsSet(name, value, opts, deps) {
     // 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 d = deps ?? (await loadDeps());
     const v = value ?? (await readStdin());
     if (!v)
         die('value is required (pass as an argument or on stdin)');
-    const branch = opts.service ? (opts.branch ?? p.branch) : opts.branch;
-    const payload = { value: v, ...(branch ? { branch } : {}), ...(opts.service ? { service: opts.service } : {}) };
-    const res = await api.rawRequest('PUT', `/projects/${p.projectId}/secrets/${encodeURIComponent(name)}`, payload);
+    const branch = opts.service ? (opts.branch ?? d.linkedBranch) : opts.branch;
+    // The batch always deploys on ONE branch, so the top level falls back to the linked one even when the entry itself is project-wide.
+    const entry = { kind: 'set', name, value: v, ...(branch ? { branch } : {}), ...(opts.service ? { service: opts.service } : {}) };
+    const res = await d.api.rawRequest('POST', `/projects/${d.projectId}/apply`, { branch: branch ?? d.linkedBranch, entries: [entry] });
     if (handleApproval(res, opts.json))
         return;
+    const entries = res.body.entries ?? [];
+    const services = res.body.services ?? [];
+    const verdict = applyVerdict(entries, services);
+    process.exitCode = applyExitCode(verdict);
     if (opts.json)
-        return printJson({ ok: true, name, branch: branch ?? null, service: opts.service ?? null });
+        return printJson({ ok: verdict === 'ok', verdict, name, branch: branch ?? null, service: opts.service ?? null, entries, services });
     info(`set ${name}${opts.service ? ` → ${opts.service}` : ''} (${branch ? `branch ${branch}` : 'project-wide'})`);
+    for (const line of applyServiceLines(services))
+        info(line);
+    // Verdict note on stderr, after the per-service lines: not success, and not the same failure either.
+    if (verdict === 'not-written')
+        process.stderr.write(`error: ${name} was not written\n`);
+    else if (verdict === 'degraded')
+        process.stderr.write(`warning: ${name} is saved but not applied everywhere — retry the deploy for the services marked failed above, do not resend this value\n`);
 }
 // 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).
@@ -192,21 +231,26 @@ export async function secretsUnset(name, opts, deps) {
     // 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}`);
+    const entry = { kind: 'delete', name, ...(branch ? { branch } : {}), ...(opts.service ? { service: opts.service } : {}) };
+    const res = await d.api.rawRequest('POST', `/projects/${d.projectId}/apply`, { branch: branch ?? d.linkedBranch, entries: [entry] });
     if (handleApproval(res, opts.json))
         return;
+    const entries = res.body.entries ?? [];
+    const services = res.body.services ?? [];
+    const verdict = applyVerdict(entries, services);
+    process.exitCode = applyExitCode(verdict);
     // 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: branch ?? null, service: opts.service ?? null });
+        return printJson({ ok: verdict === 'ok', verdict, name, branch: branch ?? null, service: opts.service ?? null, entries, services });
     const scope = opts.service ? `${opts.service}, branch ${branch}` : branch ? `branch ${branch}` : 'project-wide';
     info(`unset ${name} (${scope})`);
+    for (const line of applyServiceLines(services))
+        info(line);
+    if (verdict === 'not-written')
+        process.stderr.write(`error: ${name} was not removed\n`);
+    else if (verdict === 'degraded')
+        process.stderr.write(`warning: ${name} is removed but not applied everywhere — retry the deploy for the services marked failed above\n`);
 }
 export async function secretsBind(envName, source, opts) {
     if (!opts.to)

package/dist/commands/ssh-config.js

@@ -115,10 +115,12 @@ export function renderConfigBlock(o) {
             throw new Error(`refusing to write an unsafe ssh HostName into ssh_config: ${JSON.stringify(e.hostName)}`);
         if (!isSafeConfigValue(e.user))
             throw new Error(`refusing to write an unsafe ssh User into ssh_config: ${JSON.stringify(e.user)}`);
+        if (!Number.isInteger(e.port) || e.port < 1 || e.port > 65535)
+            throw new Error(`refusing to write an unusable ssh Port into ssh_config: ${JSON.stringify(e.port)}`);
         lines.push(`Host ${e.alias}`, 
         // Without HostName and User the alias is not routing at all: ssh resolves
         // `api.insta` in DNS and logs in as the local OS username.
-        `  HostName ${e.hostName}`, `  User ${e.user}`, `  IdentityFile ${quoteConfigPath(o.identityFile)}`, `  CertificateFile ${quoteConfigPath(e.certificateFile)}`, 
+        `  HostName ${e.hostName}`, `  User ${e.user}`, `  Port ${e.port}`, `  IdentityFile ${quoteConfigPath(o.identityFile)}`, `  CertificateFile ${quoteConfigPath(e.certificateFile)}`, 
         // WRITTEN, not left to the default, and this is the one keyword where
         // being first in the file does not save us. First-wins settles a keyword
         // two blocks both set; a keyword we never set at all goes on being filled
@@ -210,6 +212,35 @@ export function upsertConfigBlock(existing, block) {
 export function hasOwnedBlock(existing) {
     return existing.split('\n').some(isMarkerLine(BLOCK_BEGIN));
 }
+/** Whether nothing that OpenSSH would read precedes the owned block. OpenSSH
+ *  takes the FIRST obtained value for each keyword, so a `Host *` stanza -- or a
+ *  bare global `Port 22` -- above our block silently overrides the block's
+ *  Port, HostName, User and credential; that is why upsertConfigBlock writes
+ *  the block at the top. Comments and blank lines above it are harmless and do
+ *  not count. false when there is no owned block at all. */
+export function ownedBlockIsFirst(existing) {
+    const lines = existing.split('\n');
+    const begin = lines.findIndex(isMarkerLine(BLOCK_BEGIN));
+    if (begin === -1)
+        return false;
+    return lines.slice(0, begin).every((l) => /^\s*(#.*)?$/.test(l));
+}
+/** The installed owned block, BEGIN through END marker inclusive, exactly as it
+ *  sits in the file; undefined when there is none (or an unterminated one). It
+ *  exists so a writer can compare what IS installed with what it WOULD render
+ *  and touch the file only when the two differ -- a stanza written before a
+ *  keyword existed (the Port line) is the case, and "nothing changed in the
+ *  response" is not the same question as "nothing would change in the file". */
+export function ownedBlock(existing) {
+    const lines = existing.split('\n');
+    const begin = lines.findIndex(isMarkerLine(BLOCK_BEGIN));
+    if (begin === -1)
+        return undefined;
+    const end = lines.findIndex((l, n) => n > begin && isMarkerLine(BLOCK_END)(l));
+    if (end === -1)
+        return undefined;
+    return lines.slice(begin, end + 1).join('\n');
+}
 /** A marker is a WHOLE LINE, never a substring of one.
  *
  *  Matching the marker text wherever it occurred made a user's comment that

package/dist/index.js

@@ -375,6 +375,21 @@ dom.command('list').description("Domains bought through InstaCloud in this org
     .action(guard((o) => domainCmd.domainList(o)));
 dom.command('status <name>').description("A bought domain's order and attach state").option('--json')
     .action(guard((name, o) => domainCmd.domainStatus(name, o)));
+const rec = dom.command('records').description('DNS records of a bought domain — the zone InstaCloud holds at the registrar');
+rec.command('list <domain>').description('Every record in the zone, managed ones marked')
+    .option('--org <id>', "target org (default: linked project's org)").option('--json')
+    .action(guard((domain, o) => domainCmd.domainRecordsList(domain, o)));
+rec.command('add <domain> <type> <name> <content>').description('Add a record — type A|AAAA|CNAME|ANAME|MX|TXT|SRV|NS; name "@" for the domain itself, a label like "www", or the full hostname under it')
+    .option('--ttl <seconds>', 'time to live in seconds (default 300)').option('--priority <n>', 'MX and SRV only')
+    .option('--org <id>', "target org (default: linked project's org)").option('--json')
+    .action(guard((domain, type, name, content, o) => domainCmd.domainRecordsAdd(domain, type, name, content, o)));
+rec.command('set <domain> <id>').description('Change a record by its id (from `records list`); fields you omit keep their value')
+    .option('--type <t>', 'A|AAAA|CNAME|ANAME|MX|TXT|SRV|NS').option('--name <host>', '"@" for the domain itself, a label like "www", or the full hostname under it').option('--content <value>', 'the answer').option('--ttl <seconds>', 'time to live in seconds').option('--priority <n>', 'MX and SRV only')
+    .option('--org <id>', "target org (default: linked project's org)").option('--json')
+    .action(guard((domain, id, o) => domainCmd.domainRecordsSet(domain, id, o)));
+rec.command('remove <domain> <id>').description('Remove a record by its id (a record InstaCloud published for a live hostname is refused)')
+    .option('--org <id>', "target org (default: linked project's org)").option('--json')
+    .action(guard((domain, id, o) => domainCmd.domainRecordsRemove(domain, id, o)));
 const bill = program.command('billing').description('Current billing cycle overview (tier / used / included / overage / credits / forecast + per-dimension & per-project breakdown)')
     .option('--org <id>', 'target org (default: linked project\'s org)').option('--json')
     .action(guard((o) => billing(o)));

package/package.json

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