@faable/faable 1.37.0 → 1.38.0

package/dist/api/FaableApi.js

@@ -151,6 +151,12 @@ class FaableApi {
     async getDeployment(deployment_id) {
         return data(this.client.get(`/deployment/${deployment_id}`));
     }
+    // Build payload of a deployment (runnable descriptor: runtime, profile,
+    // size, checksum). Authorized by the caller's access to the parent
+    // deployment, so no team header is needed — same posture as getDeployment.
+    async getArtifact(artifact_id) {
+        return data(this.client.get(`/artifact/${artifact_id}`));
+    }
     // Attach the captured build/deploy output to a deployment. The base client
     // timeout (10s) is too short for a multi-MB body on a slow uplink.
     async uploadDeploymentLogs(deployment_id, body) {

package/dist/commands/deploy/index.js

@@ -5,6 +5,7 @@ import { link } from '../link/index.js';
 import { domains } from './domains/index.js';
 import { git_context } from './git_context.js';
 import { deployments } from './inspect/deployments.js';
+import { inspect } from './inspect/inspect.js';
 import { apps_list } from './inspect/list.js';
 import { logs } from './inspect/logs.js';
 import { open_app } from './inspect/open.js';
@@ -32,6 +33,7 @@ const deploy = {
             .command(status)
             .command(apps_list)
             .command(deployments)
+            .command(inspect)
             .command(open_app)
             .command(trigger)
             .command(redeploy)

package/dist/commands/deploy/inspect/deployments.js

@@ -34,6 +34,7 @@ const deployments = {
             const live = d.id === app.status?.deployment ? '  ← live' : '';
             log.info(`  ${deployment_row(d)}${live}`);
         }
+        log.info(`Full record of one: faable deploy inspect <deployment_id>`);
     }
 };
 

package/dist/commands/deploy/inspect/detail.js

@@ -0,0 +1,122 @@
+import { phase_badge, when, short_commit, detected_summary } from './format.js';
+
+// Pure rendering of `faable deploy inspect` — everything the platform
+// recorded about ONE deployment, in reading order. Kept out of the handler
+// so the layout is testable without an API.
+const format_bytes = (bytes) => {
+    if (!bytes || bytes < 0)
+        return '-';
+    const units = ['B', 'KB', 'MB', 'GB'];
+    let value = bytes;
+    let unit = 0;
+    while (value >= 1024 && unit < units.length - 1) {
+        value /= 1024;
+        unit++;
+    }
+    return `${unit === 0 ? value : value.toFixed(1)} ${units[unit]}`;
+};
+// "refs/heads/main" → "main"; a bare branch name passes through.
+const short_ref = (ref) => ref ? ref.replace(/^refs\/(heads|tags)\//, '') : null;
+// "next-standalone · node 22 · 41.2 MB" from the deploy-v3 runnable
+// descriptor; null while the build has not sealed one yet.
+const artifact_summary = (artifact) => {
+    const a = artifact?.artifact;
+    if (!a)
+        return null;
+    const runtime = [a.runtime.name, a.runtime.version].filter(Boolean).join(' ');
+    return [a.profile, runtime, format_bytes(a.size)].filter(Boolean).join(' · ');
+};
+// First line of a commit message (the subject), quoted.
+const commit_subject = (message) => {
+    const subject = message?.split('\n')[0].trim();
+    return subject ? `"${subject}"` : null;
+};
+const label = (name, value) => `  ${`${name}:`.padEnd(12)}${value}`;
+// Command suggestions that match the phase: what you would actually run next,
+// rendered as labeled lines so they stay in the same column as the record.
+// A BUILD_ERROR never ran, so it has no runtime logs to offer; a retired
+// deployment does (for 24h — the runtime window), plus its frozen build output.
+const next_steps = (d, is_live) => {
+    const phase = d.status?.phase ?? '';
+    const runtime = label('Logs', `faable deploy logs -d ${d.id}`);
+    const build = label('Build', `faable deploy logs --build -d ${d.id}`);
+    const retry = label('Retry', `faable deploy redeploy ${d.id}`);
+    if (phase === 'BUILD_ERROR')
+        return [build, retry];
+    if (phase === 'ERROR')
+        return [runtime, build, retry];
+    if (phase === 'BUILDING' || phase === 'QUEUED' || phase === 'UNKNOWN') {
+        return [label('Follow', `faable deploy logs --build -d ${d.id} --follow`)];
+    }
+    if (is_live)
+        return [label('Logs', 'faable deploy logs')];
+    return [runtime, build];
+};
+const deployment_detail = (args) => {
+    const { app, deployment: d, artifact } = args;
+    const is_live = d.id === app.status?.deployment;
+    const lines = [];
+    lines.push(`${phase_badge(d.status?.phase)}  ${d.id}`);
+    lines.push(label('App', `${app.name} (${app.id})`));
+    if (d.createdAt) {
+        lines.push(label('Created', `${when(d.createdAt)} (${d.createdAt})`));
+    }
+    lines.push(label('Trigger', d.trigger === 'webhook' ? 'push (webhook)' : 'cli'));
+    lines.push(label('Serving', is_live ? `yes — https://${app.url}` : 'no (not live)'));
+    if (d.github_commit) {
+        const attribution = [
+            short_ref(d.github_ref),
+            d.github_actor && `by ${d.github_actor}`
+        ]
+            .filter(Boolean)
+            .join(' ');
+        const commit = [
+            short_commit(d.github_commit),
+            commit_subject(d.github_commit_message),
+            attribution && `(${attribution})`
+        ]
+            .filter(Boolean)
+            .join(' ');
+        lines.push(label('Commit', commit));
+    }
+    if (d.release)
+        lines.push(label('Release', d.release));
+    // Stack the builder detected for THIS build (falls back to the app's, which
+    // is the last successful detection).
+    const stack = detected_summary(d.detected ?? app.detected);
+    if (stack)
+        lines.push(label('Stack', stack));
+    const runnable = artifact_summary(artifact);
+    if (runnable) {
+        const ready = d.artifact_ready_at
+            ? ` (sealed ${when(d.artifact_ready_at)})`
+            : '';
+        lines.push(label('Artifact', `${runnable}${ready}`));
+    }
+    if (artifact?.artifact?.start_command) {
+        lines.push(label('Start', artifact.artifact.start_command));
+    }
+    if (artifact?.purged_at) {
+        lines.push(label('Purged', `${when(artifact.purged_at)} — source no longer stored`));
+    }
+    if (d.image)
+        lines.push(label('Image', d.image));
+    if (d.status?.runtime_image) {
+        lines.push(label('Runtime', d.status.runtime_image));
+    }
+    if (d.redeploy_of)
+        lines.push(label('Rebuild of', d.redeploy_of));
+    if (d.quota_released_at) {
+        lines.push(label('Quota', `hold released ${when(d.quota_released_at)}`));
+    }
+    if (d.status?.reason) {
+        lines.push('  Reason:');
+        for (const line of d.status.reason.split('\n')) {
+            lines.push(`    ${line}`);
+        }
+    }
+    lines.push(...next_steps(d, is_live));
+    return lines;
+};
+
+export { artifact_summary, deployment_detail, format_bytes, short_ref };

package/dist/commands/deploy/inspect/inspect.js

@@ -0,0 +1,67 @@
+import { requireApi } from '../../../api/context.js';
+import { log } from '../../../log.js';
+import { resolve_app_id } from '../resolve_app_id.js';
+import { deployment_detail } from './detail.js';
+
+const inspect = {
+    command: 'inspect [deployment]',
+    describe: 'Show everything recorded about one deployment',
+    builder: yargs => yargs
+        .positional('deployment', {
+        type: 'string',
+        description: 'Deployment id (defaults to the latest one of the app)'
+    })
+        .option('app', {
+        alias: 'a',
+        type: 'string',
+        description: 'App Identifier (defaults to the linked app)'
+    })
+        .option('json', {
+        type: 'boolean',
+        default: false,
+        description: 'Output raw JSON (for scripting)'
+    })
+        .example('$0 deploy inspect deployment_a1b2c3', 'Everything about that deployment: phase, commit, artifact, failure reason')
+        .example('$0 deploy inspect', 'Same, for the latest deployment')
+        .showHelpOnFail(false),
+    handler: async (args) => {
+        const ctx = await requireApi();
+        const app_id = await resolve_app_id(args.app, ctx.appId, ctx.api);
+        const app = await ctx.api.getApp(app_id);
+        let deployment_id = args.deployment;
+        if (!deployment_id) {
+            const rows = await ctx.api.listDeployments(app_id, app.team);
+            deployment_id = rows[0]?.id;
+            if (!deployment_id) {
+                log.info(`📭 ${app.name} has no deployments yet.`);
+                return;
+            }
+        }
+        const deployment = await ctx.api.getDeployment(deployment_id);
+        // A deployment id is globally unique but the app comes from the link/--app
+        // flag: refuse to render one against the wrong app instead of printing a
+        // mismatched "Serving"/"App" header.
+        if (deployment.app_id && deployment.app_id !== app_id) {
+            throw new Error(`${deployment_id} belongs to another app (${deployment.app_id}), not ${app.name} (${app_id}). Pass --app ${deployment.app_id}.`);
+        }
+        // The runnable descriptor (runtime, profile, size) lives on the artifact
+        // row. Absent on image deploys, and a purged/expired row must not break
+        // the read — the rest of the record is still worth showing.
+        let artifact = null;
+        if (deployment.artifact_id) {
+            artifact = await ctx.api.getArtifact(deployment.artifact_id).catch(() => {
+                log.debug(`Could not read artifact ${deployment.artifact_id}`);
+                return null;
+            });
+        }
+        if (args.json) {
+            process.stdout.write(JSON.stringify({ ...deployment, artifact }, null, 2) + '\n');
+            return;
+        }
+        for (const line of deployment_detail({ app, deployment, artifact })) {
+            log.info(line);
+        }
+    }
+};
+
+export { inspect };

package/dist/commands/deploy/inspect/logs.js

@@ -33,6 +33,7 @@ const logs = {
         description: 'With --build: keep tailing the output while the build runs'
     })
         .example('$0 deploy logs', 'Runtime logs of the linked app (last 24h)')
+        .example('$0 deploy logs -d deployment_a1b2c3', 'Runtime logs of ONE deployment (last 24h)')
         .example('$0 deploy logs --build', 'Build output of the latest deployment')
         .example('$0 deploy logs --build --follow', 'Tail the build that is running right now')
         .showHelpOnFail(false),
@@ -87,12 +88,17 @@ const logs = {
         const lines = await ctx.api.getAppLogs(app_id, {
             deployment_id: args.deployment
         });
+        // Say WHICH scope came back empty: with -d the 24h window is usually the
+        // reason (a retired deployment stopped writing when it stopped serving).
+        const scope = args.deployment
+            ? `${args.deployment} (${app.name})`
+            : `${app.name} (${app_id})`;
         if (lines.length === 0) {
-            log.info(`📭 No runtime logs in the last 24h for ${app.name} (${app_id}).`);
-            log.info(`For build output, use: faable deploy logs --build`);
+            log.info(`📭 No runtime logs in the last 24h for ${scope}.`);
+            log.info(`For build output, use: faable deploy logs --build${args.deployment ? ` -d ${args.deployment}` : ''}`);
             return;
         }
-        log.info(`📜 Runtime logs of ${app.name} (last 24h, newest last):`);
+        log.info(`📜 Runtime logs of ${app.name}${args.deployment ? ` · ${args.deployment}` : ''} (last 24h, newest last):`);
         for (const line of format_log_lines(lines)) {
             process.stdout.write(line + '\n');
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@faable/faable",
-  "version": "1.37.0",
+  "version": "1.38.0",
   "main": "dist/index.js",
   "license": "MIT",
   "author": "Marc Pomar <marc@faable.com>",