Compare commits
1
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 jason.woltje
|
4917df1f07 |
@@ -1,110 +0,0 @@
|
||||
'use client';
|
||||
|
||||
import type { ReactElement } from 'react';
|
||||
import { formatAge, type FreshnessLabel } from '@/lib/freshness/model';
|
||||
|
||||
/**
|
||||
* Rendering rules for non-current freshness states (RI-5-001).
|
||||
*
|
||||
* - `unavailable` renders an explicit failure panel — never an empty
|
||||
* healthy collection.
|
||||
* - `stale` may render last-known data, but only under a visible label
|
||||
* carrying source identity, snapshot version, and age.
|
||||
* - `partial` renders the verified parts plus an explicit list of what is
|
||||
* missing.
|
||||
*/
|
||||
|
||||
interface RetryableNoticeProps {
|
||||
readonly onRetry?: () => void;
|
||||
readonly retryLabel?: string;
|
||||
}
|
||||
|
||||
function RetryButton({ onRetry, retryLabel }: RetryableNoticeProps): ReactElement | null {
|
||||
if (!onRetry) return null;
|
||||
return (
|
||||
<button
|
||||
type="button"
|
||||
onClick={onRetry}
|
||||
className="mt-2 rounded-lg border border-surface-border px-3 py-1.5 text-xs transition-colors hover:border-gray-500"
|
||||
>
|
||||
{retryLabel ?? 'Retry'}
|
||||
</button>
|
||||
);
|
||||
}
|
||||
|
||||
export interface UnavailableDataNoticeProps extends RetryableNoticeProps {
|
||||
/** What is unavailable, e.g. "Tasks". */
|
||||
readonly title: string;
|
||||
/** Optional underlying failure detail (network message, invalidation reason). */
|
||||
readonly detail?: string | null;
|
||||
}
|
||||
|
||||
/** Explicit `unavailable` state. Never renders as an empty healthy collection. */
|
||||
export function UnavailableDataNotice({
|
||||
title,
|
||||
detail,
|
||||
onRetry,
|
||||
retryLabel,
|
||||
}: UnavailableDataNoticeProps): ReactElement {
|
||||
return (
|
||||
<div role="alert" className="rounded-lg border border-error/40 px-4 py-3 text-sm">
|
||||
<p className="font-medium text-text-primary">{title} are unavailable</p>
|
||||
<p className="mt-1 text-text-muted">
|
||||
This is not an empty result — the data could not be verified from the gateway.
|
||||
{detail ? ` ${detail}` : ''}
|
||||
</p>
|
||||
<RetryButton onRetry={onRetry} retryLabel={retryLabel} />
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
export interface StaleDataNoticeProps extends RetryableNoticeProps {
|
||||
/** Provenance of the last-known snapshot being displayed. */
|
||||
readonly label: FreshnessLabel;
|
||||
}
|
||||
|
||||
/**
|
||||
* Situational-awareness banner for `stale` data: last-known data may render,
|
||||
* but visibly labeled with source identity, snapshot version, and age.
|
||||
*/
|
||||
export function StaleDataNotice({
|
||||
label,
|
||||
onRetry,
|
||||
retryLabel,
|
||||
}: StaleDataNoticeProps): ReactElement {
|
||||
return (
|
||||
<div role="status" className="rounded-lg border border-warning/40 px-4 py-3 text-sm">
|
||||
<p className="font-medium text-warning">Showing last-known data — it may be out of date</p>
|
||||
<p className="mt-1 text-xs text-text-muted">
|
||||
Source {label.source} · snapshot v{label.version} · fetched{' '}
|
||||
{formatAge(label.fetchedAt, Date.now())}. Verdicts derived from this data are unknown and
|
||||
changes are disabled until it is revalidated.
|
||||
</p>
|
||||
<RetryButton onRetry={onRetry} retryLabel={retryLabel ?? 'Revalidate'} />
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
export interface PartialDataNoticeProps extends RetryableNoticeProps {
|
||||
/** Display names of the sections whose collections are unavailable. */
|
||||
readonly missing: readonly string[];
|
||||
}
|
||||
|
||||
/** `partial` surface banner: verified parts render, missing parts are explicit. */
|
||||
export function PartialDataNotice({
|
||||
missing,
|
||||
onRetry,
|
||||
retryLabel,
|
||||
}: PartialDataNoticeProps): ReactElement {
|
||||
return (
|
||||
<div role="status" className="rounded-lg border border-warning/40 px-4 py-3 text-sm">
|
||||
<p className="font-medium text-warning">Some data could not be loaded</p>
|
||||
<p className="mt-1 text-xs text-text-muted">
|
||||
{missing.join(', ')} {missing.length === 1 ? 'is' : 'are'} unavailable — sections below show
|
||||
an explicit unavailable state instead of an empty list. Derived verdicts remain unknown
|
||||
until every collection is revalidated.
|
||||
</p>
|
||||
<RetryButton onRetry={onRetry} retryLabel={retryLabel ?? 'Revalidate'} />
|
||||
</div>
|
||||
);
|
||||
}
|
||||
@@ -1,324 +0,0 @@
|
||||
import { describe, expect, it } from 'vitest';
|
||||
import type { Task } from '@/lib/types';
|
||||
import {
|
||||
acceptSnapshot,
|
||||
assertMutable,
|
||||
canMutate,
|
||||
combineFreshness,
|
||||
computeDigest,
|
||||
computeFreshness,
|
||||
DEFAULT_FRESHNESS_POLICY,
|
||||
formatAge,
|
||||
type FreshSnapshot,
|
||||
invalidationReasonLabels,
|
||||
StaleMutationError,
|
||||
UNKNOWN_VERDICT,
|
||||
verdictValue,
|
||||
} from './model';
|
||||
import { validateProjectCollection, validateTaskCollection } from './validators';
|
||||
|
||||
const NOW = 1_800_000_000_000;
|
||||
|
||||
const policy = { ...DEFAULT_FRESHNESS_POLICY, staleAfterMs: 60_000 };
|
||||
|
||||
const taskPayload: Task[] = [
|
||||
{
|
||||
id: 'task-1',
|
||||
title: 'T1',
|
||||
description: null,
|
||||
status: 'not-started',
|
||||
priority: 'high',
|
||||
projectId: 'project-1',
|
||||
missionId: null,
|
||||
assignee: null,
|
||||
tags: null,
|
||||
dueDate: null,
|
||||
metadata: null,
|
||||
createdAt: '2026-08-01T00:00:00.000Z',
|
||||
updatedAt: '2026-08-01T00:00:00.000Z',
|
||||
},
|
||||
];
|
||||
|
||||
function acceptedTaskSnapshot(
|
||||
overrides: Partial<FreshSnapshot<typeof taskPayload>> = {},
|
||||
): FreshSnapshot<typeof taskPayload> {
|
||||
const result = acceptSnapshot({
|
||||
value: taskPayload,
|
||||
validate: validateTaskCollection,
|
||||
previous: null,
|
||||
policy,
|
||||
source: 'gateway:/api/tasks',
|
||||
now: NOW,
|
||||
});
|
||||
if (result.outcome !== 'accepted') {
|
||||
throw new Error(`fixture setup failed: ${result.reason}`);
|
||||
}
|
||||
return { ...result.snapshot, ...overrides };
|
||||
}
|
||||
|
||||
describe('computeFreshness', () => {
|
||||
it('treats a missing snapshot as unavailable, never as an empty healthy collection', () => {
|
||||
expect(computeFreshness({ snapshot: null, policy, now: NOW })).toBe('unavailable');
|
||||
});
|
||||
|
||||
it('returns current for a fresh verified snapshot regardless of data emptiness', () => {
|
||||
const empty = acceptSnapshot({
|
||||
value: [],
|
||||
validate: validateTaskCollection,
|
||||
previous: null,
|
||||
policy,
|
||||
source: 'gateway:/api/tasks',
|
||||
now: NOW,
|
||||
});
|
||||
if (empty.outcome !== 'accepted') throw new Error('expected acceptance');
|
||||
expect(computeFreshness({ snapshot: empty.snapshot, policy, now: NOW })).toBe('current');
|
||||
});
|
||||
|
||||
it('degrades to stale once the snapshot ages past staleAfterMs', () => {
|
||||
const snapshot = acceptedTaskSnapshot();
|
||||
expect(computeFreshness({ snapshot, policy, now: NOW + 60_001 })).toBe('stale');
|
||||
expect(computeFreshness({ snapshot, policy, now: NOW + 59_999 })).toBe('current');
|
||||
});
|
||||
|
||||
it('degrades to stale when the latest revalidation failed', () => {
|
||||
const snapshot = acceptedTaskSnapshot();
|
||||
expect(computeFreshness({ snapshot, policy, now: NOW, degraded: true })).toBe('stale');
|
||||
});
|
||||
});
|
||||
|
||||
describe('mutation guard', () => {
|
||||
it('permits mutations only on current data', () => {
|
||||
expect(canMutate('current')).toBe(true);
|
||||
for (const state of ['stale', 'partial', 'unknown', 'unavailable'] as const) {
|
||||
expect(canMutate(state)).toBe(false);
|
||||
}
|
||||
});
|
||||
|
||||
it('refuses mutations on non-current data via assertMutable', () => {
|
||||
expect(() => assertMutable('current')).not.toThrow();
|
||||
for (const state of ['stale', 'partial', 'unknown', 'unavailable'] as const) {
|
||||
let thrown: unknown;
|
||||
try {
|
||||
assertMutable(state);
|
||||
} catch (caught) {
|
||||
thrown = caught;
|
||||
}
|
||||
expect(thrown).toBeInstanceOf(StaleMutationError);
|
||||
expect(thrown).toBeInstanceOf(Error);
|
||||
if (thrown instanceof StaleMutationError) {
|
||||
expect(thrown.name).toBe('StaleMutationError');
|
||||
expect(thrown.freshness).toBe(state);
|
||||
expect(thrown.message).toContain(state);
|
||||
expect(thrown.message).toContain('revalidat');
|
||||
}
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
describe('acceptSnapshot', () => {
|
||||
it('accepts a valid payload with provenance', () => {
|
||||
const result = acceptSnapshot({
|
||||
value: taskPayload,
|
||||
validate: validateTaskCollection,
|
||||
previous: null,
|
||||
policy,
|
||||
source: 'gateway:/api/tasks',
|
||||
now: NOW,
|
||||
});
|
||||
expect(result.outcome).toBe('accepted');
|
||||
if (result.outcome !== 'accepted') return;
|
||||
expect(result.snapshot.source).toBe('gateway:/api/tasks');
|
||||
expect(result.snapshot.version).toBe(1);
|
||||
expect(result.snapshot.fetchedAt).toBe(NOW);
|
||||
expect(result.snapshot.data).toEqual(taskPayload);
|
||||
});
|
||||
|
||||
it('invalidates a schema-mismatched payload instead of rendering it', () => {
|
||||
const result = acceptSnapshot({
|
||||
value: { not: 'an array' },
|
||||
validate: validateTaskCollection,
|
||||
previous: acceptedTaskSnapshot(),
|
||||
policy,
|
||||
source: 'gateway:/api/tasks',
|
||||
now: NOW,
|
||||
});
|
||||
expect(result).toEqual({ outcome: 'invalidated', reason: 'schema-mismatch' });
|
||||
expect(invalidationReasonLabels['schema-mismatch']).toContain('schema');
|
||||
});
|
||||
|
||||
it('invalidates cross-workspace payloads', () => {
|
||||
const userOne = acceptSnapshot({
|
||||
value: [
|
||||
{
|
||||
id: 'p1',
|
||||
name: 'P1',
|
||||
description: null,
|
||||
status: 'active',
|
||||
userId: 'user-1',
|
||||
metadata: null,
|
||||
createdAt: '2026-08-01T00:00:00.000Z',
|
||||
updatedAt: '2026-08-01T00:00:00.000Z',
|
||||
},
|
||||
],
|
||||
validate: validateProjectCollection,
|
||||
previous: null,
|
||||
policy,
|
||||
source: 'gateway:/api/projects',
|
||||
now: NOW,
|
||||
});
|
||||
if (userOne.outcome !== 'accepted') throw new Error('expected acceptance');
|
||||
|
||||
const switched = acceptSnapshot({
|
||||
value: [
|
||||
{
|
||||
id: 'p9',
|
||||
name: 'P9',
|
||||
description: null,
|
||||
status: 'active',
|
||||
userId: 'user-2',
|
||||
metadata: null,
|
||||
createdAt: '2026-08-01T00:00:00.000Z',
|
||||
updatedAt: '2026-08-01T00:00:00.000Z',
|
||||
},
|
||||
],
|
||||
validate: validateProjectCollection,
|
||||
previous: userOne.snapshot,
|
||||
policy,
|
||||
source: 'gateway:/api/projects',
|
||||
now: NOW,
|
||||
});
|
||||
expect(switched).toEqual({ outcome: 'invalidated', reason: 'cross-workspace' });
|
||||
});
|
||||
|
||||
it('keeps the previous workspace for collections with no intrinsic identity', () => {
|
||||
const userOne = acceptSnapshot({
|
||||
value: [
|
||||
{
|
||||
id: 'p1',
|
||||
name: 'P1',
|
||||
description: null,
|
||||
status: 'active',
|
||||
userId: 'user-1',
|
||||
metadata: null,
|
||||
createdAt: '2026-08-01T00:00:00.000Z',
|
||||
updatedAt: '2026-08-01T00:00:00.000Z',
|
||||
},
|
||||
],
|
||||
validate: validateProjectCollection,
|
||||
previous: null,
|
||||
policy,
|
||||
source: 'gateway:/api/projects',
|
||||
now: NOW,
|
||||
});
|
||||
if (userOne.outcome !== 'accepted') throw new Error('expected acceptance');
|
||||
|
||||
// Empty list after the user deleted every project: no identity to check,
|
||||
// so the verified scope is retained and the empty state stays healthy.
|
||||
const emptied = acceptSnapshot({
|
||||
value: [],
|
||||
validate: validateProjectCollection,
|
||||
previous: userOne.snapshot,
|
||||
policy,
|
||||
source: 'gateway:/api/projects',
|
||||
now: NOW,
|
||||
});
|
||||
expect(emptied.outcome).toBe('accepted');
|
||||
if (emptied.outcome === 'accepted') {
|
||||
expect(emptied.snapshot.data).toEqual([]);
|
||||
expect(emptied.snapshot.workspace).toBe('user-1');
|
||||
}
|
||||
});
|
||||
|
||||
it('invalidates version regressions', () => {
|
||||
const previous = acceptedTaskSnapshot({ version: 7 });
|
||||
const regressed = acceptSnapshot({
|
||||
value: taskPayload,
|
||||
validate: validateTaskCollection,
|
||||
previous,
|
||||
policy,
|
||||
source: 'gateway:/api/tasks',
|
||||
now: NOW,
|
||||
incomingVersion: 3,
|
||||
});
|
||||
expect(regressed).toEqual({ outcome: 'invalidated', reason: 'version-regression' });
|
||||
|
||||
const newerSchema = acceptedTaskSnapshot({ schemaVersion: 4 });
|
||||
const downgradedClient = acceptSnapshot({
|
||||
value: taskPayload,
|
||||
validate: validateTaskCollection,
|
||||
previous: newerSchema,
|
||||
policy: { ...policy, schemaVersion: 2 },
|
||||
source: 'gateway:/api/tasks',
|
||||
now: NOW,
|
||||
});
|
||||
expect(downgradedClient).toEqual({ outcome: 'invalidated', reason: 'version-regression' });
|
||||
});
|
||||
|
||||
it('increments the version monotonically across accepted snapshots', () => {
|
||||
const first = acceptedTaskSnapshot();
|
||||
const second = acceptSnapshot({
|
||||
value: taskPayload,
|
||||
validate: validateTaskCollection,
|
||||
previous: first,
|
||||
policy,
|
||||
source: 'gateway:/api/tasks',
|
||||
now: NOW,
|
||||
});
|
||||
expect(second.outcome).toBe('accepted');
|
||||
if (second.outcome === 'accepted') {
|
||||
expect(second.snapshot.version).toBe(first.version + 1);
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
describe('combineFreshness', () => {
|
||||
it('gates the surface on the primary collection', () => {
|
||||
expect(combineFreshness('unavailable', ['current'])).toBe('unavailable');
|
||||
expect(combineFreshness('unknown', ['current'])).toBe('unknown');
|
||||
expect(combineFreshness('current', [])).toBe('current');
|
||||
});
|
||||
|
||||
it('degrades to partial when a secondary is unavailable', () => {
|
||||
expect(combineFreshness('current', ['current', 'unavailable'])).toBe('partial');
|
||||
});
|
||||
|
||||
it('degrades to unknown while a secondary is still loading', () => {
|
||||
expect(combineFreshness('current', ['unknown'])).toBe('unknown');
|
||||
});
|
||||
|
||||
it('degrades to stale when any collection is stale', () => {
|
||||
expect(combineFreshness('current', ['stale'])).toBe('stale');
|
||||
expect(combineFreshness('stale', ['current'])).toBe('stale');
|
||||
});
|
||||
|
||||
it('propagates partial secondaries', () => {
|
||||
expect(combineFreshness('current', ['partial'])).toBe('partial');
|
||||
});
|
||||
});
|
||||
|
||||
describe('computeDigest', () => {
|
||||
it('is stable across key order and changes with data', () => {
|
||||
const a = computeDigest({ x: 1, y: [1, 2] });
|
||||
const b = computeDigest({ y: [1, 2], x: 1 });
|
||||
expect(a).toBe(b);
|
||||
expect(computeDigest({ x: 1, y: [1, 3] })).not.toBe(a);
|
||||
});
|
||||
});
|
||||
|
||||
describe('verdictValue', () => {
|
||||
it('returns the value only for verified inputs', () => {
|
||||
expect(verdictValue(true, '5')).toBe('5');
|
||||
expect(verdictValue(false, '5')).toBe(UNKNOWN_VERDICT);
|
||||
expect(verdictValue(false, '5')).not.toBe('5');
|
||||
});
|
||||
});
|
||||
|
||||
describe('formatAge', () => {
|
||||
it('labels age in human terms', () => {
|
||||
expect(formatAge(NOW, NOW)).toBe('just now');
|
||||
expect(formatAge(NOW, NOW + 15_000)).toBe('under a minute ago');
|
||||
expect(formatAge(NOW, NOW + 120_000)).toBe('2m ago');
|
||||
expect(formatAge(NOW, NOW + 3 * 3_600_000)).toBe('3h ago');
|
||||
expect(formatAge(NOW, NOW + 2 * 86_400_000)).toBe('2d ago');
|
||||
});
|
||||
});
|
||||
@@ -1,261 +0,0 @@
|
||||
/**
|
||||
* Typed freshness model for gateway-fetched collections (RI-5-001).
|
||||
*
|
||||
* A failed or stale fetch must never be indistinguishable from an empty
|
||||
* healthy collection. Every fetched surface carries an explicit freshness
|
||||
* state, a verified snapshot identity (source, workspace, version, age), and
|
||||
* a mutation guard that refuses state-changing operations unless the data is
|
||||
* verified current.
|
||||
*/
|
||||
|
||||
/** Freshness states for fetched data. Never inferred from emptiness. */
|
||||
export type FreshnessState = 'current' | 'stale' | 'partial' | 'unknown' | 'unavailable';
|
||||
|
||||
/**
|
||||
* Reasons a snapshot is invalidated. An invalidated snapshot is treated as
|
||||
* unavailable and is never rendered as current.
|
||||
*/
|
||||
export type InvalidationReason =
|
||||
| 'cache-corruption'
|
||||
| 'cross-workspace'
|
||||
| 'schema-mismatch'
|
||||
| 'version-regression';
|
||||
|
||||
/** Human-readable labels for invalidation reasons (UI + error messages). */
|
||||
export const invalidationReasonLabels: Record<InvalidationReason, string> = {
|
||||
'cache-corruption': 'cached snapshot failed integrity checks',
|
||||
'cross-workspace': 'data belongs to a different workspace',
|
||||
'schema-mismatch': 'response did not match the expected schema',
|
||||
'version-regression': 'snapshot version regressed below the accepted version',
|
||||
};
|
||||
|
||||
/** A verified snapshot of fetched data with full provenance. */
|
||||
export interface FreshSnapshot<T> {
|
||||
readonly data: T;
|
||||
/** Source identity of the fetch, e.g. `gateway:/api/tasks`. */
|
||||
readonly source: string;
|
||||
/** Workspace scope the data belongs to. */
|
||||
readonly workspace: string;
|
||||
/** Monotonic snapshot sequence number for this surface. */
|
||||
readonly version: number;
|
||||
/** Schema version of the validator that accepted this snapshot. */
|
||||
readonly schemaVersion: number;
|
||||
/** Epoch ms at which the data was verified. */
|
||||
readonly fetchedAt: number;
|
||||
/** Integrity digest of `data`, used to detect cache corruption. */
|
||||
readonly digest: string;
|
||||
}
|
||||
|
||||
/** Provenance label rendered next to last-known data. */
|
||||
export interface FreshnessLabel {
|
||||
readonly source: string;
|
||||
readonly version: number;
|
||||
readonly fetchedAt: number;
|
||||
}
|
||||
|
||||
/** Policy governing freshness for a surface. */
|
||||
export interface FreshnessPolicy {
|
||||
/** Active workspace scope. Snapshots from other scopes are invalidated. */
|
||||
readonly workspace: string;
|
||||
/** Schema version of the current validator. */
|
||||
readonly schemaVersion: number;
|
||||
/** Age after which a verified snapshot degrades from current to stale. */
|
||||
readonly staleAfterMs: number;
|
||||
}
|
||||
|
||||
export const DEFAULT_FRESHNESS_POLICY: FreshnessPolicy = {
|
||||
workspace: 'default',
|
||||
schemaVersion: 1,
|
||||
staleAfterMs: 60_000,
|
||||
};
|
||||
|
||||
/** Payload returned by a successful schema validation. */
|
||||
export interface FreshPayload<T> {
|
||||
readonly data: T;
|
||||
/**
|
||||
* Workspace identity extracted from the payload itself when the collection
|
||||
* carries one (e.g. a uniform `userId` on projects). `null` when the
|
||||
* collection has no intrinsic workspace identity.
|
||||
*/
|
||||
readonly workspace: string | null;
|
||||
}
|
||||
|
||||
/** Error thrown when a mutation is attempted on non-current data. */
|
||||
export class StaleMutationError extends Error {
|
||||
readonly freshness: FreshnessState;
|
||||
|
||||
constructor(freshness: FreshnessState) {
|
||||
super(`Refused mutation on ${freshness} data: revalidation is required before mutating.`);
|
||||
this.name = 'StaleMutationError';
|
||||
this.freshness = freshness;
|
||||
}
|
||||
}
|
||||
|
||||
/** Stable JSON digest used for snapshot integrity checks. */
|
||||
export function computeDigest(value: unknown): string {
|
||||
// FNV-1a 32-bit over the stable JSON serialization. This is an integrity
|
||||
// check against corruption, not a cryptographic guarantee.
|
||||
let hash = 0x811c9dc5;
|
||||
for (const byte of stableStringify(value)) {
|
||||
hash ^= byte.charCodeAt(0);
|
||||
hash = Math.imul(hash, 0x01000193) >>> 0;
|
||||
}
|
||||
return hash.toString(16).padStart(8, '0');
|
||||
}
|
||||
|
||||
function stableStringify(value: unknown): string {
|
||||
return serialize(value);
|
||||
}
|
||||
|
||||
function serialize(value: unknown): string {
|
||||
if (value === null || typeof value !== 'object') return JSON.stringify(value) ?? 'null';
|
||||
if (Array.isArray(value)) return `[${value.map(serialize).join(',')}]`;
|
||||
const entries = Object.entries(value as Record<string, unknown>)
|
||||
.filter(([, item]) => item !== undefined)
|
||||
.sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
|
||||
.map(([key, item]) => `${JSON.stringify(key)}:${serialize(item)}`);
|
||||
return `{${entries.join(',')}}`;
|
||||
}
|
||||
|
||||
export type AcceptSnapshotResult<T> =
|
||||
| { readonly outcome: 'accepted'; readonly snapshot: FreshSnapshot<T> }
|
||||
| { readonly outcome: 'invalidated'; readonly reason: InvalidationReason };
|
||||
|
||||
export interface AcceptSnapshotOptions<T> {
|
||||
/** Raw fetched value (untrusted JSON). */
|
||||
readonly value: unknown;
|
||||
/** Schema validator; returns `null` when the value does not match. */
|
||||
readonly validate: (value: unknown) => FreshPayload<T> | null;
|
||||
/** Previously accepted snapshot for this surface, if any. */
|
||||
readonly previous: FreshSnapshot<T> | null;
|
||||
readonly policy: FreshnessPolicy;
|
||||
readonly source: string;
|
||||
/**
|
||||
* Version carried by the incoming payload when the transport exposes one.
|
||||
* Must not regress below the accepted snapshot's version.
|
||||
*/
|
||||
readonly incomingVersion?: number;
|
||||
readonly now: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* Validate and accept a fetched value as a snapshot, or invalidate it.
|
||||
*
|
||||
* Invalidation rules (each treated as unavailable, never rendered current):
|
||||
* - schema mismatch: the payload fails validation
|
||||
* - cross-workspace: the payload's workspace differs from the verified one
|
||||
* - version regression: payload/schema version is below the accepted one
|
||||
*/
|
||||
export function acceptSnapshot<T>(options: AcceptSnapshotOptions<T>): AcceptSnapshotResult<T> {
|
||||
const payload = options.validate(options.value);
|
||||
if (payload === null) {
|
||||
return { outcome: 'invalidated', reason: 'schema-mismatch' };
|
||||
}
|
||||
|
||||
// Workspace identity: the payload's own scope wins; a collection with no
|
||||
// intrinsic identity (e.g. an empty list after every project was deleted)
|
||||
// keeps the previously verified scope rather than resetting to the policy
|
||||
// default, so a legitimately empty response is not mistaken for a scope
|
||||
// change.
|
||||
const workspace = payload.workspace ?? options.previous?.workspace ?? options.policy.workspace;
|
||||
if (options.previous !== null && options.previous.workspace !== workspace) {
|
||||
return { outcome: 'invalidated', reason: 'cross-workspace' };
|
||||
}
|
||||
if (options.previous !== null && options.policy.schemaVersion < options.previous.schemaVersion) {
|
||||
return { outcome: 'invalidated', reason: 'version-regression' };
|
||||
}
|
||||
if (
|
||||
options.incomingVersion !== undefined &&
|
||||
options.previous !== null &&
|
||||
options.incomingVersion < options.previous.version
|
||||
) {
|
||||
return { outcome: 'invalidated', reason: 'version-regression' };
|
||||
}
|
||||
|
||||
const snapshot: FreshSnapshot<T> = {
|
||||
data: payload.data,
|
||||
source: options.source,
|
||||
workspace,
|
||||
version: options.incomingVersion ?? (options.previous?.version ?? 0) + 1,
|
||||
schemaVersion: options.policy.schemaVersion,
|
||||
fetchedAt: options.now,
|
||||
digest: computeDigest(payload.data),
|
||||
};
|
||||
return { outcome: 'accepted', snapshot };
|
||||
}
|
||||
|
||||
export interface ComputeFreshnessOptions {
|
||||
readonly snapshot: FreshSnapshot<unknown> | null;
|
||||
readonly policy: FreshnessPolicy;
|
||||
readonly now: number;
|
||||
/**
|
||||
* True when the snapshot cannot be trusted as current regardless of age:
|
||||
* the latest revalidation failed, or the snapshot was restored from cache
|
||||
* and has not been verified by a fetch in this session.
|
||||
*/
|
||||
readonly degraded?: boolean;
|
||||
}
|
||||
|
||||
/**
|
||||
* Compute the freshness state of a snapshot. A missing snapshot is
|
||||
* `unavailable` (never "empty and healthy"); a degraded or aged snapshot is
|
||||
* `stale` (situational awareness only).
|
||||
*/
|
||||
export function computeFreshness(options: ComputeFreshnessOptions): FreshnessState {
|
||||
const { snapshot, policy, now, degraded = false } = options;
|
||||
if (snapshot === null) return 'unavailable';
|
||||
if (degraded) return 'stale';
|
||||
if (now - snapshot.fetchedAt > policy.staleAfterMs) return 'stale';
|
||||
return 'current';
|
||||
}
|
||||
|
||||
/** Only verified-current data may back a state-changing action. */
|
||||
export function canMutate(state: FreshnessState): boolean {
|
||||
return state === 'current';
|
||||
}
|
||||
|
||||
/** Defense in depth: reject the mutation call itself on non-current data. */
|
||||
export function assertMutable(state: FreshnessState): void {
|
||||
if (!canMutate(state)) {
|
||||
throw new StaleMutationError(state);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Combine freshness across a multi-collection surface (primary + secondaries).
|
||||
* The primary collection gates the surface: unknown while it loads,
|
||||
* unavailable when it fails. Missing secondaries degrade the surface to
|
||||
* `partial`; aged collections degrade it to `stale`.
|
||||
*/
|
||||
export function combineFreshness(
|
||||
primary: FreshnessState,
|
||||
secondaries: readonly FreshnessState[],
|
||||
): FreshnessState {
|
||||
if (primary === 'unavailable') return 'unavailable';
|
||||
if (primary === 'unknown') return 'unknown';
|
||||
if (secondaries.includes('unavailable')) return 'partial';
|
||||
if (secondaries.includes('unknown')) return 'unknown';
|
||||
if (secondaries.includes('stale') || primary === 'stale') return 'stale';
|
||||
if (secondaries.includes('partial')) return 'partial';
|
||||
return 'current';
|
||||
}
|
||||
|
||||
/** Render-safe age label for snapshot provenance. */
|
||||
export function formatAge(fetchedAt: number, now: number): string {
|
||||
const ageMs = Math.max(0, now - fetchedAt);
|
||||
if (ageMs < 10_000) return 'just now';
|
||||
const minutes = Math.floor(ageMs / 60_000);
|
||||
if (minutes < 1) return 'under a minute ago';
|
||||
if (minutes < 60) return `${minutes}m ago`;
|
||||
const hours = Math.floor(minutes / 60);
|
||||
if (hours < 24) return `${hours}h ago`;
|
||||
const days = Math.floor(hours / 24);
|
||||
return `${days}d ago`;
|
||||
}
|
||||
|
||||
/** Derived verdict placeholder for non-current inputs — never a green value. */
|
||||
export const UNKNOWN_VERDICT = '?';
|
||||
|
||||
export function verdictValue(verified: boolean, value: string): string {
|
||||
return verified ? value : UNKNOWN_VERDICT;
|
||||
}
|
||||
@@ -1,197 +0,0 @@
|
||||
import { afterEach, beforeEach, describe, expect, it } from 'vitest';
|
||||
import { acceptSnapshot, DEFAULT_FRESHNESS_POLICY } from './model';
|
||||
import { clearSnapshotCache, readSnapshotCache, writeSnapshotCache } from './snapshot-cache';
|
||||
import { validateProjectCollection, validateTaskCollection } from './validators';
|
||||
import { projectFixtures, taskFixtures } from '@/spa/pages/page-fixtures';
|
||||
import type { Project, Task } from '@/lib/types';
|
||||
|
||||
const KEY = 'test:tasks';
|
||||
const NOW = 1_800_000_000_000;
|
||||
const policy = { ...DEFAULT_FRESHNESS_POLICY, staleAfterMs: 60_000 };
|
||||
|
||||
function storedTaskSnapshot() {
|
||||
const result = acceptSnapshot({
|
||||
value: taskFixtures,
|
||||
validate: validateTaskCollection,
|
||||
previous: null,
|
||||
policy,
|
||||
source: 'gateway:/api/tasks',
|
||||
now: NOW,
|
||||
});
|
||||
if (result.outcome !== 'accepted') throw new Error('fixture setup failed');
|
||||
return result.snapshot;
|
||||
}
|
||||
|
||||
function storedProjectSnapshot() {
|
||||
const result = acceptSnapshot({
|
||||
value: projectFixtures,
|
||||
validate: validateProjectCollection,
|
||||
previous: null,
|
||||
policy,
|
||||
source: 'gateway:/api/projects',
|
||||
now: NOW,
|
||||
});
|
||||
if (result.outcome !== 'accepted') throw new Error('fixture setup failed');
|
||||
return result.snapshot;
|
||||
}
|
||||
|
||||
function readTasks() {
|
||||
return readSnapshotCache({
|
||||
key: KEY,
|
||||
workspace: policy.workspace,
|
||||
policy,
|
||||
validate: validateTaskCollection,
|
||||
});
|
||||
}
|
||||
|
||||
/** Write an arbitrary value directly at the raw cache slot. */
|
||||
function writeRaw(key: string, value: unknown): void {
|
||||
sessionStorage.setItem(`mosaic:freshness:v1:${key}`, JSON.stringify(value));
|
||||
}
|
||||
|
||||
/** Parse and re-write the stored entry (for tampering with internals). */
|
||||
function tamperStored<T>(key: string, mutate: (stored: T) => void): void {
|
||||
const parsed = JSON.parse(sessionStorage.getItem(`mosaic:freshness:v1:${key}`) ?? '{}') as T;
|
||||
mutate(parsed);
|
||||
writeRaw(key, parsed);
|
||||
}
|
||||
|
||||
beforeEach(() => {
|
||||
sessionStorage.clear();
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
sessionStorage.clear();
|
||||
});
|
||||
|
||||
describe('readSnapshotCache', () => {
|
||||
it('misses when nothing is stored', () => {
|
||||
expect(readTasks()).toEqual({ outcome: 'miss' });
|
||||
});
|
||||
|
||||
it('hits for a well-formed entry and preserves provenance', () => {
|
||||
const snapshot = storedTaskSnapshot();
|
||||
writeSnapshotCache(KEY, snapshot);
|
||||
|
||||
const result = readTasks();
|
||||
expect(result.outcome).toBe('hit');
|
||||
if (result.outcome === 'hit') {
|
||||
expect(result.snapshot.data).toEqual(taskFixtures);
|
||||
expect(result.snapshot.source).toBe('gateway:/api/tasks');
|
||||
expect(result.snapshot.version).toBe(snapshot.version);
|
||||
expect(result.snapshot.fetchedAt).toBe(snapshot.fetchedAt);
|
||||
expect(result.snapshot.workspace).toBe(snapshot.workspace);
|
||||
}
|
||||
});
|
||||
|
||||
it('invalidates unparsable entries as cache corruption', () => {
|
||||
sessionStorage.setItem(`mosaic:freshness:v1:${KEY}`, '{not json');
|
||||
expect(readTasks()).toEqual({ outcome: 'invalidated', reason: 'cache-corruption' });
|
||||
});
|
||||
|
||||
it('invalidates structurally wrong entries as cache corruption', () => {
|
||||
const malformed: unknown[] = [
|
||||
'nested but not a snapshot',
|
||||
{ data: taskFixtures }, // missing provenance fields
|
||||
{
|
||||
data: taskFixtures,
|
||||
source: 1,
|
||||
workspace: 'w',
|
||||
version: 1,
|
||||
schemaVersion: 1,
|
||||
fetchedAt: 1,
|
||||
digest: 'x',
|
||||
},
|
||||
null,
|
||||
17,
|
||||
];
|
||||
for (const entry of malformed) {
|
||||
writeRaw(KEY, entry);
|
||||
expect(readTasks()).toEqual({ outcome: 'invalidated', reason: 'cache-corruption' });
|
||||
}
|
||||
});
|
||||
|
||||
it('invalidates digest mismatches as cache corruption (tampered data)', () => {
|
||||
writeSnapshotCache(KEY, storedTaskSnapshot());
|
||||
tamperStored<{ data: Task[] }>(KEY, (stored) => {
|
||||
stored.data = [...stored.data, { ...stored.data[0]!, id: 'injected-task' }];
|
||||
});
|
||||
expect(readTasks()).toEqual({ outcome: 'invalidated', reason: 'cache-corruption' });
|
||||
});
|
||||
|
||||
it('invalidates entries scoped to another workspace', () => {
|
||||
const snapshot = storedTaskSnapshot();
|
||||
writeSnapshotCache(KEY, { ...snapshot, workspace: 'someone-else' });
|
||||
expect(readTasks()).toEqual({ outcome: 'invalidated', reason: 'cross-workspace' });
|
||||
});
|
||||
|
||||
it('invalidates entries written by a newer schema as a version regression', () => {
|
||||
const snapshot = storedTaskSnapshot();
|
||||
writeSnapshotCache(KEY, { ...snapshot, schemaVersion: policy.schemaVersion + 1 });
|
||||
expect(readTasks()).toEqual({ outcome: 'invalidated', reason: 'version-regression' });
|
||||
});
|
||||
|
||||
it('invalidates entries whose data no longer validates (schema mismatch)', () => {
|
||||
writeSnapshotCache(KEY, storedTaskSnapshot());
|
||||
tamperStored<{ data: unknown }>(KEY, (stored) => {
|
||||
stored.data = { malformed: true };
|
||||
});
|
||||
expect(readTasks()).toEqual({ outcome: 'invalidated', reason: 'schema-mismatch' });
|
||||
});
|
||||
|
||||
it('never reports a corrupted raw entry as a hit (negative control)', () => {
|
||||
for (const raw of ['{oops', 'null', '"string"', '[]', '12']) {
|
||||
sessionStorage.setItem(`mosaic:freshness:v1:${KEY}`, raw);
|
||||
const result = readTasks();
|
||||
expect(result.outcome).not.toBe('hit');
|
||||
expect(result.outcome).toBe('invalidated');
|
||||
}
|
||||
});
|
||||
|
||||
it('scopes project collections by their workspace identity', () => {
|
||||
const snapshot = storedProjectSnapshot();
|
||||
writeSnapshotCache('test:projects', snapshot);
|
||||
|
||||
const sameScope = readSnapshotCache({
|
||||
key: 'test:projects',
|
||||
workspace: 'user-1',
|
||||
policy,
|
||||
validate: validateProjectCollection,
|
||||
});
|
||||
expect(sameScope.outcome).toBe('hit');
|
||||
|
||||
const foreignScope = readSnapshotCache({
|
||||
key: 'test:projects',
|
||||
workspace: 'user-2',
|
||||
policy,
|
||||
validate: validateProjectCollection,
|
||||
});
|
||||
expect(foreignScope).toEqual({ outcome: 'invalidated', reason: 'cross-workspace' });
|
||||
});
|
||||
});
|
||||
|
||||
describe('writeSnapshotCache round-trip', () => {
|
||||
it('round-trips an accepted project snapshot', () => {
|
||||
const snapshot = storedProjectSnapshot();
|
||||
writeSnapshotCache('test:projects', snapshot);
|
||||
const result = readSnapshotCache({
|
||||
key: 'test:projects',
|
||||
workspace: snapshot.workspace,
|
||||
policy,
|
||||
validate: validateProjectCollection,
|
||||
});
|
||||
expect(result.outcome).toBe('hit');
|
||||
if (result.outcome === 'hit') {
|
||||
expect(result.snapshot.data).toEqual(projectFixtures as Project[]);
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
describe('clearSnapshotCache', () => {
|
||||
it('drops the entry so the next read misses', () => {
|
||||
writeSnapshotCache(KEY, storedTaskSnapshot());
|
||||
expect(readTasks().outcome).toBe('hit');
|
||||
clearSnapshotCache(KEY);
|
||||
expect(readTasks()).toEqual({ outcome: 'miss' });
|
||||
});
|
||||
});
|
||||
@@ -1,154 +0,0 @@
|
||||
import {
|
||||
computeDigest,
|
||||
type FreshPayload,
|
||||
type FreshSnapshot,
|
||||
type FreshnessPolicy,
|
||||
type InvalidationReason,
|
||||
} from './model';
|
||||
|
||||
/**
|
||||
* Session-scoped last-known snapshot cache (RI-5-001).
|
||||
*
|
||||
* Restored snapshots are situational awareness only: they surface as `stale`
|
||||
* until a fetch re-verifies them. A cache entry that is corrupted, belongs to
|
||||
* another workspace, was written by a newer schema, or no longer validates is
|
||||
* invalidated (treated as unavailable, never rendered as current).
|
||||
*/
|
||||
|
||||
const CACHE_PREFIX = 'mosaic:freshness:v1';
|
||||
|
||||
interface StoredSnapshot {
|
||||
data: unknown;
|
||||
source: string;
|
||||
workspace: string;
|
||||
version: number;
|
||||
schemaVersion: number;
|
||||
fetchedAt: number;
|
||||
digest: string;
|
||||
}
|
||||
|
||||
export type SnapshotCacheRead<T> =
|
||||
| { readonly outcome: 'hit'; readonly snapshot: FreshSnapshot<T> }
|
||||
| { readonly outcome: 'miss' }
|
||||
| { readonly outcome: 'invalidated'; readonly reason: InvalidationReason };
|
||||
|
||||
export interface ReadSnapshotCacheOptions<T> {
|
||||
readonly key: string;
|
||||
readonly workspace: string;
|
||||
readonly policy: FreshnessPolicy;
|
||||
readonly validate: (value: unknown) => FreshPayload<T> | null;
|
||||
}
|
||||
|
||||
function cacheKey(key: string): string {
|
||||
return `${CACHE_PREFIX}:${key}`;
|
||||
}
|
||||
|
||||
function isStoredSnapshot(value: unknown): value is StoredSnapshot {
|
||||
if (typeof value !== 'object' || value === null) return false;
|
||||
const candidate = value as Record<string, unknown>;
|
||||
return (
|
||||
typeof candidate['data'] === 'object' &&
|
||||
candidate['data'] !== null &&
|
||||
typeof candidate['source'] === 'string' &&
|
||||
typeof candidate['workspace'] === 'string' &&
|
||||
typeof candidate['version'] === 'number' &&
|
||||
typeof candidate['schemaVersion'] === 'number' &&
|
||||
typeof candidate['fetchedAt'] === 'number' &&
|
||||
typeof candidate['digest'] === 'string'
|
||||
);
|
||||
}
|
||||
|
||||
function getStorage(): Storage | null {
|
||||
try {
|
||||
return globalThis.sessionStorage ?? null;
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Restore a cached snapshot under the active workspace scope. Every failure
|
||||
* mode maps to an explicit invalidation reason or a miss — never to data
|
||||
* that renders as current.
|
||||
*/
|
||||
export function readSnapshotCache<T>(options: ReadSnapshotCacheOptions<T>): SnapshotCacheRead<T> {
|
||||
const storage = getStorage();
|
||||
if (storage === null) return { outcome: 'miss' };
|
||||
|
||||
let raw: string | null;
|
||||
try {
|
||||
raw = storage.getItem(cacheKey(options.key));
|
||||
} catch {
|
||||
return { outcome: 'miss' };
|
||||
}
|
||||
if (raw === null) return { outcome: 'miss' };
|
||||
|
||||
let parsed: unknown;
|
||||
try {
|
||||
parsed = JSON.parse(raw);
|
||||
} catch {
|
||||
return { outcome: 'invalidated', reason: 'cache-corruption' };
|
||||
}
|
||||
if (!isStoredSnapshot(parsed)) {
|
||||
return { outcome: 'invalidated', reason: 'cache-corruption' };
|
||||
}
|
||||
if (parsed.workspace !== options.workspace) {
|
||||
return { outcome: 'invalidated', reason: 'cross-workspace' };
|
||||
}
|
||||
if (parsed.schemaVersion > options.policy.schemaVersion) {
|
||||
// Written by a newer build than the running client: version regression.
|
||||
return { outcome: 'invalidated', reason: 'version-regression' };
|
||||
}
|
||||
|
||||
const payload = options.validate(parsed.data);
|
||||
if (payload === null) {
|
||||
return { outcome: 'invalidated', reason: 'schema-mismatch' };
|
||||
}
|
||||
if (computeDigest(payload.data) !== parsed.digest) {
|
||||
return { outcome: 'invalidated', reason: 'cache-corruption' };
|
||||
}
|
||||
|
||||
return {
|
||||
outcome: 'hit',
|
||||
snapshot: {
|
||||
data: payload.data,
|
||||
source: parsed.source,
|
||||
workspace: parsed.workspace,
|
||||
version: parsed.version,
|
||||
schemaVersion: parsed.schemaVersion,
|
||||
fetchedAt: parsed.fetchedAt,
|
||||
digest: parsed.digest,
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
/** Persist a verified snapshot. Failures are non-fatal (cache is best-effort). */
|
||||
export function writeSnapshotCache<T>(key: string, snapshot: FreshSnapshot<T>): void {
|
||||
const storage = getStorage();
|
||||
if (storage === null) return;
|
||||
const stored: StoredSnapshot = {
|
||||
data: snapshot.data,
|
||||
source: snapshot.source,
|
||||
workspace: snapshot.workspace,
|
||||
version: snapshot.version,
|
||||
schemaVersion: snapshot.schemaVersion,
|
||||
fetchedAt: snapshot.fetchedAt,
|
||||
digest: snapshot.digest,
|
||||
};
|
||||
try {
|
||||
storage.setItem(cacheKey(key), JSON.stringify(stored));
|
||||
} catch {
|
||||
// Quota or serialization failures simply skip caching.
|
||||
}
|
||||
}
|
||||
|
||||
/** Drop a cached snapshot (used when a surface invalidates its cache entry). */
|
||||
export function clearSnapshotCache(key: string): void {
|
||||
const storage = getStorage();
|
||||
if (storage === null) return;
|
||||
try {
|
||||
storage.removeItem(cacheKey(key));
|
||||
} catch {
|
||||
// Ignorable: a wedged storage entry is detected as corruption on read.
|
||||
}
|
||||
}
|
||||
@@ -1,372 +0,0 @@
|
||||
import { act } from 'react';
|
||||
import { createRoot, type Root } from 'react-dom/client';
|
||||
import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
|
||||
import type { Task } from '@/lib/types';
|
||||
import { acceptSnapshot, StaleMutationError, DEFAULT_FRESHNESS_POLICY } from './model';
|
||||
import type { FreshnessFailure } from './use-fresh-collection';
|
||||
import {
|
||||
describeFailure,
|
||||
useFreshCollection,
|
||||
type FreshCollection,
|
||||
type UseFreshCollectionOptions,
|
||||
} from './use-fresh-collection';
|
||||
import { validateProjectCollection, validateTaskCollection } from './validators';
|
||||
import { projectFixtures, taskFixtures } from '@/spa/pages/page-fixtures';
|
||||
|
||||
/**
|
||||
* Failure-matrix coverage for the freshness seam (RI-5-001): network failure,
|
||||
* auth failure, malformed response, cache corruption, stale age, schema
|
||||
* mismatch, cross-workspace, recovery, and stale-action rejection — with
|
||||
* negative controls proving no case yields current data or an enabled
|
||||
* mutation.
|
||||
*/
|
||||
|
||||
const NOW = 1_800_000_000_000;
|
||||
|
||||
interface Deferred<T> {
|
||||
promise: Promise<T>;
|
||||
resolve: (value: T) => void;
|
||||
reject: (reason?: unknown) => void;
|
||||
}
|
||||
|
||||
function createDeferred<T>(): Deferred<T> {
|
||||
let resolve!: (value: T) => void;
|
||||
let reject!: (reason?: unknown) => void;
|
||||
const promise = new Promise<T>((res, rej) => {
|
||||
resolve = res;
|
||||
reject = rej;
|
||||
});
|
||||
return { promise, resolve, reject };
|
||||
}
|
||||
|
||||
let root: Root | null = null;
|
||||
let container: HTMLDivElement;
|
||||
let latest: FreshCollection<Task[]> | null = null;
|
||||
|
||||
function Probe({
|
||||
options,
|
||||
}: {
|
||||
options: UseFreshCollectionOptions<Task[]>;
|
||||
}): React.ReactElement | null {
|
||||
latest = useFreshCollection<Task[]>(options);
|
||||
return null;
|
||||
}
|
||||
|
||||
beforeAll(() => {
|
||||
Object.defineProperty(globalThis, 'IS_REACT_ACT_ENVIRONMENT', {
|
||||
configurable: true,
|
||||
value: true,
|
||||
});
|
||||
});
|
||||
|
||||
beforeEach(() => {
|
||||
sessionStorage.clear();
|
||||
});
|
||||
|
||||
afterEach(async () => {
|
||||
await act(async () => {
|
||||
root?.unmount();
|
||||
});
|
||||
document.body.replaceChildren();
|
||||
root = null;
|
||||
latest = null;
|
||||
sessionStorage.clear();
|
||||
vi.restoreAllMocks();
|
||||
});
|
||||
|
||||
async function renderCollection(
|
||||
options: UseFreshCollectionOptions<Task[]>,
|
||||
): Promise<FreshCollection<Task[]>> {
|
||||
container = document.createElement('div');
|
||||
document.body.append(container);
|
||||
root = createRoot(container);
|
||||
await act(async () => {
|
||||
root?.render(<Probe options={options} />);
|
||||
});
|
||||
if (latest === null) throw new Error('hook did not run');
|
||||
return latest;
|
||||
}
|
||||
|
||||
function taskOptions(
|
||||
overrides: Partial<UseFreshCollectionOptions<Task[]>> = {},
|
||||
): UseFreshCollectionOptions<Task[]> {
|
||||
return {
|
||||
source: 'gateway:/api/tasks',
|
||||
fetcher: () => Promise.resolve(taskFixtures),
|
||||
validate: validateTaskCollection,
|
||||
cacheKey: 'tasks',
|
||||
clock: () => NOW,
|
||||
...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
function authError(statusCode: number): Error & { statusCode: number } {
|
||||
return Object.assign(new Error(`Request failed with ${statusCode}`), { statusCode });
|
||||
}
|
||||
|
||||
function seedCache(key: string): number {
|
||||
const result = acceptSnapshot({
|
||||
value: taskFixtures,
|
||||
validate: validateTaskCollection,
|
||||
previous: null,
|
||||
policy: DEFAULT_FRESHNESS_POLICY,
|
||||
source: 'gateway:/api/tasks',
|
||||
now: NOW,
|
||||
});
|
||||
if (result.outcome !== 'accepted') throw new Error('fixture setup failed');
|
||||
sessionStorage.setItem(`mosaic:freshness:v1:${key}`, JSON.stringify({ ...result.snapshot }));
|
||||
return result.snapshot.version;
|
||||
}
|
||||
|
||||
describe('useFreshCollection failure matrix', () => {
|
||||
it('is unknown (not empty) while the first validation is in flight', async () => {
|
||||
const deferred = createDeferred<Task[]>();
|
||||
const collection = await renderCollection(taskOptions({ fetcher: () => deferred.promise }));
|
||||
|
||||
expect(collection.freshness).toBe('unknown');
|
||||
expect(collection.validating).toBe(true);
|
||||
expect(collection.data).toBeNull();
|
||||
expect(collection.canMutate).toBe(false);
|
||||
|
||||
await act(async () => {
|
||||
deferred.resolve(taskFixtures);
|
||||
await deferred.promise;
|
||||
});
|
||||
});
|
||||
|
||||
it('becomes current with provenance after a verified fetch', async () => {
|
||||
const collection = await renderCollection(taskOptions());
|
||||
|
||||
expect(collection.freshness).toBe('current');
|
||||
expect(collection.data).toEqual(taskFixtures);
|
||||
expect(collection.snapshot?.source).toBe('gateway:/api/tasks');
|
||||
expect(collection.snapshot?.version).toBe(1);
|
||||
expect(collection.failure).toBeNull();
|
||||
expect(collection.canMutate).toBe(true);
|
||||
// Verified snapshot is persisted for last-known restore.
|
||||
expect(sessionStorage.getItem('mosaic:freshness:v1:tasks')).toBeTruthy();
|
||||
});
|
||||
|
||||
it('treats a network failure as unavailable — never an empty healthy collection', async () => {
|
||||
const collection = await renderCollection(
|
||||
taskOptions({ fetcher: () => Promise.reject(new Error('network down')) }),
|
||||
);
|
||||
|
||||
expect(collection.freshness).toBe('unavailable');
|
||||
expect(collection.data).toBeNull();
|
||||
expect(collection.failure).toEqual({ kind: 'fetch', message: 'network down' });
|
||||
expect(collection.canMutate).toBe(false);
|
||||
expect(describeFailure(collection.failure)).toBe('network down');
|
||||
});
|
||||
|
||||
it('treats an auth failure as unavailable and drops the last-known snapshot', async () => {
|
||||
let call = 0;
|
||||
const collection = await renderCollection(
|
||||
taskOptions({
|
||||
fetcher: () => {
|
||||
call += 1;
|
||||
return call === 1 ? Promise.resolve(taskFixtures) : Promise.reject(authError(401));
|
||||
},
|
||||
}),
|
||||
);
|
||||
expect(collection.freshness).toBe('current');
|
||||
|
||||
await act(async () => {
|
||||
await collection.revalidate();
|
||||
});
|
||||
|
||||
expect(latest?.freshness).toBe('unavailable');
|
||||
expect(latest?.data).toBeNull();
|
||||
expect(latest?.failure?.kind).toBe('fetch');
|
||||
// The previous user's data must not linger in the session cache.
|
||||
expect(sessionStorage.getItem('mosaic:freshness:v1:tasks')).toBeNull();
|
||||
});
|
||||
|
||||
it('invalidates a malformed response as a schema mismatch', async () => {
|
||||
const collection = await renderCollection(
|
||||
taskOptions({ fetcher: () => Promise.resolve({ malformed: true }) }),
|
||||
);
|
||||
|
||||
expect(collection.freshness).toBe('unavailable');
|
||||
expect(collection.data).toBeNull();
|
||||
expect(collection.failure).toEqual({ kind: 'invalidated', reason: 'schema-mismatch' });
|
||||
expect(collection.canMutate).toBe(false);
|
||||
});
|
||||
|
||||
it('keeps the previous snapshot as labeled stale when a later payload mismatches', async () => {
|
||||
let call = 0;
|
||||
const collection = await renderCollection(
|
||||
taskOptions({
|
||||
fetcher: () => {
|
||||
call += 1;
|
||||
return call === 1 ? Promise.resolve(taskFixtures) : Promise.resolve('garbage');
|
||||
},
|
||||
}),
|
||||
);
|
||||
expect(collection.freshness).toBe('current');
|
||||
|
||||
await act(async () => {
|
||||
await collection.revalidate();
|
||||
});
|
||||
|
||||
expect(latest?.freshness).toBe('stale');
|
||||
expect(latest?.data).toEqual(taskFixtures);
|
||||
expect(latest?.failure).toEqual({ kind: 'invalidated', reason: 'schema-mismatch' });
|
||||
expect(latest?.canMutate).toBe(false);
|
||||
});
|
||||
|
||||
it('drops the snapshot when the workspace changes under it (cross-workspace)', async () => {
|
||||
let call = 0;
|
||||
const collection = await renderCollection(
|
||||
taskOptions({
|
||||
fetcher: () => {
|
||||
call += 1;
|
||||
return Promise.resolve(
|
||||
call === 1 ? projectFixtures : [{ ...projectFixtures[0], userId: 'user-2' }],
|
||||
);
|
||||
},
|
||||
validate: validateProjectCollection as unknown as (value: unknown) => {
|
||||
data: Task[];
|
||||
workspace: string | null;
|
||||
},
|
||||
source: 'gateway:/api/projects',
|
||||
}),
|
||||
);
|
||||
expect(collection.freshness).toBe('current');
|
||||
|
||||
await act(async () => {
|
||||
await collection.revalidate();
|
||||
});
|
||||
|
||||
expect(latest?.freshness).toBe('unavailable');
|
||||
expect(latest?.data).toBeNull();
|
||||
expect(latest?.failure).toEqual({ kind: 'invalidated', reason: 'cross-workspace' });
|
||||
});
|
||||
|
||||
it('ages from current to stale and refuses mutations on stale data', async () => {
|
||||
let fakeNow = NOW;
|
||||
const collection = await renderCollection(
|
||||
taskOptions({
|
||||
clock: () => fakeNow,
|
||||
policy: { staleAfterMs: 40 },
|
||||
tickMs: 10,
|
||||
}),
|
||||
);
|
||||
expect(collection.freshness).toBe('current');
|
||||
|
||||
// Age the snapshot past the policy and let the tick recompute.
|
||||
fakeNow = NOW + 60;
|
||||
await act(async () => {
|
||||
await new Promise((resolve) => setTimeout(resolve, 25));
|
||||
});
|
||||
|
||||
expect(latest?.freshness).toBe('stale');
|
||||
expect(latest?.data).toEqual(taskFixtures);
|
||||
expect(latest?.canMutate).toBe(false);
|
||||
|
||||
const operation = vi.fn(async () => 'result');
|
||||
await expect(latest?.mutate(operation)).rejects.toBeInstanceOf(StaleMutationError);
|
||||
expect(operation).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('recovers to current after a successful revalidation', async () => {
|
||||
let call = 0;
|
||||
const collection = await renderCollection(
|
||||
taskOptions({
|
||||
fetcher: () => {
|
||||
call += 1;
|
||||
return call === 1
|
||||
? Promise.reject(new Error('first attempt failed'))
|
||||
: Promise.resolve(taskFixtures);
|
||||
},
|
||||
}),
|
||||
);
|
||||
expect(collection.freshness).toBe('unavailable');
|
||||
|
||||
await act(async () => {
|
||||
await collection.revalidate();
|
||||
});
|
||||
|
||||
expect(latest?.freshness).toBe('current');
|
||||
expect(latest?.failure).toBeNull();
|
||||
|
||||
const operation = vi.fn(async (data: Task[]) => data.length);
|
||||
await expect(latest?.mutate(operation)).resolves.toBe(taskFixtures.length);
|
||||
expect(operation).toHaveBeenCalledOnce();
|
||||
});
|
||||
|
||||
it('restores a cached snapshot as unverified stale data, then verifies it', async () => {
|
||||
const seededVersion = seedCache('tasks');
|
||||
const deferred = createDeferred<Task[]>();
|
||||
const collection = await renderCollection(taskOptions({ fetcher: () => deferred.promise }));
|
||||
|
||||
// Restored data is situational awareness only: labeled stale, never
|
||||
// current, and mutations are refused before verification.
|
||||
expect(collection.freshness).toBe('stale');
|
||||
expect(collection.data).toEqual(taskFixtures);
|
||||
expect(collection.canMutate).toBe(false);
|
||||
await expect(collection.mutate(vi.fn())).rejects.toBeInstanceOf(StaleMutationError);
|
||||
|
||||
await act(async () => {
|
||||
deferred.resolve(taskFixtures);
|
||||
await deferred.promise;
|
||||
});
|
||||
|
||||
expect(latest?.freshness).toBe('current');
|
||||
expect(latest?.snapshot?.version).toBe(seededVersion + 1);
|
||||
});
|
||||
|
||||
it('never promotes corrupted cache data to current (cache corruption)', async () => {
|
||||
sessionStorage.setItem('mosaic:freshness:v1:tasks', '{"data":');
|
||||
const collection = await renderCollection(
|
||||
taskOptions({ fetcher: () => Promise.reject(new Error('still down')) }),
|
||||
);
|
||||
|
||||
expect(collection.freshness).toBe('unavailable');
|
||||
expect(collection.data).toBeNull();
|
||||
expect(collection.canMutate).toBe(false);
|
||||
// The corrupted entry is dropped so it cannot come back.
|
||||
expect(sessionStorage.getItem('mosaic:freshness:v1:tasks')).toBeNull();
|
||||
});
|
||||
|
||||
it('refuses mutations while unknown or unavailable — the call itself, not just the button', async () => {
|
||||
const deferred = createDeferred<Task[]>();
|
||||
const unknown = await renderCollection(taskOptions({ fetcher: () => deferred.promise }));
|
||||
const operation = vi.fn(async () => 'result');
|
||||
await expect(unknown.mutate(operation)).rejects.toBeInstanceOf(StaleMutationError);
|
||||
expect(operation).not.toHaveBeenCalled();
|
||||
await act(async () => {
|
||||
deferred.reject(new Error('failed'));
|
||||
await deferred.promise.catch(() => undefined);
|
||||
});
|
||||
|
||||
const unavailable = latest!;
|
||||
await expect(unavailable.mutate(operation)).rejects.toBeInstanceOf(StaleMutationError);
|
||||
expect(operation).not.toHaveBeenCalled();
|
||||
expect(unavailable.canMutate).toBe(false);
|
||||
});
|
||||
|
||||
it('degrades to stale with last-known data when a revalidation fails after success', async () => {
|
||||
let call = 0;
|
||||
const collection = await renderCollection(
|
||||
taskOptions({
|
||||
fetcher: () => {
|
||||
call += 1;
|
||||
return call === 1
|
||||
? Promise.resolve(taskFixtures)
|
||||
: Promise.reject(new Error('connection lost'));
|
||||
},
|
||||
}),
|
||||
);
|
||||
expect(collection.freshness).toBe('current');
|
||||
|
||||
await act(async () => {
|
||||
await collection.revalidate();
|
||||
});
|
||||
|
||||
expect(latest?.freshness).toBe('stale');
|
||||
expect(latest?.data).toEqual(taskFixtures);
|
||||
const failure: FreshnessFailure | null = latest?.failure ?? null;
|
||||
expect(failure).toEqual({ kind: 'fetch', message: 'connection lost' });
|
||||
});
|
||||
});
|
||||
@@ -1,281 +0,0 @@
|
||||
import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
|
||||
import {
|
||||
acceptSnapshot,
|
||||
assertMutable,
|
||||
computeFreshness,
|
||||
DEFAULT_FRESHNESS_POLICY,
|
||||
invalidationReasonLabels,
|
||||
type FreshPayload,
|
||||
type FreshSnapshot,
|
||||
type FreshnessPolicy,
|
||||
type FreshnessState,
|
||||
type InvalidationReason,
|
||||
StaleMutationError,
|
||||
} from './model';
|
||||
import { clearSnapshotCache, readSnapshotCache, writeSnapshotCache } from './snapshot-cache';
|
||||
|
||||
/**
|
||||
* Freshness-aware collection fetch hook (RI-5-001).
|
||||
*
|
||||
* One hook owns one gateway collection end to end: fetch, schema validation,
|
||||
* snapshot acceptance with provenance, session-scoped last-known caching,
|
||||
* aging, and the mutation guard. Pages consume `freshness` and never infer
|
||||
* health from emptiness.
|
||||
*/
|
||||
|
||||
/** Why the latest validation did not produce a current snapshot. */
|
||||
export type FreshnessFailure =
|
||||
| { readonly kind: 'fetch'; readonly message: string }
|
||||
| { readonly kind: 'invalidated'; readonly reason: InvalidationReason };
|
||||
|
||||
export interface UseFreshCollectionOptions<T> {
|
||||
/** Source identity for provenance labels, e.g. `gateway:/api/tasks`. */
|
||||
readonly source: string;
|
||||
/** Performs the unvalidated fetch. The hook owns abort and verification. */
|
||||
readonly fetcher: (signal: AbortSignal) => Promise<unknown>;
|
||||
/**
|
||||
* Runtime schema validator. Returning `null` invalidates the payload
|
||||
* (`schema-mismatch`) instead of letting malformed JSON flow into render.
|
||||
*/
|
||||
readonly validate: (value: unknown) => FreshPayload<T> | null;
|
||||
/** Overrides of the default freshness policy. */
|
||||
readonly policy?: Partial<FreshnessPolicy>;
|
||||
/**
|
||||
* Session cache key for last-known snapshots. `null`/omitted disables
|
||||
* restore. Restored snapshots are unverified: they render only as
|
||||
* labeled `stale` data until a fetch re-verifies them.
|
||||
*/
|
||||
readonly cacheKey?: string | null;
|
||||
/** Injectable clock for deterministic age transitions in tests. */
|
||||
readonly clock?: () => number;
|
||||
/** Aging tick interval override (default derived from `staleAfterMs`). */
|
||||
readonly tickMs?: number;
|
||||
/** When false, no fetch runs (surfaces stay `unavailable`/`unknown`). */
|
||||
readonly enabled?: boolean;
|
||||
}
|
||||
|
||||
export interface FreshCollection<T> {
|
||||
/** Last verified (or restored-unverified) snapshot, or `null`. */
|
||||
readonly snapshot: FreshSnapshot<T> | null;
|
||||
/** Snapshot data or `null` — never a fabricated empty collection. */
|
||||
readonly data: T | null;
|
||||
readonly freshness: FreshnessState;
|
||||
/** True while a validation request is in flight. */
|
||||
readonly validating: boolean;
|
||||
/** Outcome of the latest failed validation, `null` when healthy. */
|
||||
readonly failure: FreshnessFailure | null;
|
||||
/** False unless freshness is `current`; drives disabled UI affordances. */
|
||||
readonly canMutate: boolean;
|
||||
/** Re-run the fetch and re-verify. Always allowed (it is a read). */
|
||||
readonly revalidate: () => Promise<void>;
|
||||
/**
|
||||
* Run a state-changing operation against verified-current data only.
|
||||
* Rejects with `StaleMutationError` on any other state — the guard fires
|
||||
* even if a disabled button was bypassed (defense in depth).
|
||||
*/
|
||||
readonly mutate: <R>(operation: (data: T) => Promise<R>) => Promise<R>;
|
||||
}
|
||||
|
||||
const defaultClock = (): number => Date.now();
|
||||
|
||||
function resolveTickMs(policy: FreshnessPolicy, override?: number): number {
|
||||
if (override !== undefined && override > 0) return override;
|
||||
return Math.min(5_000, Math.max(250, Math.floor(policy.staleAfterMs / 4)));
|
||||
}
|
||||
|
||||
function isAuthFailure(caught: unknown): boolean {
|
||||
return (
|
||||
typeof caught === 'object' &&
|
||||
caught !== null &&
|
||||
'statusCode' in caught &&
|
||||
((caught as { statusCode?: unknown }).statusCode === 401 ||
|
||||
(caught as { statusCode?: unknown }).statusCode === 403)
|
||||
);
|
||||
}
|
||||
|
||||
function fetchFailureMessage(caught: unknown): string {
|
||||
if (caught instanceof Error && caught.message.trim().length > 0) return caught.message;
|
||||
return 'The request failed.';
|
||||
}
|
||||
|
||||
/** Human-readable summary of a failure for unavailable/stale notices. */
|
||||
export function describeFailure(failure: FreshnessFailure | null): string | null {
|
||||
if (failure === null) return null;
|
||||
if (failure.kind === 'fetch') return failure.message;
|
||||
return `The snapshot was invalidated: ${invalidationReasonLabels[failure.reason]}.`;
|
||||
}
|
||||
|
||||
export function useFreshCollection<T>(options: UseFreshCollectionOptions<T>): FreshCollection<T> {
|
||||
const optionsRef = useRef(options);
|
||||
optionsRef.current = options;
|
||||
|
||||
const policy = useMemo<FreshnessPolicy>(
|
||||
() => ({ ...DEFAULT_FRESHNESS_POLICY, ...options.policy }),
|
||||
[options.policy],
|
||||
);
|
||||
const policyRef = useRef(policy);
|
||||
policyRef.current = policy;
|
||||
|
||||
const clockRef = useRef(options.clock ?? defaultClock);
|
||||
clockRef.current = options.clock ?? defaultClock;
|
||||
|
||||
const [snapshot, setSnapshot] = useState<FreshSnapshot<T> | null>(null);
|
||||
const [failure, setFailure] = useState<FreshnessFailure | null>(null);
|
||||
const [unverified, setUnverified] = useState(false);
|
||||
const [validating, setValidating] = useState(options.enabled !== false);
|
||||
const [now, setNow] = useState(() => (options.clock ?? defaultClock)());
|
||||
|
||||
const snapshotRef = useRef(snapshot);
|
||||
snapshotRef.current = snapshot;
|
||||
const failureRef = useRef(failure);
|
||||
failureRef.current = failure;
|
||||
const unverifiedRef = useRef(unverified);
|
||||
unverifiedRef.current = unverified;
|
||||
|
||||
const runRef = useRef(0);
|
||||
const abortRef = useRef<AbortController | null>(null);
|
||||
|
||||
const revalidate = useCallback(async (): Promise<void> => {
|
||||
const current = optionsRef.current;
|
||||
if (current.enabled === false) {
|
||||
setValidating(false);
|
||||
return;
|
||||
}
|
||||
|
||||
const runId = ++runRef.current;
|
||||
abortRef.current?.abort();
|
||||
const controller = new AbortController();
|
||||
abortRef.current = controller;
|
||||
setValidating(true);
|
||||
|
||||
let value: unknown;
|
||||
try {
|
||||
value = await current.fetcher(controller.signal);
|
||||
} catch (caught) {
|
||||
if (runRef.current !== runId || controller.signal.aborted) return;
|
||||
if (isAuthFailure(caught)) {
|
||||
// An unauthenticated viewer must not keep (or be served) the
|
||||
// previous user's last-known data.
|
||||
setSnapshot(null);
|
||||
setUnverified(false);
|
||||
if (current.cacheKey) clearSnapshotCache(current.cacheKey);
|
||||
}
|
||||
setFailure({ kind: 'fetch', message: fetchFailureMessage(caught) });
|
||||
setValidating(false);
|
||||
return;
|
||||
}
|
||||
|
||||
if (runRef.current !== runId) return;
|
||||
|
||||
const result = acceptSnapshot({
|
||||
value,
|
||||
validate: current.validate,
|
||||
previous: snapshotRef.current,
|
||||
policy: policyRef.current,
|
||||
source: current.source,
|
||||
now: clockRef.current(),
|
||||
});
|
||||
|
||||
if (result.outcome === 'accepted') {
|
||||
setSnapshot(result.snapshot);
|
||||
setUnverified(false);
|
||||
setFailure(null);
|
||||
if (current.cacheKey) writeSnapshotCache(current.cacheKey, result.snapshot);
|
||||
} else {
|
||||
if (result.reason === 'cross-workspace') {
|
||||
// Data verified for a different workspace must not linger as
|
||||
// last-known situational awareness either.
|
||||
setSnapshot(null);
|
||||
setUnverified(false);
|
||||
}
|
||||
if (current.cacheKey) clearSnapshotCache(current.cacheKey);
|
||||
setFailure({ kind: 'invalidated', reason: result.reason });
|
||||
}
|
||||
setValidating(false);
|
||||
}, []);
|
||||
|
||||
// Restore the last-known snapshot (unverified) and run the first fetch.
|
||||
useEffect(() => {
|
||||
if (optionsRef.current.enabled === false) {
|
||||
setValidating(false);
|
||||
return;
|
||||
}
|
||||
|
||||
const cacheKey = optionsRef.current.cacheKey;
|
||||
if (cacheKey) {
|
||||
const restored = readSnapshotCache<T>({
|
||||
key: cacheKey,
|
||||
workspace: policyRef.current.workspace,
|
||||
policy: policyRef.current,
|
||||
validate: optionsRef.current.validate,
|
||||
});
|
||||
if (restored.outcome === 'hit') {
|
||||
setSnapshot(restored.snapshot);
|
||||
setUnverified(true);
|
||||
} else if (restored.outcome === 'invalidated') {
|
||||
// A corrupted/foreign/regressed entry is dropped immediately; it must
|
||||
// never surface as data. The fetch decides the visible state.
|
||||
clearSnapshotCache(cacheKey);
|
||||
}
|
||||
}
|
||||
|
||||
void revalidate();
|
||||
|
||||
return () => {
|
||||
abortRef.current?.abort();
|
||||
};
|
||||
// Mount-once by design: `revalidate` is stable and reads live options
|
||||
// through refs, so it never needs to re-run when options change.
|
||||
// Route-param pages remount this hook via an identity `key` instead.
|
||||
}, [revalidate]);
|
||||
|
||||
// Aging tick: recomputes freshness as the snapshot ages past the policy.
|
||||
useEffect(() => {
|
||||
const interval = setInterval(
|
||||
() => {
|
||||
setNow(clockRef.current());
|
||||
},
|
||||
resolveTickMs(policyRef.current, optionsRef.current.tickMs),
|
||||
);
|
||||
return () => clearInterval(interval);
|
||||
}, []);
|
||||
|
||||
const freshness = useMemo<FreshnessState>(() => {
|
||||
if (snapshot === null) return validating ? 'unknown' : 'unavailable';
|
||||
return computeFreshness({
|
||||
snapshot,
|
||||
policy,
|
||||
now,
|
||||
degraded: failure !== null || unverified,
|
||||
});
|
||||
// `now` from state covers age; refs inside computeFreshness are pure.
|
||||
}, [snapshot, validating, failure, unverified, now, policy]);
|
||||
|
||||
const canMutate = freshness === 'current';
|
||||
|
||||
const mutate = useCallback(async <R>(operation: (data: T) => Promise<R>): Promise<R> => {
|
||||
const currentSnapshot = snapshotRef.current;
|
||||
// No verified snapshot at all: with nothing verified there is nothing
|
||||
// current to mutate, regardless of the recorded failure.
|
||||
if (currentSnapshot === null) throw new StaleMutationError('unavailable');
|
||||
const state = computeFreshness({
|
||||
snapshot: currentSnapshot,
|
||||
policy: policyRef.current,
|
||||
now: clockRef.current(),
|
||||
degraded: failureRef.current !== null || unverifiedRef.current,
|
||||
});
|
||||
assertMutable(state);
|
||||
return operation(currentSnapshot.data);
|
||||
}, []);
|
||||
|
||||
return {
|
||||
snapshot,
|
||||
data: snapshot === null ? null : snapshot.data,
|
||||
freshness,
|
||||
validating,
|
||||
failure,
|
||||
canMutate,
|
||||
revalidate,
|
||||
mutate,
|
||||
};
|
||||
}
|
||||
@@ -1,103 +0,0 @@
|
||||
import { describe, expect, it } from 'vitest';
|
||||
import type { Mission, Project, Task } from '@/lib/types';
|
||||
import {
|
||||
validateMissionCollection,
|
||||
validateProjectCollection,
|
||||
validateProjectEntity,
|
||||
validateTaskCollection,
|
||||
} from './validators';
|
||||
import { missionFixtures, projectFixtures, taskFixtures } from '@/spa/pages/page-fixtures';
|
||||
|
||||
describe('validateTaskCollection', () => {
|
||||
it('accepts a well-formed task collection', () => {
|
||||
expect(validateTaskCollection(taskFixtures)).toEqual({
|
||||
data: taskFixtures,
|
||||
workspace: null,
|
||||
});
|
||||
});
|
||||
|
||||
it('accepts an empty collection (a healthy empty state is a valid payload)', () => {
|
||||
expect(validateTaskCollection([])).toEqual({ data: [], workspace: null });
|
||||
});
|
||||
|
||||
it.each([
|
||||
['not an array', { items: [] }],
|
||||
['item is not an object', ['nope']],
|
||||
['missing id', [{ ...(taskFixtures[0] as Task), id: undefined }]],
|
||||
['missing title', [{ ...(taskFixtures[0] as Task), title: undefined }]],
|
||||
['unknown status enum', [{ ...(taskFixtures[0] as Task), status: 'finished' }]],
|
||||
['unknown priority enum', [{ ...(taskFixtures[0] as Task), priority: 'urgent' }]],
|
||||
['tags of the wrong type', [{ ...(taskFixtures[0] as Task), tags: 'spa' }]],
|
||||
['metadata of the wrong type', [{ ...(taskFixtures[0] as Task), metadata: 'notes' }]],
|
||||
['createdAt of the wrong type', [{ ...(taskFixtures[0] as Task), createdAt: 1234 }]],
|
||||
['null sneaks past a required string', [{ ...(taskFixtures[0] as Task), title: null }]],
|
||||
])('rejects a malformed payload: %s', (_label, value) => {
|
||||
expect(validateTaskCollection(value)).toBeNull();
|
||||
});
|
||||
});
|
||||
|
||||
describe('validateMissionCollection', () => {
|
||||
it('accepts a well-formed mission collection', () => {
|
||||
expect(validateMissionCollection(missionFixtures)).toEqual({
|
||||
data: missionFixtures,
|
||||
workspace: null,
|
||||
});
|
||||
});
|
||||
|
||||
it.each([
|
||||
['not an array', null],
|
||||
['item missing name', [{ ...(missionFixtures[0] as Mission), name: 42 }]],
|
||||
['unknown status enum', [{ ...(missionFixtures[0] as Mission), status: 'canceled' }]],
|
||||
['projectId of the wrong type', [{ ...(missionFixtures[0] as Mission), projectId: 7 }]],
|
||||
])('rejects a malformed payload: %s', (_label, value) => {
|
||||
expect(validateMissionCollection(value)).toBeNull();
|
||||
});
|
||||
});
|
||||
|
||||
describe('validateProjectCollection', () => {
|
||||
it('accepts a uniform workspace-scoped collection and reports its workspace', () => {
|
||||
expect(validateProjectCollection(projectFixtures)).toEqual({
|
||||
data: projectFixtures,
|
||||
workspace: 'user-1',
|
||||
});
|
||||
});
|
||||
|
||||
it('accepts an empty collection with no workspace identity', () => {
|
||||
expect(validateProjectCollection([])).toEqual({ data: [], workspace: null });
|
||||
});
|
||||
|
||||
it.each([
|
||||
['not an array', 42],
|
||||
['item missing userId', [{ ...(projectFixtures[0] as Project), userId: undefined }]],
|
||||
['unknown status enum', [{ ...(projectFixtures[0] as Project), status: 'live' }]],
|
||||
['description of the wrong type', [{ ...(projectFixtures[0] as Project), description: 1 }]],
|
||||
])('rejects a malformed payload: %s', (_label, value) => {
|
||||
expect(validateProjectCollection(value)).toBeNull();
|
||||
});
|
||||
|
||||
it('rejects a collection mixing workspace identities (cross-workspace leak)', () => {
|
||||
const mixed = [
|
||||
projectFixtures[0] as Project,
|
||||
{ ...(projectFixtures[1] as Project), userId: 'user-2' },
|
||||
];
|
||||
expect(validateProjectCollection(mixed)).toBeNull();
|
||||
});
|
||||
});
|
||||
|
||||
describe('validateProjectEntity', () => {
|
||||
it('accepts a well-formed project and reports its workspace', () => {
|
||||
expect(validateProjectEntity(projectFixtures[0])).toEqual({
|
||||
data: projectFixtures[0],
|
||||
workspace: 'user-1',
|
||||
});
|
||||
});
|
||||
|
||||
it.each([
|
||||
['not an object', 'project-1'],
|
||||
['null', null],
|
||||
['array', [projectFixtures[0]]],
|
||||
['missing userId', [{ ...(projectFixtures[0] as Project), userId: null }]],
|
||||
])('rejects a malformed entity: %s', (_label, value) => {
|
||||
expect(validateProjectEntity(value)).toBeNull();
|
||||
});
|
||||
});
|
||||
@@ -1,135 +0,0 @@
|
||||
import type { Mission, Project, Task, MissionStatus, TaskPriority, TaskStatus } from '@/lib/types';
|
||||
import type { FreshPayload } from './model';
|
||||
|
||||
/**
|
||||
* Runtime schema validators for gateway collections (RI-5-001).
|
||||
*
|
||||
* `api<T>()` returns untrusted JSON cast to `T`; these validators are the
|
||||
* seam where a malformed response becomes an explicit schema mismatch
|
||||
* instead of flowing into the render path as if it were healthy data.
|
||||
*/
|
||||
|
||||
const taskStatuses: readonly TaskStatus[] = [
|
||||
'not-started',
|
||||
'in-progress',
|
||||
'blocked',
|
||||
'done',
|
||||
'cancelled',
|
||||
];
|
||||
const taskPriorities: readonly TaskPriority[] = ['critical', 'high', 'medium', 'low'];
|
||||
const missionStatuses: readonly MissionStatus[] = [
|
||||
'planning',
|
||||
'active',
|
||||
'paused',
|
||||
'completed',
|
||||
'failed',
|
||||
];
|
||||
const projectStatuses: readonly Project['status'][] = ['active', 'paused', 'completed', 'archived'];
|
||||
|
||||
function isRecord(value: unknown): value is Record<string, unknown> {
|
||||
return typeof value === 'object' && value !== null && !Array.isArray(value);
|
||||
}
|
||||
|
||||
function isString(value: unknown): value is string {
|
||||
return typeof value === 'string';
|
||||
}
|
||||
|
||||
function isNullableString(value: unknown): value is string | null {
|
||||
return value === null || typeof value === 'string';
|
||||
}
|
||||
|
||||
function isOneOf<T extends string>(value: unknown, allowed: readonly T[]): value is T {
|
||||
return typeof value === 'string' && (allowed as readonly string[]).includes(value);
|
||||
}
|
||||
|
||||
function isNullableRecord(value: unknown): value is Record<string, unknown> | null {
|
||||
return value === null || isRecord(value);
|
||||
}
|
||||
|
||||
function isNullableStringArray(value: unknown): value is string[] | null {
|
||||
if (value === null) return true;
|
||||
if (!Array.isArray(value)) return false;
|
||||
return value.every((item) => typeof item === 'string');
|
||||
}
|
||||
|
||||
function isIsoLike(value: unknown): value is string {
|
||||
return typeof value === 'string' && value.length > 0;
|
||||
}
|
||||
|
||||
function isTask(value: unknown): value is Task {
|
||||
if (!isRecord(value)) return false;
|
||||
return (
|
||||
isString(value['id']) &&
|
||||
isString(value['title']) &&
|
||||
isOneOf(value['status'], taskStatuses) &&
|
||||
isOneOf(value['priority'], taskPriorities) &&
|
||||
isNullableString(value['projectId']) &&
|
||||
isNullableString(value['missionId']) &&
|
||||
isNullableString(value['assignee']) &&
|
||||
isNullableStringArray(value['tags']) &&
|
||||
isNullableRecord(value['metadata']) &&
|
||||
isNullableString(value['dueDate']) &&
|
||||
isIsoLike(value['createdAt']) &&
|
||||
isIsoLike(value['updatedAt'])
|
||||
);
|
||||
}
|
||||
|
||||
/** Tasks carry no workspace identity; scope falls back to the policy. */
|
||||
export function validateTaskCollection(value: unknown): FreshPayload<Task[]> | null {
|
||||
if (!Array.isArray(value) || !value.every(isTask)) return null;
|
||||
return { data: value as Task[], workspace: null };
|
||||
}
|
||||
|
||||
function isMission(value: unknown): value is Mission {
|
||||
if (!isRecord(value)) return false;
|
||||
return (
|
||||
isString(value['id']) &&
|
||||
isString(value['name']) &&
|
||||
isOneOf(value['status'], missionStatuses) &&
|
||||
isNullableString(value['projectId']) &&
|
||||
isNullableString(value['description']) &&
|
||||
isNullableRecord(value['metadata']) &&
|
||||
isIsoLike(value['createdAt']) &&
|
||||
isIsoLike(value['updatedAt'])
|
||||
);
|
||||
}
|
||||
|
||||
/** Missions carry no workspace identity; scope falls back to the policy. */
|
||||
export function validateMissionCollection(value: unknown): FreshPayload<Mission[]> | null {
|
||||
if (!Array.isArray(value) || !value.every(isMission)) return null;
|
||||
return { data: value as Mission[], workspace: null };
|
||||
}
|
||||
|
||||
function isProject(value: unknown): value is Project {
|
||||
if (!isRecord(value)) return false;
|
||||
return (
|
||||
isString(value['id']) &&
|
||||
isString(value['name']) &&
|
||||
isOneOf(value['status'], projectStatuses) &&
|
||||
isString(value['userId']) &&
|
||||
isNullableString(value['description']) &&
|
||||
isNullableRecord(value['metadata']) &&
|
||||
isIsoLike(value['createdAt']) &&
|
||||
isIsoLike(value['updatedAt'])
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Projects are workspace-scoped: every item must carry the same `userId`.
|
||||
* A collection mixing identities (cross-workspace leak) is a schema
|
||||
* mismatch; the uniform `userId` becomes the snapshot workspace.
|
||||
*/
|
||||
export function validateProjectCollection(value: unknown): FreshPayload<Project[]> | null {
|
||||
if (!Array.isArray(value) || !value.every(isProject)) return null;
|
||||
const projects = value as Project[];
|
||||
const workspaces = new Set(projects.map((project) => project.userId));
|
||||
if (workspaces.size > 1) return null;
|
||||
return { data: projects, workspace: projects.length > 0 ? projects[0]!.userId : null };
|
||||
}
|
||||
|
||||
/** Single project entity (project detail primary collection). */
|
||||
export function validateProjectEntity(value: unknown): FreshPayload<Project> | null {
|
||||
if (!isProject(value)) return null;
|
||||
const project = value as Project;
|
||||
return { data: project, workspace: project.userId };
|
||||
}
|
||||
@@ -35,7 +35,6 @@ afterEach(async () => {
|
||||
document.body.replaceChildren();
|
||||
root = null;
|
||||
apiMock.mockReset();
|
||||
sessionStorage.clear();
|
||||
});
|
||||
|
||||
async function renderProjectDetailPage(): Promise<ReturnType<typeof createMemoryRouter>> {
|
||||
@@ -65,49 +64,21 @@ function clickButtonByText(text: string): void {
|
||||
button.dispatchEvent(new MouseEvent('click', { bubbles: true }));
|
||||
}
|
||||
|
||||
async function flushAct(): Promise<void> {
|
||||
await act(async () => {
|
||||
await Promise.resolve();
|
||||
});
|
||||
}
|
||||
|
||||
interface Deferred<T> {
|
||||
promise: Promise<T>;
|
||||
resolve: (value: T) => void;
|
||||
}
|
||||
|
||||
function createDeferred<T>(): Deferred<T> {
|
||||
let resolve!: (value: T) => void;
|
||||
const promise = new Promise<T>((res) => {
|
||||
resolve = res;
|
||||
});
|
||||
return { promise, resolve };
|
||||
}
|
||||
|
||||
const projectOneTasks = taskFixtures.filter((task) => task.projectId === 'project-1');
|
||||
|
||||
function mockHealthyLoad(): void {
|
||||
apiMock
|
||||
.mockResolvedValueOnce(projectFixtures[0])
|
||||
.mockResolvedValueOnce(missionFixtures)
|
||||
.mockResolvedValueOnce(projectOneTasks);
|
||||
}
|
||||
|
||||
describe('ProjectDetailPage', () => {
|
||||
it('loads the project, tasks, missions, and optional PRD content for the active project', async () => {
|
||||
mockHealthyLoad();
|
||||
apiMock
|
||||
.mockResolvedValueOnce(projectFixtures[0])
|
||||
.mockResolvedValueOnce(missionFixtures)
|
||||
.mockResolvedValueOnce(taskFixtures.filter((task) => task.projectId === 'project-1'));
|
||||
|
||||
await renderProjectDetailPage();
|
||||
|
||||
expect(apiMock.mock.calls.map((call) => call[0])).toEqual([
|
||||
'/api/projects/project-1',
|
||||
'/api/missions',
|
||||
'/api/tasks?projectId=project-1',
|
||||
expect(apiMock.mock.calls).toEqual([
|
||||
['/api/projects/project-1'],
|
||||
['/api/missions'],
|
||||
['/api/tasks?projectId=project-1'],
|
||||
]);
|
||||
|
||||
expect(container.querySelector('[data-freshness]')?.getAttribute('data-freshness')).toBe(
|
||||
'current',
|
||||
);
|
||||
expect(container.textContent).toContain('Mosaic Stack');
|
||||
expect(container.textContent).toContain('Route /projects/:id');
|
||||
expect(container.textContent).toContain('Tasks');
|
||||
@@ -130,7 +101,10 @@ describe('ProjectDetailPage', () => {
|
||||
});
|
||||
|
||||
it('opens and closes the existing read-only task modal from the tasks tab', async () => {
|
||||
mockHealthyLoad();
|
||||
apiMock
|
||||
.mockResolvedValueOnce(projectFixtures[0])
|
||||
.mockResolvedValueOnce(missionFixtures)
|
||||
.mockResolvedValueOnce(taskFixtures.filter((task) => task.projectId === 'project-1'));
|
||||
|
||||
await renderProjectDetailPage();
|
||||
|
||||
@@ -160,153 +134,35 @@ describe('ProjectDetailPage', () => {
|
||||
expect(container.querySelector('[role="dialog"]')).toBeNull();
|
||||
});
|
||||
|
||||
it('shows verified completion verdicts when the task collection is current', async () => {
|
||||
mockHealthyLoad();
|
||||
|
||||
await renderProjectDetailPage();
|
||||
|
||||
const doneCard = [...container.querySelectorAll('div')].find(
|
||||
(candidate) => candidate.textContent === 'Done1',
|
||||
);
|
||||
expect(doneCard).toBeTruthy();
|
||||
const inProgressCard = [...container.querySelectorAll('div')].find(
|
||||
(candidate) => candidate.textContent === 'In Progress1',
|
||||
);
|
||||
expect(inProgressCard).toBeTruthy();
|
||||
});
|
||||
|
||||
it('renders an explicit unavailable missions tab when the missions request fails (partial, not empty)', async () => {
|
||||
it('renders the project with an empty missions tab when the missions request fails', async () => {
|
||||
apiMock
|
||||
.mockResolvedValueOnce(projectFixtures[0])
|
||||
.mockRejectedValueOnce(new Error('Missions request failed'))
|
||||
.mockResolvedValueOnce(projectOneTasks);
|
||||
.mockResolvedValueOnce(taskFixtures.filter((task) => task.projectId === 'project-1'));
|
||||
|
||||
await renderProjectDetailPage();
|
||||
|
||||
// Secondary failure degrades the surface to partial; the project itself
|
||||
// still renders.
|
||||
expect(container.querySelector('[data-freshness]')?.getAttribute('data-freshness')).toBe(
|
||||
'partial',
|
||||
);
|
||||
expect(container.textContent).toContain('Mosaic Stack');
|
||||
const partial = container.querySelector('[role="status"]');
|
||||
expect(partial?.textContent).toContain('Missions');
|
||||
expect(partial?.textContent).toContain('unavailable');
|
||||
expect(container.querySelector('[role="alert"]')).toBeNull();
|
||||
|
||||
await act(async () => {
|
||||
clickButtonByText('Missions (?)');
|
||||
clickButtonByText('Missions (0)');
|
||||
});
|
||||
|
||||
const alert = container.querySelector('[role="alert"]');
|
||||
expect(alert?.textContent).toContain('Missions request failed');
|
||||
// Negative control: a failed fetch must not look like an empty list.
|
||||
expect(container.textContent).not.toContain('No missions for this project');
|
||||
expect(container.textContent).toContain('No missions for this project');
|
||||
});
|
||||
|
||||
it('marks derived verdicts unknown when the tasks collection is unavailable', async () => {
|
||||
apiMock
|
||||
.mockResolvedValueOnce(projectFixtures[0])
|
||||
.mockResolvedValueOnce(missionFixtures)
|
||||
.mockRejectedValueOnce(new Error('Tasks request failed'));
|
||||
|
||||
await renderProjectDetailPage();
|
||||
|
||||
expect(container.querySelector('[data-freshness]')?.getAttribute('data-freshness')).toBe(
|
||||
'partial',
|
||||
);
|
||||
|
||||
// Completion verdicts become unknown ('?') — never green counts.
|
||||
for (const label of ['Done', 'In Progress', 'Blocked', 'Tasks']) {
|
||||
const unknownCard = [...container.querySelectorAll('div')].find(
|
||||
(candidate) => candidate.textContent === `${label}?`,
|
||||
);
|
||||
expect(unknownCard, `expected ${label} card to render ?`).toBeTruthy();
|
||||
}
|
||||
// Negative control: no green "Done 1" verdict anywhere.
|
||||
expect(
|
||||
[...container.querySelectorAll('div')].some((candidate) => candidate.textContent === 'Done1'),
|
||||
).toBe(false);
|
||||
|
||||
await act(async () => {
|
||||
clickButtonByText('Tasks (?)');
|
||||
});
|
||||
|
||||
const alert = container.querySelector('[role="alert"]');
|
||||
expect(alert?.textContent).toContain('Tasks request failed');
|
||||
// Negative control: no healthy empty task list from a failed fetch.
|
||||
expect(container.textContent).not.toContain('No tasks found');
|
||||
expect(container.querySelector('table')).toBeNull();
|
||||
});
|
||||
|
||||
it('recovers a partial surface to current after revalidation', async () => {
|
||||
apiMock
|
||||
.mockResolvedValueOnce(projectFixtures[0])
|
||||
.mockResolvedValueOnce(missionFixtures)
|
||||
.mockRejectedValueOnce(new Error('Tasks request failed'))
|
||||
.mockResolvedValueOnce(projectFixtures[0])
|
||||
.mockResolvedValueOnce(missionFixtures)
|
||||
.mockResolvedValueOnce(projectOneTasks);
|
||||
|
||||
await renderProjectDetailPage();
|
||||
expect(container.querySelector('[data-freshness]')?.getAttribute('data-freshness')).toBe(
|
||||
'partial',
|
||||
);
|
||||
|
||||
await act(async () => {
|
||||
clickButtonByText('Revalidate');
|
||||
});
|
||||
await flushAct();
|
||||
|
||||
expect(container.querySelector('[data-freshness]')?.getAttribute('data-freshness')).toBe(
|
||||
'current',
|
||||
);
|
||||
expect(
|
||||
[...container.querySelectorAll('div')].some((candidate) => candidate.textContent === 'Done1'),
|
||||
).toBe(true);
|
||||
});
|
||||
|
||||
it("never shows one project's data on another project's route after navigation", async () => {
|
||||
mockHealthyLoad();
|
||||
|
||||
const router = await renderProjectDetailPage();
|
||||
expect(container.textContent).toContain('Mosaic Stack');
|
||||
|
||||
const deferred = createDeferred<(typeof projectFixtures)[number]>();
|
||||
apiMock
|
||||
.mockResolvedValueOnce(deferred.promise)
|
||||
.mockResolvedValueOnce([])
|
||||
.mockResolvedValueOnce([]);
|
||||
|
||||
await act(async () => {
|
||||
await router.navigate('/projects/project-2');
|
||||
});
|
||||
|
||||
// While project-2 loads, nothing from project-1 may render on its route.
|
||||
expect(container.textContent).toContain('Loading project...');
|
||||
expect(container.textContent).not.toContain('Mosaic Stack');
|
||||
expect(container.textContent).not.toContain('Route /projects/:id');
|
||||
|
||||
await act(async () => {
|
||||
deferred.resolve(projectFixtures[1]!);
|
||||
await deferred.promise;
|
||||
});
|
||||
|
||||
expect(container.textContent).toContain('Agent Runtime');
|
||||
expect(apiMock.mock.calls[3]?.[0]).toBe('/api/projects/project-2');
|
||||
});
|
||||
|
||||
it('renders a visible unavailable state when the project request fails and lets the user navigate back', async () => {
|
||||
it('renders a visible alert when the project request fails and lets the user navigate back', async () => {
|
||||
apiMock
|
||||
.mockRejectedValueOnce(new Error('Project request failed'))
|
||||
.mockResolvedValueOnce(missionFixtures)
|
||||
.mockResolvedValueOnce(projectOneTasks);
|
||||
.mockResolvedValueOnce(taskFixtures.filter((task) => task.projectId === 'project-1'));
|
||||
|
||||
const router = await renderProjectDetailPage();
|
||||
|
||||
const alert = container.querySelector('[role="alert"]');
|
||||
expect(alert).toBeTruthy();
|
||||
expect(alert?.textContent).toContain('Project request failed');
|
||||
expect(alert?.textContent).toContain('not an empty result');
|
||||
expect(container.textContent).not.toContain('Mosaic Stack');
|
||||
|
||||
await act(async () => {
|
||||
|
||||
@@ -1,30 +1,14 @@
|
||||
import { useState, type ReactElement } from 'react';
|
||||
import { useEffect, useState, type ReactElement } from 'react';
|
||||
import { useNavigate, useParams } from 'react-router-dom';
|
||||
import { MissionTimeline } from '@/components/projects/mission-timeline';
|
||||
import { PrdViewer } from '@/components/projects/prd-viewer';
|
||||
import { TaskDetailModal } from '@/components/tasks/task-detail-modal';
|
||||
import { TaskListView } from '@/components/tasks/task-list-view';
|
||||
import { TaskStatusSummary } from '@/components/tasks/task-status-summary';
|
||||
import {
|
||||
PartialDataNotice,
|
||||
StaleDataNotice,
|
||||
UnavailableDataNotice,
|
||||
} from '@/components/freshness/freshness-notices';
|
||||
import { api } from '@/lib/api';
|
||||
import { cn } from '@/lib/cn';
|
||||
import type { Mission, Project, Task, TaskStatus } from '@/lib/types';
|
||||
import {
|
||||
combineFreshness,
|
||||
UNKNOWN_VERDICT,
|
||||
verdictValue,
|
||||
type FreshSnapshot,
|
||||
} from '@/lib/freshness/model';
|
||||
import { describeFailure, useFreshCollection } from '@/lib/freshness/use-fresh-collection';
|
||||
import {
|
||||
validateMissionCollection,
|
||||
validateProjectEntity,
|
||||
validateTaskCollection,
|
||||
} from '@/lib/freshness/validators';
|
||||
import { getErrorMessage } from './page-errors';
|
||||
|
||||
type Tab = 'overview' | 'tasks' | 'missions' | 'prd';
|
||||
|
||||
@@ -67,75 +51,55 @@ function TabButton({ id, label, activeTab, onClick }: TabButtonProps): ReactElem
|
||||
);
|
||||
}
|
||||
|
||||
/** Remounts per project id so no state from one project renders for another. */
|
||||
export function ProjectDetailPage(): ReactElement {
|
||||
const { id = '' } = useParams();
|
||||
return <ProjectDetail id={id} key={id} />;
|
||||
}
|
||||
|
||||
function ProjectDetail({ id }: { id: string }): ReactElement {
|
||||
const navigate = useNavigate();
|
||||
const enabled = id.length > 0;
|
||||
|
||||
// Primary collection gates the surface; missions and tasks are secondaries
|
||||
// whose failures degrade the surface to `partial` instead of rendering
|
||||
// empty healthy lists.
|
||||
const project = useFreshCollection<Project>({
|
||||
source: `gateway:/api/projects/${id}`,
|
||||
fetcher: (signal) => api<unknown>(`/api/projects/${id}`, { signal }),
|
||||
validate: validateProjectEntity,
|
||||
// No last-known restore: the entity carries workspace identity that
|
||||
// cannot be scope-checked before display (see ProjectsPage note).
|
||||
enabled,
|
||||
});
|
||||
const missions = useFreshCollection<Mission[]>({
|
||||
source: 'gateway:/api/missions',
|
||||
fetcher: (signal) => api<unknown>('/api/missions', { signal }),
|
||||
validate: validateMissionCollection,
|
||||
cacheKey: enabled ? 'missions' : null,
|
||||
enabled,
|
||||
});
|
||||
const tasks = useFreshCollection<Task[]>({
|
||||
source: `gateway:/api/tasks?projectId=${id}`,
|
||||
fetcher: (signal) => api<unknown>(`/api/tasks?projectId=${id}`, { signal }),
|
||||
validate: validateTaskCollection,
|
||||
cacheKey: enabled ? `project-tasks:${id}` : null,
|
||||
enabled,
|
||||
});
|
||||
|
||||
const [project, setProject] = useState<Project | null>(null);
|
||||
const [missions, setMissions] = useState<Mission[]>([]);
|
||||
const [tasks, setTasks] = useState<Task[]>([]);
|
||||
const [loading, setLoading] = useState(true);
|
||||
const [error, setError] = useState<string | null>(null);
|
||||
const [activeTab, setActiveTab] = useState<Tab>('overview');
|
||||
const [taskFilter, setTaskFilter] = useState<TaskStatus | 'all'>('all');
|
||||
const [selectedTask, setSelectedTask] = useState<Task | null>(null);
|
||||
|
||||
const surface = combineFreshness(project.freshness, [missions.freshness, tasks.freshness]);
|
||||
const tasksVerified = tasks.freshness === 'current';
|
||||
const projectMissions = missions.data?.filter((mission) => mission.projectId === id) ?? null;
|
||||
useEffect(() => {
|
||||
if (!id) {
|
||||
setError('Project id is missing.');
|
||||
setLoading(false);
|
||||
return;
|
||||
}
|
||||
|
||||
const retryAll = (): void => {
|
||||
void Promise.all([project.revalidate(), missions.revalidate(), tasks.revalidate()]);
|
||||
};
|
||||
let cancelled = false;
|
||||
setLoading(true);
|
||||
setError(null);
|
||||
|
||||
if (!enabled) {
|
||||
return (
|
||||
<div className="flex min-h-screen flex-col px-4 py-6 sm:px-6">
|
||||
<header className="mb-6 border-b px-1 pb-3">
|
||||
<h1 className="text-2xl font-semibold">Project</h1>
|
||||
</header>
|
||||
<div role="alert" className="rounded-lg border border-error/40 px-4 py-3 text-sm">
|
||||
Project id is missing.
|
||||
</div>
|
||||
<button
|
||||
type="button"
|
||||
onClick={() => navigate('/projects')}
|
||||
className="mt-4 w-fit text-sm underline"
|
||||
>
|
||||
Back to projects
|
||||
</button>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
void Promise.all([
|
||||
api<Project>('/api/projects/' + id),
|
||||
api<Mission[]>('/api/missions').catch(() => [] as Mission[]),
|
||||
api<Task[]>('/api/tasks?projectId=' + id).catch(() => [] as Task[]),
|
||||
])
|
||||
.then(([loadedProject, allMissions, loadedTasks]) => {
|
||||
if (cancelled) return;
|
||||
setProject(loadedProject);
|
||||
setMissions(allMissions.filter((mission) => mission.projectId === id));
|
||||
setTasks(loadedTasks);
|
||||
})
|
||||
.catch((caught: unknown) => {
|
||||
if (cancelled) return;
|
||||
setError(getErrorMessage(caught, 'Failed to load project.'));
|
||||
})
|
||||
.finally(() => {
|
||||
if (cancelled) return;
|
||||
setLoading(false);
|
||||
});
|
||||
|
||||
if (project.freshness === 'unknown') {
|
||||
return () => {
|
||||
cancelled = true;
|
||||
};
|
||||
}, [id]);
|
||||
|
||||
if (loading) {
|
||||
return (
|
||||
<div className="flex min-h-screen flex-col px-4 py-6 sm:px-6">
|
||||
<header className="mb-6 border-b px-1 pb-3">
|
||||
@@ -146,17 +110,15 @@ function ProjectDetail({ id }: { id: string }): ReactElement {
|
||||
);
|
||||
}
|
||||
|
||||
if (project.freshness === 'unavailable' || project.data === null) {
|
||||
if (error || !project) {
|
||||
return (
|
||||
<div className="flex min-h-screen flex-col px-4 py-6 sm:px-6">
|
||||
<header className="mb-6 border-b px-1 pb-3">
|
||||
<h1 className="text-2xl font-semibold">Project</h1>
|
||||
</header>
|
||||
<UnavailableDataNotice
|
||||
title="This project"
|
||||
detail={describeFailure(project.failure)}
|
||||
onRetry={retryAll}
|
||||
/>
|
||||
<div role="alert" className="rounded-lg border border-error/40 px-4 py-3 text-sm">
|
||||
{error ?? 'Project not found.'}
|
||||
</div>
|
||||
<button
|
||||
type="button"
|
||||
onClick={() => navigate('/projects')}
|
||||
@@ -168,48 +130,18 @@ function ProjectDetail({ id }: { id: string }): ReactElement {
|
||||
);
|
||||
}
|
||||
|
||||
const projectTasks = tasks.data ?? null;
|
||||
const filteredTasks =
|
||||
projectTasks === null
|
||||
? []
|
||||
: taskFilter === 'all'
|
||||
? projectTasks
|
||||
: projectTasks.filter((task) => task.status === taskFilter);
|
||||
|
||||
// Derived completion verdicts: unknown (never green) unless the task
|
||||
// collection is verified current.
|
||||
const doneCount = projectTasks?.filter((task) => task.status === 'done').length ?? 0;
|
||||
const inProgressCount = projectTasks?.filter((task) => task.status === 'in-progress').length ?? 0;
|
||||
const blockedCount = projectTasks?.filter((task) => task.status === 'blocked').length ?? 0;
|
||||
|
||||
const prdContent = getPrdContent(project.data);
|
||||
taskFilter === 'all' ? tasks : tasks.filter((task) => task.status === taskFilter);
|
||||
const prdContent = getPrdContent(project);
|
||||
const tabs: Array<{ id: Tab; label: string }> = [
|
||||
{ id: 'overview', label: 'Overview' },
|
||||
{
|
||||
id: 'tasks',
|
||||
label: `Tasks (${projectTasks === null ? UNKNOWN_VERDICT : projectTasks.length})`,
|
||||
},
|
||||
{
|
||||
id: 'missions',
|
||||
label: `Missions (${projectMissions === null ? UNKNOWN_VERDICT : projectMissions.length})`,
|
||||
},
|
||||
{ id: 'tasks', label: `Tasks (${tasks.length})` },
|
||||
{ id: 'missions', label: `Missions (${missions.length})` },
|
||||
...(prdContent ? [{ id: 'prd' as const, label: 'PRD' }] : []),
|
||||
];
|
||||
|
||||
const staleSnapshot: FreshSnapshot<unknown> | null =
|
||||
project.freshness === 'stale'
|
||||
? project.snapshot
|
||||
: missions.freshness === 'stale'
|
||||
? missions.snapshot
|
||||
: tasks.freshness === 'stale'
|
||||
? tasks.snapshot
|
||||
: null;
|
||||
const missingSections: string[] = [];
|
||||
if (missions.freshness === 'unavailable') missingSections.push('Missions');
|
||||
if (tasks.freshness === 'unavailable') missingSections.push('Tasks');
|
||||
|
||||
return (
|
||||
<div data-freshness={surface} className="flex min-h-screen flex-col px-4 py-6 sm:px-6">
|
||||
<div className="flex min-h-screen flex-col px-4 py-6 sm:px-6">
|
||||
<header className="mb-6 border-b px-1 pb-3">
|
||||
<nav className="mb-4 flex items-center gap-2 text-sm text-text-muted">
|
||||
<button
|
||||
@@ -220,64 +152,49 @@ function ProjectDetail({ id }: { id: string }): ReactElement {
|
||||
Projects
|
||||
</button>
|
||||
<span>/</span>
|
||||
<span className="text-text-primary">{project.data.name}</span>
|
||||
<span className="text-text-primary">{project.name}</span>
|
||||
</nav>
|
||||
|
||||
<div className="flex items-start justify-between gap-4">
|
||||
<div>
|
||||
<div className="flex items-center gap-3">
|
||||
<h1 className="text-2xl font-semibold text-text-primary">{project.data.name}</h1>
|
||||
<h1 className="text-2xl font-semibold text-text-primary">{project.name}</h1>
|
||||
<span
|
||||
className={cn(
|
||||
'rounded-full px-2 py-0.5 text-xs',
|
||||
projectStatusColors[project.data.status] ?? 'bg-gray-600/20 text-gray-400',
|
||||
projectStatusColors[project.status] ?? 'bg-gray-600/20 text-gray-400',
|
||||
)}
|
||||
>
|
||||
{project.data.status}
|
||||
{project.status}
|
||||
</span>
|
||||
</div>
|
||||
{project.data.description ? (
|
||||
<p className="mt-1 text-sm text-text-muted">{project.data.description}</p>
|
||||
{project.description ? (
|
||||
<p className="mt-1 text-sm text-text-muted">{project.description}</p>
|
||||
) : null}
|
||||
<p className="mt-2 text-xs text-text-muted">
|
||||
Created {new Date(project.data.createdAt).toLocaleDateString()} · Updated{' '}
|
||||
{new Date(project.data.updatedAt).toLocaleDateString()}
|
||||
Created {new Date(project.createdAt).toLocaleDateString()} · Updated{' '}
|
||||
{new Date(project.updatedAt).toLocaleDateString()}
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</header>
|
||||
|
||||
{staleSnapshot !== null ? (
|
||||
<div className="mb-6">
|
||||
<StaleDataNotice label={staleSnapshot} onRetry={retryAll} />
|
||||
</div>
|
||||
) : null}
|
||||
|
||||
{missingSections.length > 0 ? (
|
||||
<div className="mb-6">
|
||||
<PartialDataNotice missing={missingSections} onRetry={retryAll} />
|
||||
</div>
|
||||
) : null}
|
||||
|
||||
<div className="mb-6 grid grid-cols-2 gap-3 sm:grid-cols-4">
|
||||
<StatCard
|
||||
label="Tasks"
|
||||
value={projectTasks === null ? UNKNOWN_VERDICT : String(projectTasks.length)}
|
||||
/>
|
||||
<StatCard label="Tasks" value={String(tasks.length)} />
|
||||
<StatCard
|
||||
label="Done"
|
||||
value={verdictValue(tasksVerified, String(doneCount))}
|
||||
valueClass={tasksVerified ? 'text-success' : undefined}
|
||||
value={String(tasks.filter((task) => task.status === 'done').length)}
|
||||
valueClass="text-success"
|
||||
/>
|
||||
<StatCard
|
||||
label="In Progress"
|
||||
value={verdictValue(tasksVerified, String(inProgressCount))}
|
||||
valueClass={tasksVerified ? 'text-blue-400' : undefined}
|
||||
value={String(tasks.filter((task) => task.status === 'in-progress').length)}
|
||||
valueClass="text-blue-400"
|
||||
/>
|
||||
<StatCard
|
||||
label="Blocked"
|
||||
value={verdictValue(tasksVerified, String(blockedCount))}
|
||||
valueClass={tasksVerified && blockedCount > 0 ? 'text-error' : undefined}
|
||||
value={String(tasks.filter((task) => task.status === 'blocked').length)}
|
||||
valueClass={tasks.some((task) => task.status === 'blocked') ? 'text-error' : undefined}
|
||||
/>
|
||||
</div>
|
||||
|
||||
@@ -294,43 +211,23 @@ function ProjectDetail({ id }: { id: string }): ReactElement {
|
||||
</div>
|
||||
|
||||
{activeTab === 'overview' ? (
|
||||
<OverviewTab project={project.data} missions={projectMissions} tasks={projectTasks} />
|
||||
<OverviewTab project={project} missions={missions} tasks={tasks} />
|
||||
) : null}
|
||||
|
||||
{activeTab === 'tasks' ? (
|
||||
<div>
|
||||
{projectTasks === null ? (
|
||||
<UnavailableDataNotice
|
||||
title="Tasks"
|
||||
detail={describeFailure(tasks.failure)}
|
||||
onRetry={retryAll}
|
||||
<div className="mb-4">
|
||||
<TaskStatusSummary
|
||||
tasks={tasks}
|
||||
activeFilter={taskFilter}
|
||||
onFilterChange={setTaskFilter}
|
||||
/>
|
||||
) : (
|
||||
<>
|
||||
<div className="mb-4">
|
||||
<TaskStatusSummary
|
||||
tasks={projectTasks}
|
||||
activeFilter={taskFilter}
|
||||
onFilterChange={setTaskFilter}
|
||||
/>
|
||||
</div>
|
||||
<TaskListView tasks={filteredTasks} onTaskClick={setSelectedTask} />
|
||||
</>
|
||||
)}
|
||||
</div>
|
||||
<TaskListView tasks={filteredTasks} onTaskClick={setSelectedTask} />
|
||||
</div>
|
||||
) : null}
|
||||
|
||||
{activeTab === 'missions' ? (
|
||||
projectMissions === null ? (
|
||||
<UnavailableDataNotice
|
||||
title="Missions"
|
||||
detail={describeFailure(missions.failure)}
|
||||
onRetry={retryAll}
|
||||
/>
|
||||
) : (
|
||||
<MissionTimeline missions={projectMissions} />
|
||||
)
|
||||
) : null}
|
||||
{activeTab === 'missions' ? <MissionTimeline missions={missions} /> : null}
|
||||
|
||||
{activeTab === 'prd' && prdContent ? (
|
||||
<div className="rounded-lg border border-surface-border bg-surface-card p-6">
|
||||
@@ -351,26 +248,18 @@ function OverviewTab({
|
||||
tasks,
|
||||
}: {
|
||||
project: Project;
|
||||
missions: Mission[] | null;
|
||||
tasks: Task[] | null;
|
||||
missions: Mission[];
|
||||
tasks: Task[];
|
||||
}): ReactElement {
|
||||
const recentTasks =
|
||||
tasks === null
|
||||
? null
|
||||
: [...tasks]
|
||||
.sort(
|
||||
(left, right) =>
|
||||
new Date(right.updatedAt).getTime() - new Date(left.updatedAt).getTime(),
|
||||
)
|
||||
.slice(0, 5);
|
||||
const recentTasks = [...tasks]
|
||||
.sort((left, right) => new Date(right.updatedAt).getTime() - new Date(left.updatedAt).getTime())
|
||||
.slice(0, 5);
|
||||
|
||||
return (
|
||||
<div className="grid gap-6 lg:grid-cols-2">
|
||||
<section>
|
||||
<h2 className="mb-3 text-sm font-semibold text-text-secondary">Recent Tasks</h2>
|
||||
{recentTasks === null ? (
|
||||
<UnavailableDataNotice title="Tasks" />
|
||||
) : recentTasks.length === 0 ? (
|
||||
{recentTasks.length === 0 ? (
|
||||
<div className="rounded-lg border border-surface-border bg-surface-card p-4 text-center">
|
||||
<p className="text-sm text-text-muted">No tasks yet</p>
|
||||
</div>
|
||||
@@ -398,9 +287,7 @@ function OverviewTab({
|
||||
|
||||
<section>
|
||||
<h2 className="mb-3 text-sm font-semibold text-text-secondary">Missions</h2>
|
||||
{missions === null ? (
|
||||
<UnavailableDataNotice title="Missions" />
|
||||
) : missions.length === 0 ? (
|
||||
{missions.length === 0 ? (
|
||||
<div className="rounded-lg border border-surface-border bg-surface-card p-4 text-center">
|
||||
<p className="text-sm text-text-muted">No missions yet</p>
|
||||
</div>
|
||||
|
||||
@@ -51,7 +51,6 @@ afterEach(async () => {
|
||||
document.body.replaceChildren();
|
||||
root = null;
|
||||
apiMock.mockReset();
|
||||
sessionStorage.clear();
|
||||
});
|
||||
|
||||
async function renderProjectsPage(): Promise<ReturnType<typeof createMemoryRouter>> {
|
||||
@@ -72,22 +71,6 @@ async function renderProjectsPage(): Promise<ReturnType<typeof createMemoryRoute
|
||||
return router;
|
||||
}
|
||||
|
||||
function clickButtonByText(text: string): void {
|
||||
const button = [...container.querySelectorAll('button')].find((candidate) =>
|
||||
candidate.textContent?.includes(text),
|
||||
);
|
||||
if (!button) {
|
||||
throw new Error(`Button containing "${text}" not found`);
|
||||
}
|
||||
button.dispatchEvent(new MouseEvent('click', { bubbles: true }));
|
||||
}
|
||||
|
||||
async function flushAct(): Promise<void> {
|
||||
await act(async () => {
|
||||
await Promise.resolve();
|
||||
});
|
||||
}
|
||||
|
||||
describe('ProjectsPage', () => {
|
||||
it('shows a visible loading state while the project request is in flight', async () => {
|
||||
const deferred = createDeferred<typeof projectFixtures>();
|
||||
@@ -108,7 +91,7 @@ describe('ProjectsPage', () => {
|
||||
|
||||
const router = await renderProjectsPage();
|
||||
|
||||
expect(apiMock.mock.calls[0]?.[0]).toBe('/api/projects');
|
||||
expect(apiMock).toHaveBeenCalledWith('/api/projects');
|
||||
expect(container.textContent).toContain('Mosaic Stack');
|
||||
expect(container.textContent).toContain('Agent Runtime');
|
||||
|
||||
@@ -125,7 +108,7 @@ describe('ProjectsPage', () => {
|
||||
expect(container.textContent).toContain('Project detail target');
|
||||
});
|
||||
|
||||
it('renders the empty state only for a verified empty collection', async () => {
|
||||
it('renders the empty state when the API returns no projects', async () => {
|
||||
apiMock.mockResolvedValueOnce([]);
|
||||
|
||||
await renderProjectsPage();
|
||||
@@ -134,12 +117,9 @@ describe('ProjectsPage', () => {
|
||||
expect(container.textContent).toContain(
|
||||
'Projects will appear here when created via the gateway API',
|
||||
);
|
||||
expect(container.querySelector('[data-freshness]')?.getAttribute('data-freshness')).toBe(
|
||||
'current',
|
||||
);
|
||||
});
|
||||
|
||||
it('renders a failed fetch as an explicit unavailable state, never an empty collection', async () => {
|
||||
it('renders a visible alert when the projects request fails', async () => {
|
||||
apiMock.mockRejectedValueOnce(new Error('Projects are unavailable'));
|
||||
|
||||
await renderProjectsPage();
|
||||
@@ -147,51 +127,5 @@ describe('ProjectsPage', () => {
|
||||
const alert = container.querySelector('[role="alert"]');
|
||||
expect(alert).toBeTruthy();
|
||||
expect(alert?.textContent).toContain('Projects are unavailable');
|
||||
expect(alert?.textContent).toContain('not an empty result');
|
||||
|
||||
// Negative controls: no healthy empty state and no project cards render
|
||||
// from a failed fetch.
|
||||
expect(container.textContent).not.toContain('No projects yet');
|
||||
expect(container.textContent).not.toContain('Mosaic Stack');
|
||||
expect(container.querySelector('[data-freshness]')?.getAttribute('data-freshness')).toBe(
|
||||
'unavailable',
|
||||
);
|
||||
});
|
||||
|
||||
it('renders an auth failure as unavailable and recovers after retry', async () => {
|
||||
apiMock
|
||||
.mockRejectedValueOnce(Object.assign(new Error('Unauthorized'), { statusCode: 401 }))
|
||||
.mockResolvedValueOnce(projectFixtures);
|
||||
|
||||
await renderProjectsPage();
|
||||
|
||||
const alert = container.querySelector('[role="alert"]');
|
||||
expect(alert?.textContent).toContain('Unauthorized');
|
||||
expect(container.textContent).not.toContain('No projects yet');
|
||||
|
||||
await act(async () => {
|
||||
clickButtonByText('Retry');
|
||||
});
|
||||
await flushAct();
|
||||
|
||||
expect(container.querySelector('[role="alert"]')).toBeNull();
|
||||
expect(container.textContent).toContain('Mosaic Stack');
|
||||
expect(container.querySelector('[data-freshness]')?.getAttribute('data-freshness')).toBe(
|
||||
'current',
|
||||
);
|
||||
});
|
||||
|
||||
it('renders a schema-mismatched response as unavailable, never as data', async () => {
|
||||
apiMock.mockResolvedValueOnce({ results: projectFixtures });
|
||||
|
||||
await renderProjectsPage();
|
||||
|
||||
const alert = container.querySelector('[role="alert"]');
|
||||
expect(alert?.textContent).toContain('not an empty result');
|
||||
expect(container.textContent).not.toContain('Mosaic Stack');
|
||||
expect(container.textContent).not.toContain('No projects yet');
|
||||
expect(container.querySelector('[data-freshness]')?.getAttribute('data-freshness')).toBe(
|
||||
'unavailable',
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
@@ -1,51 +1,53 @@
|
||||
import { type ReactElement } from 'react';
|
||||
import { useEffect, useState, type ReactElement } from 'react';
|
||||
import { useNavigate } from 'react-router-dom';
|
||||
import { ProjectCard } from '@/components/projects/project-card';
|
||||
import { StaleDataNotice, UnavailableDataNotice } from '@/components/freshness/freshness-notices';
|
||||
import { api } from '@/lib/api';
|
||||
import type { Project } from '@/lib/types';
|
||||
import { useFreshCollection, describeFailure } from '@/lib/freshness/use-fresh-collection';
|
||||
import { validateProjectCollection } from '@/lib/freshness/validators';
|
||||
import { getErrorMessage } from './page-errors';
|
||||
|
||||
export function ProjectsPage(): ReactElement {
|
||||
const navigate = useNavigate();
|
||||
const projects = useFreshCollection<Project[]>({
|
||||
source: 'gateway:/api/projects',
|
||||
fetcher: (signal) => api<unknown>('/api/projects', { signal }),
|
||||
validate: validateProjectCollection,
|
||||
// Projects carry workspace identity (userId) that is only knowable from
|
||||
// the payload itself, so a restored entry cannot be scope-checked before
|
||||
// display. Conservative choice: no last-known restore for this surface;
|
||||
// cross-workspace switching is still invalidated at verification time.
|
||||
});
|
||||
const retry = (): void => {
|
||||
void projects.revalidate();
|
||||
};
|
||||
const [projects, setProjects] = useState<Project[]>([]);
|
||||
const [loading, setLoading] = useState(true);
|
||||
const [error, setError] = useState<string | null>(null);
|
||||
|
||||
useEffect(() => {
|
||||
let cancelled = false;
|
||||
|
||||
void api<Project[]>('/api/projects')
|
||||
.then((response) => {
|
||||
if (cancelled) return;
|
||||
setProjects(response);
|
||||
})
|
||||
.catch((caught: unknown) => {
|
||||
if (cancelled) return;
|
||||
setError(getErrorMessage(caught, 'Failed to load projects.'));
|
||||
})
|
||||
.finally(() => {
|
||||
if (cancelled) return;
|
||||
setLoading(false);
|
||||
});
|
||||
|
||||
return () => {
|
||||
cancelled = true;
|
||||
};
|
||||
}, []);
|
||||
|
||||
return (
|
||||
<div
|
||||
data-freshness={projects.freshness}
|
||||
className="flex min-h-screen flex-col px-4 py-6 sm:px-6"
|
||||
>
|
||||
<div className="flex min-h-screen flex-col px-4 py-6 sm:px-6">
|
||||
<header className="mb-6 border-b px-1 pb-3">
|
||||
<h1 className="text-2xl font-semibold">Projects</h1>
|
||||
</header>
|
||||
|
||||
{projects.freshness === 'stale' && projects.snapshot ? (
|
||||
<div className="mb-6">
|
||||
<StaleDataNotice label={projects.snapshot} onRetry={retry} />
|
||||
{error ? (
|
||||
<div role="alert" className="mb-6 rounded-lg border border-error/40 px-4 py-3 text-sm">
|
||||
{error}
|
||||
</div>
|
||||
) : null}
|
||||
|
||||
{projects.freshness === 'unknown' ? (
|
||||
{loading ? (
|
||||
<p className="py-8 text-center text-sm text-text-muted">Loading projects...</p>
|
||||
) : projects.freshness === 'unavailable' ? (
|
||||
<UnavailableDataNotice
|
||||
title="Projects"
|
||||
detail={describeFailure(projects.failure)}
|
||||
onRetry={retry}
|
||||
/>
|
||||
) : projects.data !== null && projects.data.length === 0 ? (
|
||||
) : projects.length === 0 ? (
|
||||
<div className="py-12 text-center">
|
||||
<h2 className="text-lg font-medium text-text-secondary">No projects yet</h2>
|
||||
<p className="mt-1 text-sm text-text-muted">
|
||||
@@ -54,7 +56,7 @@ export function ProjectsPage(): ReactElement {
|
||||
</div>
|
||||
) : (
|
||||
<div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
|
||||
{(projects.data ?? []).map((project) => (
|
||||
{projects.map((project) => (
|
||||
<ProjectCard
|
||||
key={project.id}
|
||||
project={project}
|
||||
|
||||
@@ -3,9 +3,6 @@ import { createRoot, type Root } from 'react-dom/client';
|
||||
import { createMemoryRouter, RouterProvider, type RouteObject } from 'react-router-dom';
|
||||
import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from 'vitest';
|
||||
import { taskFixtures } from './page-fixtures';
|
||||
import { acceptSnapshot, DEFAULT_FRESHNESS_POLICY } from '@/lib/freshness/model';
|
||||
import { writeSnapshotCache } from '@/lib/freshness/snapshot-cache';
|
||||
import { validateTaskCollection } from '@/lib/freshness/validators';
|
||||
|
||||
const { apiMock } = vi.hoisted(() => ({
|
||||
apiMock: vi.fn(),
|
||||
@@ -51,7 +48,6 @@ afterEach(async () => {
|
||||
document.body.replaceChildren();
|
||||
root = null;
|
||||
apiMock.mockReset();
|
||||
sessionStorage.clear();
|
||||
});
|
||||
|
||||
async function renderTasksPage(): Promise<void> {
|
||||
@@ -76,13 +72,6 @@ function clickButtonByText(text: string): void {
|
||||
button.dispatchEvent(new MouseEvent('click', { bubbles: true }));
|
||||
}
|
||||
|
||||
/** Flush pending promise callbacks inside the act environment. */
|
||||
async function flushAct(): Promise<void> {
|
||||
await act(async () => {
|
||||
await Promise.resolve();
|
||||
});
|
||||
}
|
||||
|
||||
describe('TasksPage', () => {
|
||||
it('shows a visible loading state before the tasks request settles', async () => {
|
||||
const deferred = createDeferred<typeof taskFixtures>();
|
||||
@@ -143,7 +132,7 @@ describe('TasksPage', () => {
|
||||
expect(container.textContent).toContain('Wire list and kanban modal interactions');
|
||||
});
|
||||
|
||||
it('renders a failed fetch as an explicit unavailable state, never an empty healthy board', async () => {
|
||||
it('renders a visible alert when the tasks request fails', async () => {
|
||||
apiMock.mockRejectedValueOnce(new Error('Tasks request failed'));
|
||||
|
||||
await renderTasksPage();
|
||||
@@ -151,80 +140,5 @@ describe('TasksPage', () => {
|
||||
const alert = container.querySelector('[role="alert"]');
|
||||
expect(alert).toBeTruthy();
|
||||
expect(alert?.textContent).toContain('Tasks request failed');
|
||||
expect(alert?.textContent).toContain('not an empty result');
|
||||
|
||||
// Negative controls: no board, no healthy empty-state markers, and the
|
||||
// surface is marked unavailable rather than current.
|
||||
expect(container.textContent).not.toContain('Not Started');
|
||||
expect(container.textContent).not.toContain('No tasks');
|
||||
expect(container.querySelector('[data-freshness]')?.getAttribute('data-freshness')).toBe(
|
||||
'unavailable',
|
||||
);
|
||||
});
|
||||
|
||||
it('recovers to a current board after retrying a failed fetch', async () => {
|
||||
apiMock
|
||||
.mockRejectedValueOnce(new Error('Tasks request failed'))
|
||||
.mockResolvedValueOnce(taskFixtures);
|
||||
|
||||
await renderTasksPage();
|
||||
expect(container.querySelector('[role="alert"]')).toBeTruthy();
|
||||
|
||||
await act(async () => {
|
||||
clickButtonByText('Retry');
|
||||
});
|
||||
await flushAct();
|
||||
|
||||
expect(container.querySelector('[role="alert"]')).toBeNull();
|
||||
expect(container.textContent).toContain('Not Started');
|
||||
expect(container.querySelector('[data-freshness]')?.getAttribute('data-freshness')).toBe(
|
||||
'current',
|
||||
);
|
||||
});
|
||||
|
||||
it('labels restored last-known data as stale with source, version, and age until verified', async () => {
|
||||
// Seed a last-known snapshot fetched five minutes ago; the page must
|
||||
// render it only under an explicit staleness label while the fetch is
|
||||
// still in flight.
|
||||
const restored = acceptSnapshot({
|
||||
value: taskFixtures,
|
||||
validate: validateTaskCollection,
|
||||
previous: null,
|
||||
policy: DEFAULT_FRESHNESS_POLICY,
|
||||
source: 'gateway:/api/tasks',
|
||||
now: Date.now() - 5 * 60_000,
|
||||
});
|
||||
if (restored.outcome !== 'accepted') throw new Error('fixture setup failed');
|
||||
writeSnapshotCache('tasks', restored.snapshot);
|
||||
|
||||
const deferred = createDeferred<typeof taskFixtures>();
|
||||
apiMock.mockReturnValueOnce(deferred.promise);
|
||||
|
||||
await renderTasksPage();
|
||||
|
||||
expect(container.querySelector('[data-freshness]')?.getAttribute('data-freshness')).toBe(
|
||||
'stale',
|
||||
);
|
||||
const banner = container.querySelector('[role="status"]');
|
||||
expect(banner?.textContent).toContain('last-known');
|
||||
expect(banner?.textContent).toContain('may be out of date');
|
||||
expect(banner?.textContent).toContain('gateway:/api/tasks');
|
||||
expect(banner?.textContent).toContain('snapshot v1');
|
||||
expect(banner?.textContent).toContain('5m ago');
|
||||
|
||||
// Last-known data still renders as situational awareness under the label.
|
||||
expect(container.textContent).toContain('Route /tasks');
|
||||
expect(container.textContent).not.toContain('Loading tasks...');
|
||||
|
||||
// Verification lands: the banner clears and the surface becomes current.
|
||||
await act(async () => {
|
||||
deferred.resolve(taskFixtures);
|
||||
await deferred.promise;
|
||||
});
|
||||
|
||||
expect(container.querySelector('[role="status"]')).toBeNull();
|
||||
expect(container.querySelector('[data-freshness]')?.getAttribute('data-freshness')).toBe(
|
||||
'current',
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
@@ -1,32 +1,45 @@
|
||||
import { useState, type ReactElement } from 'react';
|
||||
import { useEffect, useState, type ReactElement } from 'react';
|
||||
import { KanbanBoard } from '@/components/tasks/kanban-board';
|
||||
import { TaskDetailModal } from '@/components/tasks/task-detail-modal';
|
||||
import { TaskListView } from '@/components/tasks/task-list-view';
|
||||
import { StaleDataNotice, UnavailableDataNotice } from '@/components/freshness/freshness-notices';
|
||||
import { api } from '@/lib/api';
|
||||
import { cn } from '@/lib/cn';
|
||||
import type { Task } from '@/lib/types';
|
||||
import { useFreshCollection, describeFailure } from '@/lib/freshness/use-fresh-collection';
|
||||
import { validateTaskCollection } from '@/lib/freshness/validators';
|
||||
import { getErrorMessage } from './page-errors';
|
||||
|
||||
type ViewMode = 'list' | 'kanban';
|
||||
|
||||
export function TasksPage(): ReactElement {
|
||||
const tasks = useFreshCollection<Task[]>({
|
||||
source: 'gateway:/api/tasks',
|
||||
fetcher: (signal) => api<unknown>('/api/tasks', { signal }),
|
||||
validate: validateTaskCollection,
|
||||
cacheKey: 'tasks',
|
||||
});
|
||||
const [tasks, setTasks] = useState<Task[]>([]);
|
||||
const [view, setView] = useState<ViewMode>('kanban');
|
||||
const [loading, setLoading] = useState(true);
|
||||
const [error, setError] = useState<string | null>(null);
|
||||
const [selectedTask, setSelectedTask] = useState<Task | null>(null);
|
||||
|
||||
const retry = (): void => {
|
||||
void tasks.revalidate();
|
||||
};
|
||||
useEffect(() => {
|
||||
let cancelled = false;
|
||||
|
||||
void api<Task[]>('/api/tasks')
|
||||
.then((response) => {
|
||||
if (cancelled) return;
|
||||
setTasks(response);
|
||||
})
|
||||
.catch((caught: unknown) => {
|
||||
if (cancelled) return;
|
||||
setError(getErrorMessage(caught, 'Failed to load tasks.'));
|
||||
})
|
||||
.finally(() => {
|
||||
if (cancelled) return;
|
||||
setLoading(false);
|
||||
});
|
||||
|
||||
return () => {
|
||||
cancelled = true;
|
||||
};
|
||||
}, []);
|
||||
|
||||
return (
|
||||
<div data-freshness={tasks.freshness} className="flex min-h-screen flex-col px-4 py-6 sm:px-6">
|
||||
<div className="flex min-h-screen flex-col px-4 py-6 sm:px-6">
|
||||
<header className="mb-6 flex items-center justify-between gap-4 border-b px-1 pb-3">
|
||||
<h1 className="text-2xl font-semibold">Tasks</h1>
|
||||
<div className="flex rounded-lg border border-surface-border">
|
||||
@@ -57,24 +70,18 @@ export function TasksPage(): ReactElement {
|
||||
</div>
|
||||
</header>
|
||||
|
||||
{tasks.freshness === 'stale' && tasks.snapshot ? (
|
||||
<div className="mb-6">
|
||||
<StaleDataNotice label={tasks.snapshot} onRetry={retry} />
|
||||
{error ? (
|
||||
<div role="alert" className="mb-6 rounded-lg border border-error/40 px-4 py-3 text-sm">
|
||||
{error}
|
||||
</div>
|
||||
) : null}
|
||||
|
||||
{tasks.freshness === 'unknown' ? (
|
||||
{loading ? (
|
||||
<p className="py-8 text-center text-sm text-text-muted">Loading tasks...</p>
|
||||
) : tasks.freshness === 'unavailable' ? (
|
||||
<UnavailableDataNotice
|
||||
title="Tasks"
|
||||
detail={describeFailure(tasks.failure)}
|
||||
onRetry={retry}
|
||||
/>
|
||||
) : view === 'kanban' ? (
|
||||
<KanbanBoard tasks={tasks.data ?? []} onTaskClick={setSelectedTask} />
|
||||
<KanbanBoard tasks={tasks} onTaskClick={setSelectedTask} />
|
||||
) : (
|
||||
<TaskListView tasks={tasks.data ?? []} onTaskClick={setSelectedTask} />
|
||||
<TaskListView tasks={tasks} onTaskClick={setSelectedTask} />
|
||||
)}
|
||||
|
||||
{selectedTask ? (
|
||||
|
||||
@@ -34,6 +34,7 @@ export default tseslint.config(
|
||||
'packages/storage/vitest.config.ts',
|
||||
'packages/mosaic/vitest.config.ts',
|
||||
'packages/mosaic/__tests__/*.ts',
|
||||
'packages/forge/__tests__/*.ts',
|
||||
'tools/federation-harness/*.ts',
|
||||
],
|
||||
},
|
||||
|
||||
@@ -539,3 +539,43 @@ Not every brief needs full Board of Directors review. The classification system
|
||||
### Backward compatibility
|
||||
|
||||
Existing briefs without a `class` field are auto-classified. The default (no matching keywords) is `strategic`, so all existing runs get the full pipeline unless keywords trigger `technical`.
|
||||
|
||||
---
|
||||
|
||||
## Fail-Closed Execution & Explicit Simulation (SDLC-D-035)
|
||||
|
||||
**Added:** 2026-08-17
|
||||
|
||||
Forge fails closed when a required capability is missing. It never runs a
|
||||
pipeline with a stub executor and reports success.
|
||||
|
||||
### Normal mode (default)
|
||||
|
||||
- No task executor wired → the CLI exits nonzero with the typed capability
|
||||
error `FORGE_NO_EXECUTOR`. No run is created.
|
||||
- A stage whose gate is approval-based (board approval, planning approvals,
|
||||
remediation re-review, discovery/analysis attestations) records a typed
|
||||
`waiting-for-authority` stage result and raises `FORGE_AUTHORITY_REQUIRED`.
|
||||
It never passes vacuously.
|
||||
- A stage whose gate requires an unwired provider (AI reviewer, CI pipeline)
|
||||
records a typed `blocked` stage result and raises `FORGE_NO_REVIEWER` /
|
||||
`FORGE_NO_CI_PIPELINE`. The synthetic echo-review approval in `06-review`
|
||||
and all vacuous `true` gates were removed.
|
||||
|
||||
### Explicit simulation (`--simulate`)
|
||||
|
||||
Opts into stub/synthetic execution. Every stage result, every gate result, and
|
||||
the run manifest carry the distinct typed status `simulated` (manifest also
|
||||
records `mode: "simulated"`). `simulated` is a non-satisfying outcome:
|
||||
`isSatisfyingOutcome()` and all completion/gate consumers treat only `passed`
|
||||
as satisfying. The CLI exits 0 for a simulated run only because the caller
|
||||
explicitly passed `--simulate`, and prints a loud SIMULATED banner.
|
||||
|
||||
### Typed outcome model
|
||||
|
||||
Every gate/task outcome is one of the closed set
|
||||
`passed | failed | blocked | error | waiting-for-authority | simulated |
|
||||
not-applicable`, with the reason recorded on the stage status and each gate
|
||||
result in `manifest.json`. Missing implementations, missing gate evidence,
|
||||
unknown stages, process errors, and timeouts map to fail-closed members —
|
||||
never to `passed`.
|
||||
|
||||
@@ -0,0 +1,319 @@
|
||||
import fs from 'node:fs';
|
||||
import os from 'node:os';
|
||||
import path from 'node:path';
|
||||
import { describe, it, expect, beforeEach, afterEach } from 'vitest';
|
||||
|
||||
import { generateBoardTasks } from '../src/board-tasks.js';
|
||||
import { STAGE_SPECS } from '../src/constants.js';
|
||||
import { ForgeCapabilityError } from '../src/errors.js';
|
||||
import {
|
||||
evaluateStageGates,
|
||||
gateLabel,
|
||||
isCommandGate,
|
||||
isSatisfyingOutcome,
|
||||
} from '../src/outcomes.js';
|
||||
import { loadManifest, runPipeline } from '../src/pipeline-runner.js';
|
||||
import type { ForgeTask, ForgeTaskResult, TaskExecutor } from '../src/types.js';
|
||||
|
||||
/**
|
||||
* Mock real executor that returns typed results.
|
||||
*
|
||||
* Command gates are "verified" by the mock so normal-mode runs can pass
|
||||
* mechanically gated stages; authority/provider gates are never reported
|
||||
* because they have no mechanical implementation.
|
||||
*/
|
||||
function createTypedExecutor(options?: {
|
||||
failStage?: string;
|
||||
gateOutcomes?: Record<string, 'passed' | 'failed' | 'simulated' | 'error' | 'blocked'>;
|
||||
}): TaskExecutor & { submittedTasks: ForgeTask[] } {
|
||||
const submittedTasks: ForgeTask[] = [];
|
||||
return {
|
||||
submittedTasks,
|
||||
async submitTask(task: ForgeTask) {
|
||||
submittedTasks.push(task);
|
||||
},
|
||||
async waitForCompletion(taskId: string): Promise<ForgeTaskResult> {
|
||||
const task = submittedTasks.find((t) => t.id === taskId);
|
||||
const stageName = task?.metadata?.['stageName'] as string | undefined;
|
||||
|
||||
if (options?.failStage && stageName === options.failStage) {
|
||||
return {
|
||||
task_id: taskId,
|
||||
outcome: 'failed',
|
||||
reason: 'mock task failure',
|
||||
completed_at: new Date().toISOString(),
|
||||
exit_code: 1,
|
||||
gate_results: [],
|
||||
};
|
||||
}
|
||||
|
||||
const gateResults = (task?.qualityGates ?? [])
|
||||
.filter((gate) => isCommandGate(gate))
|
||||
.map((gate) => {
|
||||
const label = gateLabel(gate);
|
||||
const outcome = options?.gateOutcomes?.[label] ?? 'passed';
|
||||
return {
|
||||
gate: label,
|
||||
outcome,
|
||||
reason: outcome === 'passed' ? 'mock verified' : `mock gate outcome: ${outcome}`,
|
||||
};
|
||||
});
|
||||
|
||||
return {
|
||||
task_id: taskId,
|
||||
outcome: 'passed',
|
||||
reason: 'mock verified',
|
||||
completed_at: new Date().toISOString(),
|
||||
exit_code: 0,
|
||||
gate_results: gateResults,
|
||||
};
|
||||
},
|
||||
async getTaskStatus() {
|
||||
return 'completed' as const;
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
describe('fail-closed: no executor wired', () => {
|
||||
let tmpDir: string;
|
||||
let briefPath: string;
|
||||
|
||||
beforeEach(() => {
|
||||
tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'forge-failclosed-'));
|
||||
briefPath = path.join(tmpDir, 'brief.md');
|
||||
fs.writeFileSync(briefPath, '# Fix bug\n\nA bugfix for lint cleanup.');
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
fs.rmSync(tmpDir, { recursive: true, force: true });
|
||||
});
|
||||
|
||||
it('throws a typed FORGE_NO_EXECUTOR capability error without --simulate', async () => {
|
||||
await expect(
|
||||
runPipeline(briefPath, tmpDir, {
|
||||
// no executor, no simulate — must fail closed, never run with a stub
|
||||
stages: ['00-intake'],
|
||||
}),
|
||||
).rejects.toMatchObject({
|
||||
name: 'ForgeCapabilityError',
|
||||
code: 'FORGE_NO_EXECUTOR',
|
||||
capability: 'task-executor',
|
||||
});
|
||||
});
|
||||
|
||||
it('does not create a run directory when failing closed on a missing executor', async () => {
|
||||
try {
|
||||
await runPipeline(briefPath, tmpDir, { stages: ['00-intake'] });
|
||||
} catch {
|
||||
// expected
|
||||
}
|
||||
expect(fs.existsSync(path.join(tmpDir, '.forge', 'runs'))).toBe(false);
|
||||
});
|
||||
|
||||
it('completes with every result typed simulated when simulate is set', async () => {
|
||||
const result = await runPipeline(briefPath, tmpDir, {
|
||||
simulate: true,
|
||||
stages: ['00-intake', '00b-discovery', '02-planning-1', '06-review'],
|
||||
});
|
||||
|
||||
expect(result.manifest.mode).toBe('simulated');
|
||||
expect(result.manifest.status).toBe('simulated');
|
||||
|
||||
for (const stage of result.stages) {
|
||||
const stageStatus = result.manifest.stages[stage];
|
||||
expect(stageStatus?.status, `stage ${stage}`).toBe('simulated');
|
||||
expect(stageStatus?.status, `stage ${stage}`).not.toBe('passed');
|
||||
expect(stageStatus?.reason, `stage ${stage}`).toBeTruthy();
|
||||
for (const gateResult of stageStatus?.gateResults ?? []) {
|
||||
expect(gateResult.outcome, `gate ${gateResult.gate} of ${stage}`).toBe('simulated');
|
||||
expect(gateResult.outcome, `gate ${gateResult.gate} of ${stage}`).not.toBe('passed');
|
||||
}
|
||||
}
|
||||
|
||||
// The persisted manifest agrees.
|
||||
const persisted = loadManifest(result.runDir);
|
||||
expect(persisted.mode).toBe('simulated');
|
||||
expect(persisted.status).toBe('simulated');
|
||||
expect(persisted.stages['02-planning-1']?.status).toBe('simulated');
|
||||
});
|
||||
});
|
||||
|
||||
describe('fail-closed: typed outcome model', () => {
|
||||
it('only passed satisfies the gate/dependency predicate', () => {
|
||||
expect(isSatisfyingOutcome('passed')).toBe(true);
|
||||
expect(isSatisfyingOutcome('failed')).toBe(false);
|
||||
expect(isSatisfyingOutcome('blocked')).toBe(false);
|
||||
expect(isSatisfyingOutcome('error')).toBe(false);
|
||||
expect(isSatisfyingOutcome('waiting-for-authority')).toBe(false);
|
||||
expect(isSatisfyingOutcome('simulated')).toBe(false);
|
||||
expect(isSatisfyingOutcome('not-applicable')).toBe(false);
|
||||
});
|
||||
|
||||
it('a simulated gate result cannot satisfy the stage gate evaluation', () => {
|
||||
const evaluation = evaluateStageGates('05-coding', STAGE_SPECS['05-coding']!.qualityGates, {
|
||||
task_id: 'FORGE-x-05',
|
||||
outcome: 'passed',
|
||||
reason: 'executor claims success',
|
||||
completed_at: new Date().toISOString(),
|
||||
exit_code: 0,
|
||||
gate_results: [{ gate: 'pnpm lint', outcome: 'simulated', reason: 'simulated gate' }],
|
||||
});
|
||||
expect(isSatisfyingOutcome(evaluation.outcome)).toBe(false);
|
||||
expect(evaluation.outcome).toBe('error');
|
||||
});
|
||||
|
||||
it('a simulated task outcome cannot satisfy evaluation in normal mode', () => {
|
||||
const evaluation = evaluateStageGates('00-intake', [], {
|
||||
task_id: 'FORGE-x-00',
|
||||
outcome: 'simulated',
|
||||
reason: 'executor reported simulated',
|
||||
completed_at: new Date().toISOString(),
|
||||
exit_code: 0,
|
||||
gate_results: [],
|
||||
});
|
||||
expect(isSatisfyingOutcome(evaluation.outcome)).toBe(false);
|
||||
});
|
||||
|
||||
it('a missing gate result blocks the stage instead of passing vacuously', () => {
|
||||
const evaluation = evaluateStageGates('05-coding', STAGE_SPECS['05-coding']!.qualityGates, {
|
||||
task_id: 'FORGE-x-05',
|
||||
outcome: 'passed',
|
||||
reason: 'executor claims success',
|
||||
completed_at: new Date().toISOString(),
|
||||
exit_code: 0,
|
||||
gate_results: [],
|
||||
});
|
||||
expect(evaluation.outcome).toBe('blocked');
|
||||
});
|
||||
});
|
||||
|
||||
describe('fail-closed: authority and provider gates', () => {
|
||||
let tmpDir: string;
|
||||
let briefPath: string;
|
||||
|
||||
beforeEach(() => {
|
||||
tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'forge-authority-'));
|
||||
briefPath = path.join(tmpDir, 'brief.md');
|
||||
fs.writeFileSync(briefPath, '# Fix bug\n\nA bugfix for lint cleanup.');
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
fs.rmSync(tmpDir, { recursive: true, force: true });
|
||||
});
|
||||
|
||||
it.each(['02-planning-1', '03-planning-2', '04-planning-3', '07-remediate'])(
|
||||
'planning/remediation stage %s yields waiting-for-authority (not passed) in normal mode',
|
||||
async (stage) => {
|
||||
const executor = createTypedExecutor();
|
||||
let runDir: string | undefined;
|
||||
|
||||
try {
|
||||
await runPipeline(briefPath, tmpDir, {
|
||||
executor,
|
||||
stages: [stage as string],
|
||||
});
|
||||
expect.unreachable('runPipeline should have failed closed');
|
||||
} catch (err) {
|
||||
expect(err).toBeInstanceOf(ForgeCapabilityError);
|
||||
expect((err as ForgeCapabilityError).code).toBe('FORGE_AUTHORITY_REQUIRED');
|
||||
runDir = path.join(tmpDir, '.forge', 'runs');
|
||||
}
|
||||
|
||||
const runIds = fs.readdirSync(runDir!);
|
||||
expect(runIds).toHaveLength(1);
|
||||
const manifest = loadManifest(path.join(runDir!, runIds[0]!));
|
||||
expect(manifest.stages[stage]?.status).toBe('waiting-for-authority');
|
||||
expect(manifest.stages[stage]?.status).not.toBe('passed');
|
||||
expect(manifest.status).toBe('waiting-for-authority');
|
||||
},
|
||||
);
|
||||
|
||||
it('review stage fails closed with a typed FORGE_NO_REVIEWER error in normal mode', async () => {
|
||||
const executor = createTypedExecutor();
|
||||
|
||||
try {
|
||||
await runPipeline(briefPath, tmpDir, {
|
||||
executor,
|
||||
stages: ['06-review'],
|
||||
});
|
||||
expect.unreachable('runPipeline should have failed closed');
|
||||
} catch (err) {
|
||||
expect(err).toBeInstanceOf(ForgeCapabilityError);
|
||||
expect((err as ForgeCapabilityError).code).toBe('FORGE_NO_REVIEWER');
|
||||
expect((err as ForgeCapabilityError).capability).toBe('reviewer');
|
||||
}
|
||||
|
||||
const runsDir = path.join(tmpDir, '.forge', 'runs');
|
||||
const runIds = fs.readdirSync(runsDir);
|
||||
const manifest = loadManifest(path.join(runsDir, runIds[0]!));
|
||||
expect(manifest.stages['06-review']?.status).toBe('blocked');
|
||||
expect(manifest.stages['06-review']?.status).not.toBe('passed');
|
||||
expect(manifest.status).toBe('failed');
|
||||
});
|
||||
|
||||
it('review stage produces simulated results under --simulate', async () => {
|
||||
const result = await runPipeline(briefPath, tmpDir, {
|
||||
simulate: true,
|
||||
stages: ['06-review'],
|
||||
});
|
||||
|
||||
expect(result.manifest.mode).toBe('simulated');
|
||||
expect(result.manifest.stages['06-review']?.status).toBe('simulated');
|
||||
for (const gateResult of result.manifest.stages['06-review']?.gateResults ?? []) {
|
||||
expect(gateResult.outcome).toBe('simulated');
|
||||
}
|
||||
});
|
||||
|
||||
it('deploy stage fails closed without a wired ci-pipeline provider in normal mode', async () => {
|
||||
const executor = createTypedExecutor();
|
||||
|
||||
await expect(
|
||||
runPipeline(briefPath, tmpDir, {
|
||||
executor,
|
||||
stages: ['09-deploy'],
|
||||
}),
|
||||
).rejects.toMatchObject({
|
||||
name: 'ForgeCapabilityError',
|
||||
code: 'FORGE_NO_CI_PIPELINE',
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe('fail-closed: no vacuous gate commands remain', () => {
|
||||
it('stage constants contain no echo/synthetic-approval, vacuous true, or empty gate commands', () => {
|
||||
for (const [stageName, spec] of Object.entries(STAGE_SPECS)) {
|
||||
for (const gate of spec.qualityGates) {
|
||||
const serialized = JSON.stringify(gate);
|
||||
// The echo-review synthetic approval must be gone.
|
||||
expect(serialized, `stage ${stageName} gate ${serialized}`).not.toContain('echo');
|
||||
expect(serialized, `stage ${stageName} gate ${serialized}`).not.toMatch(/"verdict"\s*:/);
|
||||
expect(serialized, `stage ${stageName} gate ${serialized}`).not.toMatch(
|
||||
/"summary"\s*:\s*"review-pass"/,
|
||||
);
|
||||
// No vacuous literal `true` gate.
|
||||
expect(gate, `stage ${stageName}`).not.toBe('true');
|
||||
// Command gates must carry a real, non-empty command.
|
||||
if (isCommandGate(gate)) {
|
||||
const command = typeof gate === 'string' ? gate : gate.command;
|
||||
expect(command.trim().length, `stage ${stageName} gate ${serialized}`).toBeGreaterThan(0);
|
||||
}
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
it('board tasks contain no vacuous true gates', () => {
|
||||
const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'forge-board-gates-'));
|
||||
try {
|
||||
const tasks = generateBoardTasks('# Brief', [], tmpDir, 'BOARD-TEST');
|
||||
for (const task of tasks) {
|
||||
for (const gate of task.qualityGates) {
|
||||
expect(gate, `task ${task.id}`).not.toBe('true');
|
||||
const serialized = JSON.stringify(gate);
|
||||
expect(serialized, `task ${task.id} gate ${serialized}`).not.toContain('echo');
|
||||
}
|
||||
}
|
||||
} finally {
|
||||
fs.rmSync(tmpDir, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
});
|
||||
@@ -12,10 +12,10 @@ import {
|
||||
resumePipeline,
|
||||
getPipelineStatus,
|
||||
} from '../src/pipeline-runner.js';
|
||||
import type { ForgeTask, RunManifest, TaskExecutor } from '../src/types.js';
|
||||
import type { TaskResult } from '@mosaicstack/macp';
|
||||
import type { ForgeTask, ForgeTaskResult, RunManifest, TaskExecutor } from '../src/types.js';
|
||||
import { gateLabel, isCommandGate } from '../src/outcomes.js';
|
||||
|
||||
/** Mock TaskExecutor that records submitted tasks and returns success. */
|
||||
/** Mock TaskExecutor that records submitted tasks and returns typed results. */
|
||||
function createMockExecutor(options?: {
|
||||
failStage?: string;
|
||||
}): TaskExecutor & { submittedTasks: ForgeTask[] } {
|
||||
@@ -25,7 +25,7 @@ function createMockExecutor(options?: {
|
||||
async submitTask(task: ForgeTask) {
|
||||
submittedTasks.push(task);
|
||||
},
|
||||
async waitForCompletion(taskId: string): Promise<TaskResult> {
|
||||
async waitForCompletion(taskId: string): Promise<ForgeTaskResult> {
|
||||
const failStage = options?.failStage;
|
||||
const task = submittedTasks.find((t) => t.id === taskId);
|
||||
const stageName = task?.metadata?.['stageName'] as string | undefined;
|
||||
@@ -33,7 +33,8 @@ function createMockExecutor(options?: {
|
||||
if (failStage && stageName === failStage) {
|
||||
return {
|
||||
task_id: taskId,
|
||||
status: 'failed',
|
||||
outcome: 'failed',
|
||||
reason: 'mock task failure',
|
||||
completed_at: new Date().toISOString(),
|
||||
exit_code: 1,
|
||||
gate_results: [],
|
||||
@@ -41,10 +42,17 @@ function createMockExecutor(options?: {
|
||||
}
|
||||
return {
|
||||
task_id: taskId,
|
||||
status: 'completed',
|
||||
outcome: 'passed',
|
||||
reason: 'mock verified',
|
||||
completed_at: new Date().toISOString(),
|
||||
exit_code: 0,
|
||||
gate_results: [],
|
||||
gate_results: (task?.qualityGates ?? [])
|
||||
.filter((gate) => isCommandGate(gate))
|
||||
.map((gate) => ({
|
||||
gate: gateLabel(gate),
|
||||
outcome: 'passed' as const,
|
||||
reason: 'mock verified',
|
||||
})),
|
||||
};
|
||||
},
|
||||
async getTaskStatus() {
|
||||
@@ -156,12 +164,13 @@ describe('runPipeline', () => {
|
||||
const executor = createMockExecutor();
|
||||
const result = await runPipeline(briefPath, tmpDir, {
|
||||
executor,
|
||||
stages: ['00-intake', '00b-discovery'],
|
||||
stages: ['00-intake', '05-coding'],
|
||||
});
|
||||
|
||||
expect(result.runId).toMatch(/^\d{8}-\d{6}$/);
|
||||
expect(result.stages).toEqual(['00-intake', '00b-discovery']);
|
||||
expect(result.stages).toEqual(['00-intake', '05-coding']);
|
||||
expect(result.manifest.status).toBe('completed');
|
||||
expect(result.manifest.mode).toBe('normal');
|
||||
expect(executor.submittedTasks).toHaveLength(2);
|
||||
});
|
||||
|
||||
@@ -180,12 +189,17 @@ describe('runPipeline', () => {
|
||||
const executor = createMockExecutor();
|
||||
const result = await runPipeline(briefPath, tmpDir, {
|
||||
executor,
|
||||
stages: ['00-intake', '00b-discovery'],
|
||||
stages: ['00-intake', '05-coding'],
|
||||
});
|
||||
|
||||
const manifest = loadManifest(result.runDir);
|
||||
expect(manifest.stages['00-intake']?.status).toBe('passed');
|
||||
expect(manifest.stages['00b-discovery']?.status).toBe('passed');
|
||||
expect(manifest.stages['05-coding']?.status).toBe('passed');
|
||||
expect(manifest.stages['05-coding']?.gateResults?.map((g) => g.outcome)).toEqual([
|
||||
'passed',
|
||||
'passed',
|
||||
'passed',
|
||||
]);
|
||||
});
|
||||
|
||||
it('respects CLI class override', async () => {
|
||||
@@ -215,7 +229,7 @@ describe('runPipeline', () => {
|
||||
const executor = createMockExecutor();
|
||||
await runPipeline(briefPath, tmpDir, {
|
||||
executor,
|
||||
stages: ['00-intake', '00b-discovery', '02-planning-1'],
|
||||
stages: ['00-intake', '05-coding', '08-test'],
|
||||
});
|
||||
|
||||
expect(executor.submittedTasks[0]!.dependsOn).toBeUndefined();
|
||||
@@ -224,14 +238,14 @@ describe('runPipeline', () => {
|
||||
});
|
||||
|
||||
it('handles stage failure', async () => {
|
||||
const executor = createMockExecutor({ failStage: '00b-discovery' });
|
||||
const executor = createMockExecutor({ failStage: '05-coding' });
|
||||
|
||||
await expect(
|
||||
runPipeline(briefPath, tmpDir, {
|
||||
executor,
|
||||
stages: ['00-intake', '00b-discovery'],
|
||||
stages: ['00-intake', '05-coding'],
|
||||
}),
|
||||
).rejects.toThrow('Stage 00b-discovery failed');
|
||||
).rejects.toThrow('Stage 05-coding failed');
|
||||
});
|
||||
|
||||
it('marks manifest as failed on stage failure', async () => {
|
||||
@@ -270,30 +284,143 @@ describe('resumePipeline', () => {
|
||||
fs.rmSync(tmpDir, { recursive: true, force: true });
|
||||
});
|
||||
|
||||
it('resumes from first incomplete stage', async () => {
|
||||
// First run fails on discovery
|
||||
const executor1 = createMockExecutor({ failStage: '00b-discovery' });
|
||||
let runDir: string;
|
||||
it('resumes from first incomplete stage and fails closed at the next provider gate', async () => {
|
||||
// Simulate a run whose authority stages were approved out-of-band
|
||||
// (recorded as passed) and whose coding stage failed mechanically.
|
||||
const runId = '20260101-000000';
|
||||
const runDir = path.join(tmpDir, '.forge', 'runs', runId);
|
||||
fs.mkdirSync(runDir, { recursive: true });
|
||||
const passed = { status: 'passed' as const, startedAt: '2026-01-01T00:00:00Z' };
|
||||
saveManifest(runDir, {
|
||||
runId,
|
||||
brief: briefPath,
|
||||
codebase: tmpDir,
|
||||
briefClass: 'hotfix',
|
||||
classSource: 'frontmatter',
|
||||
forceBoard: false,
|
||||
mode: 'normal',
|
||||
createdAt: '2026-01-01T00:00:00Z',
|
||||
updatedAt: '2026-01-01T00:00:00Z',
|
||||
currentStage: '05-coding',
|
||||
status: 'failed',
|
||||
stages: {
|
||||
'00-intake': passed,
|
||||
'00b-discovery': passed,
|
||||
'02-planning-1': passed,
|
||||
'03-planning-2': passed,
|
||||
'04-planning-3': passed,
|
||||
'05-coding': { status: 'failed', reason: 'gate failed' },
|
||||
},
|
||||
});
|
||||
|
||||
try {
|
||||
await runPipeline(briefPath, tmpDir, {
|
||||
executor: executor1,
|
||||
stages: ['00-intake', '00b-discovery', '02-planning-1'],
|
||||
});
|
||||
} catch {
|
||||
// expected
|
||||
// Resume re-runs 05-coding (the first non-passed stage), then fails
|
||||
// closed at 06-review because no reviewer provider is wired.
|
||||
const executor = createMockExecutor();
|
||||
await expect(resumePipeline(runDir, executor)).rejects.toMatchObject({
|
||||
name: 'ForgeCapabilityError',
|
||||
code: 'FORGE_NO_REVIEWER',
|
||||
});
|
||||
|
||||
const manifest = loadManifest(runDir);
|
||||
expect(manifest.stages['05-coding']?.status).toBe('passed');
|
||||
expect(manifest.stages['06-review']?.status).toBe('blocked');
|
||||
expect(manifest.status).toBe('failed');
|
||||
});
|
||||
|
||||
it('resumes to completion as simulated under explicit simulate', async () => {
|
||||
const runId = '20260101-000003';
|
||||
const runDir = path.join(tmpDir, '.forge', 'runs', runId);
|
||||
fs.mkdirSync(runDir, { recursive: true });
|
||||
const passed = { status: 'passed' as const, startedAt: '2026-01-01T00:00:00Z' };
|
||||
saveManifest(runDir, {
|
||||
runId,
|
||||
brief: briefPath,
|
||||
codebase: tmpDir,
|
||||
briefClass: 'hotfix',
|
||||
classSource: 'frontmatter',
|
||||
forceBoard: false,
|
||||
mode: 'normal',
|
||||
createdAt: '2026-01-01T00:00:00Z',
|
||||
updatedAt: '2026-01-01T00:00:00Z',
|
||||
currentStage: '05-coding',
|
||||
status: 'failed',
|
||||
stages: {
|
||||
'00-intake': passed,
|
||||
'00b-discovery': passed,
|
||||
'02-planning-1': passed,
|
||||
'03-planning-2': passed,
|
||||
'04-planning-3': passed,
|
||||
'05-coding': { status: 'failed', reason: 'gate failed' },
|
||||
},
|
||||
});
|
||||
|
||||
const result = await resumePipeline(runDir, undefined, { simulate: true });
|
||||
|
||||
expect(result.manifest.status).toBe('simulated');
|
||||
expect(result.manifest.mode).toBe('simulated');
|
||||
expect(result.stages[0]).toBe('05-coding');
|
||||
for (const stage of result.stages) {
|
||||
expect(result.manifest.stages[stage]?.status).toBe('simulated');
|
||||
}
|
||||
});
|
||||
|
||||
const runsDir = path.join(tmpDir, '.forge', 'runs');
|
||||
runDir = path.join(runsDir, fs.readdirSync(runsDir)[0]!);
|
||||
it('fails closed on resume when the next stage needs authority sign-off', async () => {
|
||||
const runId = '20260101-000001';
|
||||
const runDir = path.join(tmpDir, '.forge', 'runs', runId);
|
||||
fs.mkdirSync(runDir, { recursive: true });
|
||||
saveManifest(runDir, {
|
||||
runId,
|
||||
brief: briefPath,
|
||||
codebase: tmpDir,
|
||||
briefClass: 'hotfix',
|
||||
classSource: 'frontmatter',
|
||||
forceBoard: false,
|
||||
mode: 'normal',
|
||||
createdAt: '2026-01-01T00:00:00Z',
|
||||
updatedAt: '2026-01-01T00:00:00Z',
|
||||
currentStage: '00-intake',
|
||||
status: 'in_progress',
|
||||
stages: {
|
||||
'00-intake': { status: 'passed' },
|
||||
},
|
||||
});
|
||||
|
||||
// Resume should pick up from 00b-discovery
|
||||
const executor2 = createMockExecutor();
|
||||
const result = await resumePipeline(runDir, executor2);
|
||||
const executor = createMockExecutor();
|
||||
await expect(resumePipeline(runDir, executor)).rejects.toMatchObject({
|
||||
name: 'ForgeCapabilityError',
|
||||
code: 'FORGE_AUTHORITY_REQUIRED',
|
||||
});
|
||||
|
||||
expect(result.manifest.status).toBe('completed');
|
||||
// Should have re-run from 00b-discovery onward
|
||||
expect(result.stages[0]).toBe('00b-discovery');
|
||||
const manifest = loadManifest(runDir);
|
||||
expect(manifest.stages['00b-discovery']?.status).toBe('waiting-for-authority');
|
||||
expect(manifest.status).toBe('waiting-for-authority');
|
||||
});
|
||||
|
||||
it('fails closed on resume without an executor or --simulate', async () => {
|
||||
const runId = '20260101-000002';
|
||||
const runDir = path.join(tmpDir, '.forge', 'runs', runId);
|
||||
fs.mkdirSync(runDir, { recursive: true });
|
||||
saveManifest(runDir, {
|
||||
runId,
|
||||
brief: briefPath,
|
||||
codebase: tmpDir,
|
||||
briefClass: 'hotfix',
|
||||
classSource: 'frontmatter',
|
||||
forceBoard: false,
|
||||
mode: 'normal',
|
||||
createdAt: '2026-01-01T00:00:00Z',
|
||||
updatedAt: '2026-01-01T00:00:00Z',
|
||||
currentStage: '00-intake',
|
||||
status: 'in_progress',
|
||||
stages: {
|
||||
'00-intake': { status: 'passed' },
|
||||
},
|
||||
});
|
||||
|
||||
await expect(resumePipeline(runDir)).rejects.toMatchObject({
|
||||
name: 'ForgeCapabilityError',
|
||||
code: 'FORGE_NO_EXECUTOR',
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
|
||||
@@ -95,7 +95,14 @@ export function generateBoardTasks(
|
||||
briefPath,
|
||||
resultPath: resultRelPath,
|
||||
timeoutSeconds: 120,
|
||||
qualityGates: ['true'],
|
||||
qualityGates: [
|
||||
{
|
||||
kind: 'authority',
|
||||
capability: 'board-approval',
|
||||
reason:
|
||||
'persona evaluation is judged by board synthesis (authority review); no mechanical gate exists',
|
||||
},
|
||||
],
|
||||
metadata: {
|
||||
personaName: persona.name,
|
||||
personaSlug: persona.slug,
|
||||
@@ -121,7 +128,13 @@ export function generateBoardTasks(
|
||||
timeoutSeconds: 120,
|
||||
dependsOn: personaTaskIds,
|
||||
dependsOnPolicy: 'all_terminal',
|
||||
qualityGates: ['true'],
|
||||
qualityGates: [
|
||||
{
|
||||
kind: 'authority',
|
||||
capability: 'board-approval',
|
||||
reason: 'board synthesis is an authority decision; no mechanical gate exists',
|
||||
},
|
||||
],
|
||||
metadata: {
|
||||
resultOutputPath: synthesisResult,
|
||||
inputResultPaths: personaResultPaths,
|
||||
|
||||
@@ -1,7 +1,11 @@
|
||||
import fs from 'node:fs';
|
||||
import os from 'node:os';
|
||||
import path from 'node:path';
|
||||
import { Command } from 'commander';
|
||||
import { describe, expect, it } from 'vitest';
|
||||
import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
|
||||
|
||||
import { registerForgeCommand } from './cli.js';
|
||||
import { loadManifest } from './pipeline-runner.js';
|
||||
|
||||
describe('registerForgeCommand', () => {
|
||||
it('registers a "forge" command on the parent program', () => {
|
||||
@@ -55,3 +59,94 @@ describe('registerForgeCommand', () => {
|
||||
}).not.toThrow();
|
||||
});
|
||||
});
|
||||
|
||||
describe('forge run fail-closed behavior (SDLC-D-035)', () => {
|
||||
let tmpDir: string;
|
||||
let briefPath: string;
|
||||
let errSpy: ReturnType<typeof vi.spyOn>;
|
||||
let logSpy: ReturnType<typeof vi.spyOn>;
|
||||
let prevExitCode: string | number | null | undefined;
|
||||
|
||||
const parse = (args: string[]) => {
|
||||
const program = new Command();
|
||||
registerForgeCommand(program);
|
||||
return program.parseAsync(['forge', ...args], { from: 'user' });
|
||||
};
|
||||
|
||||
beforeEach(() => {
|
||||
tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'forge-cli-failclosed-'));
|
||||
briefPath = path.join(tmpDir, 'brief.md');
|
||||
fs.writeFileSync(briefPath, '# Fix bug\n\nA bugfix for lint cleanup.');
|
||||
errSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
|
||||
logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
|
||||
prevExitCode = process.exitCode;
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
errSpy.mockRestore();
|
||||
logSpy.mockRestore();
|
||||
process.exitCode = prevExitCode;
|
||||
fs.rmSync(tmpDir, { recursive: true, force: true });
|
||||
});
|
||||
|
||||
it('exits nonzero with a typed FORGE_NO_EXECUTOR error when no executor is wired and --simulate is absent', async () => {
|
||||
await parse(['run', '--brief', briefPath, '--codebase', tmpDir]);
|
||||
|
||||
expect(process.exitCode).toBe(1);
|
||||
const errText = errSpy.mock.calls.map((c) => c.join(' ')).join('\n');
|
||||
expect(errText).toContain('FORGE_NO_EXECUTOR');
|
||||
// It must never run the pipeline with a stub and report success.
|
||||
expect(fs.existsSync(path.join(tmpDir, '.forge', 'runs'))).toBe(false);
|
||||
});
|
||||
|
||||
it('completes with typed simulated results and exit 0 under explicit --simulate', async () => {
|
||||
await parse(['run', '--brief', briefPath, '--codebase', tmpDir, '--simulate']);
|
||||
|
||||
expect(process.exitCode).toBeUndefined();
|
||||
|
||||
// Loud simulated-mode summary.
|
||||
const logText = logSpy.mock.calls.map((c) => c.join(' ')).join('\n');
|
||||
expect(logText).toContain('SIMULATED');
|
||||
|
||||
// Manifest records the mode and simulated per-result statuses.
|
||||
const runsDir = path.join(tmpDir, '.forge', 'runs');
|
||||
const runIds = fs.readdirSync(runsDir);
|
||||
expect(runIds).toHaveLength(1);
|
||||
const manifest = loadManifest(path.join(runsDir, runIds[0]!));
|
||||
expect(manifest.mode).toBe('simulated');
|
||||
expect(manifest.status).toBe('simulated');
|
||||
for (const stageStatus of Object.values(manifest.stages)) {
|
||||
expect(stageStatus?.status).toBe('simulated');
|
||||
for (const gateResult of stageStatus?.gateResults ?? []) {
|
||||
expect(gateResult.outcome).toBe('simulated');
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
it('resume exits nonzero with a typed FORGE_NO_EXECUTOR error without --simulate', async () => {
|
||||
const runDir = path.join(tmpDir, '.forge', 'runs', '20260101-000000');
|
||||
fs.mkdirSync(runDir, { recursive: true });
|
||||
fs.writeFileSync(
|
||||
path.join(runDir, 'manifest.json'),
|
||||
JSON.stringify({
|
||||
runId: '20260101-000000',
|
||||
brief: briefPath,
|
||||
codebase: tmpDir,
|
||||
briefClass: 'hotfix',
|
||||
classSource: 'frontmatter',
|
||||
forceBoard: false,
|
||||
createdAt: '2026-01-01T00:00:00Z',
|
||||
updatedAt: '2026-01-01T00:00:00Z',
|
||||
currentStage: '00-intake',
|
||||
status: 'in_progress',
|
||||
stages: { '00-intake': { status: 'passed' } },
|
||||
}),
|
||||
);
|
||||
|
||||
await parse(['resume', '20260101-000000', '--project', tmpDir]);
|
||||
|
||||
expect(process.exitCode).toBe(1);
|
||||
const errText = errSpy.mock.calls.map((c) => c.join(' ')).join('\n');
|
||||
expect(errText).toContain('FORGE_NO_EXECUTOR');
|
||||
});
|
||||
});
|
||||
|
||||
+122
-48
@@ -5,37 +5,47 @@ import type { Command } from 'commander';
|
||||
|
||||
import { classifyBrief } from './brief-classifier.js';
|
||||
import { STAGE_LABELS, STAGE_SEQUENCE } from './constants.js';
|
||||
import { ForgeCapabilityError } from './errors.js';
|
||||
import { getEffectivePersonas, loadBoardPersonas } from './persona-loader.js';
|
||||
import { generateRunId, getPipelineStatus, loadManifest, runPipeline } from './pipeline-runner.js';
|
||||
import type { PipelineOptions, RunManifest, TaskExecutor } from './types.js';
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Stub executor — used when no real executor is wired at CLI invocation time.
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
const stubExecutor: TaskExecutor = {
|
||||
async submitTask(task) {
|
||||
console.log(` [forge] stage submitted: ${task.id} (${task.title})`);
|
||||
},
|
||||
async waitForCompletion(taskId, _timeoutMs) {
|
||||
console.log(` [forge] stage complete: ${taskId}`);
|
||||
return {
|
||||
task_id: taskId,
|
||||
status: 'completed' as const,
|
||||
completed_at: new Date().toISOString(),
|
||||
exit_code: 0,
|
||||
gate_results: [],
|
||||
};
|
||||
},
|
||||
async getTaskStatus(_taskId) {
|
||||
return 'completed' as const;
|
||||
},
|
||||
};
|
||||
import { createSimulatedExecutor } from './simulated-executor.js';
|
||||
import type { PipelineOptions, RunManifest, RunMode } from './types.js';
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Helpers
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/** Resolve a run's effective mode, defaulting legacy manifests to normal. */
|
||||
function runModeOf(manifest: RunManifest): RunMode {
|
||||
return manifest.mode ?? 'normal';
|
||||
}
|
||||
|
||||
/** Print a loud banner so a simulated run can never be misread as verified. */
|
||||
function printSimulatedBanner(): void {
|
||||
console.log('');
|
||||
console.log('[forge] ===============================================================');
|
||||
console.log('[forge] MODE: SIMULATED — no stage or gate was really executed.');
|
||||
console.log('[forge] All results are synthetic and MUST NOT be read as verified');
|
||||
console.log('[forge] success. Wire a real executor/providers and re-run to verify.');
|
||||
console.log('[forge] ===============================================================');
|
||||
}
|
||||
|
||||
/** Print a typed error line for fail-closed capability errors. */
|
||||
function printCapabilityError(err: ForgeCapabilityError): void {
|
||||
console.error(`[forge] error ${err.code}: ${err.message}`);
|
||||
console.error(`[forge] missing capability: ${err.capability}`);
|
||||
}
|
||||
|
||||
/** Handle a pipeline error uniformly: typed capability errors get their code. */
|
||||
function handlePipelineError(err: unknown): void {
|
||||
if (err instanceof ForgeCapabilityError) {
|
||||
printCapabilityError(err);
|
||||
} else {
|
||||
console.error(`[forge] pipeline failed: ${err instanceof Error ? err.message : String(err)}`);
|
||||
}
|
||||
process.exitCode = 1;
|
||||
}
|
||||
|
||||
function formatDuration(startedAt?: string, completedAt?: string): string {
|
||||
if (!startedAt || !completedAt) return '-';
|
||||
const ms = new Date(completedAt).getTime() - new Date(startedAt).getTime();
|
||||
@@ -44,19 +54,24 @@ function formatDuration(startedAt?: string, completedAt?: string): string {
|
||||
}
|
||||
|
||||
function printManifestTable(manifest: RunManifest): void {
|
||||
const mode = runModeOf(manifest);
|
||||
console.log(`\nRun ID : ${manifest.runId}`);
|
||||
console.log(`Status : ${manifest.status}`);
|
||||
console.log(`Mode : ${mode}`);
|
||||
if (mode === 'simulated') {
|
||||
console.log('WARNING: SIMULATED RUN — results are synthetic, not verified success.');
|
||||
}
|
||||
console.log(`Brief : ${manifest.brief}`);
|
||||
console.log(`Class : ${manifest.briefClass} (${manifest.classSource})`);
|
||||
console.log(`Updated: ${manifest.updatedAt}`);
|
||||
console.log('');
|
||||
console.log('Stage'.padEnd(22) + 'Status'.padEnd(14) + 'Duration');
|
||||
console.log('-'.repeat(50));
|
||||
console.log('Stage'.padEnd(22) + 'Status'.padEnd(24) + 'Duration');
|
||||
console.log('-'.repeat(60));
|
||||
for (const stage of STAGE_SEQUENCE) {
|
||||
const s = manifest.stages[stage];
|
||||
if (!s) continue;
|
||||
const label = (STAGE_LABELS[stage] ?? stage).padEnd(22);
|
||||
const status = s.status.padEnd(14);
|
||||
const status = s.status.padEnd(24);
|
||||
const dur = formatDuration(s.startedAt, s.completedAt);
|
||||
console.log(`${label}${status}${dur}`);
|
||||
}
|
||||
@@ -90,23 +105,58 @@ function listRecentRuns(projectRoot?: string): void {
|
||||
}
|
||||
|
||||
console.log('\nRecent runs:');
|
||||
console.log('Run ID'.padEnd(22) + 'Status'.padEnd(14) + 'Brief');
|
||||
console.log('-'.repeat(70));
|
||||
console.log('Run ID'.padEnd(22) + 'Status'.padEnd(24) + 'Mode'.padEnd(12) + 'Brief');
|
||||
console.log('-'.repeat(80));
|
||||
|
||||
for (const runId of entries) {
|
||||
const runDir = path.join(runsDir, runId);
|
||||
try {
|
||||
const manifest = loadManifest(runDir);
|
||||
const status = manifest.status.padEnd(14);
|
||||
const status = manifest.status.padEnd(24);
|
||||
const mode = runModeOf(manifest).padEnd(12);
|
||||
const brief = path.basename(manifest.brief);
|
||||
console.log(`${runId.padEnd(22)}${status}${brief}`);
|
||||
console.log(`${runId.padEnd(22)}${status}${mode}${brief}`);
|
||||
} catch {
|
||||
console.log(`${runId.padEnd(22)}${'(unreadable)'.padEnd(14)}`);
|
||||
console.log(`${runId.padEnd(22)}${'(unreadable)'.padEnd(24)}`);
|
||||
}
|
||||
}
|
||||
console.log('');
|
||||
}
|
||||
|
||||
/**
|
||||
* Apply the exit-code policy for a finished pipeline run (SDLC-D-035):
|
||||
*
|
||||
* - exit 0 only for a verified `completed` normal run, or for an overall
|
||||
* `simulated` run when the caller explicitly passed --simulate;
|
||||
* - anything else exits nonzero so it can never be read as success.
|
||||
*/
|
||||
function applyRunExitPolicy(result: { manifest: RunManifest; runDir: string }, simulate: boolean) {
|
||||
const { manifest } = result;
|
||||
|
||||
if (runModeOf(manifest) === 'simulated') {
|
||||
if (!simulate || manifest.status !== 'simulated') {
|
||||
console.error(
|
||||
'[forge] error FORGE_MODE_MISMATCH: run reports simulated results without an explicit, ' +
|
||||
'consistent --simulate request; refusing to report success.',
|
||||
);
|
||||
process.exitCode = 1;
|
||||
return;
|
||||
}
|
||||
printSimulatedBanner();
|
||||
console.log(`[forge] run directory: ${result.runDir}`);
|
||||
return; // exit 0 — the caller explicitly opted into simulation
|
||||
}
|
||||
|
||||
if (manifest.status !== 'completed') {
|
||||
console.error(`[forge] run did not complete: terminal status '${manifest.status}'`);
|
||||
process.exitCode = 1;
|
||||
return;
|
||||
}
|
||||
|
||||
console.log(`[forge] pipeline complete (mode: normal): ${manifest.runId}`);
|
||||
console.log(`[forge] run directory: ${result.runDir}`);
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Register function
|
||||
// ---------------------------------------------------------------------------
|
||||
@@ -129,6 +179,11 @@ export function registerForgeCommand(parent: Command): void {
|
||||
.option('--config <path>', 'Path to forge config file (.forge/config.yaml)')
|
||||
.option('--codebase <path>', 'Codebase root to pass to the pipeline', process.cwd())
|
||||
.option('--dry-run', 'Print planned stages without executing', false)
|
||||
.option(
|
||||
'--simulate',
|
||||
'Simulate execution without real providers (every result is typed simulated, never verified)',
|
||||
false,
|
||||
)
|
||||
.action(
|
||||
async (opts: {
|
||||
brief: string;
|
||||
@@ -137,6 +192,7 @@ export function registerForgeCommand(parent: Command): void {
|
||||
config?: string;
|
||||
codebase: string;
|
||||
dryRun: boolean;
|
||||
simulate: boolean;
|
||||
}) => {
|
||||
const briefPath = path.resolve(opts.brief);
|
||||
|
||||
@@ -149,14 +205,22 @@ export function registerForgeCommand(parent: Command): void {
|
||||
const briefContent = fs.readFileSync(briefPath, 'utf-8');
|
||||
const briefClass = classifyBrief(briefContent);
|
||||
const projectRoot = opts.codebase;
|
||||
// A real executor is never wired at CLI invocation time today, so the
|
||||
// only executor we may construct is the explicitly-requested simulated
|
||||
// one. Normal mode fails closed with FORGE_NO_EXECUTOR.
|
||||
const executor = opts.simulate ? createSimulatedExecutor() : undefined;
|
||||
|
||||
if (opts.resume) {
|
||||
const runId = opts.runId ?? generateRunId();
|
||||
const runDir = resolveRunDir(runId, projectRoot);
|
||||
console.log(`[forge] resuming run: ${runId}`);
|
||||
const { resumePipeline } = await import('./pipeline-runner.js');
|
||||
const result = await resumePipeline(runDir, stubExecutor);
|
||||
console.log(`[forge] pipeline complete: ${result.runId}`);
|
||||
try {
|
||||
const { resumePipeline } = await import('./pipeline-runner.js');
|
||||
const result = await resumePipeline(runDir, executor, { simulate: opts.simulate });
|
||||
applyRunExitPolicy(result, opts.simulate);
|
||||
} catch (err) {
|
||||
handlePipelineError(err);
|
||||
}
|
||||
return;
|
||||
}
|
||||
|
||||
@@ -164,7 +228,8 @@ export function registerForgeCommand(parent: Command): void {
|
||||
briefClass,
|
||||
codebase: projectRoot,
|
||||
dryRun: opts.dryRun,
|
||||
executor: stubExecutor,
|
||||
executor,
|
||||
simulate: opts.simulate,
|
||||
};
|
||||
|
||||
if (opts.dryRun) {
|
||||
@@ -180,16 +245,15 @@ export function registerForgeCommand(parent: Command): void {
|
||||
|
||||
console.log(`[forge] starting pipeline for brief: ${briefPath}`);
|
||||
console.log(`[forge] classified as: ${briefClass}`);
|
||||
if (opts.simulate) {
|
||||
console.log('[forge] mode: SIMULATED (explicit --simulate)');
|
||||
}
|
||||
|
||||
try {
|
||||
const result = await runPipeline(briefPath, projectRoot, pipelineOptions);
|
||||
console.log(`[forge] pipeline complete: ${result.runId}`);
|
||||
console.log(`[forge] run directory: ${result.runDir}`);
|
||||
applyRunExitPolicy(result, opts.simulate);
|
||||
} catch (err) {
|
||||
console.error(
|
||||
`[forge] pipeline failed: ${err instanceof Error ? err.message : String(err)}`,
|
||||
);
|
||||
process.exitCode = 1;
|
||||
handlePipelineError(err);
|
||||
}
|
||||
},
|
||||
);
|
||||
@@ -224,7 +288,12 @@ export function registerForgeCommand(parent: Command): void {
|
||||
.command('resume <runId>')
|
||||
.description('Resume a stopped or failed pipeline run')
|
||||
.option('--project <path>', 'Project root (defaults to cwd)', process.cwd())
|
||||
.action(async (runId: string, opts: { project: string }) => {
|
||||
.option(
|
||||
'--simulate',
|
||||
'Simulate execution without real providers (every result is typed simulated, never verified)',
|
||||
false,
|
||||
)
|
||||
.action(async (runId: string, opts: { project: string; simulate: boolean }) => {
|
||||
const runDir = resolveRunDir(runId, opts.project);
|
||||
|
||||
if (!fs.existsSync(runDir)) {
|
||||
@@ -234,15 +303,20 @@ export function registerForgeCommand(parent: Command): void {
|
||||
}
|
||||
|
||||
console.log(`[forge] resuming run: ${runId}`);
|
||||
if (opts.simulate) {
|
||||
console.log('[forge] mode: SIMULATED (explicit --simulate)');
|
||||
}
|
||||
|
||||
// No real executor is wired at CLI invocation time; only the explicitly
|
||||
// requested simulated executor may be constructed (fail closed otherwise).
|
||||
const executor = opts.simulate ? createSimulatedExecutor() : undefined;
|
||||
|
||||
try {
|
||||
const { resumePipeline } = await import('./pipeline-runner.js');
|
||||
const result = await resumePipeline(runDir, stubExecutor);
|
||||
console.log(`[forge] pipeline complete: ${result.runId}`);
|
||||
console.log(`[forge] run directory: ${result.runDir}`);
|
||||
const result = await resumePipeline(runDir, executor, { simulate: opts.simulate });
|
||||
applyRunExitPolicy(result, opts.simulate);
|
||||
} catch (err) {
|
||||
console.error(`[forge] resume failed: ${err instanceof Error ? err.message : String(err)}`);
|
||||
process.exitCode = 1;
|
||||
handlePipelineError(err);
|
||||
}
|
||||
});
|
||||
|
||||
|
||||
@@ -9,7 +9,16 @@ export const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.
|
||||
/** Pipeline asset directory (stages, agents, rails, gates, templates). */
|
||||
export const PIPELINE_DIR = path.join(PACKAGE_ROOT, 'pipeline');
|
||||
|
||||
/** Stage specifications — defines every pipeline stage. */
|
||||
/** Stage specifications — defines every pipeline stage.
|
||||
*\n * Gate semantics (SDLC-D-035): every gate is one of
|
||||
* - a real command string / GateEntry a mechanical runner can execute,
|
||||
* - an `authority` gate (human/board sign-off; produces waiting-for-authority),
|
||||
* - a `provider` gate (requires a wired provider such as a reviewer or CI pipeline).
|
||||
*
|
||||
* Vacuous gates (`true`, echo'd synthetic approvals, placeholder ci-pipeline
|
||||
* commands) are forbidden: a stage whose gate has no real implementation
|
||||
* fails closed instead of passing.
|
||||
*/
|
||||
export const STAGE_SPECS: Record<string, StageSpec> = {
|
||||
'00-intake': {
|
||||
number: '00',
|
||||
@@ -27,7 +36,13 @@ export const STAGE_SPECS: Record<string, StageSpec> = {
|
||||
type: 'research',
|
||||
gate: 'discovery-complete',
|
||||
promptFile: '00b-discovery.md',
|
||||
qualityGates: ['true'],
|
||||
qualityGates: [
|
||||
{
|
||||
kind: 'authority',
|
||||
capability: 'discovery-complete',
|
||||
reason: 'discovery completion is attested by an authority; no mechanical check exists',
|
||||
},
|
||||
],
|
||||
},
|
||||
'01-board': {
|
||||
number: '01',
|
||||
@@ -36,7 +51,13 @@ export const STAGE_SPECS: Record<string, StageSpec> = {
|
||||
type: 'review',
|
||||
gate: 'board-approval',
|
||||
promptFile: '01-board.md',
|
||||
qualityGates: [{ type: 'ci-pipeline', command: 'board-approval (via board-tasks)' }],
|
||||
qualityGates: [
|
||||
{
|
||||
kind: 'authority',
|
||||
capability: 'board-approval',
|
||||
reason: 'board approval is a board/human decision; no mechanical gate exists',
|
||||
},
|
||||
],
|
||||
},
|
||||
'01b-brief-analyzer': {
|
||||
number: '01b',
|
||||
@@ -45,7 +66,13 @@ export const STAGE_SPECS: Record<string, StageSpec> = {
|
||||
type: 'research',
|
||||
gate: 'brief-analysis-complete',
|
||||
promptFile: '01-board.md',
|
||||
qualityGates: ['true'],
|
||||
qualityGates: [
|
||||
{
|
||||
kind: 'authority',
|
||||
capability: 'brief-analysis-complete',
|
||||
reason: 'brief analysis completion is attested by an authority; no mechanical check exists',
|
||||
},
|
||||
],
|
||||
},
|
||||
'02-planning-1': {
|
||||
number: '02',
|
||||
@@ -54,7 +81,13 @@ export const STAGE_SPECS: Record<string, StageSpec> = {
|
||||
type: 'research',
|
||||
gate: 'architecture-approval',
|
||||
promptFile: '02-planning-1-architecture.md',
|
||||
qualityGates: ['true'],
|
||||
qualityGates: [
|
||||
{
|
||||
kind: 'authority',
|
||||
capability: 'architecture-approval',
|
||||
reason: 'ADR approval requires authority sign-off; no mechanical check exists',
|
||||
},
|
||||
],
|
||||
},
|
||||
'03-planning-2': {
|
||||
number: '03',
|
||||
@@ -63,7 +96,14 @@ export const STAGE_SPECS: Record<string, StageSpec> = {
|
||||
type: 'research',
|
||||
gate: 'implementation-approval',
|
||||
promptFile: '03-planning-2-implementation.md',
|
||||
qualityGates: ['true'],
|
||||
qualityGates: [
|
||||
{
|
||||
kind: 'authority',
|
||||
capability: 'implementation-approval',
|
||||
reason:
|
||||
'implementation spec approval requires authority sign-off; no mechanical check exists',
|
||||
},
|
||||
],
|
||||
},
|
||||
'04-planning-3': {
|
||||
number: '04',
|
||||
@@ -72,7 +112,14 @@ export const STAGE_SPECS: Record<string, StageSpec> = {
|
||||
type: 'research',
|
||||
gate: 'decomposition-approval',
|
||||
promptFile: '04-planning-3-decomposition.md',
|
||||
qualityGates: ['true'],
|
||||
qualityGates: [
|
||||
{
|
||||
kind: 'authority',
|
||||
capability: 'decomposition-approval',
|
||||
reason:
|
||||
'task decomposition approval requires authority sign-off; no mechanical check exists',
|
||||
},
|
||||
],
|
||||
},
|
||||
'05-coding': {
|
||||
number: '05',
|
||||
@@ -92,9 +139,10 @@ export const STAGE_SPECS: Record<string, StageSpec> = {
|
||||
promptFile: '06-review.md',
|
||||
qualityGates: [
|
||||
{
|
||||
type: 'ai-review',
|
||||
command:
|
||||
'echo \'{"summary":"review-pass","verdict":"approve","findings":[],"stats":{"blockers":0,"should_fix":0,"suggestions":0}}\'',
|
||||
kind: 'provider',
|
||||
capability: 'reviewer',
|
||||
reason:
|
||||
'review verdicts require a wired reviewer provider; synthetic approvals are not permitted',
|
||||
},
|
||||
],
|
||||
},
|
||||
@@ -105,7 +153,13 @@ export const STAGE_SPECS: Record<string, StageSpec> = {
|
||||
type: 'coding',
|
||||
gate: 're-review',
|
||||
promptFile: '07-remediate.md',
|
||||
qualityGates: ['true'],
|
||||
qualityGates: [
|
||||
{
|
||||
kind: 'authority',
|
||||
capability: 're-review',
|
||||
reason: 'remediation re-review is an approval-based gate; no mechanical check exists',
|
||||
},
|
||||
],
|
||||
},
|
||||
'08-test': {
|
||||
number: '08',
|
||||
@@ -123,7 +177,13 @@ export const STAGE_SPECS: Record<string, StageSpec> = {
|
||||
type: 'deploy',
|
||||
gate: 'deploy-verification',
|
||||
promptFile: '09-deploy.md',
|
||||
qualityGates: [{ type: 'ci-pipeline', command: 'deploy-verification' }],
|
||||
qualityGates: [
|
||||
{
|
||||
kind: 'provider',
|
||||
capability: 'ci-pipeline',
|
||||
reason: 'deploy verification requires a wired CI pipeline provider',
|
||||
},
|
||||
],
|
||||
},
|
||||
};
|
||||
|
||||
|
||||
@@ -0,0 +1,46 @@
|
||||
/**
|
||||
* Typed fail-closed capability errors (SDLC-D-035).
|
||||
*
|
||||
* A Forge run must fail closed when a required capability (executor, reviewer
|
||||
* provider, CI pipeline, authority sign-off) is missing. These typed errors
|
||||
* name the missing capability so callers can distinguish "not wired" from
|
||||
* ordinary execution failures.
|
||||
*/
|
||||
|
||||
/** Closed set of typed Forge capability error codes. */
|
||||
export const FORGE_ERROR_CODES = [
|
||||
'FORGE_NO_EXECUTOR',
|
||||
'FORGE_NO_REVIEWER',
|
||||
'FORGE_NO_CI_PIPELINE',
|
||||
'FORGE_NO_PROVIDER',
|
||||
'FORGE_AUTHORITY_REQUIRED',
|
||||
] as const;
|
||||
|
||||
export type ForgeErrorCode = (typeof FORGE_ERROR_CODES)[number];
|
||||
|
||||
/** Raised when a required capability is missing and the pipeline must fail closed. */
|
||||
export class ForgeCapabilityError extends Error {
|
||||
/** Typed error code from the closed FORGE_ERROR_CODES set. */
|
||||
readonly code: ForgeErrorCode;
|
||||
/** The missing capability, e.g. `task-executor`, `reviewer`, `board-approval`. */
|
||||
readonly capability: string;
|
||||
|
||||
constructor(code: ForgeErrorCode, capability: string, message: string) {
|
||||
super(message);
|
||||
this.name = 'ForgeCapabilityError';
|
||||
this.code = code;
|
||||
this.capability = capability;
|
||||
}
|
||||
}
|
||||
|
||||
/** Map a provider gate capability to its typed error code. */
|
||||
export function providerErrorCode(capability: string): ForgeErrorCode {
|
||||
switch (capability) {
|
||||
case 'reviewer':
|
||||
return 'FORGE_NO_REVIEWER';
|
||||
case 'ci-pipeline':
|
||||
return 'FORGE_NO_CI_PIPELINE';
|
||||
default:
|
||||
return 'FORGE_NO_PROVIDER';
|
||||
}
|
||||
}
|
||||
@@ -5,6 +5,13 @@ export type {
|
||||
StageSpec,
|
||||
BriefClass,
|
||||
ClassSource,
|
||||
ForgeOutcome,
|
||||
AuthorityGate,
|
||||
ProviderGate,
|
||||
ForgeGate,
|
||||
ForgeGateResult,
|
||||
ForgeTaskResult,
|
||||
RunMode,
|
||||
StageStatus,
|
||||
RunManifest,
|
||||
ForgeTaskStatus,
|
||||
@@ -81,5 +88,24 @@ export {
|
||||
getPipelineStatus,
|
||||
} from './pipeline-runner.js';
|
||||
|
||||
// Fail-closed errors and typed outcome model (SDLC-D-035)
|
||||
export { FORGE_ERROR_CODES, ForgeCapabilityError, providerErrorCode } from './errors.js';
|
||||
export type { ForgeErrorCode } from './errors.js';
|
||||
export {
|
||||
isSatisfyingOutcome,
|
||||
isCapabilityGate,
|
||||
isCommandGate,
|
||||
gateLabel,
|
||||
uniformGateResults,
|
||||
simulatedGateResults,
|
||||
waitingGateResults,
|
||||
blockedGateResults,
|
||||
evaluateStageGates,
|
||||
} from './outcomes.js';
|
||||
export type { StageEvaluation } from './outcomes.js';
|
||||
|
||||
// Simulated executor (explicit --simulate only)
|
||||
export { createSimulatedExecutor } from './simulated-executor.js';
|
||||
|
||||
// CLI
|
||||
export { registerForgeCommand } from './cli.js';
|
||||
|
||||
@@ -0,0 +1,147 @@
|
||||
import type { GateEntry } from '@mosaicstack/macp';
|
||||
|
||||
import type {
|
||||
AuthorityGate,
|
||||
ForgeGate,
|
||||
ForgeGateResult,
|
||||
ForgeOutcome,
|
||||
ForgeTaskResult,
|
||||
ProviderGate,
|
||||
} from './types.js';
|
||||
|
||||
/**
|
||||
* Gate and dependency satisfaction predicate (SDLC-D-035).
|
||||
*
|
||||
* ONLY a verified `passed` outcome satisfies. Every other member of the closed
|
||||
* outcome set — including `simulated` — is non-satisfying, so a simulated or
|
||||
* authority-blocked result can never be read as success-by-verification.
|
||||
*/
|
||||
export function isSatisfyingOutcome(outcome: ForgeOutcome): boolean {
|
||||
return outcome === 'passed';
|
||||
}
|
||||
|
||||
/** Whether a gate is an authority or provider gate (capability-based, command-less). */
|
||||
export function isCapabilityGate(gate: ForgeGate): gate is AuthorityGate | ProviderGate {
|
||||
if (typeof gate !== 'object' || gate === null) return false;
|
||||
const kind = (gate as Record<string, unknown>)['kind'];
|
||||
return kind === 'authority' || kind === 'provider';
|
||||
}
|
||||
|
||||
/** Whether a gate definition carries a real command a mechanical runner can execute. */
|
||||
export function isCommandGate(gate: ForgeGate): gate is string | GateEntry {
|
||||
if (typeof gate === 'string') {
|
||||
return gate.trim().length > 0;
|
||||
}
|
||||
if (isCapabilityGate(gate)) {
|
||||
// Authority and provider gates are satisfied by a capability, not a command.
|
||||
return false;
|
||||
}
|
||||
return typeof gate.command === 'string' && gate.command.trim().length > 0;
|
||||
}
|
||||
|
||||
/** Typed label identifying a gate in results and logs. */
|
||||
export function gateLabel(gate: ForgeGate): string {
|
||||
if (typeof gate === 'string') return gate;
|
||||
if (isCapabilityGate(gate)) return `${gate.kind}:${gate.capability}`;
|
||||
return gate.command || gate.type || 'unnamed-gate';
|
||||
}
|
||||
|
||||
/** Reason string stamped on every simulated gate result. */
|
||||
export const SIMULATED_GATE_REASON =
|
||||
'simulated execution (--simulate): gate was not evaluated by a real implementation';
|
||||
|
||||
/** Build typed gate results with a uniform outcome for a stage's declared gates. */
|
||||
export function uniformGateResults(
|
||||
gates: ForgeGate[],
|
||||
outcome: ForgeOutcome,
|
||||
reason: string,
|
||||
): ForgeGateResult[] {
|
||||
return gates.map((gate) => ({ gate: gateLabel(gate), outcome, reason }));
|
||||
}
|
||||
|
||||
/** Typed simulated gate results — used exclusively in `--simulate` runs. */
|
||||
export function simulatedGateResults(gates: ForgeGate[]): ForgeGateResult[] {
|
||||
return uniformGateResults(gates, 'simulated', SIMULATED_GATE_REASON);
|
||||
}
|
||||
|
||||
/** Typed waiting-for-authority gate results for approval-based stages. */
|
||||
export function waitingGateResults(gates: ForgeGate[], reason: string): ForgeGateResult[] {
|
||||
return uniformGateResults(gates, 'waiting-for-authority', reason);
|
||||
}
|
||||
|
||||
/** Typed blocked gate results for stages whose provider capability is not wired. */
|
||||
export function blockedGateResults(gates: ForgeGate[], reason: string): ForgeGateResult[] {
|
||||
return uniformGateResults(gates, 'blocked', reason);
|
||||
}
|
||||
|
||||
/** Outcome of evaluating a completed stage in normal mode. */
|
||||
export interface StageEvaluation {
|
||||
outcome: ForgeOutcome;
|
||||
reason: string;
|
||||
gateResults: ForgeGateResult[];
|
||||
}
|
||||
|
||||
/**
|
||||
* Evaluate a stage's declared gates against the executor's typed result.
|
||||
*
|
||||
* Fail-closed mapping:
|
||||
* - a `simulated` task or gate outcome in normal mode maps to `error`
|
||||
* - a missing gate result for a required command gate maps to `blocked`
|
||||
* - a non-passing task outcome propagates as the stage outcome
|
||||
* - only verified `passed` task and gate outcomes yield a `passed` stage
|
||||
*/
|
||||
export function evaluateStageGates(
|
||||
stageName: string,
|
||||
gates: ForgeGate[],
|
||||
result: ForgeTaskResult,
|
||||
): StageEvaluation {
|
||||
const gateResults = result.gate_results ?? [];
|
||||
|
||||
if (result.outcome === 'simulated') {
|
||||
return {
|
||||
outcome: 'error',
|
||||
reason: `executor reported a simulated outcome for stage '${stageName}' in normal mode — refusing to treat simulated results as verified`,
|
||||
gateResults,
|
||||
};
|
||||
}
|
||||
|
||||
if (!isSatisfyingOutcome(result.outcome)) {
|
||||
return {
|
||||
outcome: result.outcome,
|
||||
reason: `task outcome is '${result.outcome}': ${result.reason}`,
|
||||
gateResults,
|
||||
};
|
||||
}
|
||||
|
||||
for (const gate of gates) {
|
||||
// Authority and provider gates are pre-flighted before execution; they have
|
||||
// no mechanical result to verify here.
|
||||
if (!isCommandGate(gate)) continue;
|
||||
|
||||
const label = gateLabel(gate);
|
||||
const gateResult = gateResults.find((r) => r.gate === label);
|
||||
if (!gateResult) {
|
||||
return {
|
||||
outcome: 'blocked',
|
||||
reason: `no gate result was reported for required gate '${label}' (stage '${stageName}')`,
|
||||
gateResults,
|
||||
};
|
||||
}
|
||||
if (!isSatisfyingOutcome(gateResult.outcome)) {
|
||||
return {
|
||||
outcome: gateResult.outcome === 'simulated' ? 'error' : gateResult.outcome,
|
||||
reason: `gate '${label}' outcome is '${gateResult.outcome}': ${gateResult.reason}`,
|
||||
gateResults,
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
return {
|
||||
outcome: 'passed',
|
||||
reason:
|
||||
gates.length === 0
|
||||
? "stage declares no gates; task outcome 'passed' accepted"
|
||||
: 'all declared gates verified passed',
|
||||
gateResults,
|
||||
};
|
||||
}
|
||||
@@ -1,18 +1,33 @@
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
|
||||
import { STAGE_SEQUENCE } from './constants.js';
|
||||
import { STAGE_SEQUENCE, STAGE_SPECS } from './constants.js';
|
||||
import { determineBriefClass, stagesForClass } from './brief-classifier.js';
|
||||
import { ForgeCapabilityError, providerErrorCode } from './errors.js';
|
||||
import {
|
||||
blockedGateResults,
|
||||
evaluateStageGates,
|
||||
isCapabilityGate,
|
||||
simulatedGateResults,
|
||||
waitingGateResults,
|
||||
} from './outcomes.js';
|
||||
import { mapStageToTask } from './stage-adapter.js';
|
||||
import { createSimulatedExecutor } from './simulated-executor.js';
|
||||
import type {
|
||||
ForgeTask,
|
||||
ForgeTaskResult,
|
||||
PipelineOptions,
|
||||
PipelineResult,
|
||||
RunManifest,
|
||||
RunMode,
|
||||
StageStatus,
|
||||
TaskExecutor,
|
||||
} from './types.js';
|
||||
|
||||
/** Reason stamped on stages that complete under explicit simulation. */
|
||||
const SIMULATED_STAGE_REASON =
|
||||
'simulated execution (--simulate): stage was not executed by a real executor';
|
||||
|
||||
/**
|
||||
* Generate a timestamp-based run ID.
|
||||
*/
|
||||
@@ -47,6 +62,7 @@ function createManifest(opts: {
|
||||
briefClass: RunManifest['briefClass'];
|
||||
classSource: RunManifest['classSource'];
|
||||
forceBoard: boolean;
|
||||
mode: RunMode;
|
||||
runDir: string;
|
||||
}): RunManifest {
|
||||
const ts = nowISO();
|
||||
@@ -57,6 +73,7 @@ function createManifest(opts: {
|
||||
briefClass: opts.briefClass,
|
||||
classSource: opts.classSource,
|
||||
forceBoard: opts.forceBoard,
|
||||
mode: opts.mode,
|
||||
createdAt: ts,
|
||||
updatedAt: ts,
|
||||
currentStage: '',
|
||||
@@ -108,20 +125,199 @@ export function selectStages(stages?: string[], skipTo?: string): string[] {
|
||||
return selected.slice(skipIndex);
|
||||
}
|
||||
|
||||
/**
|
||||
* Fail closed when the required executor capability is missing (SDLC-D-035).
|
||||
*/
|
||||
function requireExecutor(executor: TaskExecutor | undefined, simulate: boolean): TaskExecutor {
|
||||
if (executor) return executor;
|
||||
if (simulate) return createSimulatedExecutor({ log: false });
|
||||
throw new ForgeCapabilityError(
|
||||
'FORGE_NO_EXECUTOR',
|
||||
'task-executor',
|
||||
'no task executor is wired; refusing to run the pipeline with a stub executor (fail closed). ' +
|
||||
'Pass --simulate to opt into explicitly simulated execution.',
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Pre-flight a stage's gates in normal mode (fail closed, SDLC-D-035).
|
||||
*
|
||||
* - authority gates: record a typed `waiting-for-authority` stage result and
|
||||
* raise FORGE_AUTHORITY_REQUIRED — approval-based gates never pass vacuously.
|
||||
* - provider gates: record a typed `blocked` stage result and raise the typed
|
||||
* capability error for the missing provider.
|
||||
*
|
||||
* Returns the stage status to record when the pre-flight blocks, or undefined
|
||||
* when the stage may proceed.
|
||||
*/
|
||||
function preflightStageGates(
|
||||
stageName: string,
|
||||
manifest: RunManifest,
|
||||
): { status: StageStatus; error: ForgeCapabilityError } | undefined {
|
||||
const spec = STAGE_SPECS[stageName];
|
||||
if (!spec) throw new Error(`Unknown Forge stage: ${stageName}`);
|
||||
|
||||
for (const gate of spec.qualityGates) {
|
||||
if (!isCapabilityGate(gate)) continue;
|
||||
|
||||
const startedAt = manifest.stages[stageName]?.startedAt;
|
||||
const completedAt = nowISO();
|
||||
|
||||
if (gate.kind === 'authority') {
|
||||
const reason = `gate '${gate.capability}' requires authority sign-off; no mechanical implementation exists (${gate.reason})`;
|
||||
return {
|
||||
status: {
|
||||
status: 'waiting-for-authority',
|
||||
reason,
|
||||
startedAt,
|
||||
completedAt,
|
||||
gateResults: waitingGateResults(spec.qualityGates, reason),
|
||||
},
|
||||
error: new ForgeCapabilityError(
|
||||
'FORGE_AUTHORITY_REQUIRED',
|
||||
gate.capability,
|
||||
`stage '${stageName}' is blocked on authority gate '${gate.capability}': ${gate.reason}. ` +
|
||||
'The pipeline fails closed instead of passing vacuously. Record the approval out-of-band ' +
|
||||
'or run with --simulate for explicitly simulated execution.',
|
||||
),
|
||||
};
|
||||
}
|
||||
|
||||
const reason = `gate '${gate.capability}' requires provider '${gate.capability}' and none is wired (${gate.reason})`;
|
||||
return {
|
||||
status: {
|
||||
status: 'blocked',
|
||||
reason,
|
||||
startedAt,
|
||||
completedAt,
|
||||
gateResults: blockedGateResults(spec.qualityGates, reason),
|
||||
},
|
||||
error: new ForgeCapabilityError(
|
||||
providerErrorCode(gate.capability),
|
||||
gate.capability,
|
||||
`stage '${stageName}' requires provider '${gate.capability}' which is not wired: ${gate.reason}. ` +
|
||||
'The pipeline fails closed instead of passing vacuously.',
|
||||
),
|
||||
};
|
||||
}
|
||||
|
||||
return undefined;
|
||||
}
|
||||
|
||||
/**
|
||||
* Execute the given stage tasks sequentially, updating the manifest.
|
||||
*
|
||||
* Normal mode requires a real executor and evaluates every declared command
|
||||
* gate through the typed outcome model; any non-verified result fails closed.
|
||||
* Simulate mode types every stage and gate result as `simulated`.
|
||||
*/
|
||||
async function executeStages(opts: {
|
||||
manifest: RunManifest;
|
||||
runDir: string;
|
||||
tasks: ForgeTask[];
|
||||
stageNames: string[];
|
||||
executor: TaskExecutor;
|
||||
simulate: boolean;
|
||||
}): Promise<void> {
|
||||
const { manifest, runDir, tasks, stageNames, executor, simulate } = opts;
|
||||
|
||||
for (let i = 0; i < tasks.length; i++) {
|
||||
const task = tasks[i]!;
|
||||
const stageName = stageNames[i]!;
|
||||
const spec = STAGE_SPECS[stageName];
|
||||
if (!spec) throw new Error(`Unknown Forge stage: ${stageName}`);
|
||||
|
||||
// Update manifest: stage in progress
|
||||
manifest.currentStage = stageName;
|
||||
manifest.stages[stageName] = {
|
||||
status: 'in_progress',
|
||||
startedAt: nowISO(),
|
||||
};
|
||||
saveManifest(runDir, manifest);
|
||||
|
||||
// Fail-closed pre-flight (normal mode only): authority/provider gates have
|
||||
// no mechanical implementation and must never pass vacuously.
|
||||
if (!simulate) {
|
||||
const blocked = preflightStageGates(stageName, manifest);
|
||||
if (blocked) {
|
||||
manifest.stages[stageName] = blocked.status;
|
||||
manifest.status =
|
||||
blocked.status.status === 'waiting-for-authority' ? 'waiting-for-authority' : 'failed';
|
||||
saveManifest(runDir, manifest);
|
||||
throw blocked.error;
|
||||
}
|
||||
}
|
||||
|
||||
let result: ForgeTaskResult;
|
||||
try {
|
||||
await executor.submitTask(task);
|
||||
result = await executor.waitForCompletion(task.id, task.timeoutSeconds * 1000);
|
||||
} catch (error) {
|
||||
// Process errors (including timeouts) map to the fail-closed `error` outcome.
|
||||
const reason = error instanceof Error ? error.message : String(error);
|
||||
manifest.stages[stageName] = {
|
||||
status: 'error',
|
||||
reason: `executor error: ${reason}`,
|
||||
startedAt: manifest.stages[stageName]?.startedAt,
|
||||
completedAt: nowISO(),
|
||||
gateResults: [],
|
||||
};
|
||||
manifest.status = 'failed';
|
||||
saveManifest(runDir, manifest);
|
||||
throw error instanceof Error ? error : new Error(reason);
|
||||
}
|
||||
|
||||
if (simulate) {
|
||||
manifest.stages[stageName] = {
|
||||
status: 'simulated',
|
||||
reason: SIMULATED_STAGE_REASON,
|
||||
startedAt: manifest.stages[stageName]?.startedAt,
|
||||
completedAt: nowISO(),
|
||||
gateResults: simulatedGateResults(spec.qualityGates),
|
||||
};
|
||||
saveManifest(runDir, manifest);
|
||||
continue;
|
||||
}
|
||||
|
||||
const evaluation = evaluateStageGates(stageName, spec.qualityGates, result);
|
||||
manifest.stages[stageName] = {
|
||||
status: evaluation.outcome,
|
||||
reason: evaluation.reason,
|
||||
startedAt: manifest.stages[stageName]?.startedAt,
|
||||
completedAt: nowISO(),
|
||||
gateResults: evaluation.gateResults,
|
||||
};
|
||||
|
||||
if (evaluation.outcome !== 'passed') {
|
||||
manifest.status =
|
||||
evaluation.outcome === 'waiting-for-authority' ? 'waiting-for-authority' : 'failed';
|
||||
saveManifest(runDir, manifest);
|
||||
throw new Error(`Stage ${stageName} ${evaluation.outcome}: ${evaluation.reason}`);
|
||||
}
|
||||
|
||||
saveManifest(runDir, manifest);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Run the Forge pipeline.
|
||||
*
|
||||
* 1. Classify the brief
|
||||
* 2. Generate a run ID and create run directory
|
||||
* 3. Map stages to tasks and submit to TaskExecutor
|
||||
* 4. Track manifest with stage statuses
|
||||
* 5. Return pipeline result
|
||||
* 1. Fail closed unless a real executor is wired or simulation is explicit
|
||||
* 2. Classify the brief
|
||||
* 3. Generate a run ID and create run directory
|
||||
* 4. Map stages to tasks and submit to TaskExecutor
|
||||
* 5. Track manifest with typed stage outcomes
|
||||
* 6. Return pipeline result
|
||||
*/
|
||||
export async function runPipeline(
|
||||
briefPath: string,
|
||||
projectRoot: string,
|
||||
options: PipelineOptions,
|
||||
): Promise<PipelineResult> {
|
||||
const simulate = options.simulate ?? false;
|
||||
const executor = requireExecutor(options.executor, simulate);
|
||||
const mode: RunMode = simulate ? 'simulated' : 'normal';
|
||||
|
||||
const resolvedRoot = path.resolve(projectRoot);
|
||||
const resolvedBrief = path.resolve(briefPath);
|
||||
const briefContent = fs.readFileSync(resolvedBrief, 'utf-8');
|
||||
@@ -146,6 +342,7 @@ export async function runPipeline(
|
||||
briefClass,
|
||||
classSource,
|
||||
forceBoard: options.forceBoard ?? false,
|
||||
mode,
|
||||
runDir,
|
||||
});
|
||||
|
||||
@@ -172,54 +369,10 @@ export async function runPipeline(
|
||||
}
|
||||
|
||||
// Execute stages
|
||||
const { executor } = options;
|
||||
for (let i = 0; i < tasks.length; i++) {
|
||||
const task = tasks[i]!;
|
||||
const stageName = selectedStages[i]!;
|
||||
await executeStages({ manifest, runDir, tasks, stageNames: selectedStages, executor, simulate });
|
||||
|
||||
// Update manifest: stage in progress
|
||||
manifest.currentStage = stageName;
|
||||
manifest.stages[stageName] = {
|
||||
status: 'in_progress',
|
||||
startedAt: nowISO(),
|
||||
};
|
||||
saveManifest(runDir, manifest);
|
||||
|
||||
try {
|
||||
await executor.submitTask(task);
|
||||
const result = await executor.waitForCompletion(task.id, task.timeoutSeconds * 1000);
|
||||
|
||||
// Update manifest: stage completed or failed
|
||||
const stageStatus: StageStatus = {
|
||||
status: result.status === 'completed' ? 'passed' : 'failed',
|
||||
startedAt: manifest.stages[stageName]!.startedAt,
|
||||
completedAt: nowISO(),
|
||||
};
|
||||
manifest.stages[stageName] = stageStatus;
|
||||
|
||||
if (result.status !== 'completed') {
|
||||
manifest.status = 'failed';
|
||||
saveManifest(runDir, manifest);
|
||||
throw new Error(`Stage ${stageName} failed with status: ${result.status}`);
|
||||
}
|
||||
|
||||
saveManifest(runDir, manifest);
|
||||
} catch (error) {
|
||||
if (!manifest.stages[stageName]?.completedAt) {
|
||||
manifest.stages[stageName] = {
|
||||
status: 'failed',
|
||||
startedAt: manifest.stages[stageName]?.startedAt,
|
||||
completedAt: nowISO(),
|
||||
};
|
||||
}
|
||||
manifest.status = 'failed';
|
||||
saveManifest(runDir, manifest);
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
|
||||
// All stages passed
|
||||
manifest.status = 'completed';
|
||||
// All stages reached a terminal state for this mode
|
||||
manifest.status = simulate ? 'simulated' : 'completed';
|
||||
saveManifest(runDir, manifest);
|
||||
|
||||
return {
|
||||
@@ -234,22 +387,30 @@ export async function runPipeline(
|
||||
}
|
||||
|
||||
/**
|
||||
* Resume a pipeline from the last incomplete stage.
|
||||
* Resume a pipeline from the last non-passed stage.
|
||||
*/
|
||||
export async function resumePipeline(
|
||||
runDir: string,
|
||||
executor: TaskExecutor,
|
||||
executor?: TaskExecutor,
|
||||
options?: { simulate?: boolean },
|
||||
): Promise<PipelineResult> {
|
||||
const simulate = options?.simulate ?? false;
|
||||
const wiredExecutor = requireExecutor(executor, simulate);
|
||||
const mode: RunMode = simulate ? 'simulated' : 'normal';
|
||||
|
||||
const manifest = loadManifest(runDir);
|
||||
const resolvedRoot = path.dirname(path.dirname(path.dirname(runDir))); // .forge/runs/{id} → project root
|
||||
|
||||
const briefContent = fs.readFileSync(manifest.brief, 'utf-8');
|
||||
const allStages = stagesForClass(manifest.briefClass, manifest.forceBoard);
|
||||
|
||||
// Find first non-passed stage
|
||||
manifest.mode = mode;
|
||||
|
||||
// Find first non-satisfying stage (only a verified `passed` counts as done;
|
||||
// simulated and waiting-for-authority stages are re-run).
|
||||
const resumeFrom = allStages.find((s) => manifest.stages[s]?.status !== 'passed');
|
||||
if (!resumeFrom) {
|
||||
manifest.status = 'completed';
|
||||
manifest.status = mode === 'simulated' ? 'simulated' : 'completed';
|
||||
saveManifest(runDir, manifest);
|
||||
return {
|
||||
runId: manifest.runId,
|
||||
@@ -284,49 +445,16 @@ export async function resumePipeline(
|
||||
tasks.push(task);
|
||||
}
|
||||
|
||||
for (let i = 0; i < tasks.length; i++) {
|
||||
const task = tasks[i]!;
|
||||
const stageName = remainingStages[i]!;
|
||||
await executeStages({
|
||||
manifest,
|
||||
runDir,
|
||||
tasks,
|
||||
stageNames: remainingStages,
|
||||
executor: wiredExecutor,
|
||||
simulate,
|
||||
});
|
||||
|
||||
manifest.currentStage = stageName;
|
||||
manifest.stages[stageName] = {
|
||||
status: 'in_progress',
|
||||
startedAt: nowISO(),
|
||||
};
|
||||
saveManifest(runDir, manifest);
|
||||
|
||||
try {
|
||||
await executor.submitTask(task);
|
||||
const result = await executor.waitForCompletion(task.id, task.timeoutSeconds * 1000);
|
||||
|
||||
manifest.stages[stageName] = {
|
||||
status: result.status === 'completed' ? 'passed' : 'failed',
|
||||
startedAt: manifest.stages[stageName]!.startedAt,
|
||||
completedAt: nowISO(),
|
||||
};
|
||||
|
||||
if (result.status !== 'completed') {
|
||||
manifest.status = 'failed';
|
||||
saveManifest(runDir, manifest);
|
||||
throw new Error(`Stage ${stageName} failed with status: ${result.status}`);
|
||||
}
|
||||
|
||||
saveManifest(runDir, manifest);
|
||||
} catch (error) {
|
||||
if (!manifest.stages[stageName]?.completedAt) {
|
||||
manifest.stages[stageName] = {
|
||||
status: 'failed',
|
||||
startedAt: manifest.stages[stageName]?.startedAt,
|
||||
completedAt: nowISO(),
|
||||
};
|
||||
}
|
||||
manifest.status = 'failed';
|
||||
saveManifest(runDir, manifest);
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
|
||||
manifest.status = 'completed';
|
||||
manifest.status = simulate ? 'simulated' : 'completed';
|
||||
saveManifest(runDir, manifest);
|
||||
|
||||
return {
|
||||
|
||||
@@ -0,0 +1,32 @@
|
||||
import type { ForgeTask, ForgeTaskResult, TaskExecutor } from './types.js';
|
||||
|
||||
/**
|
||||
* Simulated executor — used ONLY when the caller explicitly passes --simulate.
|
||||
*
|
||||
* It submits no real work and returns typed `simulated` results so a simulated
|
||||
* run can never be confused with a verified one. In normal mode (no --simulate)
|
||||
* the CLI refuses to run at all with FORGE_NO_EXECUTOR instead of wiring this
|
||||
* stub (fail closed, SDLC-D-035).
|
||||
*/
|
||||
export function createSimulatedExecutor(options?: { log?: boolean }): TaskExecutor {
|
||||
const log = options?.log ?? true;
|
||||
return {
|
||||
async submitTask(task: ForgeTask) {
|
||||
if (log) console.log(` [forge:simulated] stage submitted: ${task.id} (${task.title})`);
|
||||
},
|
||||
async waitForCompletion(taskId: string): Promise<ForgeTaskResult> {
|
||||
if (log) console.log(` [forge:simulated] stage complete: ${taskId}`);
|
||||
return {
|
||||
task_id: taskId,
|
||||
outcome: 'simulated',
|
||||
reason: 'no executor wired; simulated execution requested via --simulate',
|
||||
completed_at: new Date().toISOString(),
|
||||
exit_code: 0,
|
||||
gate_results: [],
|
||||
};
|
||||
},
|
||||
async getTaskStatus() {
|
||||
return 'completed' as const;
|
||||
},
|
||||
};
|
||||
}
|
||||
@@ -1,4 +1,4 @@
|
||||
import type { GateEntry, TaskResult } from '@mosaicstack/macp';
|
||||
import type { GateEntry } from '@mosaicstack/macp';
|
||||
|
||||
/** Stage dispatch mode. */
|
||||
export type StageDispatch = 'exec' | 'yolo' | 'pi';
|
||||
@@ -6,6 +6,58 @@ export type StageDispatch = 'exec' | 'yolo' | 'pi';
|
||||
/** Stage type — determines agent selection and gate requirements. */
|
||||
export type StageType = 'research' | 'review' | 'coding' | 'deploy';
|
||||
|
||||
/**
|
||||
* Typed outcome for every gate and stage evaluation — closed set (SDLC-D-035).
|
||||
*
|
||||
* Only `passed` means "verified by a real implementation". `simulated` is
|
||||
* produced exclusively in explicit `--simulate` runs and is never satisfying.
|
||||
*/
|
||||
export type ForgeOutcome =
|
||||
| 'passed'
|
||||
| 'failed'
|
||||
| 'blocked'
|
||||
| 'error'
|
||||
| 'waiting-for-authority'
|
||||
| 'simulated'
|
||||
| 'not-applicable';
|
||||
|
||||
/** A gate that requires authority (human/board) sign-off; no mechanical command can satisfy it. */
|
||||
export interface AuthorityGate {
|
||||
kind: 'authority';
|
||||
capability: string;
|
||||
reason: string;
|
||||
}
|
||||
|
||||
/** A gate that requires a wired provider (e.g. an AI reviewer, CI pipeline) to evaluate. */
|
||||
export interface ProviderGate {
|
||||
kind: 'provider';
|
||||
capability: string;
|
||||
reason: string;
|
||||
}
|
||||
|
||||
/** Forge quality gate: a real command, an authority sign-off, or a provider-backed check. */
|
||||
export type ForgeGate = string | GateEntry | AuthorityGate | ProviderGate;
|
||||
|
||||
/** Typed result of evaluating a single quality gate. */
|
||||
export interface ForgeGateResult {
|
||||
gate: string;
|
||||
outcome: ForgeOutcome;
|
||||
reason: string;
|
||||
exitCode?: number;
|
||||
output?: string;
|
||||
timedOut?: boolean;
|
||||
}
|
||||
|
||||
/** Typed result of a task/stage execution returned by a TaskExecutor. */
|
||||
export interface ForgeTaskResult {
|
||||
task_id: string;
|
||||
outcome: ForgeOutcome;
|
||||
reason: string;
|
||||
completed_at: string;
|
||||
exit_code: number;
|
||||
gate_results: ForgeGateResult[];
|
||||
}
|
||||
|
||||
/** Stage specification — defines a single pipeline stage. */
|
||||
export interface StageSpec {
|
||||
number: string;
|
||||
@@ -14,7 +66,7 @@ export interface StageSpec {
|
||||
type: StageType;
|
||||
gate: string;
|
||||
promptFile: string;
|
||||
qualityGates: (string | GateEntry)[];
|
||||
qualityGates: ForgeGate[];
|
||||
}
|
||||
|
||||
/** Brief classification. */
|
||||
@@ -25,11 +77,18 @@ export type ClassSource = 'cli' | 'frontmatter' | 'auto';
|
||||
|
||||
/** Per-stage status within a run manifest. */
|
||||
export interface StageStatus {
|
||||
status: 'pending' | 'in_progress' | 'passed' | 'failed';
|
||||
status: 'pending' | 'in_progress' | ForgeOutcome;
|
||||
/** Why the stage reached its current (terminal) outcome, when applicable. */
|
||||
reason?: string;
|
||||
startedAt?: string;
|
||||
completedAt?: string;
|
||||
/** Typed per-gate results recorded alongside the stage outcome. */
|
||||
gateResults?: ForgeGateResult[];
|
||||
}
|
||||
|
||||
/** Execution mode of a run. */
|
||||
export type RunMode = 'normal' | 'simulated';
|
||||
|
||||
/** Run manifest — persisted to disk as manifest.json. */
|
||||
export interface RunManifest {
|
||||
runId: string;
|
||||
@@ -38,10 +97,23 @@ export interface RunManifest {
|
||||
briefClass: BriefClass;
|
||||
classSource: ClassSource;
|
||||
forceBoard: boolean;
|
||||
/**
|
||||
* Execution mode. `simulated` runs stub execution; their results are typed
|
||||
* `simulated` and must never be read as verified success. Optional because
|
||||
* manifests written before this field existed default to `normal`.
|
||||
*/
|
||||
mode?: RunMode;
|
||||
createdAt: string;
|
||||
updatedAt: string;
|
||||
currentStage: string;
|
||||
status: 'in_progress' | 'completed' | 'failed' | 'interrupted' | 'rejected';
|
||||
status:
|
||||
| 'in_progress'
|
||||
| 'completed'
|
||||
| 'failed'
|
||||
| 'interrupted'
|
||||
| 'rejected'
|
||||
| 'simulated'
|
||||
| 'waiting-for-authority';
|
||||
stages: Record<string, StageStatus>;
|
||||
}
|
||||
|
||||
@@ -65,7 +137,7 @@ export interface ForgeTask {
|
||||
briefPath: string;
|
||||
resultPath: string;
|
||||
timeoutSeconds: number;
|
||||
qualityGates: (string | GateEntry)[];
|
||||
qualityGates: ForgeGate[];
|
||||
worktree?: string;
|
||||
command?: string;
|
||||
dependsOn?: string[];
|
||||
@@ -76,7 +148,7 @@ export interface ForgeTask {
|
||||
/** Abstract task executor — decouples from packages/coord. */
|
||||
export interface TaskExecutor {
|
||||
submitTask(task: ForgeTask): Promise<void>;
|
||||
waitForCompletion(taskId: string, timeoutMs: number): Promise<TaskResult>;
|
||||
waitForCompletion(taskId: string, timeoutMs: number): Promise<ForgeTaskResult>;
|
||||
getTaskStatus(taskId: string): Promise<ForgeTaskStatus>;
|
||||
}
|
||||
|
||||
@@ -122,7 +194,16 @@ export interface PipelineOptions {
|
||||
stages?: string[];
|
||||
skipTo?: string;
|
||||
dryRun?: boolean;
|
||||
executor: TaskExecutor;
|
||||
/**
|
||||
* Real task executor. Required in normal mode: the pipeline fails closed
|
||||
* with FORGE_NO_EXECUTOR when it is absent.
|
||||
*/
|
||||
executor?: TaskExecutor;
|
||||
/**
|
||||
* Explicit opt-in to simulated execution. Every stage and gate result is
|
||||
* typed `simulated` and is never satisfying.
|
||||
*/
|
||||
simulate?: boolean;
|
||||
}
|
||||
|
||||
/** Pipeline run result. */
|
||||
|
||||
Reference in New Issue
Block a user