Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
---
depth: standard
id: EVID-038
kind: evidence
last_modified_at: 2026-05-09T16:37:02.382471+00:00
last_modified_by: claude-code/2.1.138
links:
- target: PRD-027
relation: informs
- target: RFC-023
relation: informs
status: active
title: instance-status endpoint smoke test
---

# EVID-038: instance-status endpoint smoke test

| Field | Value |
|-------|-------|
| Status | Draft |
| Created | 2026-05-09 |
| Valid Until | 2026-08-09 |
| Target | PRD-027 (instance registry + viewer) |

<!-- REQUIRED for R_eff scoring. Legal values documented in templates/evidence/README.md. -->

## Structured Fields

evidence_type: test
verdict: supports
congruence_level: 3

## Measurement

`GET /api/instance-status` endpoint added in PR #136 (`feat(health-bar): instance switcher relevance`).
Verified via `npm run check` (svelte-check) — 0 errors, 0 warnings across 1070 files.
Endpoint calls `runForgeplan(['health', '--json'])` and `runForgeplan(['claims', '--json'])` in parallel,
both of which are in `READ_ONLY_SUBCOMMANDS` (rule 22 enforcement in `forgeplan.ts`).

Test surface: the endpoint itself + `HealthBar.svelte` (pre-flight fetch to `http://{host}:{port}/api/instance-status`
before any instance switch).

## Result

- `svelte-check`: 0 errors, 0 warnings (1070 files) — merge commit `6f633cc`
- `READ_ONLY_SUBCOMMANDS` check: `health` ✓, `claims` ✓ — no new subcommands added
- Rule 22 proxy constraint: only `GET`, no spawn of mutating subcommands, no external network calls
- CI matrix (ubuntu / macos / windows × node 22): 6/6 passing (PR #136)

## Interpretation

The endpoint is structurally correct (type-safe, rule 22-compliant, CI green) and is used by the
instance switcher as the pre-flight validation target. Supports the PRD-027 goal of a reliable,
read-only instance-viewer surface.

## Congruence Level Justification

CL3: evidence is a direct test of the exact surface (the `/api/instance-status` endpoint in this repo,
built and type-checked in the same CI run). Same context — no extrapolation from external data.

## Related Artifacts

| Artifact | Relation |
|----------|----------|
| PRD-027 | informs |
| RFC-023 | informs |




Original file line number Diff line number Diff line change
Expand Up @@ -290,3 +290,4 @@ And each entry has fields per SPEC-003 v1




Original file line number Diff line number Diff line change
Expand Up @@ -408,3 +408,4 @@ process.on('beforeExit', cleanup);




2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@forgeplan/web",
"version": "0.2.1",
"version": "0.2.2",
"description": "Interactive realtime web map for a Forgeplan workspace. Ships a pre-built SvelteKit app and a tiny init/start CLI — no npm install at user side.",
"type": "module",
"bin": {
Expand Down
2 changes: 1 addition & 1 deletion template/package.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "forgeplan-web-app",
"private": true,
"version": "0.2.1",
"version": "0.2.2",
"type": "module",
"scripts": {
"dev": "vite dev --port 5174 --host 127.0.0.1",
Expand Down
2 changes: 2 additions & 0 deletions template/src/entities/instance/index.ts
Original file line number Diff line number Diff line change
@@ -1,2 +1,4 @@
export type { Instance, InstanceScope, InstancesPayload } from "./model/types";
export type { InstanceStatus, InstanceHealth } from "./model/instance-status";
export { instancePoller } from "./api/store";
export { InstanceItem } from "./ui";
14 changes: 14 additions & 0 deletions template/src/entities/instance/model/instance-status.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
// Subset of HealthResponse used by the instance-switcher.
// Defined here (not imported from entities/health) to avoid cross-entity imports
// per FSD same-layer isolation rules.
export interface InstanceHealth {
total: number;
project: string;
stale_count: number;
by_status: { status: string; count: number }[];
}

export interface InstanceStatus {
health: InstanceHealth | null;
agentCount: number;
}
81 changes: 81 additions & 0 deletions template/src/entities/instance/ui/InstanceItem.svelte
Original file line number Diff line number Diff line change
@@ -0,0 +1,81 @@
<script lang="ts">
import type { Instance } from "../model/types";
import type { InstanceStatus } from "../model/instance-status";

interface Props {
instance: Instance;
status: InstanceStatus | null | undefined;
}

let { instance, status }: Props = $props();
</script>

<span class="item">
<span class="item-name">{instance.projectName}</span>
<span class="item-meta">
<span class="item-host">{instance.host}:{instance.port}</span>
{#if status === undefined}
<span class="item-skeleton" aria-hidden="true"></span>
{:else if status !== null}
<span class="item-status" data-test="instance-status">
{status.agentCount} agent{status.agentCount === 1 ? "" : "s"}
· {status.health?.total ?? "?"} artifacts
</span>
{:else}
<span class="item-offline" data-test="instance-offline">offline</span>
{/if}
</span>
</span>

<style>
.item {
display: inline-flex;
flex-direction: column;
gap: 3px;
min-width: 0;
}
.item-name {
display: inline-flex;
align-items: center;
gap: 8px;
color: var(--fg-1);
font-size: 12px;
font-family: var(--font-mono);
}
.item-meta {
display: inline-flex;
align-items: center;
gap: 8px;
}
.item-host {
color: var(--fg-3);
font-family: var(--font-mono);
font-size: 10px;
letter-spacing: 0.04em;
}
.item-skeleton {
display: inline-block;
width: 56px;
height: 9px;
border-radius: 2px;
background: color-mix(in srgb, var(--fg) 10%, transparent);
animation: skeleton-pulse 1.4s ease-in-out infinite;
}
@keyframes skeleton-pulse {
0%, 100% { opacity: 0.3; }
50% { opacity: 0.7; }
}
.item-status {
color: var(--fg-4);
font-family: var(--font-mono);
font-size: 10px;
letter-spacing: 0.02em;
}
.item-offline {
color: var(--bad);
font-family: var(--font-mono);
font-size: 10px;
letter-spacing: 0.06em;
text-transform: uppercase;
}
</style>
1 change: 1 addition & 0 deletions template/src/entities/instance/ui/index.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
export { default as InstanceItem } from './InstanceItem.svelte';
31 changes: 31 additions & 0 deletions template/src/routes/api/instance-status/+server.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
import { json } from '@sveltejs/kit';
import type { RequestHandler } from './$types';
import { runForgeplan } from '@/shared/server';

// Issue #134: pre-flight validation + live-status polling endpoint for the
// instance switcher. Uses only allowed subcommands (health, claims) per rule 22;
// no new non-forgeplan external calls.
const CMD_LABEL = 'health + claims --json';

export const GET: RequestHandler = async () => {
const [healthResult, claimsResult] = await Promise.all([
runForgeplan(['health', '--json']),
runForgeplan(['claims', '--json']),
]);

const claimsData =
claimsResult.ok && claimsResult.data
? (claimsResult.data as { count?: number; claims?: unknown[] })
: null;

const agentCount = claimsData?.count ?? claimsData?.claims?.length ?? 0;

return json({
ok: healthResult.ok,
data: {
health: healthResult.ok ? healthResult.data : null,
agentCount,
},
cmd: CMD_LABEL,
});
};
5 changes: 5 additions & 0 deletions template/src/shared/ui/button/Button.svelte
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,11 @@
user-select: none;
}

:global(.btn > svg) {
display: flex;
flex-shrink: 0;
}

.btn:focus-visible {
outline: 2px solid var(--accent);
outline-offset: 2px;
Expand Down
Loading
Loading