@frontera-sdk/cli 1.52.39 → 1.52.41

package/src/commands/app/deploy.ts

@@ -1,26 +1,56 @@
-import { existsSync, statSync } from 'node:fs'
+import { spawnSync } from 'node:child_process'
+import { existsSync, readFileSync, statSync } from 'node:fs'
 import { join } from 'node:path'
 
 import { AppsApi } from '../../api/apps-api'
-import { CliError } from '../../errors'
+import { isKeyToken } from '../../auth-verify'
+import { CliError, UsageError } from '../../errors'
 import { resolveManifest } from '../../manifest'
 import { collectSourceFiles, formatBytes } from '../../packaging'
 import { packDirectory } from '../../pack'
-import { readPackageVersion, writeAppId, writeState } from '../../project'
+import { collectAppContract } from '../../app-contract'
+import { writeAppId, writeState } from '../../project'
 import { collectBuildProvenance } from '../../provenance'
 import { validateStaticAppProject } from '../../static-app-validation'
-import { describeRenderEvidence, readRenderEvidence, readRenderThumbnail } from '../../render-evidence'
+import { describeRenderEvidence, readRenderEvidence, readRenderThumbnail, type RenderEvidence } from '../../render-evidence'
 import { createTarGz } from '../../tar'
+import { keepBuildWrittenFiles } from '../../local/local-app-pulled'
+import { setAsideCopyPaths } from '../../local/local-app-sdk-paths'
 import { requireProjectFrom } from './shared'
+import { canPrompt } from '../../prompt'
 import { flagBool, flagString, type Command } from '../types'
 
 /**
- * Publish, and say the useful thing when the version is taken.
+ * A release label is a version, as `package.json` gives one: what the
+ * platform accepts (`RELEASE_LABEL` in the service's app-deployment-id.ts,
+ * which refuses anything else with a 400 after the build and upload).
+ */
+export const RELEASE_LABEL = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/
+
+/** A label the platform accepts, made from one it would refuse: `e2e-1` → `0.1.0-e2e-1`, keeping the App's own version when it has one. */
+export function suggestedLabel(label: string, packageVersion?: string | null): string {
+  const base = packageVersion && /^\d+\.\d+\.\d+$/.test(packageVersion) ? packageVersion : '0.1.0'
+  const tail = label.replace(/^v(?=\d)/i, '').replace(/[^0-9A-Za-z.-]+/g, '-').replace(/^[-.]+|[-.]+$/g, '')
+  if (RELEASE_LABEL.test(tail)) return tail
+  const partial = /^(\d+)(?:\.(\d+))?(?:\.(\d+))?$/.exec(tail)
+  if (partial) return `${partial[1]}.${partial[2] ?? 0}.${partial[3] ?? 0}`
+  return tail ? `${base}-${tail}` : base
+}
+
+/** Refuse a label the platform would refuse, before anything is built or uploaded. */
+export function assertReleaseLabel(label: string | null, packageVersion?: string | null): void {
+  if (label === null || RELEASE_LABEL.test(label)) return
+  throw new UsageError(
+    `release label "${label}" is not a version: labels look like 1.4.0, or 1.4.0-e2e.1 with a suffix`,
+    `pass --label ${suggestedLabel(label, packageVersion)}, or deploy without --label (every deployment has its own id anyway)`,
+  )
+}
+
+/**
+ * Publish, and say the useful thing when the release label is taken.
  *
- * Versions are immutable, so republishing one is a CONFLICT — but the generic
- * conflict hint says "re-fetch, reapply your edit", which is the recovery for a
- * DRAFT conflict and does nothing here. The fix is to bump a number, and this
- * is the only layer that knows that.
+ * Every deployment gets its own id, so a deploy never collides with another;
+ * only an optional release label can, and the fix is a new label.
  */
 async function publish(
   client: AppsApi,
@@ -31,16 +61,109 @@ async function publish(
     return await client.publish(appId, args)
   } catch (err) {
     const code = (err as { code?: string }).code
-    if (code === 'CONFLICT' || code === 'DRAFT_CONFLICT') {
-      throw new CliError(`version ${args.version} already exists for this app`, {
+    if ((code === 'CONFLICT' || code === 'DRAFT_CONFLICT') && args.label) {
+      throw new CliError(`release label ${args.label} is already used by another deployment of this app`, {
         code: 'CONFLICT',
-        hint: 'versions are immutable — bump "version" in package.json, or pass --version <next>',
+        hint: 'labels are unique per App — pass a new --label, or deploy without one',
       })
     }
     throw err
   }
 }
 
+/** The App's `package.json` version, when it has one. */
+function packageVersionAt(root: string): string | null {
+  try {
+    const v = (JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) as { version?: unknown }).version
+    return typeof v === 'string' ? v : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * The App's own check (`bun run check`: its typecheck and tests, as the
+ * scaffold defines it), when it has one. Its result travels with the
+ * deployment, and a required build check holds production on it.
+ */
+function runBuildCheck(root: string, skip: boolean): { status: 'passed' | 'failed' | 'skipped'; detail: string; output?: string } {
+  if (skip) return { status: 'skipped', detail: 'Deployed with --skip-build-check' }
+  let scripts: Record<string, string> = {}
+  try {
+    scripts = (JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) as { scripts?: Record<string, string> }).scripts ?? {}
+  } catch {
+    scripts = {}
+  }
+  if (!scripts.check) return { status: 'passed', detail: 'Validated as a static export with a current build (no check script)' }
+  const run = spawnSync('bun', ['run', 'check'], { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 10 * 60_000 })
+  if (run.status === 0) return { status: 'passed', detail: 'bun run check passed; validated as a static export' }
+  const output = `${run.stdout ?? ''}${run.stderr ?? ''}`.trim().split('\n').slice(-25).join('\n')
+  return { status: 'failed', detail: 'bun run check failed', output }
+}
+
+/**
+ * Run the App's build or its check in its folder as `local check` and `app
+ * dev` run them, so the three agree on whether it builds:
+ *
+ * - A pulled App installed as its bun.lock records, whose tsconfig.json still
+ *   sends the SDK to the older copy under src/frontera/, runs with those
+ *   `paths` set aside (`setAsideCopyPaths`) and put back byte for byte with
+ *   their time, so it builds against the release it was written for.
+ * - What the run writes into the folder's top (`tsconfig.tsbuildinfo`,
+ *   `next-env.d.ts`, `next build`'s `tsconfig.json`) goes back as it was, and
+ *   one it created is removed (`keepBuildWrittenFiles`): a deploy is not a
+ *   change to the tree.
+ *
+ * Both put back with the times the files had, so a render before the deploy
+ * is still of this source (`render-evidence.ts`), and the build's are back
+ * before the source is packaged.
+ */
+function asLocalCheckRuns<T>(root: string, note: (line: string) => void, run: () => T): T {
+  const putBack = keepBuildWrittenFiles(root)
+  const aside = setAsideCopyPaths(root)
+  if (aside) note(`  ${aside.line}`)
+  try {
+    return run()
+  } finally {
+    if (aside) note(`  ${aside.restore()}`)
+    const restored = putBack()
+    if (restored.length) note(`  it wrote ${restored.join(', ')}; put back as ${restored.length === 1 ? 'it was' : 'they were'} before it`)
+  }
+}
+
+/**
+ * `bun run build`, before anything is validated, for `--build`: what
+ * `app_deploy` runs so a deploy never ships the bundle from before the last
+ * edit. Its failure stops the deploy with the build's own last lines.
+ */
+function runBuild(root: string): void {
+  const run = spawnSync('bun', ['run', 'build'], { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 10 * 60_000 })
+  if (run.status === 0) return
+  const output = `${run.stdout ?? ''}${run.stderr ?? ''}`.trim().split('\n').slice(-30).join('\n')
+  throw new CliError('bun run build failed; nothing was deployed', { code: 'VALIDATION_ERROR', hint: output || 'run `bun run build` to see why' })
+}
+
+/**
+ * Whether the render this deployment carries was clean, in the terms the
+ * platform's checks use (`app-deployment-checks.ts`): a fresh render, no
+ * console errors (the Fresh render check), no serious accessibility findings
+ * (the Accessibility check), and no failed requests, which that check
+ * reports. A preview deploys either way; this says what a person promoting
+ * it should know.
+ */
+export function renderVerdict(evidence: RenderEvidence): { ok: boolean; problems: string[] } {
+  const problems: string[] = []
+  if (evidence.notThisApp) problems.push(`the last render (${evidence.notThisApp.url}) is not attached: ${evidence.notThisApp.why}. Render the App (app_render with no url) and deploy again`)
+  else if (evidence.reason === 'none') problems.push('nobody has rendered this build: app_render (or a browser) has not opened it')
+  if (evidence.reason === 'stale') problems.push('the source changed after the last render, so nobody has seen this version')
+  if (evidence.rendered) {
+    const plural = (n: number, word: string) => `${n} ${word}${n === 1 ? '' : 's'}`
+    if (evidence.consoleErrors) problems.push(`the last render had ${plural(evidence.consoleErrors, 'console error')}`)
+    if (evidence.failedRequests) problems.push(`the last render had ${plural(evidence.failedRequests, 'failed request')}`)
+    if (evidence.a11y?.violations) problems.push(`the accessibility scan found ${plural(evidence.a11y.violations, 'serious violation')}`)
+  }
+  return { ok: problems.length === 0, problems }
+}
 
 /**
  * Newest modification time across a set of project-relative files.
@@ -73,23 +196,50 @@ export const appDeploy: Command = {
     noun: 'app',
     verb: 'deploy',
     args: [],
-    flags: { version: 'string', 'no-promote': 'boolean', 'skip-build-check': 'boolean' },
-    summary: 'Build output up to an immutable version, and promote it',
-    examples: ['frontera app deploy', 'frontera app deploy --no-promote'],
+    flags: { label: 'string', version: 'string', prod: 'boolean', preview: 'boolean', 'no-promote': 'boolean', 'skip-build-check': 'boolean', build: 'boolean' },
+    summary: 'Upload the build as a preview deployment; --build to build first, --prod to go live',
+    details: [
+      'A deploy is a preview unless --prod is given. A pipeline (a key, no terminal) must say which it wants: --prod or --preview. Without either it exits with an error, so a pipeline written when a deploy went live stops instead of silently making previews.',
+    ],
+    examples: ['frontera app deploy', 'frontera app deploy --build', 'frontera app deploy --label 1.4.0', 'frontera app deploy --prod', 'frontera app deploy --preview', 'frontera app deploy --prod --no-promote'],
     needsProject: true,
   },
 
   async run(ctx) {
     const project = requireProjectFrom(ctx)
-    const version = flagString(ctx, 'version') ?? readPackageVersion(project.root)
+    // `--version` is the label's earlier name; a deployment's id is the platform's.
+    const label = flagString(ctx, 'label') ?? flagString(ctx, 'version') ?? null
+    if (flagString(ctx, 'version') && !flagString(ctx, 'label')) ctx.output.note('  --version is now --label: a release label, unique per App')
+    assertReleaseLabel(label, packageVersionAt(project.root))
+    const prod = flagBool(ctx, 'prod')
+    const preview = flagBool(ctx, 'preview')
+    if (prod && preview) throw new UsageError('--prod and --preview ask for opposite things', 'pass --prod to go live, or --preview for a preview')
+    const stage = prod && flagBool(ctx, 'no-promote')
+    if (!prod && !preview && !flagBool(ctx, 'no-promote')) {
+      // A pipeline written when a deploy went live would now make previews and exit 0, and nobody reads
+      // the note in its log. A key with no terminal is a pipeline: it says which it wants, for a release
+      // or two after deploys became previews, before anything is built or uploaded.
+      if (isKeyToken(ctx.token) && !(ctx.interactive ?? canPrompt())) {
+        throw new UsageError(
+          'frontera app deploy no longer goes live by default: in a pipeline, say whether this deployment goes to production',
+          'add --prod to go live once the required checks pass (what this command did before), or --preview to make a preview',
+        )
+      }
+      // One release of notice for scripts that relied on deploy going live.
+      ctx.output.note('  deploy now creates a preview and never changes what users see; pass --prod to go live')
+    }
     const outputDirectory = project.outputDirectory ?? 'dist'
     const distDir = join(project.root, outputDirectory)
+    if (flagBool(ctx, 'build')) {
+      ctx.output.note('  building: bun run build')
+      asLocalCheckRuns(project.root, (line) => ctx.output.note(line), () => runBuild(project.root))
+    }
     validateStaticAppProject(project.root, project.routing ?? 'spa')
 
     if (!existsSync(join(distDir, 'index.html'))) {
       throw new CliError(`${outputDirectory}/index.html not found`, {
         code: 'VALIDATION_ERROR',
-        hint: 'run your build first: bun run build',
+        hint: 'run your build first: bun run build, or deploy with --build',
       })
     }
 
@@ -125,7 +275,7 @@ export const appDeploy: Command = {
           {
             code: 'VALIDATION_ERROR',
             hint:
-              'run your build first: bun run build. '
+              'run your build first: bun run build (or deploy with --build). '
               + 'Deploying now would publish the previous bundle, and nothing would say so. '
               + 'Pass --skip-build-check if the output really is current.',
           },
@@ -153,71 +303,104 @@ export const appDeploy: Command = {
     // Reported whichever way it comes out: "rendered" is worth saying too, and
     // a line that only ever appears when something is wrong is a line people
     // learn to skim past.
-    const renderEvidence = readRenderEvidence(project.root)
+    // Only a render of THIS App counts: its dev server or one of its previews, not whatever was opened last.
+    const renderEvidence = readRenderEvidence(project.root, project.slug)
     ctx.output.note(describeRenderEvidence(renderEvidence))
+    const evidence = renderVerdict(renderEvidence)
+    if (renderEvidence.rendered && !evidence.ok) ctx.output.note(`  render evidence: ${evidence.problems.join('; ')}`)
 
     // The picture from that same render. Uploaded whenever one exists — the
     // gallery has shown every app as an identical tinted tile, and a screenshot
     // of a slightly older state of the app says more than its first letter.
-    const thumbnail = readRenderThumbnail(project.root)
+    // Not a picture of another page: a render that is not this App's is not its thumbnail either.
+    const thumbnail = renderEvidence.notThisApp ? null : readRenderThumbnail(project.root)
+
+    const skipCheck = flagBool(ctx, 'skip-build-check')
+    const build = skipCheck ? runBuildCheck(project.root, true) : asLocalCheckRuns(project.root, (line) => ctx.output.note(line), () => runBuildCheck(project.root, false))
+    if (build.status === 'failed') {
+      // Going live on a failing check is refused here; a preview still uploads, marked.
+      if (prod && !stage) {
+        throw new CliError('bun run check failed: production needs the build check to pass', { code: 'VALIDATION_ERROR', hint: `${build.output ?? ''}\nfix it, or deploy a preview first: frontera app deploy` })
+      }
+      ctx.output.note(`  bun run check failed; deploying a preview marked as failing it\n${build.output ?? ''}`)
+    }
+    const contract = collectAppContract(project.root)
+    const provenance = { ...collectBuildProvenance(project.root), checks: { build: { status: build.status, detail: build.detail } }, contract }
 
-    const promote = !flagBool(ctx, 'no-promote')
     const res = await publish(client, app.id, {
-      version,
+      label,
+      prod,
+      stage,
       parentVersion: project.parentVersion,
       dist,
       source,
       manifest,
-      promote,
       renderEvidence,
-      provenance: collectBuildProvenance(project.root),
+      provenance,
       thumbnail,
     })
+    const deployment = res.deployment ?? res.version
 
-    writeState(project.root, { appId: app.id, parentVersion: res.version })
+    // On the runtime again: whatever a database restore had taken away is back.
+    writeState(project.root, { appId: app.id, parentVersion: deployment, restoredAway: undefined })
     // Local environment binding: source remains portable and package.json
     // remains ordinary package metadata.
     writeAppId(project.root, app.id)
 
-    // The one line that turns "published" into something a person can act on.
-    // A version that was published and not promoted used to be described to
-    // users as one nobody could see — so the turn ended by asking to make an
-    // unreviewed build live for the whole workspace, rather than showing it to
-    // the person who asked for it. It was always viewable; only the URL was
-    // missing.
-    if (res.previewUrl) {
-      ctx.output.note(
-        res.promoted
-          ? `  live at ${res.liveUrl ?? ''} · this exact build: ${res.previewUrl}`
-          : `  open it: ${res.previewUrl}`,
-      )
-    }
+    // Where a person opens what was just made: its own link, and the moving
+    // links of its branch and session. A preview was once described as one
+    // nobody could see, and the turn ended asking to make it live for everyone.
+    if (res.previewUrl) ctx.output.note(`  this deployment: ${res.previewUrl}`)
+    if (res.branchUrl) ctx.output.note(`  branch ${res.branch}: ${res.branchUrl}`)
+    if (res.sessionUrl) ctx.output.note(`  this session: ${res.sessionUrl}`)
+    if (res.promoted && res.liveUrl) ctx.output.note(`  live at ${res.liveUrl}`)
     if (res.addressUrl) ctx.output.note(`  address: ${res.addressUrl}`)
 
+    const name = `${app.slug}@${res.label ?? deployment}`
+    const data = {
+      app: app.slug,
+      appId: app.id,
+      deployment,
+      // The same id, under its earlier name, for scripts that read `version`.
+      version: deployment,
+      label: res.label ?? null,
+      promoted: res.promoted,
+      staged: res.staged ?? false,
+      ...(res.promoteRefused ? { promoteRefused: res.promoteRefused } : {}),
+      ...(res.previewUrl ? { previewUrl: res.previewUrl } : {}),
+      ...(res.branchUrl ? { branchUrl: res.branchUrl } : {}),
+      ...(res.sessionUrl ? { sessionUrl: res.sessionUrl } : {}),
+      ...(res.liveUrl && res.promoted ? { liveUrl: res.liveUrl } : {}),
+      ...(res.addressUrl ? { addressUrl: res.addressUrl } : {}),
+      // In `data` as well as in the note: an agent reads the JSON, and this
+      // is the fact it most needs to carry into what it tells the user.
+      rendered: renderEvidence.rendered,
+      renderEvidence,
+      // Whether that render was clean, and if not, what it found.
+      evidence,
+      build: build.status,
+    }
+
+    // Asked for production and refused: the deployment exists as a preview; say why it is not live.
+    if (prod && !stage && !res.promoted) {
+      const refused = res.promoteRefused
+      const blocking = (refused?.checks ?? []).filter((c) => c.required && c.status !== 'passed')
+      throw new CliError(`deployed ${name} as a preview, but it did not go live: ${refused?.message ?? 'production was not changed'}`, {
+        code: refused?.code === 'FORBIDDEN' ? 'FORBIDDEN' : 'CONFLICT',
+        hint: blocking.length
+          ? `required checks: ${blocking.map((c) => `${c.label} — ${c.detail}`).join('; ')}. Fix them and deploy again, or ask someone who may promote to force it.`
+          : refused?.code === 'PRODUCTION_PINNED'
+            ? 'production is pinned since a rollback: frontera app rollback --undo, or unpin it on the App\'s Deployments'
+            : `open it: ${res.previewUrl ?? 'frontera app deployments'}`,
+        details: data,
+      })
+    }
+
     return {
-      data: {
-        app: app.slug,
-        appId: app.id,
-        version: res.version,
-        promoted: res.promoted,
-        ...(res.previewUrl ? { previewUrl: res.previewUrl } : {}),
-        ...(res.liveUrl && res.promoted ? { liveUrl: res.liveUrl } : {}),
-        ...(res.addressUrl ? { addressUrl: res.addressUrl } : {}),
-        // In `data` as well as in the note: an agent reads the JSON, and this
-        // is the fact it most needs to carry into what it tells the user.
-        rendered: renderEvidence.rendered,
-        renderEvidence,
-      },
-      // The slug as the PLATFORM knows it: `project.slug` is a bootstrap name
-      // and goes stale the moment the app is renamed, so printing it would
-      // report a deploy to an app that no longer exists.
+      data,
       text:
-        `Published ${app.slug}@${res.version}` +
-        (res.promoted ? ' and promoted it' : '') +
-        (renderEvidence.rendered ? '' : ' — nobody has looked at this version') +
-        // Not "use `frontera app promote`". That read as "invisible until you
-        // promote", which is false and is what sent an agent asking to publish
-        // an unreviewed build to everyone.
+        (res.promoted ? `Deployed ${name} and it is live` : stage ? `Staged ${name} for production: nothing serves it until it is promoted` : `Deployed ${name} as a preview`) +
+        (renderEvidence.rendered ? (evidence.ok ? '' : ` — its render was not clean: ${evidence.problems.join('; ')}`) : ' — nobody has looked at this deployment') +
         (res.previewUrl ? `\n\nOpen it: ${res.previewUrl}` : '') +
         (res.addressUrl ? `\nAddress: ${res.addressUrl}` : ''),
     }

package/src/commands/app/deployments.ts

@@ -0,0 +1,97 @@
+import { AppsApi, type DeploymentCheck, type DeploymentLedger, type DeploymentRow } from '../../api/apps-api'
+import { table } from '../../table'
+import { projectApp, requireProjectFrom } from './shared'
+import type { Command } from '../types'
+
+/** Who produced a deployment, in a few words. */
+function producerWords(d: DeploymentRow): string {
+  const who = d.producer.name ?? (d.producer.kind === 'person' ? 'someone' : d.producer.kind === 'agent-key' ? 'an Agent key' : 'a workspace key')
+  return d.session ? `${who} (${d.session.harness ?? 'Forge'} session)` : who
+}
+
+/** What the render evidence says, short: rendered, stale, or not looked at. */
+function renderWords(d: DeploymentRow): string {
+  const e = d.renderEvidence
+  if (e.rendered === true) return Number(e.consoleErrors ?? 0) > 0 ? `rendered, ${e.consoleErrors} errors` : 'rendered'
+  return e.reason === 'stale' ? 'render stale' : 'not rendered'
+}
+
+/** How many of the newest deployments the list asks checks for: one request each. */
+const CHECKED = 10
+
+/**
+ * The checks of one deployment, short: "all passed", or what did not pass,
+ * the workspace's required checks first. Without checks, the render evidence.
+ */
+function checkWords(d: DeploymentRow, checks: DeploymentCheck[] | undefined): string {
+  if (!checks) return renderWords(d)
+  const open = checks.filter((c) => c.status !== 'passed').sort((a, b) => Number(b.required) - Number(a.required))
+  if (!open.length) return checks.length ? 'all passed' : '-'
+  return open.map((c) => `${c.id} ${c.status}${c.required ? ' (required)' : ''}`).join(', ')
+}
+
+/** The ledger for a person: production and its pin, the previews, then every deployment. */
+export function renderLedger(ledger: DeploymentLedger, checks: Record<string, DeploymentCheck[]> = {}): string {
+  const pin = ledger.production.pinned
+  const lines = [
+    `Production: ${ledger.production.label ?? ledger.production.deployment ?? 'nothing yet'}${pin ? `  — pinned since a rollback${pin.reason ? `: ${pin.reason}` : ''} (frontera app rollback --undo, or unpin)` : ''}`,
+  ]
+  if (ledger.previews.length) lines.push(`Previews: ${ledger.previews.map((p) => `${p.kind} ${p.name} → ${p.label ?? p.deployment ?? '-'}`).join(' · ')}`)
+  lines.push('')
+  if (!ledger.deployments.length) return `${lines.join('\n')}No deployments yet. frontera app deploy uploads a preview.`
+  lines.push(
+    table(
+      ['DEPLOYMENT', 'LABEL', 'SERVES', 'BY', 'BRANCH', 'COMMIT', 'CHECKS', 'CREATED'],
+      ledger.deployments.map((d) => [
+        d.id,
+        d.label ?? '-',
+        d.serves.length ? d.serves.join(', ') : d.staged ? 'staged' : d.pruned ? 'pruned' : '-',
+        producerWords(d),
+        d.branch ?? '-',
+        d.commit ? `${d.commit.slice(0, 8)}${d.dirty ? '+dirty' : ''}` : '-',
+        checkWords(d, checks[d.id]),
+        d.createdAt.slice(0, 16).replace('T', ' '),
+      ]),
+      [undefined, undefined, 32, 28, 24, undefined, 48],
+    ),
+  )
+  return lines.join('\n')
+}
+
+export const appDeployments: Command = {
+  meta: {
+    noun: 'app',
+    verb: 'deployments',
+    args: [],
+    flags: {},
+    summary: 'List deployments: id, label, who and where from, and which link serves each',
+    examples: ['frontera app deployments', 'frontera app deployments --json'],
+    needsProject: true,
+  },
+
+  async run(ctx) {
+    const project = requireProjectFrom(ctx)
+    const client = new AppsApi(ctx.apiUrl, ctx.token)
+    const app = await projectApp(client, project)
+    const ledger = await client.deployments(app.id)
+    // The checks of the newest deployments that still have files; an older or
+    // failed read falls back to the render evidence the ledger already carries.
+    const checks: Record<string, DeploymentCheck[]> = {}
+    await Promise.all(
+      ledger.deployments
+        .filter((d) => !d.pruned)
+        .slice(0, CHECKED)
+        .map(async (d) => {
+          try {
+            checks[d.id] = (await client.checks(app.id, d.id)).checks
+          } catch {
+            // Best effort: the list still says who made it and what it serves.
+          }
+        }),
+    )
+    return {
+      data: { ...ledger, deployments: ledger.deployments.map((d) => (checks[d.id] ? { ...d, checks: checks[d.id] } : d)) },
+      text: renderLedger(ledger, checks),
+    }
+  },
+}