@specific.dev/cli 0.1.181 → 0.1.183

package/dist/cli.js

@@ -368079,8 +368079,13 @@ function toDeployment(response) {
     error: response.error,
     changes: response.changes,
     pendingActions: response.pendingActions,
+    builds: response.builds,
     publicUrls: response.publicUrls,
+    triggeredBy: response.triggeredBy,
+    gitCommitSha: response.gitCommitSha,
     createdAt: response.createdAt,
+    startedAt: response.startedAt,
+    completedAt: response.completedAt,
     uploadUrl: response.uploadUrl,
     maxTarballBytes: response.maxTarballBytes
   };
@@ -374765,7 +374770,7 @@ function trackEvent(event, properties) {
     event,
     properties: {
       ...properties,
-      cli_version: "0.1.181",
+      cli_version: "0.1.183",
       platform: process.platform,
       node_version: process.version,
       project_id: getProjectId()
@@ -376743,6 +376748,22 @@ import { render as render5, Text as Text7, Box as Box7, useApp as useApp3, useIn
 import Spinner4 from "ink-spinner";
 import * as fs23 from "fs";
 import * as path21 from "path";
+
+// src/lib/deployments/format.ts
+function formatErrorCode(code) {
+  const labels = {
+    build_failed: "Build failed",
+    pre_deploy_failed: "Pre-deploy hook failed",
+    deploy_failed: "Service failed to deploy",
+    health_check_failed: "Health check failed",
+    post_deploy_failed: "Post-deploy hook failed",
+    volume_reset_failed: "Volume reset failed",
+    internal_error: "Internal error"
+  };
+  return labels[code] || code;
+}
+
+// src/commands/deploy.tsx
 import { execFileSync as execFileSync2 } from "child_process";
 function getGitInfo(cwd) {
   try {
@@ -376944,17 +376965,6 @@ function getFailedBuild(pendingActions) {
   if (!pendingActions) return void 0;
   return pendingActions.find((a) => a.type === "build_failed");
 }
-function formatErrorCode(code) {
-  const labels = {
-    pre_deploy_failed: "Pre-deploy hook failed",
-    deploy_failed: "Service failed to deploy",
-    health_check_failed: "Health check failed",
-    post_deploy_failed: "Post-deploy hook failed",
-    volume_reset_failed: "Volume reset failed",
-    internal_error: "Internal error"
-  };
-  return labels[code] || code;
-}
 function StructuredError({ error }) {
   return /* @__PURE__ */ React7.createElement(Box7, { flexDirection: "column" }, /* @__PURE__ */ React7.createElement(Text7, { color: "red", bold: true }, formatErrorCode(error.code), ": ", error.message), error.resource && /* @__PURE__ */ React7.createElement(Text7, { dimColor: true }, "Resource: ", error.resource), error.output && /* @__PURE__ */ React7.createElement(Box7, { flexDirection: "column", marginTop: 1 }, /* @__PURE__ */ React7.createElement(Text7, { bold: true }, "Output:"), /* @__PURE__ */ React7.createElement(Text7, null, error.output)));
 }
@@ -379147,7 +379157,7 @@ function compareVersions(a, b) {
   return 0;
 }
 async function checkForUpdate() {
-  const currentVersion = "0.1.181";
+  const currentVersion = "0.1.183";
   const response = await fetch(`${BINARIES_BASE_URL}/latest?t=${Date.now()}`);
   if (!response.ok) {
     throw new Error(`Failed to check for updates: HTTP ${response.status}`);
@@ -379434,13 +379444,35 @@ function PreviewBlock({ env: env2 }) {
   const urls = managedUrls(env2.domains);
   return /* @__PURE__ */ React12.createElement(Box11, { flexDirection: "column" }, /* @__PURE__ */ React12.createElement(Text12, null, /* @__PURE__ */ React12.createElement(Text12, { bold: true }, env2.name), /* @__PURE__ */ React12.createElement(Text12, { dimColor: true }, " (", env2.id, ")")), env2.prNumber !== null && /* @__PURE__ */ React12.createElement(Text12, null, "  ", "PR #", env2.prNumber, env2.prTitle ? /* @__PURE__ */ React12.createElement(Text12, { dimColor: true }, " \u2014 ", env2.prTitle) : null), urls.length > 0 && /* @__PURE__ */ React12.createElement(Text12, null, "  ", "URL: ", urls.join(", ")), env2.expiresAt && /* @__PURE__ */ React12.createElement(Text12, null, "  ", "Expires: ", /* @__PURE__ */ React12.createElement(Text12, { dimColor: true }, new Date(env2.expiresAt).toLocaleString())));
 }
+function PreviewConfigurationBlock({
+  config,
+  activePreviewCount,
+  showDetails
+}) {
+  const configured = config.github;
+  const enabledConfigs = configured.filter((c) => c.prPreviewsEnabled);
+  const labelGated = enabledConfigs.filter((c) => c.previewsRequireLabel);
+  const githubSummary = enabledConfigs.length > 0 ? `enabled for ${enabledConfigs.length} environment${enabledConfigs.length === 1 ? "" : "s"}` : configured.length > 0 ? "configured but disabled" : "not configured";
+  return /* @__PURE__ */ React12.createElement(Box11, { flexDirection: "column" }, /* @__PURE__ */ React12.createElement(Text12, { bold: true }, "Preview configuration"), /* @__PURE__ */ React12.createElement(Box11, { flexDirection: "column", marginLeft: 2 }, /* @__PURE__ */ React12.createElement(Text12, null, "PR previews: ", config.enabledForOrganization ? "available" : "unavailable", "; GitHub ", githubSummary, ";", " ", labelGated.length > 0 ? `requires ${config.requiredLabel}` : "no label required", "; active ", activePreviewCount), !showDetails && configured.length > 0 && /* @__PURE__ */ React12.createElement(Text12, { dimColor: true }, "  ", "Run `specific status --previews` for GitHub preview details."), showDetails && /* @__PURE__ */ React12.createElement(Box11, { flexDirection: "column", marginTop: 1 }, /* @__PURE__ */ React12.createElement(Text12, null, "Required label: ", config.requiredLabel), configured.length === 0 ? /* @__PURE__ */ React12.createElement(Text12, null, "GitHub PR automation: not configured") : configured.map((githubConfig) => /* @__PURE__ */ React12.createElement(Box11, { key: githubConfig.environmentId, flexDirection: "column" }, /* @__PURE__ */ React12.createElement(Text12, null, /* @__PURE__ */ React12.createElement(Text12, { bold: true }, githubConfig.environmentName), /* @__PURE__ */ React12.createElement(Text12, { dimColor: true }, " (", githubConfig.environmentId, ")")), /* @__PURE__ */ React12.createElement(Text12, null, "  ", "PR previews: ", githubConfig.prPreviewsEnabled ? "enabled" : "disabled", "; ", "requires label: ", githubConfig.previewsRequireLabel ? "yes" : "no"), /* @__PURE__ */ React12.createElement(Text12, null, "  ", "Repository: ", githubConfig.repositoryFullName, /* @__PURE__ */ React12.createElement(Text12, { dimColor: true }, " (", githubConfig.branch, ", ", githubConfig.hclPath, ")")))))));
+}
 function EnvironmentBlock({ env: env2 }) {
-  return /* @__PURE__ */ React12.createElement(Box11, { flexDirection: "column" }, /* @__PURE__ */ React12.createElement(Text12, null, /* @__PURE__ */ React12.createElement(Text12, { bold: true }, env2.name), /* @__PURE__ */ React12.createElement(Text12, { dimColor: true }, " (", env2.id, ")")), /* @__PURE__ */ React12.createElement(Text12, null, "  ", "Status: ", /* @__PURE__ */ React12.createElement(Text12, { color: statusColor(env2.status), bold: true }, env2.status)), /* @__PURE__ */ React12.createElement(Text12, null, "  ", "Active deployment:", " ", env2.activeDeployment ? /* @__PURE__ */ React12.createElement(Text12, { dimColor: true }, env2.activeDeployment.id) : /* @__PURE__ */ React12.createElement(Text12, { dimColor: true }, "none")), env2.inProgressDeployment && /* @__PURE__ */ React12.createElement(Text12, null, "  ", "In progress:", " ", /* @__PURE__ */ React12.createElement(Text12, { dimColor: true }, env2.inProgressDeployment.id), /* @__PURE__ */ React12.createElement(Text12, { dimColor: true }, " (", env2.inProgressDeployment.state, ")")), env2.domains && Object.keys(env2.domains).length > 0 && /* @__PURE__ */ React12.createElement(Box11, { flexDirection: "column" }, /* @__PURE__ */ React12.createElement(Text12, null, "  ", "Domains:"), Object.entries(env2.domains).map(([serviceName, urls]) => {
+  const latest = env2.latestDeployment;
+  const latestIsShownElsewhere = !latest || latest.id === env2.activeDeployment?.id || latest.id === env2.inProgressDeployment?.id;
+  return /* @__PURE__ */ React12.createElement(Box11, { flexDirection: "column" }, /* @__PURE__ */ React12.createElement(Text12, null, /* @__PURE__ */ React12.createElement(Text12, { bold: true }, env2.name), /* @__PURE__ */ React12.createElement(Text12, { dimColor: true }, " (", env2.id, ")")), /* @__PURE__ */ React12.createElement(Text12, null, "  ", "Status: ", /* @__PURE__ */ React12.createElement(Text12, { color: statusColor(env2.status), bold: true }, env2.status)), /* @__PURE__ */ React12.createElement(Text12, null, "  ", "Active deployment:", " ", env2.activeDeployment ? /* @__PURE__ */ React12.createElement(Text12, { dimColor: true }, env2.activeDeployment.id) : /* @__PURE__ */ React12.createElement(Text12, { dimColor: true }, "none")), env2.inProgressDeployment && /* @__PURE__ */ React12.createElement(Text12, null, "  ", "In progress:", " ", /* @__PURE__ */ React12.createElement(Text12, { dimColor: true }, env2.inProgressDeployment.id), /* @__PURE__ */ React12.createElement(Text12, { dimColor: true }, " (", env2.inProgressDeployment.state, ")")), !latestIsShownElsewhere && /* @__PURE__ */ React12.createElement(Text12, null, "  ", "Last deployment:", " ", /* @__PURE__ */ React12.createElement(Text12, { dimColor: true }, latest.id), " ", /* @__PURE__ */ React12.createElement(
+    Text12,
+    {
+      ...latest.state === "failed" ? { color: "red", bold: true } : {}
+    },
+    "(",
+    latest.state,
+    latest.triggeredBy ? ` via ${latest.triggeredBy}` : "",
+    ")"
+  )), !latestIsShownElsewhere && latest.state === "failed" && /* @__PURE__ */ React12.createElement(Text12, { dimColor: true }, "    ", "Run `specific deployment show ", latest.id, "` for details."), env2.domains && Object.keys(env2.domains).length > 0 && /* @__PURE__ */ React12.createElement(Box11, { flexDirection: "column" }, /* @__PURE__ */ React12.createElement(Text12, null, "  ", "Domains:"), Object.entries(env2.domains).map(([serviceName, urls]) => {
     const displayUrls = urls.custom.length > 0 ? urls.custom : urls.managed ? [urls.managed] : [];
     return /* @__PURE__ */ React12.createElement(Text12, { key: serviceName }, "    - ", serviceName, displayUrls.length > 0 ? `: ${displayUrls.join(", ")}` : null);
   })));
 }
-function StatusUI() {
+function StatusUI({ previews = false }) {
   const [state, setState] = useState11({ phase: "loading" });
   useEffect11(() => {
     (async () => {
@@ -379468,14 +379500,21 @@ function StatusUI() {
     return /* @__PURE__ */ React12.createElement(Text12, { color: "red" }, "Failed to get status: ", state.error);
   }
   const status = state.status;
-  return /* @__PURE__ */ React12.createElement(Box11, { flexDirection: "column", gap: 1 }, /* @__PURE__ */ React12.createElement(Text12, null, /* @__PURE__ */ React12.createElement(Text12, { bold: true }, status.name), /* @__PURE__ */ React12.createElement(Text12, { dimColor: true }, " (", status.id, ")")), /* @__PURE__ */ React12.createElement(Box11, { flexDirection: "column" }, /* @__PURE__ */ React12.createElement(Text12, { bold: true }, "Environments"), status.environments.length === 0 ? /* @__PURE__ */ React12.createElement(Box11, { marginLeft: 2 }, /* @__PURE__ */ React12.createElement(Text12, { dimColor: true }, "No environments found.")) : /* @__PURE__ */ React12.createElement(Box11, { flexDirection: "column", gap: 1, marginLeft: 2 }, status.environments.map((env2) => /* @__PURE__ */ React12.createElement(EnvironmentBlock, { key: env2.id, env: env2 })))), (status.previewEnvironments ?? []).length > 0 && /* @__PURE__ */ React12.createElement(Box11, { flexDirection: "column" }, /* @__PURE__ */ React12.createElement(Text12, { bold: true }, "Preview environments"), /* @__PURE__ */ React12.createElement(Box11, { flexDirection: "column", gap: 1, marginLeft: 2 }, status.previewEnvironments.map((env2) => /* @__PURE__ */ React12.createElement(PreviewBlock, { key: env2.id, env: env2 })))));
+  return /* @__PURE__ */ React12.createElement(Box11, { flexDirection: "column", gap: 1 }, /* @__PURE__ */ React12.createElement(Text12, null, /* @__PURE__ */ React12.createElement(Text12, { bold: true }, status.name), /* @__PURE__ */ React12.createElement(Text12, { dimColor: true }, " (", status.id, ")")), /* @__PURE__ */ React12.createElement(Box11, { flexDirection: "column" }, /* @__PURE__ */ React12.createElement(Text12, { bold: true }, "Environments"), status.environments.length === 0 ? /* @__PURE__ */ React12.createElement(Box11, { marginLeft: 2 }, /* @__PURE__ */ React12.createElement(Text12, { dimColor: true }, "No environments found.")) : /* @__PURE__ */ React12.createElement(Box11, { flexDirection: "column", gap: 1, marginLeft: 2 }, status.environments.map((env2) => /* @__PURE__ */ React12.createElement(EnvironmentBlock, { key: env2.id, env: env2 })))), /* @__PURE__ */ React12.createElement(
+    PreviewConfigurationBlock,
+    {
+      config: status.previewEnvironmentConfig,
+      activePreviewCount: (status.previewEnvironments ?? []).length,
+      showDetails: previews
+    }
+  ), (status.previewEnvironments ?? []).length > 0 && /* @__PURE__ */ React12.createElement(Box11, { flexDirection: "column" }, /* @__PURE__ */ React12.createElement(Text12, { bold: true }, "Preview environments"), /* @__PURE__ */ React12.createElement(Box11, { flexDirection: "column", gap: 1, marginLeft: 2 }, status.previewEnvironments.map((env2) => /* @__PURE__ */ React12.createElement(PreviewBlock, { key: env2.id, env: env2 })))));
 }
-function statusCommand() {
-  render10(/* @__PURE__ */ React12.createElement(StatusUI, null));
+function statusCommand(options2 = {}) {
+  render10(/* @__PURE__ */ React12.createElement(StatusUI, { previews: options2.previews ?? false }));
 }
 
 // src/lib/project/resolve-env.ts
-async function resolveEnvironmentId(client2, projectId, envFlag) {
+async function resolveEnvironmentStatus(client2, projectId, envFlag) {
   const status = await client2.getProjectStatus(projectId);
   const environments = status.environments;
   const previewEnvironments = status.previewEnvironments ?? [];
@@ -379490,16 +379529,19 @@ async function resolveEnvironmentId(client2, projectId, envFlag) {
         `Environment "${envFlag}" not found (matched against name and ID). Available: ${available}`
       );
     }
-    return match.id;
+    return match;
   }
   if (hasEnvironmentId()) {
     const savedId = readEnvironmentId();
-    if (environments.some((e) => e.id === savedId)) {
-      return savedId;
+    const saved = environments.find(
+      (e) => e.id === savedId
+    );
+    if (saved) {
+      return saved;
     }
   }
   if (environments.length === 1) {
-    return environments[0].id;
+    return environments[0];
   }
   if (environments.length === 0) {
     throw new Error("This project has no environments yet.");
@@ -379509,6 +379551,10 @@ async function resolveEnvironmentId(client2, projectId, envFlag) {
     `Project has multiple environments (${names}). Pass --environment <name|id>.`
   );
 }
+async function resolveEnvironmentId(client2, projectId, envFlag) {
+  const match = await resolveEnvironmentStatus(client2, projectId, envFlag);
+  return match.id;
+}
 
 // src/lib/query/render-table.ts
 var MAX_COL_WIDTH = 60;
@@ -379750,6 +379796,204 @@ function friendlyErrorMessage(raw) {
   return raw;
 }
 
+// src/commands/deployment.tsx
+var ANSI2 = {
+  dim: "\x1B[2m",
+  red: "\x1B[31m",
+  green: "\x1B[32m",
+  yellow: "\x1B[33m",
+  bold: "\x1B[1m",
+  reset: "\x1B[0m"
+};
+async function deploymentShowCommand(idArg, options2) {
+  try {
+    const format = resolveOutputFormat2(options2.format);
+    const includeOutput = options2.output ?? false;
+    const client2 = new SpecificClient({ tokenProvider: getValidAccessToken });
+    let deploymentId = idArg;
+    if (!deploymentId) {
+      const projectId = readProjectId();
+      const env2 = await resolveEnvironmentStatus(
+        client2,
+        projectId,
+        options2.environment
+      );
+      const latest = env2.latestDeployment ?? env2.inProgressDeployment ?? env2.activeDeployment;
+      if (!latest) {
+        throw new Error(
+          `No deployments found for environment "${env2.name}".`
+        );
+      }
+      deploymentId = latest.id;
+    }
+    const deployment = await client2.getDeployment(deploymentId);
+    if (format === "json") {
+      const payload = includeOutput ? deployment : stripOutput(deployment);
+      process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
+      return;
+    }
+    process.stdout.write(renderDeployment(deployment, includeOutput));
+  } catch (err) {
+    const message = err instanceof Error ? err.message : "Unknown error occurred";
+    console.error(`Error: ${message}`);
+    process.exit(1);
+  }
+}
+function resolveOutputFormat2(format) {
+  if (!format) {
+    return isInteractive() ? "text" : "json";
+  }
+  if (format === "text" || format === "json") {
+    return format;
+  }
+  throw new Error(`Invalid format "${format}". Expected one of: text, json.`);
+}
+function omitOutput(value) {
+  const copy = { ...value };
+  delete copy.output;
+  return copy;
+}
+function stripOutput(deployment) {
+  const stripped = { ...deployment };
+  if (stripped.error) {
+    stripped.error = omitOutput(stripped.error);
+  }
+  if (stripped.builds) {
+    stripped.builds = stripped.builds.map(omitOutput);
+  }
+  if (stripped.pendingActions) {
+    stripped.pendingActions = stripped.pendingActions.map(
+      (a) => a.type === "build_failed" ? omitOutput(a) : a
+    );
+  }
+  return stripped;
+}
+function stateColor(state) {
+  switch (state) {
+    case "active":
+    case "completed":
+      return ANSI2.green;
+    case "failed":
+    case "cancelled":
+      return ANSI2.red;
+    case "superseded":
+      return ANSI2.dim;
+    default:
+      return ANSI2.yellow;
+  }
+}
+function colored(color, text) {
+  return `${color}${text}${ANSI2.reset}`;
+}
+function formatDuration(startIso, endIso) {
+  const ms = new Date(endIso).getTime() - new Date(startIso).getTime();
+  if (!Number.isFinite(ms) || ms < 0) return null;
+  const totalSeconds = Math.round(ms / 1e3);
+  const minutes = Math.floor(totalSeconds / 60);
+  const seconds = totalSeconds % 60;
+  return minutes > 0 ? `${minutes}m ${seconds}s` : `${seconds}s`;
+}
+function formatBytes3(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  return `${(bytes / 1024).toFixed(1)} KB`;
+}
+function renderDeployment(deployment, includeOutput) {
+  const lines = [];
+  lines.push(
+    `${ANSI2.bold}Deployment ${deployment.id}${ANSI2.reset} ${ANSI2.dim}(${deployment.environment})${ANSI2.reset}`
+  );
+  lines.push(
+    `  State:      ${colored(stateColor(deployment.state), deployment.state)}`
+  );
+  if (deployment.stateMessage) {
+    lines.push(`  Message:    ${deployment.stateMessage}`);
+  }
+  if (deployment.triggeredBy) {
+    lines.push(`  Triggered:  ${deployment.triggeredBy}`);
+  }
+  if (deployment.gitCommitSha) {
+    lines.push(`  Commit:     ${deployment.gitCommitSha}`);
+  }
+  lines.push(`  Created:    ${deployment.createdAt}`);
+  if (deployment.completedAt) {
+    const duration = deployment.startedAt ? formatDuration(deployment.startedAt, deployment.completedAt) : null;
+    lines.push(
+      `  Completed:  ${deployment.completedAt}${duration ? ` ${ANSI2.dim}(took ${duration})${ANSI2.reset}` : ""}`
+    );
+  }
+  const builds = deployment.builds ?? [];
+  if (builds.length > 0) {
+    lines.push("");
+    lines.push(`${ANSI2.bold}Builds${ANSI2.reset}`);
+    const nameWidth = Math.max(...builds.map((b) => b.name.length));
+    for (const build of builds) {
+      const marker = build.state === "failed" ? "\u2716" : build.state === "completed" ? "\u2714" : "\u2026";
+      let line = `  ${colored(stateColor(build.state), marker)} ${build.name.padEnd(nameWidth)}  ${colored(stateColor(build.state), build.state)}`;
+      if (build.state === "failed" && build.error) {
+        line += ` ${ANSI2.dim}\u2014 ${build.error}${ANSI2.reset}`;
+      }
+      lines.push(line);
+    }
+  }
+  const pendingActions = deployment.pendingActions ?? [];
+  const missingSecrets = pendingActions.flatMap(
+    (a) => a.type === "missing_secrets" ? a.secrets : []
+  );
+  const missingConfigs = pendingActions.flatMap(
+    (a) => a.type === "missing_configs" ? a.configs : []
+  );
+  if (missingSecrets.length > 0 || missingConfigs.length > 0) {
+    lines.push("");
+    lines.push(colored(ANSI2.yellow, `${ANSI2.bold}Action required${ANSI2.reset}`));
+    if (missingSecrets.length > 0) {
+      lines.push(`  Missing secrets: ${missingSecrets.join(", ")}`);
+    }
+    if (missingConfigs.length > 0) {
+      lines.push(`  Missing configs: ${missingConfigs.join(", ")}`);
+    }
+  }
+  if (deployment.error) {
+    lines.push("");
+    lines.push(
+      colored(
+        ANSI2.red,
+        `${ANSI2.bold}${formatErrorCode(deployment.error.code)}:${ANSI2.reset}${ANSI2.red} ${deployment.error.message}`
+      )
+    );
+    if (deployment.error.resource) {
+      lines.push(`${ANSI2.dim}Resource: ${deployment.error.resource}${ANSI2.reset}`);
+    }
+  }
+  const buildsWithOutput = builds.filter(
+    (b) => typeof b.output === "string" && b.output.length > 0
+  );
+  const extraErrorOutput = deployment.error?.output && !buildsWithOutput.some((b) => b.output === deployment.error?.output) ? deployment.error.output : null;
+  if (includeOutput) {
+    const ordered = [...buildsWithOutput].sort(
+      (a, b) => Number(b.state === "failed") - Number(a.state === "failed")
+    );
+    for (const build of ordered) {
+      lines.push("");
+      lines.push(`${ANSI2.bold}Output (${build.name})${ANSI2.reset}`);
+      lines.push(build.output.trimEnd());
+    }
+    if (extraErrorOutput) {
+      lines.push("");
+      lines.push(`${ANSI2.bold}Output${ANSI2.reset}`);
+      lines.push(extraErrorOutput.trimEnd());
+    }
+  } else {
+    const totalBytes = buildsWithOutput.reduce((sum, b) => sum + b.output.length, 0) + (extraErrorOutput?.length ?? 0);
+    if (totalBytes > 0) {
+      lines.push("");
+      lines.push(
+        `${ANSI2.dim}Output hidden (${formatBytes3(totalBytes)}). Run \`specific deployment show ${deployment.id} --output\` to print it.${ANSI2.reset}`
+      );
+    }
+  }
+  return lines.join("\n") + "\n";
+}
+
 // src/lib/domain/format-dns-instructions.ts
 function isApex(domain) {
   return domain.split(".").length === 2;
@@ -379830,7 +380074,7 @@ async function domainAddCommand(service, domain, options2) {
 var program = new Command();
 var env = "production";
 var envLabel = env !== "production" ? `[${env.toUpperCase()}] ` : "";
-program.name("specific").description(`${envLabel}Infrastructure-as-code for coding agents`).version("0.1.181").enablePositionalOptions();
+program.name("specific").description(`${envLabel}Infrastructure-as-code for coding agents`).version("0.1.183").enablePositionalOptions();
 program.command("init").description("Initialize project for use with a coding agent").option("--agent <name...>", "Agents to configure (cursor, claude, codex, other)").addHelpText("after", `
 Examples:
   $ specific init
@@ -379912,9 +380156,28 @@ Examples:
   $ specific domain add web example.com --environment staging`).action((service, domain, options2) => {
   domainAddCommand(service, domain, options2);
 });
-program.command("status").description("Show project, environments, and deployment status").addHelpText("after", `
+var deploymentCmd = program.command("deployment").description("Inspect deployments");
+deploymentCmd.command("show [id]").description(
+  "Show a deployment's state, builds, and errors (defaults to the latest deployment)"
+).option("-e, --environment <name|id>", "Target environment (defaults to the current one; ignored when an ID is given)").option(
+  "--format <text|json>",
+  "Output format (defaults to text on a TTY, json when piped)"
+).option(
+  "--output",
+  "Include build output (logs); can be large, so it is hidden by default"
+).addHelpText("after", `
+Examples:
+  $ specific deployment show
+  $ specific deployment show dep_0abc123
+  $ specific deployment show dep_0abc123 --output
+  $ specific deployment show --environment staging
+  $ specific deployment show -e preview-a1b2c3d4 --format json`).action((id, options2) => {
+  deploymentShowCommand(id, options2);
+});
+program.command("status").description("Show project, environments, and deployment status").option("--previews", "Show detailed preview environment and GitHub PR preview configuration").addHelpText("after", `
 Examples:
-  $ specific status`).action(statusCommand);
+  $ specific status
+  $ specific status --previews`).action((options2) => statusCommand(options2));
 program.command("query [sql]").description(
   "Run a SQL query against your environment's observability data (ClickHouse), or a Postgres database with --db"
 ).option("-e, --environment <name|id>", "Target environment (defaults to the current one)").option(

package/dist/docs/deployments.md

@@ -0,0 +1,79 @@
+# Deployments
+
+Every deploy — whether started with `specific deploy`, by a GitHub push, or from the dashboard — creates a deployment record with its state, the builds it ran, and any failure details. Use `specific deployment show` to inspect one, most importantly to answer "why did my deploy fail?" when you didn't run the deploy yourself.
+
+## Inspecting a deployment
+
+```sh
+# The latest deployment of the current environment (whatever its state)
+specific deployment show
+
+# A specific deployment by ID
+specific deployment show dep_0abc123
+
+# The latest deployment of another environment (or a preview environment)
+specific deployment show --environment staging
+specific deployment show -e preview-a1b2c3d4
+
+# Machine-readable output for agents and scripts
+specific deployment show --format json
+
+# Include the build output (logs) — hidden by default because it can be large
+specific deployment show dep_0abc123 --output
+```
+
+Flags:
+
+- `-e, --environment <name|id>` — target environment when no ID is given (defaults to the current one). Run `specific status` to list every environment and its ID.
+- `--format <text|json>` — output format. When stdout is a terminal, the default is `text`. When stdout is piped or redirected, the default is `json`.
+- `--output` — include build output (logs) and the error's diagnostic output. Without this flag, output is omitted in **both** formats (a size hint is printed in text mode) so a state check never floods the terminal or an agent's context with logs.
+
+The output includes:
+
+- **State** — `pending`, `queued`, `deploying`, `active`, `failed`, `cancelled`, or `superseded`, plus the state message.
+- **Trigger** — how the deploy was started (`cli`, `github`, …) and the git commit, when known.
+- **Builds** — each image build with its state and, for failed builds, the error message. Add `--output` for the full **build output (logs)** — where compile errors, missing dependencies, and failing build commands show up.
+- **Action required** — for pending deployments, the missing secrets and configs blocking it (see below).
+- **Error** — a structured error for failed deployments (`build_failed`, `pre_deploy_failed`, `health_check_failed`, …) with the failing resource; add `--output` for its diagnostic output (pod logs, Kubernetes events).
+
+The `text` format is for quick human inspection. Agents and scripts should use `json` to get complete, untruncated values.
+
+## Pending deployments
+
+A deployment stays `pending` while builds run and until every required secret and config has a value. `specific deployment show` lists what is missing:
+
+```
+Action required
+  Missing secrets: STRIPE_KEY
+  Missing configs: DOMAIN
+```
+
+Values can be provided in the dashboard (the state message links the deployment page), or by deploying from the CLI with `specific deploy --secret KEY=value --config KEY=value`, which prompts for anything still missing. See `specific docs secrets-config`.
+
+## Finding the deployment to inspect
+
+`specific status` shows, per environment, the active deployment, any in-progress deployment, and — when it differs — the **last** deployment. A failed deploy never becomes active, so after a failed GitHub push the environment still shows an older active deployment; the failure appears on the "Last deployment" line with its ID.
+
+```sh
+specific status            # find the deployment ID (active, in progress, or last/failed)
+specific deployment show   # or skip the lookup: shows the latest deployment directly
+```
+
+## Debugging a failed deploy
+
+1. Run `specific deployment show` (with `-e <env>` if it isn't the current environment) to see what failed.
+2. If a **build** failed: re-run with `--output` to print the build log with the exact command that failed. Fix the code or the `build` block in `specific.hcl` (see `specific docs builds`) and deploy again.
+3. If a **service** failed to deploy or its health check failed: re-run with `--output` for pod logs and Kubernetes events. For deeper investigation of runtime behaviour, query logs and metrics with `specific query` (see `specific docs observability`).
+
+Build output is kept on the deployment record (the last portion of the log, which contains the failure). It is **not** part of the `observability.logs` stream — that stream contains runtime service and database logs only.
+
+GitHub-triggered deploys behave exactly the same: the deployment record carries the build failure and its output, so `specific deployment show` works without access to GitHub.
+
+---
+
+Related topics:
+
+- Run `specific docs builds` for build configuration (`base`, `command`, custom Dockerfiles)
+- Run `specific docs observability` for querying runtime logs and metrics of deployed services
+- Run `specific docs previews` for pull-request preview environments
+- Run `specific docs secrets-config` if a deploy is waiting for missing secrets or configs

package/dist/docs/index.md

@@ -12,6 +12,8 @@ This documentation is nested and references to other docs are in Markdown link f
 
 A full development environment can be started with `specific dev`. To deploy any changes, the user can run `specific deploy`.
 
+If the project is connected to GitHub in the Specific Dashboard, pushes to the configured branch can deploy automatically. Run `specific status` to inspect the project and environment state. If a deploy fails — including GitHub-triggered deploys — run `specific deployment show` to see why, and add `--output` for the failed build's log.
+
 After deploying, the user can manage their project from the Specific Dashboard at https://dashboard.specific.dev — monitoring logs and metrics, scaling services, browsing the database and object storage, updating secrets and configuration, and deleting projects. Point them there whenever production management comes up.
 
 ## Topics
@@ -27,6 +29,7 @@ After deploying, the user can manage their project from the Specific Dashboard a
 - [Redis](/redis): define non-durable Redis-compatible databases for caching and more.
 - [Volumes](/volumes): define persistent storage volumes for services to store files in.
 - [Temporal](/temporal): managed durable workflow engine for background tasks, AI agents and more.
+- [Deployments](/deployments): inspect deployments and debug failed deploys (including build output) with `specific deployment show`, regardless of whether the deploy was started from the CLI, GitHub, or the dashboard.
 - [Observability](/observability): query logs and metrics from running environments using `specific query` for debugging and analytics.
 - [Preview environments](/previews): ephemeral copies of an environment created per pull request, with the parent's databases branched, object storage forked, and volumes cloned.
 <!-- beta:mail -->

package/dist/docs/observability.md

@@ -66,7 +66,7 @@ Column names follow OpenTelemetry's ClickHouse exporter conventions and are case
 
 ### `observability.logs`
 
-Unified log stream from services.
+Unified log stream from services. This is **runtime** data: service and database logs from running containers. Build output from deploys is not part of this stream — it lives on the deployment record (run `specific deployment show`, see `specific docs deployments`).
 
 | Column | Type | Notes |
 |---|---|---|
@@ -227,3 +227,4 @@ Related topics:
 - Run `specific status` to list environments (standard and preview) and their IDs before querying a specific one
 - Run `specific docs services` for how services are defined
 - Run `specific docs postgres` for querying your application database (`specific psql` for local development, `specific query --db <name>` for production)
+- Run `specific docs deployments` for debugging failed deploys — build output is on the deployment record (`specific deployment show`), not in `observability.logs`

package/dist/docs/previews.md

@@ -9,6 +9,10 @@ A preview environment is a temporary, fully isolated copy of an existing environ
 
 Preview environments are ephemeral: pull-request previews are removed when the PR is closed or merged, and a preview can be given an expiry, after which Specific cleans it up automatically.
 
+Pull-request previews depend on both the organization's plan and the GitHub environment configuration. Run `specific status` to see a concise preview summary, or `specific status --previews` to see whether preview environments are enabled, whether GitHub PR previews are configured, and whether PRs require a label.
+
+Some projects require the `specific:preview` pull request label before Specific creates or updates a PR preview. When label gating is enabled, adding `specific:preview` starts the preview and removing it tears the preview down.
+
 Run `specific status` to list every environment and its `env_…` ID, including preview environments. Target a preview with `--environment` on commands that take one (see `specific docs observability`).
 
 ## What's copied from the parent
@@ -32,3 +36,4 @@ Related topics:
 - Run `specific docs volumes` for declaring persistent volumes
 - Run `specific docs services` for service configuration
 - Run `specific docs observability` for querying a preview's logs and metrics
+- Run `specific docs deployments` for debugging a failed preview deploy (`specific deployment show -e <preview>` prints the failure; add `--output` for the build log)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/cli",
-  "version": "0.1.181",
+  "version": "0.1.183",
   "description": "CLI for Specific infrastructure-as-code",
   "type": "module",
   "main": "dist/cli.js",