From d4792b0464b3c1737be9f39affbc83002ce88e0b Mon Sep 17 00:00:00 2001 From: Jose Antonio Alatorre Date: Wed, 18 Nov 2026 20:44:55 +0100 Subject: [PATCH 1/2] Read releases, their run history and stats, active runs, and wait for a run Four read-only deployment actions for the Claude and Codex panes and model tools: deployment-releases (a page of releases plus their runs of the window in one request), deployment-release (serving and wanted revisions, runs and stats), deployment-active (only queued and running runs) and deployment-wait (one run every ten seconds, at most two minutes). releaseStats() computes success rate, durations, the slowest stage (including the wait before the first stage) and the most common failure, since the backend has no statistics endpoint. docs/deployments.md gives hosts the polling rules. Co-Authored-By: Claude Opus 5.5 --- README.md | 2 + docs/deployments.md | 46 +++++++ src/index.ts | 2 +- src/shared/deployments.ts | 191 ++++++++++++++++++++++++++++- tests/deployment-releases.test.cjs | 144 ++++++++++++++++++++++ 5 files changed, 379 insertions(+), 6 deletions(-) create mode 100644 docs/deployments.md create mode 100644 tests/deployment-releases.test.cjs 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/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); +}); From e13057053290576057d33b3d12df0c3f7b4f3198 Mon Sep 17 00:00:00 2001 From: Jose Antonio Alatorre Date: Wed, 18 Nov 2026 20:45:15 +0100 Subject: [PATCH 2/2] Version 0.3.19 Co-Authored-By: Claude Opus 5.5 --- package-lock.json | 4 ++-- package.json | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) 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": {