insta 0.0.80 → 0.0.81

package/README.md

@@ -226,6 +226,7 @@ build never reaches a production installer.
 | `insta db` | `url` (print the postgres DSN) · `connect` (psql session) · `limits` · `stats` · `always-on` · `volume` |
 | `insta regions` | Regions available for postgres and compute |
 | `insta manifest` | Agent-legible view of every branch and its URLs |
+| `insta build-logs <id>` | Read source-build output; `--source archive` (default) uses the deploy operation ID, `--source github` uses a GitHub build ID; `--follow` watches output, `--json` returns one snapshot |
 | `insta metrics` · `logs` · `events` | Service metrics; runtime logs (`--deploy` for deploy events); audit timeline |
 | `insta usage` · `billing` | Usage by billing dimension; `billing upgrade` · `billing portal` |
 | `insta approvals` | `list` · `approve` · `deny` |

package/dist/build-logs.js

@@ -0,0 +1,206 @@
+import { createHash } from 'node:crypto';
+import { stripVTControlCharacters } from 'node:util';
+import { ApiError } from './api.js';
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const terminal = new Set(['succeeded', 'failed', 'canceled', 'unknown', 'live']);
+const entryKey = (step, entry) => createHash('sha256').update(JSON.stringify([step, entry.timestamp, entry.message])).digest('hex');
+class LogsNotReady extends Error {
+}
+export async function readBuildLogs(api, projectId, source, buildId, signal = AbortSignal.timeout(30_000), follow) {
+    let bytes = 0;
+    let requests = 0;
+    let pending = false;
+    async function pages(step) {
+        const result = [];
+        const seen = new Set();
+        const tail = step ? follow?.tails.get(step) ?? { counts: new Map() } : undefined;
+        let cursor = tail?.cursor;
+        do {
+            if (++requests > 200)
+                throw new Error('build logs exceed the per-read page limit');
+            const params = new URLSearchParams({ ...(step ? { step } : {}), ...(cursor ? { cursor } : {}) });
+            const { body } = await api.rawRequest('GET', `/projects/${projectId}/builds/${source}/${encodeURIComponent(buildId)}/logs?${params}`, undefined, { signal });
+            if (!body || !['ready', 'pending', 'unsupported', 'unavailable'].includes(body.state) || !Array.isArray(body.steps) || !Array.isArray(body.entries))
+                throw new Error('invalid build log response');
+            bytes += Buffer.byteLength(JSON.stringify(body));
+            if (bytes > 16 * 1024 * 1024)
+                throw new Error('build logs exceed the 16 MiB per-read limit');
+            if (body.state === 'pending')
+                pending = true;
+            if (step && follow && body.state === 'ready') {
+                const counts = new Map(tail.counts);
+                const entries = body.entries.map(entry => {
+                    const key = entryKey(step, entry);
+                    const occurrence = (counts.get(key) ?? 0) + 1;
+                    if (counts.size >= 100_000 && !counts.has(key))
+                        throw new Error('live build logs exceed the display limit');
+                    counts.set(key, occurrence);
+                    return { ...entry, occurrence };
+                });
+                const name = steps.find(item => item.digest === step).name;
+                follow.emit({ ...body, output: [{ step, name, entries }] });
+                if (body.nextCursor) {
+                    tail.counts = counts;
+                    tail.cursor = body.nextCursor;
+                }
+                follow.tails.set(step, tail);
+                result.push({ ...body, entries: [] });
+            }
+            else
+                result.push(body);
+            cursor = body.nextCursor || undefined;
+            if (cursor && seen.has(cursor))
+                throw new Error('build log pagination did not advance');
+            if (cursor)
+                seen.add(cursor);
+        } while (cursor);
+        return result;
+    }
+    const stepPages = await pages();
+    const first = stepPages[0];
+    if (stepPages.some((page) => page.state !== first.state))
+        throw new LogsNotReady('build steps are temporarily unavailable');
+    const steps = stepPages.flatMap((page) => page.steps);
+    follow?.emit({ ...first, steps, output: [] });
+    const output = [];
+    for (const step of steps) {
+        if (!step.hasLogs)
+            continue;
+        const logs = await pages(step.digest);
+        if (logs.some((page) => page.state !== 'ready' && page.state !== 'pending'))
+            throw new LogsNotReady('step output is temporarily unavailable');
+        output.push({ step: step.digest, name: step.name, entries: logs.flatMap((page) => page.entries) });
+    }
+    return { ...first, nextCursor: undefined, state: pending ? 'pending' : first.state, steps, output };
+}
+const safeText = (text) => stripVTControlCharacters(text).replace(/[\x00-\x08\x0b-\x1f\x7f]/g, '');
+export class BuildLogPrinter {
+    seen = new Map();
+    diagnostics = new Set();
+    lastStep;
+    lineStart = true;
+    finishLine(write) {
+        if (!this.lineStart)
+            write('\n');
+        this.lineStart = true;
+    }
+    print(snapshot, write) {
+        const errors = [
+            ...(snapshot.error ? [{ id: 'build', message: snapshot.error }] : []),
+            ...snapshot.steps.filter(step => step.error).map(step => ({ id: step.digest, message: `${step.name}: ${step.error}` })),
+        ];
+        for (const error of errors) {
+            const key = JSON.stringify([error.id, error.message]);
+            if (this.diagnostics.has(key))
+                continue;
+            this.finishLine(write);
+            write(safeText(error.message) + '\n');
+            this.diagnostics.add(key);
+        }
+        for (const step of snapshot.output) {
+            const counts = new Map();
+            for (const entry of step.entries) {
+                const key = entryKey(step.step, entry);
+                const count = entry.occurrence ?? (counts.get(key) ?? 0) + 1;
+                counts.set(key, count);
+                if (count <= (this.seen.get(key) ?? 0))
+                    continue;
+                if (this.seen.size >= 100_000)
+                    throw new Error('live build logs exceed the display limit');
+                if (this.lastStep !== step.step) {
+                    this.finishLine(write);
+                    write(safeText(step.name) + '\n');
+                    this.lastStep = step.step;
+                }
+                const text = safeText(entry.message);
+                write(text);
+                if (text)
+                    this.lineStart = text.endsWith('\n');
+            }
+            for (const [key, count] of counts)
+                this.seen.set(key, Math.max(count, this.seen.get(key) ?? 0));
+        }
+    }
+}
+export function archiveLogWatcher(api, projectId, write, wait = sleep) {
+    const printer = new BuildLogPrinter();
+    const follow = { tails: new Map(), emit: snapshot => printer.print(snapshot, write) };
+    let warned = '';
+    let unavailable = false;
+    return async (buildId, finished, remainingMs = 30_000) => {
+        if (unavailable)
+            return;
+        const deadline = Date.now() + Math.min(remainingMs, finished ? 18_000 : 3000);
+        for (let attempt = 0; attempt < (finished ? 6 : 1); attempt++) {
+            if (attempt > 0)
+                await wait(Math.min(3000, Math.max(0, deadline - Date.now())));
+            const remaining = deadline - Date.now();
+            if (remaining <= 0)
+                return;
+            if (finished && (attempt === 0 || attempt === 5))
+                follow.tails.clear();
+            try {
+                const snapshot = await readBuildLogs(api, projectId, 'archive', buildId, AbortSignal.timeout(remaining), follow);
+                if (snapshot.state === 'unsupported') {
+                    printer.finishLine(write);
+                    write('Build logs are not supported for this build provider.\n');
+                    unavailable = true;
+                    return;
+                }
+                if (snapshot.state === 'unavailable')
+                    throw new Error('build logs unavailable');
+                warned = '';
+            }
+            catch (error) {
+                if (error instanceof ApiError && error.status === 400)
+                    follow.tails.clear();
+                printer.finishLine(write);
+                const message = `Could not read build logs. Retry with: insta build-logs ${buildId}\n`;
+                if (warned !== message)
+                    write(message);
+                warned = message;
+            }
+        }
+    };
+}
+export async function followBuildLogs(api, projectId, source, buildId, write, wait = sleep) {
+    const printer = new BuildLogPrinter();
+    const follow = { tails: new Map(), emit: snapshot => printer.print(snapshot, write) };
+    let finalReads = 0;
+    let failures = 0;
+    for (;;) {
+        let snapshot;
+        try {
+            snapshot = await readBuildLogs(api, projectId, source, buildId, AbortSignal.timeout(30_000), follow);
+            failures = 0;
+        }
+        catch (error) {
+            const retryable = error instanceof ApiError ? error.status === 400 || error.status === 429 || error.status >= 500
+                : error instanceof LogsNotReady || error instanceof TypeError || (error instanceof Error && ['AbortError', 'TimeoutError'].includes(error.name));
+            if (error instanceof ApiError && error.status === 400)
+                follow.tails.clear();
+            if (!retryable || ++failures >= 5) {
+                printer.finishLine(write);
+                throw error;
+            }
+            printer.finishLine(write);
+            write('Could not refresh build logs; retrying…\n');
+            await wait(3000);
+            continue;
+        }
+        if (snapshot.state === 'unsupported' || snapshot.state === 'unavailable') {
+            printer.finishLine(write);
+            throw new Error(`Build logs ${snapshot.state}`);
+        }
+        if (snapshot.state === 'ready' && terminal.has(snapshot.buildState)) {
+            if (++finalReads >= 6) {
+                printer.finishLine(write);
+                return;
+            }
+            if (finalReads === 1 || finalReads === 5)
+                follow.tails.clear();
+        }
+        await wait(3000);
+    }
+}
+//# sourceMappingURL=build-logs.js.map

package/dist/commands/build-logs.js

@@ -0,0 +1,23 @@
+import { ApiClient, requireProject } from '../api.js';
+import { BuildLogPrinter, followBuildLogs, readBuildLogs } from '../build-logs.js';
+import { info, printJson } from '../util.js';
+export async function buildLogs(buildId, opts) {
+    if (opts.source !== 'github' && opts.source !== 'archive')
+        throw new Error('--source must be github or archive');
+    if (opts.follow && opts.json)
+        throw new Error('--follow cannot be combined with --json');
+    const api = await ApiClient.load();
+    const { projectId } = await requireProject();
+    if (opts.follow)
+        return followBuildLogs(api, projectId, opts.source, buildId, (text) => { process.stdout.write(text); });
+    const snapshot = await readBuildLogs(api, projectId, opts.source, buildId);
+    if (opts.json)
+        return printJson(snapshot);
+    const printer = new BuildLogPrinter();
+    const write = (text) => { process.stdout.write(text); };
+    printer.print(snapshot, write);
+    printer.finishLine(write);
+    if (snapshot.state !== 'ready')
+        info(`Build logs ${snapshot.state}`);
+}
+//# sourceMappingURL=build-logs.js.map

package/dist/commands/deploy.js

@@ -1,3 +1,4 @@
+import { archiveLogWatcher } from '../build-logs.js';
 import { resolve, join } from 'node:path';
 import { existsSync, readFileSync } from 'node:fs';
 import { ApiClient, ApiError, requireProject } from '../api.js';
@@ -74,7 +75,13 @@ export async function prepareSource(api, projectId, dir, branch, opts, run = opt
         // flyctl, local-docker and legacy all end in an image, and all three need a Dockerfile.
         return { image: await buildFromSource(api, projectId, dir, branch, opts, run) };
     }
-    const log = note(opts);
+    const stream = opts.json ? process.stderr : process.stdout;
+    let lineStart = true;
+    const finishLine = () => { if (!lineStart)
+        stream.write('\n'); lineStart = true; };
+    const log = (message) => { finishLine(); note(opts)(message); };
+    const writeOutput = (text) => { stream.write(text); if (text)
+        lineStart = text.endsWith('\n'); };
     const absDir = resolve(process.cwd(), dir);
     const caveat = windowsModeCaveat();
     if (caveat)
@@ -89,7 +96,8 @@ export async function prepareSource(api, projectId, dir, branch, opts, run = opt
     // time, because a platform request has to answer inside the ALB's 60s while a build runs minutes.
     // A repo-connected service refuses this with a 409 the same way it refuses an image deploy, and
     // the hint that names the FLAG rather than the API field lives here, beside the `/deploy` path.
-    const out = await deployArchive(api, projectId, ref, branch, opts, Date.now, undefined, log)
+    const out = await deployArchive(api, projectId, ref, branch, opts, Date.now, undefined, log, archiveLogWatcher(api, projectId, writeOutput))
+        .finally(finishLine)
         .catch((e) => { throw e instanceof ApiError && e.status === 409 ? new ApiError(e.status, repoConnectedHint(e.message), e.body) : e; });
     if (!out)
         return null;

package/dist/deploy-archive.js

@@ -64,7 +64,7 @@ const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 // The operation is idempotent on (target, archive, build kind), so a re-run after approving finds
 // the one it already started rather than building again: same image, same result, no second
 // approval for a build that already happened.
-export async function deployArchive(api, projectId, ref, branch, opts, now = Date.now, wait = sleep, log = () => { }) {
+export async function deployArchive(api, projectId, ref, branch, opts, now = Date.now, wait = sleep, log = () => { }, watchLogs) {
     const started = await api.rawRequest('POST', `/projects/${projectId}/archive-deploys`, {
         branch,
         group: opts.group,
@@ -79,6 +79,7 @@ export async function deployArchive(api, projectId, ref, branch, opts, now = Dat
     const operationId = started.body?.operationId;
     if (typeof operationId !== 'string' || !operationId)
         throw new Error('the platform accepted the deploy but returned no operation id — re-run the deploy');
+    log(`build logs: insta build-logs ${operationId}`);
     if (started.body?.resumed === true)
         log('resuming the deploy this archive already started');
     const deadline = now() + DEPLOY_DEADLINE_MS;
@@ -99,6 +100,7 @@ export async function deployArchive(api, projectId, ref, branch, opts, now = Dat
             throw remaining <= POLL_REQUEST_TIMEOUT_MS ? overdue() : new Error(`the platform did not answer a status poll within ${POLL_REQUEST_TIMEOUT_MS / 1000}s — check \`insta status\` or re-run`);
         });
         const state = res.body?.state;
+        await watchLogs?.(operationId, state === 'failed' || state === 'live', Math.max(0, deadline - now()));
         // A failed operation is an ANSWER, not a transport error: the poll worked, and the sentence
         // it carries (usually the gateway's own, e.g. "no Dockerfile at ./api") is the one to show.
         if (state === 'failed') {

package/dist/index.js

@@ -21,6 +21,7 @@ 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 { buildLogs } from './commands/build-logs.js';
 import * as computeCmd from './commands/compute.js';
 import * as githubCmd from './commands/github.js';
 import * as dbCmd from './commands/db.js';
@@ -347,6 +348,9 @@ 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('build-logs <build-id>').description('Read source-build output for a deploy operation or GitHub build')
+    .option('--source <source>', 'archive or github', 'archive').option('--follow', 'poll new output until the build ends').option('--json')
+    .action(guard((id, opts) => buildLogs(id, opts)));
 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)));

package/package.json

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