diff --git a/README.md b/README.md index 934ad42..5988360 100644 --- a/README.md +++ b/README.md @@ -279,6 +279,8 @@ blocks to Messages API blocks and spawns one worker per action. repositories-folder resolution and environment-scoped MCP actions. - [Shared desktop transport](docs/shared-desktop-transport.md): the per-user worker that hosts with one process per chat use to share HTTP connections, reads and token renewal. +- [Deployments and releases](docs/deployments.md): deployment runs, release history and + stats, the active-run check, waiting for a run, and the polling rules hosts follow. Decisions are recorded in [ADR 0001](docs/adr/0001-shared-developer-tooling-and-codex.md) (shared tooling), [ADR 0002](docs/adr/0002-conversational-project-mcp-client.md) (the MCP diff --git a/docs/deployments.md b/docs/deployments.md new file mode 100644 index 0000000..d2f7508 --- /dev/null +++ b/docs/deployments.md @@ -0,0 +1,46 @@ +# Deployments and releases + +`createDeployments()` reads deployment runs and resource releases for the host panes and +model tools. Every action is a read (`GET`) bound to the shared session's account. Billing, +cost and credential fields never reach the result. A run or release the reader may not see +answers with `hidden: true` and a sentence that does not say whether it exists. + +| Action | Reads | Use | +| --- | --- | --- | +| `deployment-history` | One page of the environment's workflow runs and the deployment runs no workflow owns, optionally for one branch | The environment-wide list | +| `deployment-run` | One deployment or workflow run with its stages | The run detail | +| `deployment-logs` | One page of a run's logs, by cursor | Logs | +| `deployment-releases` | One page of the environment's releases (APIs, agents, static sites), then their runs of the last `days` (default 30) in one more request | The Releases list: the last ten run states, the last run, the active run and stats per release | +| `deployment-release` | One release, its revisions and its runs of the last `days` | A release's history: the serving and wanted revisions, the runs and their stats | +| `deployment-active` | Only runs still `queued` or `running` (at most 20), optionally for one branch | The cheap check while something is deploying | +| `deployment-wait` | One run, every ten seconds, until it ends or `timeoutSeconds` (at most 120) runs out | Waiting for a deployment the person or the model started | + +## Stats + +The backend has no statistics endpoint, so `releaseStats()` computes them from the runs +read: + +- **Success rate:** succeeded runs out of those that succeeded, failed or were blocked. + Superseded, cancelled and skipped runs don't count. +- **Median and 90th-percentile time:** taken over runs that succeeded. +- **Slowest stage:** the stage with the longest median time across runs that succeeded. + The time a run waits before its first stage, usually for its workflow's image build, is + its own stage, "Waiting to start". +- **Most common failure:** the error code of failed and blocked runs. A blocked run + without one is named by its outcome, such as `workflow_prerequisite_failed`. + +## Polling + +The backend offers no push channel, so hosts poll. These rules keep that small: + +- **Nothing re-reads while no run is active.** Opening a list or a release reads it once. +- **Finished runs never change.** `ACTIVE_RUN_STATES` (`queued`, `running`) are the only + states that do, and the backend allows one active run per target. +- **While runs are active, re-read with `deployment-active`.** It returns only the active + runs. When its count reaches zero, read the list once more and stop. +- **Watching one run re-reads only that run,** at `WAIT_INTERVAL_MS`. Stop when it ends, + and pause after an hour. +- **Poll once per account and environment, not once per chat.** The + [shared desktop transport](shared-desktop-transport.md) merges identical reads that are + in flight at the same moment. A host with several chats still lets one of them run the + timer and shares its result with the others. diff --git a/package-lock.json b/package-lock.json index e37c0e1..1950efb 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@dev-mainsequence/devtools", - "version": "0.3.18", + "version": "0.3.19", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@dev-mainsequence/devtools", - "version": "0.3.18", + "version": "0.3.19", "license": "MIT", "bin": { "ms-devtools": "dist/runner.js" diff --git a/package.json b/package.json index 391b73d..1acba06 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@dev-mainsequence/devtools", - "version": "0.3.18", + "version": "0.3.19", "description": "Shared MainSequence developer actions, project operations, MCP client and command runner", "license": "MIT", "engines": { diff --git a/src/index.ts b/src/index.ts index a312e31..a09b322 100644 --- a/src/index.ts +++ b/src/index.ts @@ -57,6 +57,6 @@ export { parseArguments, tokenizeCommand, HELP } from './shared/arguments'; export { createAgentAssets, stillAgentPng } from './shared/agentAssets'; export type { AgentAsset } from './shared/agentAssets'; -export { createDeployments, DEPLOYMENT_ACTIONS, HIDDEN_DEPLOYMENT } from './shared/deployments'; +export { createDeployments, DEPLOYMENT_ACTIONS, HIDDEN_DEPLOYMENT, HIDDEN_RELEASE, RELEASE_KINDS, ACTIVE_RUN_STATES, WAIT_INTERVAL_MS, WAIT_LIMIT_SECONDS, WAITING_STAGE, releaseStats } from './shared/deployments'; export type { DeploymentRequest } from './shared/deployments'; export { writeWorkspacePreferences, readDesktopPreferences } from './shared/workspaceSettings'; diff --git a/src/shared/deployments.ts b/src/shared/deployments.ts index 22e9237..523333a 100644 --- a/src/shared/deployments.ts +++ b/src/shared/deployments.ts @@ -7,14 +7,29 @@ import { bindSessionAccount } from './accountScope'; export type DeploymentRequest = { action: 'deployment-history'; backend: string; expectedAccount: string; environmentUid: string; codeRepositoryBranchUid?: string; limit?: number; offset?: number } | { action: 'deployment-run'; backend: string; expectedAccount: string; runUid: string; kind?: 'deployment_run' | 'workflow_run' } - | { action: 'deployment-logs'; backend: string; expectedAccount: string; runUid: string; stepUid?: string; cursor?: string; limit?: number }; -export const DEPLOYMENT_ACTIONS = new Set(['deployment-history', 'deployment-run', 'deployment-logs']); + | { action: 'deployment-logs'; backend: string; expectedAccount: string; runUid: string; stepUid?: string; cursor?: string; limit?: number } + | { action: 'deployment-releases'; backend: string; expectedAccount: string; environmentUid: string; codeRepositoryBranchUid?: string; releaseKind?: string; search?: string; days?: number; limit?: number; offset?: number } + | { action: 'deployment-release'; backend: string; expectedAccount: string; environmentUid: string; releaseUid: string; days?: number; limit?: number } + | { action: 'deployment-active'; backend: string; expectedAccount: string; environmentUid: string; codeRepositoryBranchUid?: string } + | { action: 'deployment-wait'; backend: string; expectedAccount: string; runUid: string; timeoutSeconds?: number }; +export const DEPLOYMENT_ACTIONS = new Set(['deployment-history', 'deployment-run', 'deployment-logs', 'deployment-releases', 'deployment-release', 'deployment-active', 'deployment-wait']); +/** Release kinds as the backend names them, with the words the pane shows. */ +export const RELEASE_KINDS: Record = { fastapi: 'API', harness_agent: 'Agent', agent: 'Agent', static_site: 'Static site' }; +/** A run in any other state has ended and never changes again. */ +export const ACTIVE_RUN_STATES = new Set(['queued', 'running']); +/** How often a wait re-reads its run, and the longest one call waits. */ +export const WAIT_INTERVAL_MS = 10_000; +export const WAIT_LIMIT_SECONDS = 120; +/** The stage name release stats give the time a run waits before its first stage starts. */ +export const WAITING_STAGE = 'Waiting to start'; /** Command Center's wording for a run that answers 404: it never says whether the record exists. */ export const HIDDEN_DEPLOYMENT = "You can't see this deployment. A deployment is shown to the people who can see its release or Job."; +export const HIDDEN_RELEASE = "You can't see this release. A release is shown to the people it is shared with."; const UUID = /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i; const ACTIVE = new Set(['pending', 'queued', 'running']); -const RUN_PATH = /^\/api\/v1\/(?:deployment-runs\/[a-f0-9-]{36}\/(?:logs\/)?|deployment-history\/[a-f0-9-]{36}\/)$/; +const RUN_PATH = /^\/api\/v1\/(?:deployment-runs\/[a-f0-9-]{36}\/(?:logs\/)?|deployment-history\/[a-f0-9-]{36}\/|resource-releases\/[a-f0-9-]{36}\/(?:revisions\/)?)$/; +const RELEASE_TARGETS = new Set(['resource_release', 'harness_agent', 'static_site']); function uuid(value: unknown, message: string): string { if (typeof value !== 'string' || !UUID.test(value)) throw new ToolingError('INVALID_REQUEST', message); @@ -96,7 +111,7 @@ export function deploymentRun(row: unknown, now: number) { const stepUid = optionalUuid(step.uid), key = text(step.key, 200); return { id: stepUid ?? key, uid: stepUid, sequence: Number(step.sequence), key, name: text(step.name, 200), kind: text(step.kind, 60), state: text(step.state, 40) || 'unknown', outcome: text(step.outcome, 100), reason: text(step.reason ?? step.skip_reason, 500), - startedAt, finishedAt, durationMs: duration(startedAt, finishedAt, now), error: errorText(step.error) }; + startedAt, finishedAt, durationMs: duration(startedAt, finishedAt, now), error: errorText(step.error), errorCode: errorCode(step.error) }; }); const createdAt = when(run.created_at), finishedAt = when(run.finished_at); const startedAt = when(run.started_at) ?? earliest(steps.map(step => step.startedAt)) ?? createdAt; @@ -108,7 +123,88 @@ export function deploymentRun(row: unknown, now: number) { commit: text(run.commit_sha, 40).slice(0, 7), createdAt, startedAt, finishedAt, durationMs: duration(startedAt, finishedAt, now), currentStepKey: text(rec(run.pipeline).current_step_key, 200), steps, workflowStepKeys: list(run.workflow_step_keys).slice(0, 40).map(key => text(key, 200)), workflowRun: workflow, - logsAvailable: rec(run.logs).state === 'available' || typeof rec(run.logs).url === 'string', error: errorText(run.error) }; + logsAvailable: rec(run.logs).state === 'available' || typeof rec(run.logs).url === 'string', error: errorText(run.error), errorCode: errorCode(run.error), + releaseUid: optionalUuid(rec(target.resource_release).uid) ?? (RELEASE_TARGETS.has(text(run.target_type, 60)) ? optionalUuid(target.uid) ?? optionalUuid(run.target_uid) : null) }; +} +type Run = NonNullable>; + +function errorCode(value: unknown): string { + const code = rec(value).code; + return typeof code === 'string' ? text(code, 100) : ''; +} +function percentile(sorted: number[], share: number): number | null { + if (!sorted.length) return null; + return sorted[Math.min(sorted.length - 1, Math.max(0, Math.ceil(share * sorted.length) - 1))]; +} +const numbers = (values: (number | null)[]) => values.filter((value): value is number => typeof value === 'number' && Number.isFinite(value)).sort((a, b) => a - b); + +/** What a set of runs says about a release: counts by state, success rate over runs that + * either deployed or failed, durations of the runs that succeeded, the stage that takes + * longest and the failure seen most. The backend has no statistics endpoint. */ +export function releaseStats(runs: Run[]) { + const counts: Record = { succeeded: 0, failed: 0, blocked: 0, cancelled: 0, superseded: 0, skipped: 0, active: 0 }; + const stages = new Map(), failures = new Map(); + for (const run of runs) { + if (ACTIVE_RUN_STATES.has(run.state)) { counts.active++; continue; } + if (run.state in counts) counts[run.state]++; + if (run.state === 'succeeded') { + // A run can sit for minutes before its first stage, waiting on its workflow (an image + // build in another run): that wait is counted as a stage of its own. + const first = earliest(run.steps.map(step => step.startedAt)), waited = duration(run.startedAt, first, Number.NaN); + if (waited !== null) stages.set(WAITING_STAGE, [...(stages.get(WAITING_STAGE) || []), waited]); + for (const step of run.steps) if (step.state === 'succeeded') { + const name = step.name || step.key || step.kind; + if (name) stages.set(name, [...(stages.get(name) || []), step.durationMs]); + } + } + if (run.state === 'failed' || run.state === 'blocked') { + // Blocked runs often say why only in their outcome (workflow_prerequisite_failed). + const code = run.errorCode || run.steps.find(step => step.errorCode)?.errorCode || run.outcome || 'unknown'; + failures.set(code, (failures.get(code) || 0) + 1); + } + } + const decided = counts.succeeded + counts.failed + counts.blocked; + const durations = numbers(runs.filter(run => run.state === 'succeeded' && run.finishedAt).map(run => run.durationMs)); + let slowestStage: { name: string; medianMs: number } | null = null; + for (const [name, values] of stages) { + const median = percentile(numbers(values), 0.5); + if (median !== null && (!slowestStage || median > slowestStage.medianMs)) slowestStage = { name, medianMs: median }; + } + const [code, count] = [...failures].sort((a, b) => b[1] - a[1])[0] || []; + return { runs: runs.length, ...counts, successRate: decided ? counts.succeeded / decided : null, + medianMs: percentile(durations, 0.5), p90Ms: percentile(durations, 0.9), slowestStage, + commonFailure: code ? { code, count: count as number, of: counts.failed + counts.blocked } : null }; +} +function runSummary(run: Run) { + return { uid: run.uid, state: run.state, outcome: run.outcome, operation: run.operation, source: run.source, commit: run.commit, + createdAt: run.createdAt, startedAt: run.startedAt, finishedAt: run.finishedAt, durationMs: run.durationMs, error: run.error, errorCode: run.errorCode, + currentStepKey: run.currentStepKey, stepsDone: run.steps.filter(step => step.state === 'succeeded').length, stepsTotal: run.steps.length, + releaseUid: run.releaseUid, targetLabel: run.targetLabel, repositoryName: run.repositoryName, branchName: run.branchName }; +} +function releaseRow(row: unknown) { + const release = rec(row), kind = text(release.release_kind, 40); + return { uid: optionalUuid(release.uid), name: text(release.name, 200), kind, kindLabel: RELEASE_KINDS[kind] || kind.replace(/_/g, ' '), + branchUid: optionalUuid(release.code_repository_branch_uid), activeRevisionUid: optionalUuid(release.active_revision), desiredRevisionUid: optionalUuid(release.desired_revision) }; +} +function revisionRow(row: unknown) { + const revision = rec(row); + return { uid: optionalUuid(revision.uid), state: text(revision.state, 40), commit: text(revision.commit_sha, 40).slice(0, 7), + configurationRevision: Number.isInteger(revision.configuration_revision) ? revision.configuration_revision as number : null, + createdAt: when(revision.created_at), activatedAt: when(revision.activated_at) }; +} +const since = (days: number, now: number) => new Date(now - days * 86_400_000).toISOString(); +function page(value: unknown, what: string): { count: number; results: unknown[] } { + const body = rec(value); + if (!Array.isArray(body.results) || !Number.isInteger(body.count) || (body.count as number) < 0) throw new ToolingError('API_ERROR', `${what} ${what.endsWith('s') ? 'are' : 'is'} unavailable.`); + return { count: body.count as number, results: body.results }; +} +function pause(ms: number, signal?: AbortSignal): Promise { + return new Promise((resolve, reject) => { + if (signal?.aborted) { reject(new ToolingError('CANCELLED', 'The read was cancelled.')); return; } + const timer = setTimeout(() => { signal?.removeEventListener('abort', stop); resolve(); }, ms); + const stop = () => { clearTimeout(timer); reject(new ToolingError('CANCELLED', 'The read was cancelled.')); }; + signal?.addEventListener('abort', stop, { once: true }); + }); } function historyEntry(row: unknown, now: number) { @@ -183,6 +279,91 @@ export function createDeployments(options: { host: HostServices; signal?: AbortS complete: page.complete === true, entries, now: at }; summary = `${entries.length} log ${entries.length === 1 ? 'entry' : 'entries'}.`; } + } else if (input.action === 'deployment-releases') { + // Two reads: one page of releases, then their runs of the window in one request. + const environmentUid = uuid(input.environmentUid, 'Choose an organization environment first.'); + const days = integer(input.days, 1, 90, 30, 'Choose between 1 and 90 days of release history.'); + const limit = integer(input.limit, 1, 100, 50, 'Request between 1 and 100 releases.'); + const offset = integer(input.offset, 0, 1_000_000, 0, 'The release list offset is invalid.'); + const branchUid = input.codeRepositoryBranchUid === undefined ? '' : uuid(input.codeRepositoryBranchUid, 'Choose a repository branch from the current environment.'); + if (input.releaseKind !== undefined && !(typeof input.releaseKind === 'string' && input.releaseKind in RELEASE_KINDS)) throw new ToolingError('INVALID_REQUEST', `Choose a release kind: ${Object.keys(RELEASE_KINDS).join(', ')}.`); + if (input.search !== undefined && typeof input.search !== 'string') throw new ToolingError('INVALID_REQUEST', 'Search with text.'); + const kind = input.releaseKind || '', search = text(input.search ?? '', 300).trim(); + const query = new URLSearchParams({ organization_environment_uid: environmentUid, ordering: 'name', limit: String(limit), offset: String(offset) }); + if (branchUid) query.set('code_repository_branch_uid', branchUid); + if (kind) query.set('release_kind', kind); + if (search) query.set('search', search); + const releases = page(await scoped.request(backend, 'GET', `/api/v1/resource-releases/?${query}`), 'The release list'); + const rows = releases.results.map(releaseRow).filter(row => row.uid); + let runs: Run[] = [], inWindow = 0; + if (rows.length) { + const runQuery = new URLSearchParams({ organization_environment_uid: environmentUid, target_uid__in: rows.map(row => row.uid).join(','), + created_after: since(days, now), ordering: '-creation_date', limit: '500' }); + const found = page(await scoped.request(backend, 'GET', `/api/v1/deployment-runs/?${runQuery}`), 'The deployment runs'); + inWindow = found.count; runs = found.results.map(row => deploymentRun(row, now)).filter((run): run is Run => !!run); + } + const byRelease = new Map(); + for (const run of runs) if (run.releaseUid) byRelease.set(run.releaseUid, [...(byRelease.get(run.releaseUid) || []), run]); + const results = rows.map(row => { + const own = byRelease.get(row.uid as string) || [], last = own[0], active = own.find(run => ACTIVE_RUN_STATES.has(run.state)); + return { ...row, repositoryName: last?.repositoryName || '', branchName: last?.branchName || '', recent: own.slice(0, 10).map(run => ({ uid: run.uid, state: run.state })), + lastRun: last ? runSummary(last) : null, activeRun: active ? runSummary(active) : null, stats: releaseStats(own) }; + }); + const deploying = results.filter(row => row.activeRun).length; + data = { environmentUid, branchUid: branchUid || null, releaseKind: kind || null, search: search || null, days, count: releases.count, limit, offset, now: at, + runsCounted: runs.length, runsInWindow: inWindow, runsTruncated: inWindow > runs.length, results }; + summary = `${releases.count} ${releases.count === 1 ? 'release' : 'releases'}${deploying ? `; ${deploying} deploying` : ''}.`; + } else if (input.action === 'deployment-release') { + const environmentUid = uuid(input.environmentUid, 'Choose an organization environment first.'); + const releaseUid = uuid(input.releaseUid, 'Choose a release from the current environment.'); + const days = integer(input.days, 1, 90, 30, 'Choose between 1 and 90 days of release history.'); + const limit = integer(input.limit, 1, 200, 100, 'Request between 1 and 200 runs.'); + const body = await scoped.request(backend, 'GET', `/api/v1/resource-releases/${releaseUid}/`); + if (rec(body).hidden === true) { data = { hidden: true, uid: releaseUid, now: at }; summary = HIDDEN_RELEASE; } + else { + const release = releaseRow(body); + if (release.uid !== releaseUid) throw new ToolingError('API_ERROR', 'The release record is unavailable.'); + const revisionBody = rec(await scoped.request(backend, 'GET', `/api/v1/resource-releases/${releaseUid}/revisions/?limit=20`)); + const revisions = list(revisionBody.results).map(revisionRow); + const runQuery = new URLSearchParams({ target_uid: releaseUid, organization_environment_uid: environmentUid, created_after: since(days, now), ordering: '-creation_date', limit: String(limit) }); + const found = page(await scoped.request(backend, 'GET', `/api/v1/deployment-runs/?${runQuery}`), 'The deployment runs'); + const runs = found.results.map(row => deploymentRun(row, now)).filter((run): run is Run => !!run); + const revision = (uid: string | null) => uid ? revisions.find(item => item.uid === uid) || { uid, state: '', commit: '', configurationRevision: null, createdAt: null, activatedAt: null } : null; + data = { hidden: false, uid: releaseUid, environmentUid, days, now: at, + release: { ...release, repositoryName: runs[0]?.repositoryName || '', branchName: runs[0]?.branchName || '', + activeRevision: revision(release.activeRevisionUid), desiredRevision: revision(release.desiredRevisionUid) }, + count: found.count, counted: runs.length, truncated: found.count > runs.length, runs: runs.map(runSummary), stats: releaseStats(runs) }; + summary = `${release.name || 'Release'}: ${found.count} ${found.count === 1 ? 'run' : 'runs'} in ${days} ${days === 1 ? 'day' : 'days'}.`; + } + } else if (input.action === 'deployment-active') { + // The cheap check: only runs still queued or running, which the backend allows one of per target. + const environmentUid = uuid(input.environmentUid, 'Choose an organization environment first.'); + const branchUid = input.codeRepositoryBranchUid === undefined ? '' : uuid(input.codeRepositoryBranchUid, 'Choose a repository branch from the current environment.'); + const query = new URLSearchParams({ organization_environment_uid: environmentUid, state__in: [...ACTIVE_RUN_STATES].join(','), ordering: '-creation_date', limit: '20' }); + if (branchUid) query.set('code_repository_branch_uid', branchUid); + const found = page(await scoped.request(backend, 'GET', `/api/v1/deployment-runs/?${query}`), 'The deployment runs'); + const runs = found.results.map(row => deploymentRun(row, now)).filter((run): run is Run => !!run).map(runSummary); + data = { environmentUid, branchUid: branchUid || null, count: found.count, now: at, runs }; + summary = found.count ? `${found.count} ${found.count === 1 ? 'deployment' : 'deployments'} in progress.` : 'No deployments in progress.'; + } else if (input.action === 'deployment-wait') { + // Re-reads one run every ten seconds until it ends or the wait runs out; never longer than two minutes. + const runUid = uuid(input.runUid, 'Choose a deployment run.'); + const timeout = integer(input.timeoutSeconds, 1, WAIT_LIMIT_SECONDS, 60, `Wait between 1 and ${WAIT_LIMIT_SECONDS} seconds.`); + const deadline = now + timeout * 1000; + for (let reads = 1; ; reads++) { + const row = await scoped.request(backend, 'GET', `/api/v1/deployment-runs/${runUid}/`); + const read = Date.now(), readAt = new Date(read).toISOString(); + if (rec(row).hidden === true) { data = { hidden: true, uid: runUid, now: readAt }; summary = HIDDEN_DEPLOYMENT; break; } + const run = deploymentRun(row, read); + if (!run || run.uid !== runUid) throw new ToolingError('API_ERROR', 'The deployment run record is unavailable.'); + const finished = !ACTIVE_RUN_STATES.has(run.state); + if (finished || read >= deadline) { + data = { hidden: false, uid: runUid, run, finished, waitedMs: read - now, reads, now: readAt }; + summary = finished ? `Deployment ${run.state}.` : `Deployment still ${run.state} after ${Math.round((read - now) / 1000)} s.`; + break; + } + await pause(Math.min(WAIT_INTERVAL_MS, deadline - read), options.signal); + } } else throw new ToolingError('INVALID_REQUEST', 'Unknown deployment action.'); await scoped.status(backend, true); return JSON.parse(session.sanitize(JSON.stringify({ schemaVersion: 1, action, status: 'success', summary, data }))); diff --git a/tests/deployment-releases.test.cjs b/tests/deployment-releases.test.cjs new file mode 100644 index 0000000..bd7efc3 --- /dev/null +++ b/tests/deployment-releases.test.cjs @@ -0,0 +1,144 @@ +const test = require('node:test'), assert = require('node:assert/strict'); +const { createDeployments, createNodeHost, releaseStats, WAIT_LIMIT_SECONDS } = require('../dist'); +const id = n => '00000000-0000-4000-8000-' + String(n).padStart(12, '0'), backend = 'https://fixture.example'; +const API = id(10), AGENT = id(11), SITE = id(12), ENV = id(1), BRANCH = id(5); +const iso = minutes => new Date(Date.parse('2026-11-18T12:00:00Z') + minutes * 60_000).toISOString(); +const step = (sequence, name, state, minutes, base = 0) => ({ uid: id(500 + sequence), sequence, name, kind: name.toLowerCase(), state, + started_at: iso(base), finished_at: state === 'running' || state === 'pending' ? null : iso(base + minutes) }); +function run(n, release, state, { minutes = 4, error, type = 'resource_release', steps } = {}) { + return { uid: id(100 + n), target_type: type, target_uid: release, state, operation: 'build_and_deploy', source: 'repository_event', commit_sha: `abc${n}def0123456`, + code_repository_branch_uid: BRANCH, created_at: iso(-n * 60), started_at: iso(-n * 60), finished_at: ['queued', 'running'].includes(state) ? null : iso(-n * 60 + minutes), + target: { uid: release, display_name: 'pricing-api', code_repository: { uid: id(4), name: 'pricing-engine' }, code_repository_branch: { uid: BRANCH, repository_branch: 'main' }, + resource_release: type === 'static_site' ? null : { uid: release, name: 'x' } }, + pipeline: { current_step_key: state === 'running' ? 'deploy' : '', steps: steps || [step(1, 'Build', 'succeeded', 3, -n * 60), step(2, 'Deploy', state === 'succeeded' ? 'succeeded' : state === 'running' ? 'running' : 'failed', minutes, -n * 60)] }, + ...(error ? { error } : {}), billing: { secret: 'never-return' }, cost_summary: { total: 99 } }; +} +function fixture({ runs, waitStates } = {}) { + const calls = [], state = { username: 'fixture' }; + const allRuns = runs || [run(0, API, 'running'), run(1, API, 'succeeded'), run(2, API, 'failed', { error: { code: 'runtime_readiness_timeout', detail: 'not ready' } }), + run(3, AGENT, 'failed', { type: 'harness_agent', error: { code: 'image_build_failed' } }), run(4, AGENT, 'superseded', { type: 'harness_agent' }), run(5, SITE, 'succeeded', { type: 'static_site' })]; + const reads = { wait: 0 }; + const api = createDeployments({ host: createNodeHost(), env: { MAINSEQUENCE_ENDPOINT: backend, MAINSEQUENCE_ACCESS_TOKEN: 'synthetic-secret' }, fetch: async (url, init) => { + const u = new URL(url); calls.push({ path: u.pathname, query: Object.fromEntries(u.searchParams), method: init.method }); + if (u.pathname === '/api/v1/users/me/') return Response.json({ username: state.username }); + if (u.pathname === '/api/v1/resource-releases/') return Response.json({ count: 3, results: [ + { uid: API, name: 'pricing-api', release_kind: 'fastapi', code_repository_branch_uid: BRANCH, active_revision: id(20), desired_revision: id(21), workload_user_uid: 'w' }, + { uid: AGENT, name: 'risk-agent', release_kind: 'harness_agent', code_repository_branch_uid: BRANCH }, + { uid: SITE, name: 'docs-site', release_kind: 'static_site', code_repository_branch_uid: BRANCH }] }); + if (u.pathname === `/api/v1/resource-releases/${API}/`) return Response.json({ uid: API, name: 'pricing-api', release_kind: 'fastapi', code_repository_branch_uid: BRANCH, active_revision: id(20), desired_revision: id(21) }); + if (u.pathname === `/api/v1/resource-releases/${API}/revisions/`) return Response.json({ count: 2, results: [ + { uid: id(21), state: 'pending', commit_sha: 'abc0def0123456', configuration_revision: 15, created_at: iso(0) }, + { uid: id(20), state: 'ready', commit_sha: 'abc1def0123456', configuration_revision: 14, created_at: iso(-60), activated_at: iso(-56) }] }); + if (u.pathname === '/api/v1/deployment-runs/') { + let rows = allRuns; + if (u.searchParams.get('target_uid__in')) rows = rows.filter(row => u.searchParams.get('target_uid__in').split(',').includes(row.target_uid)); + if (u.searchParams.get('target_uid')) rows = rows.filter(row => row.target_uid === u.searchParams.get('target_uid')); + if (u.searchParams.get('state__in')) rows = rows.filter(row => u.searchParams.get('state__in').split(',').includes(row.state)); + return Response.json({ count: rows.length, results: rows }); + } + if (u.pathname === `/api/v1/deployment-runs/${id(100)}/`) { + const states = waitStates || ['running']; const now = states[Math.min(reads.wait++, states.length - 1)]; + return Response.json(run(0, API, now)); + } + return Response.json({ detail: 'not found' }, { status: 404 }); + } }); + return { calls, state, reads, run: (action, args = {}) => api.dispatch({ action, backend, expectedAccount: 'fixture', ...args }) }; +} + +test('the release list reads one page of releases and their runs in one more request, grouped by release', async () => { + const f = fixture(), result = await f.run('deployment-releases', { environmentUid: ENV, days: 30 }); + assert.equal(result.status, 'success', result.summary); + const reads = f.calls.filter(call => call.path !== '/api/v1/users/me/'); + assert.deepEqual(reads.map(call => call.path), ['/api/v1/resource-releases/', '/api/v1/deployment-runs/']); + assert.ok(f.calls.every(call => call.method === 'GET')); + assert.equal(reads[0].query.organization_environment_uid, ENV); + assert.deepEqual(reads[1].query.target_uid__in.split(','), [API, AGENT, SITE]); + assert.ok(Date.parse(reads[1].query.created_after) <= Date.now() - 29 * 86_400_000, 'the window starts 30 days back'); + const [api, agent, site] = result.data.results; + assert.deepEqual([api.kindLabel, agent.kindLabel, site.kindLabel], ['API', 'Agent', 'Static site']); + assert.deepEqual(api.recent.map(item => item.state), ['running', 'succeeded', 'failed']); + assert.equal(api.activeRun.uid, id(100)); assert.equal(api.activeRun.stepsTotal, 2); + assert.equal(api.lastRun.uid, id(100)); assert.equal(api.repositoryName, 'pricing-engine'); assert.equal(api.branchName, 'main'); + assert.equal(api.stats.succeeded, 1); assert.equal(api.stats.failed, 1); assert.equal(api.stats.active, 1); assert.equal(api.stats.successRate, 0.5); + assert.equal(agent.activeRun, null); assert.equal(agent.stats.superseded, 1); + assert.equal(site.recent.length, 1, 'a static site run without a release reference still counts by its target'); + assert.match(result.summary, /3 releases; 1 deploying/); + assert.doesNotMatch(JSON.stringify(result), /never-return|cost_summary|synthetic-secret/); +}); + +test('the release list passes its filters to the backend and refuses unknown ones', async () => { + const f = fixture(); + assert.equal((await f.run('deployment-releases', { environmentUid: ENV, codeRepositoryBranchUid: BRANCH, releaseKind: 'fastapi', search: 'pricing' })).status, 'success'); + const query = f.calls.find(call => call.path === '/api/v1/resource-releases/').query; + assert.equal(query.code_repository_branch_uid, BRANCH); assert.equal(query.release_kind, 'fastapi'); assert.equal(query.search, 'pricing'); + for (const bad of [{ releaseKind: 'streamlit' }, { days: 0 }, { days: 91 }, { limit: 101 }, { search: 7 }, { environmentUid: 'nope' }]) { + const result = await f.run('deployment-releases', { environmentUid: ENV, ...bad }); + assert.equal(result.status, 'failure', JSON.stringify(bad)); assert.equal(result.error.code, 'INVALID_REQUEST'); + } +}); + +test('a release history shows what is serving, what is wanted, its runs and their stats', async () => { + const f = fixture(), result = await f.run('deployment-release', { environmentUid: ENV, releaseUid: API, days: 7 }); + assert.equal(result.status, 'success', result.summary); + const runs = f.calls.find(call => call.path === '/api/v1/deployment-runs/').query; + assert.equal(runs.target_uid, API); assert.equal(runs.organization_environment_uid, ENV); assert.equal(runs.ordering, '-creation_date'); + const { release, stats } = result.data; + assert.equal(release.activeRevision.commit, 'abc1def'); assert.equal(release.activeRevision.configurationRevision, 14); + assert.equal(release.desiredRevision.commit, 'abc0def'); assert.equal(release.repositoryName, 'pricing-engine'); + assert.equal(result.data.runs.length, 3); assert.equal(result.data.runs[2].errorCode, 'runtime_readiness_timeout'); + assert.deepEqual(stats.commonFailure, { code: 'runtime_readiness_timeout', count: 1, of: 1 }); + assert.equal(stats.medianMs, 4 * 60_000); + assert.deepEqual(stats.slowestStage, { name: 'Deploy', medianMs: 4 * 60_000 }); + const hidden = await f.run('deployment-release', { environmentUid: ENV, releaseUid: id(99) }); + assert.equal(hidden.status, 'success'); assert.equal(hidden.data.hidden, true); assert.match(hidden.summary, /can't see this release/); +}); + +test('release stats count only decided runs toward the success rate and ignore unfinished durations', () => { + const t = s => new Date(Date.parse('2026-11-18T12:00:00Z') + s * 1000).toISOString(); + const runs = [ + { state: 'succeeded', finishedAt: 'x', durationMs: 1000, startedAt: t(0), steps: [{ state: 'succeeded', name: 'Build', durationMs: 600, startedAt: t(0) }, { state: 'succeeded', name: 'Deploy', durationMs: 400, startedAt: t(1) }] }, + { state: 'succeeded', finishedAt: 'x', durationMs: 3000, startedAt: t(0), steps: [{ state: 'succeeded', name: 'Build', durationMs: 2600, startedAt: t(0) }, { state: 'succeeded', name: 'Deploy', durationMs: 400, startedAt: t(3) }] }, + { state: 'succeeded', finishedAt: 'x', durationMs: 2000, steps: [] }, + { state: 'blocked', errorCode: 'quota', steps: [] }, { state: 'failed', errorCode: '', steps: [{ state: 'failed', errorCode: 'image_build_failed' }] }, + { state: 'blocked', errorCode: '', outcome: 'workflow_prerequisite_failed', steps: [] }, { state: 'blocked', errorCode: '', outcome: 'workflow_prerequisite_failed', steps: [] }, + { state: 'superseded', steps: [] }, { state: 'cancelled', steps: [] }, { state: 'running', durationMs: 99_000, steps: [] }]; + const stats = releaseStats(runs); + assert.equal(stats.runs, 10); assert.equal(stats.active, 1); assert.equal(stats.successRate, 3 / 7); + assert.equal(stats.medianMs, 2000); assert.equal(stats.p90Ms, 3000); + assert.deepEqual(stats.slowestStage, { name: 'Build', medianMs: 600 }); + assert.deepEqual(stats.commonFailure, { code: 'workflow_prerequisite_failed', count: 2, of: 4 }, 'a blocked run without an error code is named by its outcome'); + const waiting = releaseStats([{ state: 'succeeded', finishedAt: 'x', durationMs: 300_000, startedAt: t(0), steps: [{ state: 'succeeded', name: 'Deploy', durationMs: 60_000, startedAt: t(240) }] }]); + assert.deepEqual(waiting.slowestStage, { name: 'Waiting to start', medianMs: 240_000 }, 'the wait before the first stage counts as a stage'); + assert.equal(releaseStats([]).successRate, null); assert.equal(releaseStats([]).medianMs, null); assert.equal(releaseStats([]).commonFailure, null); +}); + +test('the active check asks only for queued and running runs', async () => { + const f = fixture(), result = await f.run('deployment-active', { environmentUid: ENV, codeRepositoryBranchUid: BRANCH }); + assert.equal(result.status, 'success'); + const query = f.calls.find(call => call.path === '/api/v1/deployment-runs/').query; + assert.equal(query.state__in, 'queued,running'); assert.equal(query.code_repository_branch_uid, BRANCH); + assert.equal(result.data.count, 1); assert.equal(result.data.runs[0].uid, id(100)); assert.equal(result.summary, '1 deployment in progress.'); + const quiet = fixture({ runs: [run(1, API, 'succeeded')] }); + assert.equal((await quiet.run('deployment-active', { environmentUid: ENV })).summary, 'No deployments in progress.'); +}); + +test('a wait returns as soon as the run ends, and says so when it is still running at the limit', async () => { + const done = fixture({ waitStates: ['running', 'succeeded'] }); + const started = Date.now(), finished = await done.run('deployment-wait', { runUid: id(100), timeoutSeconds: 2 }); + assert.equal(finished.status, 'success', finished.summary); assert.equal(finished.data.finished, true); assert.equal(finished.data.run.state, 'succeeded'); + assert.equal(finished.summary, 'Deployment succeeded.'); assert.ok(Date.now() - started < 4000); + const still = fixture({ waitStates: ['running'] }), waited = await still.run('deployment-wait', { runUid: id(100), timeoutSeconds: 1 }); + assert.equal(waited.data.finished, false); assert.match(waited.summary, /still running after \d+ s/); + assert.ok(still.reads.wait >= 2 && still.reads.wait <= 3, `reads ${still.reads.wait}`); + assert.equal((await still.run('deployment-wait', { runUid: id(100), timeoutSeconds: WAIT_LIMIT_SECONDS + 1 })).error.code, 'INVALID_REQUEST'); + assert.equal((await still.run('deployment-wait', { runUid: id(77), timeoutSeconds: 1 })).data.hidden, true); +}); + +test('a wait stops when its read is cancelled', async () => { + const controller = new AbortController(); + const api = createDeployments({ host: createNodeHost(), signal: controller.signal, env: { MAINSEQUENCE_ENDPOINT: backend, MAINSEQUENCE_ACCESS_TOKEN: 'synthetic-secret' }, + fetch: async url => new URL(url).pathname === '/api/v1/users/me/' ? Response.json({ username: 'fixture' }) : Response.json(run(0, API, 'running')) }); + setTimeout(() => controller.abort(), 300); + const started = Date.now(), result = await api.dispatch({ action: 'deployment-wait', backend, expectedAccount: 'fixture', runUid: id(100), timeoutSeconds: 60 }); + assert.equal(result.status, 'cancelled'); assert.ok(Date.now() - started < 3000); +});