Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
 tiny
|
133c3b67f7 |
@@ -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 ? (
|
||||
|
||||
+14
-12
@@ -115,18 +115,19 @@ gateway-backed agent catalog.
|
||||
|
||||
### Normative requirements
|
||||
|
||||
| ID | Requirement |
|
||||
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `FCM-REQ-01` | The roster SHALL be the sole writable desired-state source for local fleet membership, launch policy, and persisted lifecycle target. Generated environment files, systemd enablement, tmux sessions, and heartbeat state SHALL be non-authoritative projections. |
|
||||
| `FCM-REQ-02` | The implementation SHALL provide one executable structural contract for YAML/JSON input and one shared semantic validator. Roster load, profile validation, provision, migration, and apply SHALL reuse the existing baseline-plus-`roles.local` profile/persona resolver; a parallel role resolver is forbidden. |
|
||||
| `FCM-REQ-03` | The local fleet CLI SHALL expose documented programmatic validate, show, plan, apply/reconcile, create, inspect, update, delete, start, stop, restart, status, verify, and doctor operations with stable JSON and exit-code behavior. Existing `fleet add/remove` compatibility aliases may remain during the stated deprecation window. |
|
||||
| `FCM-REQ-04` | A fresh create SHALL persist `enabled:true` and `desired_state:stopped` unless an explicit persisted start is requested. The model SHALL distinguish enabled state, persisted desired state, and observed state. Migration, apply, reboot, and rollback SHALL not start an agent that was observed stopped before cutover. |
|
||||
| `FCM-REQ-05` | The launch chain SHALL consume deterministic, digest-stamped generated input only. Optional local overrides SHALL be parsed as strict data, may not shadow authoritative generated keys, and may not contain arbitrary commands, credential values, channels, or unknown `MOSAIC_AGENT_*` keys. Forbidden legacy keys, including `MOSAIC_AGENT_COMMAND`, SHALL be privately quarantined before launch and reported only by key name and content hash. |
|
||||
| `FCM-REQ-06` | Mutations and apply SHALL validate before mutation, use an expected generation/lock, write projections atomically, produce a deterministic plan, and emit recovery information on partial failure. Reconciliation SHALL act only on local, enabled, roster-owned projections and SHALL not kill unmanaged tmux sessions by fuzzy name. |
|
||||
| `FCM-REQ-07` | Canonical required classes are `code`, `review`, `validator`, `orchestrator`, `team-leader`, `enhancer`, and `interaction`. `validator` issues an independent final certificate but has no merge authority; `merge-gate` remains sole approve-to-land/merge authority. Team-leader capacity is bounded by an orchestrator-issued lease, and interaction is request/status only. Tess and Ultron are configurable instance/display names, not required machine identities. |
|
||||
| `FCM-REQ-08` | v1 migration SHALL be field-complete, reversible, and explicit about aliases, unresolved classes, lifecycle inference, generated-file regeneration, local override quarantine, schema-only remote/connector fields, and rollback. Every shipped example, profile, and service preset SHALL be migrated and executable, retained as an explicitly versioned v1 fixture, or retired with a replacement and deprecation note. |
|
||||
| `FCM-REQ-09` | M1–M5 SHALL remain local tmux/systemd control-plane work. Remote/SSH reconciliation, connector mutation, secret references, arbitrary command/channel overrides, gateway/API convergence, and UI configuration storage are excluded and require a separate PRD/threat model. |
|
||||
| `FCM-REQ-10` | Documentation and examples are delivery gates. The M0 checklist at [docs/fleet/FLEET-CONFIG-DOCS-IA-CHECKLIST.md](./fleet/FLEET-CONFIG-DOCS-IA-CHECKLIST.md) and the baseline disposition inventory at [docs/fleet/LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md](./fleet/LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md) SHALL be maintained as acceptance evidence. |
|
||||
| ID | Requirement |
|
||||
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `FCM-REQ-01` | The roster SHALL be the sole writable desired-state source for local fleet membership, launch policy, and persisted lifecycle target. Generated environment files, systemd enablement, tmux sessions, and heartbeat state SHALL be non-authoritative projections. |
|
||||
| `FCM-REQ-02` | The implementation SHALL provide one executable structural contract for YAML/JSON input and one shared semantic validator. Roster load, profile validation, provision, migration, and apply SHALL reuse the existing baseline-plus-`roles.local` profile/persona resolver; a parallel role resolver is forbidden. |
|
||||
| `FCM-REQ-03` | The local fleet CLI SHALL expose documented programmatic validate, show, plan, apply/reconcile, create, inspect, update, delete, start, stop, restart, status, verify, and doctor operations with stable JSON and exit-code behavior. Existing `fleet add/remove` compatibility aliases may remain during the stated deprecation window. |
|
||||
| `FCM-REQ-04` | A fresh create SHALL persist `enabled:true` and `desired_state:stopped` unless an explicit persisted start is requested. The model SHALL distinguish enabled state, persisted desired state, and observed state. Migration, apply, reboot, and rollback SHALL not start an agent that was observed stopped before cutover. |
|
||||
| `FCM-REQ-05` | The launch chain SHALL consume deterministic, digest-stamped generated input only. Optional local overrides SHALL be parsed as strict data, may not shadow authoritative generated keys, and may not contain arbitrary commands, credential values, channels, or unknown `MOSAIC_AGENT_*` keys. Forbidden legacy keys, including `MOSAIC_AGENT_COMMAND`, SHALL be privately quarantined before launch and reported only by key name and content hash. |
|
||||
| `FCM-REQ-06` | Mutations and apply SHALL validate before mutation, use an expected generation/lock, write projections atomically, produce a deterministic plan, and emit recovery information on partial failure. Reconciliation SHALL act only on local, enabled, roster-owned projections and SHALL not kill unmanaged tmux sessions by fuzzy name. |
|
||||
| `FCM-REQ-07` | Canonical required classes are `code`, `review`, `validator`, `orchestrator`, `team-leader`, `enhancer`, and `interaction`. `validator` issues an independent final certificate but has no merge authority; `merge-gate` remains sole approve-to-land/merge authority. Team-leader capacity is bounded by an orchestrator-issued lease, and interaction is request/status only. Tess and Ultron are configurable instance/display names, not required machine identities. |
|
||||
| `FCM-REQ-08` | v1 migration SHALL be field-complete, reversible, and explicit about aliases, unresolved classes, lifecycle inference, generated-file regeneration, local override quarantine, schema-only remote/connector fields, and rollback. Every shipped example, profile, and service preset SHALL be migrated and executable, retained as an explicitly versioned v1 fixture, or retired with a replacement and deprecation note. |
|
||||
| `FCM-REQ-09` | M1–M5 SHALL remain local tmux/systemd control-plane work. Remote/SSH reconciliation, connector mutation, secret references, arbitrary command/channel overrides, gateway/API convergence, and UI configuration storage are excluded and require a separate PRD/threat model. |
|
||||
| `FCM-REQ-10` | Documentation and examples are delivery gates. The M0 checklist at [docs/fleet/FLEET-CONFIG-DOCS-IA-CHECKLIST.md](./fleet/FLEET-CONFIG-DOCS-IA-CHECKLIST.md) and the baseline disposition inventory at [docs/fleet/LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md](./fleet/LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md) SHALL be maintained as acceptance evidence. |
|
||||
| `FCM-REQ-11` | Fleet provisioning SHALL validate the fleet CLI and distinct runtimes requested by the roster against the exact PATH construction used by the runtime pane, through one shared implementation rather than the operator PATH or a parallel PATH model. Name resolution alone is insufficient: a resolved script's shebang interpreter SHALL also be reachable, and Node SHALL execute a side-effect-free version probe when it is that interpreter. `fleet install` and `install-systemd` SHALL fail before installation effects when a required executable is absent or unreachable. `fleet doctor` SHALL emit the same named checks as non-green evidence. Every runtime failure SHALL name the runtime, all requesting roster rows, the pane PATH searched, and an exact install command. |
|
||||
|
||||
### Acceptance criteria
|
||||
|
||||
@@ -138,6 +139,7 @@ gateway-backed agent catalog.
|
||||
6. `AC-FCM-06`: A v1 roster migration previews field-by-field disposition, preserves observed stopped/running state, inventories rather than reconciles remote/schema-only entries, supports a canary and rollback, and classifies every shipped example, profile, and service preset according to the M0 inventory.
|
||||
7. `AC-FCM-07`: Required role authority is validated: validator certificate is consumed but does not merge, merge-gate is the sole merge authority, team-leader leases do not change roster/credentials/authority, and interaction/Tess cannot claim orchestration or merge powers.
|
||||
8. `AC-FCM-08`: Documentation, examples, migration, troubleshooting, operational recovery, package/update asset drift, schema/example/profile validation, independent code/security review, validator certificate, and terminal-green CI are complete before #758 closes.
|
||||
9. `AC-FCM-09`: Red-first isolated tests create (a) a roster whose runtime exists on the operator PATH but is absent from the constructed pane PATH and (b) a greenfield pane where `mosaic` and a runtime resolve as Node-shebang scripts while Node is absent. They prove `fleet install` fails before effects, the launcher creates no doomed session, and `fleet doctor` reports named non-green checks. Diagnostics include the executable or runtime, all requesting rows, searched pane PATH, shebang dependency when present, and exact runtime install command; repeated rows are checked once per distinct runtime/effective pane path. Tests use temporary `--mosaic-home` state and fixture binaries, never host runtime mutation.
|
||||
|
||||
### M0 implementation gate
|
||||
|
||||
|
||||
@@ -59,6 +59,28 @@ valid allowed local data can move to `.env.local`; invalid legacy input is priva
|
||||
Diagnostics expose only rule code, key name, and a SHA-256 content hash. They do not reveal command
|
||||
text, credentials, or other values.
|
||||
|
||||
## Pane executable preflight
|
||||
|
||||
The fleet install, install-systemd, and doctor commands plus the session launcher use
|
||||
**pane-runtime-path.sh** as the single pane-PATH implementation. Install inspects every distinct
|
||||
roster runtime and effective MOSAIC_RUNTIME_BIN pair before creating holder identity, tool,
|
||||
projection, or unit files. Doctor reports the same checks as JSON.
|
||||
|
||||
A resolved command is not automatically executable. The helper reads a script shebang, unwraps the
|
||||
common “/usr/bin/env node” and “/usr/bin/env -S node …” forms, then resolves the declared command
|
||||
against the pane PATH. When Node is the declared interpreter, the helper runs the side-effect-free
|
||||
“node --version” probe. It does not run “mosaic --version”, whose startup update check can write cache
|
||||
state. Native binaries have no PATH-resolved shebang dependency and retain their normal executable
|
||||
check. Failures name the executable or runtime, requesting roster rows, searched pane PATH,
|
||||
dependency, and runtime install command.
|
||||
|
||||
Supported runtime install commands are:
|
||||
|
||||
- **Claude:** curl -fsSL https://claude.ai/install.sh | bash
|
||||
- **Codex:** npm install -g @openai/codex
|
||||
- **OpenCode:** npm install -g opencode-ai
|
||||
- **Pi:** npm install -g @earendil-works/pi-coding-agent
|
||||
|
||||
## Launch and stop behavior
|
||||
|
||||
The launcher obtains the agent's socket only from the validated generated projection. It creates or
|
||||
|
||||
@@ -0,0 +1,71 @@
|
||||
# #1256 — Fleet runtime preflight
|
||||
|
||||
**Agent:** tiny
|
||||
|
||||
**Branch:** `fix/1256-fleet-runtime-preflight` from `origin/next@476db12b92971634b67fd2057b7577ee5894e449`
|
||||
|
||||
**Issue:** `mosaicstack/stack#1256` blocker 1
|
||||
|
||||
**Adjacent PR:** `#1258` (`fix/1256-fleet-pane-path-node`) owns the bootstrapped-Node candidate and must remain a separate change
|
||||
|
||||
**Budget:** 30K-token soft cap; one bounded implementation lane
|
||||
|
||||
## Objective
|
||||
|
||||
Make fleet provisioning fail before installation effects when the roster names a runtime binary absent from the exact PATH the tmux pane will receive. Make `mosaic fleet doctor` report the same named runtime check. Diagnostics must name the runtime, every requesting roster row, the pane PATH searched, and an exact install command.
|
||||
|
||||
For Pi the exact command is:
|
||||
|
||||
```text
|
||||
npm install -g @earendil-works/pi-coding-agent
|
||||
```
|
||||
|
||||
## Constraints
|
||||
|
||||
- TDD: add the failing behavior test and capture RED before implementation.
|
||||
- Runtime resolution uses the launcher's pane-PATH construction; a second PATH model is forbidden.
|
||||
- Operator PATH is non-authoritative and must not cause a false pass.
|
||||
- Tests use an isolated `--mosaic-home`/temporary HOME and never mutate host runtime binaries.
|
||||
- No install, removal, or binary-resolution changes on sb-it-1-dt.
|
||||
- PR targets `next` and requires a reviewer other than fred.
|
||||
- Commit identity is `tiny <[email protected]>`.
|
||||
- #1258's Node candidate is a dependency/adjacent change, never reimplemented here.
|
||||
|
||||
## Planned seam
|
||||
|
||||
1. Factor the shell pane-path builder/resolver into one sourceable and executable fleet helper.
|
||||
2. Have `start-agent-session.sh` source that helper, preserving one definition of the pane PATH.
|
||||
3. Have the TypeScript fleet command invoke the same helper under the unit-equivalent clean launcher environment.
|
||||
4. Group roster rows by distinct runtime and effective pane PATH, then report requesting row names.
|
||||
5. Run the preflight before `installFleet` performs any write.
|
||||
6. Add the named result to roster-v2 `fleet doctor` JSON and set a failing exit when a runtime is absent.
|
||||
7. Install/copy the helper alongside `start-agent-session.sh` and update framework manifest/docs as required.
|
||||
|
||||
This seam overlaps #1258 only at the location of the existing shell function. Development may use #1258 as a local dependency, but the final PR diff must exclude #1258's separately owned Node change after that PR lands or after an agreed rebase order.
|
||||
|
||||
## Acceptance evidence
|
||||
|
||||
| Requirement | Evidence |
|
||||
|---|---|
|
||||
| Missing Pi blocks install before effects | isolated CLI test: nonzero + no installed files/runner effects |
|
||||
| Operator PATH cannot create false green | test puts Pi only on operator PATH and omits it from constructed pane PATH |
|
||||
| Exact pane PATH reused | launcher and CLI call one shared shell helper; contract test exercises both |
|
||||
| Actionable diagnosis | runtime + roster rows + searched PATH + exact install command assertions |
|
||||
| Distinct runtimes | repeated rows produce one check with all row names |
|
||||
| Doctor reports named check | JSON assertion + nonzero exit for missing runtime |
|
||||
| Present runtime passes | isolated pane-path fixture with executable binary |
|
||||
| No host mutation | tests use temporary HOME/Mosaic home and fixture binaries only |
|
||||
| Baseline safety | focused tests, package typecheck/lint/format, full relevant suite, CI |
|
||||
|
||||
## Progress log
|
||||
|
||||
- 2026-08-16: Dispatch received from fred; issue #1256 and PR #1258 measured.
|
||||
- 2026-08-16: Fresh clone created under `~/agent-work/tiny-fleet-runtime-preflight`; local Git identity pinned to tiny so retired global `mos-dt-0` identity cannot win.
|
||||
- 2026-08-16: Design inspection found the pane PATH exists only inside `start-agent-session.sh`; the right seam is a shared shell helper rather than a parallel TypeScript reconstruction.
|
||||
- 2026-08-16: RED measured on `origin/next@476db12b`: focused `fleet-roster-v2-dispatch.spec.ts` ran 11 tests; the new case failed because install returned success, wrote units for two agents, and emitted no `runtime=pi` diagnosis while Pi existed only on operator PATH.
|
||||
- 2026-08-16: Factored pane home/PATH/resolution into sourceable and executable `pane-runtime-path.sh`; install invokes it before the first effect, doctor emits the same named checks, and the launcher sources it.
|
||||
- 2026-08-16: Fred/rhodey review exposed the #1241 name-resolution blind spot: `mosaic` can resolve while its `#!/usr/bin/env node` interpreter cannot. Measurement confirmed every supported current Mosaic package shape is a Node-shebang script, but executing `mosaic --version` is not observational because CLI startup runs the cache-writing/network update checker before Commander handles the flag.
|
||||
- 2026-08-16: Final executable check reads and unwraps direct and `/usr/bin/env` shebangs (including `env -S`), resolves the declared dependency against pane PATH, and runs only side-effect-free `node --version` when Node is declared. Native binaries do not inherit a permanent Node requirement. Install, doctor, and launcher share this implementation.
|
||||
- 2026-08-16: Isolated greenfield fixture places resolved Mosaic and Pi Node-shebang scripts in pane-visible npm-global bin while using an empty system suffix; both checks become `unexecutable` with `dependency=node`, and install leaves holder/tools/units absent. No host binary or HOME is changed.
|
||||
- 2026-08-16: GREEN evidence before #1258 rebase: focused install/doctor/preflight suites pass; `fleet.spec.ts` 209/209; full Vitest 87 files / 1,557 tests; launcher shell suite, typecheck, lint, build, and focused format check pass. Full framework-shell reaches an unrelated host-measurement drift in unchanged `invariant_r_unittest.py` (expected Pi 0.84.1, host resolves 0.84.2); no invariant was changed in this lane.
|
||||
- 2026-08-16: Merge-order gate remains: `origin/next` is still `476db12b`; #1258 is unmerged at `6dc35e5`. Rebase after it lands, relocate its Node candidate into the helper with explicit provenance, rerun gates, then open the PR to `next` for an independent non-fred review.
|
||||
@@ -51,8 +51,12 @@ See `docs/fleet/reference/generated-env-boundary.md` for the full contract.
|
||||
## Manual canary sequence
|
||||
|
||||
Use the roster and the supported installer; do not pre-create the agent environment directory or
|
||||
edit a generated projection. `mosaic fleet install` validates the roster, installs the units and
|
||||
helpers, and writes private roster-derived projections before any service is started.
|
||||
edit a generated projection. Before it writes any holder identity, tool, projection, or unit file,
|
||||
`mosaic fleet install` validates the fleet CLI and every distinct roster runtime through the exact
|
||||
pane PATH. The shared helper also unwraps `/usr/bin/env` shebangs, so a resolved Node script with no
|
||||
pane-visible Node fails before effects. `mosaic fleet doctor` reports the same named executable
|
||||
checks without mutation. After that preflight, install places the units and helpers and writes private
|
||||
roster-derived projections before any service starts.
|
||||
|
||||
```bash
|
||||
# Create a site-owned canary roster. Inspect an existing roster before using --force.
|
||||
|
||||
+199
@@ -0,0 +1,199 @@
|
||||
#!/usr/bin/env bash
|
||||
# Canonical fleet-pane PATH construction and executable reachability checks.
|
||||
#
|
||||
# This file is both sourceable by start-agent-session.sh and executable by the
|
||||
# fleet CLI preflight. Keep the pane PATH in one implementation: provisioning
|
||||
# checks and the eventual pane must answer the same question.
|
||||
|
||||
mosaic_fleet_pane_home() {
|
||||
local mosaic_home="$1"
|
||||
local fallback_home="$2"
|
||||
case "$mosaic_home" in
|
||||
*/.config/mosaic) printf '%s' "${mosaic_home%/.config/mosaic}" ;;
|
||||
*) printf '%s' "$fallback_home" ;;
|
||||
esac
|
||||
}
|
||||
|
||||
mosaic_fleet_build_runtime_bin_prefix() {
|
||||
local pane_home="$1"
|
||||
local runtime_bin="${2:-}"
|
||||
local candidates=()
|
||||
if [ -n "$runtime_bin" ]; then candidates+=("$runtime_bin"); fi
|
||||
if command -v npm >/dev/null 2>&1; then
|
||||
local npm_prefix
|
||||
npm_prefix=$(npm config get prefix 2>/dev/null) || true
|
||||
if [ -n "$npm_prefix" ]; then candidates+=("${npm_prefix}/bin"); fi
|
||||
fi
|
||||
candidates+=("$pane_home/.npm-global/bin" "$pane_home/.local/bin")
|
||||
|
||||
local prefix="" dir
|
||||
for dir in "${candidates[@]}"; do
|
||||
[ -d "$dir" ] || continue
|
||||
case ":${prefix}:" in *":${dir}:"*) ;; *) prefix="${prefix:+$prefix:}$dir" ;; esac
|
||||
done
|
||||
printf '%s' "$prefix"
|
||||
}
|
||||
|
||||
mosaic_fleet_build_pane_path() {
|
||||
local pane_home="$1"
|
||||
local runtime_bin="${2:-}"
|
||||
local system_path="${3:-/usr/local/bin:/usr/bin:/bin}"
|
||||
local prefix
|
||||
prefix=$(mosaic_fleet_build_runtime_bin_prefix "$pane_home" "$runtime_bin")
|
||||
printf '%s' "${prefix:+${prefix}:}${system_path}"
|
||||
}
|
||||
|
||||
mosaic_fleet_resolve_in_pane_path() {
|
||||
local pane_path="$1"
|
||||
local binary="$2"
|
||||
PATH="$pane_path" command -v -- "$binary" 2>/dev/null
|
||||
}
|
||||
|
||||
# Sets executable evidence in MOSAIC_FLEET_EXECUTABLE_* and returns nonzero when
|
||||
# a resolved script's shebang interpreter cannot run in the pane. Native/ELF
|
||||
# binaries have no PATH-resolved interpreter dependency and pass the executable
|
||||
# bit check. Node receives an additional side-effect-free `node --version`
|
||||
# execution check; invoking `mosaic --version` itself is intentionally avoided
|
||||
# because Mosaic performs a cache-writing/network update check at CLI startup.
|
||||
mosaic_fleet_check_resolved_executable() {
|
||||
local pane_path="$1"
|
||||
local resolved="$2"
|
||||
MOSAIC_FLEET_EXECUTABLE_DEPENDENCY=""
|
||||
MOSAIC_FLEET_EXECUTABLE_PROBE=""
|
||||
MOSAIC_FLEET_EXECUTABLE_EXIT=""
|
||||
MOSAIC_FLEET_EXECUTABLE_OUTPUT=""
|
||||
|
||||
[ -x "$resolved" ] || {
|
||||
MOSAIC_FLEET_EXECUTABLE_OUTPUT="resolved path is not executable"
|
||||
return 70
|
||||
}
|
||||
|
||||
local magic=""
|
||||
IFS= read -r -n 2 magic < "$resolved" || true
|
||||
[ "$magic" = '#!' ] || return 0
|
||||
|
||||
local shebang
|
||||
IFS= read -r shebang < "$resolved" || true
|
||||
shebang=${shebang%$'\r'}
|
||||
shebang=${shebang#\#!}
|
||||
local parts=()
|
||||
read -r -a parts <<< "$shebang"
|
||||
local interpreter="${parts[0]:-}"
|
||||
[[ "$interpreter" = /* ]] && [ -x "$interpreter" ] || {
|
||||
MOSAIC_FLEET_EXECUTABLE_DEPENDENCY="$interpreter"
|
||||
MOSAIC_FLEET_EXECUTABLE_OUTPUT="shebang interpreter is absent or not executable"
|
||||
return 70
|
||||
}
|
||||
|
||||
local dependency="$interpreter"
|
||||
local dependency_path="$interpreter"
|
||||
if [ "${interpreter##*/}" = env ]; then
|
||||
local index=1
|
||||
if [ "${parts[$index]:-}" = -S ]; then index=$((index + 1)); fi
|
||||
dependency="${parts[$index]:-}"
|
||||
if [ -z "$dependency" ] || [[ "$dependency" = -* ]]; then
|
||||
MOSAIC_FLEET_EXECUTABLE_DEPENDENCY="$dependency"
|
||||
MOSAIC_FLEET_EXECUTABLE_OUTPUT="unsupported env shebang"
|
||||
return 70
|
||||
fi
|
||||
fi
|
||||
|
||||
MOSAIC_FLEET_EXECUTABLE_DEPENDENCY="$dependency"
|
||||
if [ "${dependency##*/}" = node ]; then
|
||||
MOSAIC_FLEET_EXECUTABLE_PROBE="node --version"
|
||||
fi
|
||||
if [ "${interpreter##*/}" = env ]; then
|
||||
if ! dependency_path=$(mosaic_fleet_resolve_in_pane_path "$pane_path" "$dependency"); then
|
||||
MOSAIC_FLEET_EXECUTABLE_OUTPUT="shebang command is not on the pane PATH"
|
||||
return 70
|
||||
fi
|
||||
fi
|
||||
|
||||
if [ "${dependency##*/}" = node ]; then
|
||||
if MOSAIC_FLEET_EXECUTABLE_OUTPUT=$(PATH="$pane_path" "$dependency_path" --version 2>&1); then
|
||||
MOSAIC_FLEET_EXECUTABLE_EXIT=0
|
||||
else
|
||||
MOSAIC_FLEET_EXECUTABLE_EXIT=$?
|
||||
return 70
|
||||
fi
|
||||
fi
|
||||
return 0
|
||||
}
|
||||
|
||||
mosaic_fleet_runtime_path_main() {
|
||||
local mosaic_home=""
|
||||
local runtime_bin=""
|
||||
local system_path="/usr/local/bin:/usr/bin:/bin"
|
||||
local binary=""
|
||||
local check_executable=0
|
||||
|
||||
while [ "$#" -gt 0 ]; do
|
||||
case "$1" in
|
||||
--mosaic-home)
|
||||
[ "$#" -ge 2 ] || return 64
|
||||
mosaic_home="$2"
|
||||
shift 2
|
||||
;;
|
||||
--runtime-bin)
|
||||
[ "$#" -ge 2 ] || return 64
|
||||
runtime_bin="$2"
|
||||
shift 2
|
||||
;;
|
||||
--binary)
|
||||
[ "$#" -ge 2 ] || return 64
|
||||
binary="$2"
|
||||
shift 2
|
||||
;;
|
||||
--check-executable)
|
||||
check_executable=1
|
||||
shift
|
||||
;;
|
||||
# Test seam for measuring a greenfield host with no system Node. The
|
||||
# launcher and production CLI omit it and retain the fixed system suffix.
|
||||
--system-path)
|
||||
[ "$#" -ge 2 ] || return 64
|
||||
system_path="$2"
|
||||
shift 2
|
||||
;;
|
||||
*) return 64 ;;
|
||||
esac
|
||||
done
|
||||
|
||||
[ -n "$mosaic_home" ] && [ -n "$binary" ] || return 64
|
||||
local pane_home pane_path resolved
|
||||
pane_home=$(mosaic_fleet_pane_home "$mosaic_home" "${HOME:-}")
|
||||
# npm config is HOME-sensitive. Pin it to the derived pane home before asking
|
||||
# for its prefix so an operator's unrelated npmrc cannot influence preflight.
|
||||
HOME=$pane_home
|
||||
export HOME
|
||||
pane_path=$(mosaic_fleet_build_pane_path "$pane_home" "$runtime_bin" "$system_path")
|
||||
if ! resolved=$(mosaic_fleet_resolve_in_pane_path "$pane_path" "$binary"); then
|
||||
printf 'pane_path\0%s\0status\0missing\0binary_path\0\0dependency\0\0probe_command\0\0probe_exit\0\0probe_output\0\0' \
|
||||
"$pane_path"
|
||||
return 69
|
||||
fi
|
||||
|
||||
if [ "$check_executable" -eq 1 ]; then
|
||||
if mosaic_fleet_check_resolved_executable "$pane_path" "$resolved"; then
|
||||
printf 'pane_path\0%s\0status\0present\0binary_path\0%s\0dependency\0%s\0probe_command\0%s\0probe_exit\0%s\0probe_output\0%s\0' \
|
||||
"$pane_path" "$resolved" "$MOSAIC_FLEET_EXECUTABLE_DEPENDENCY" \
|
||||
"$MOSAIC_FLEET_EXECUTABLE_PROBE" "$MOSAIC_FLEET_EXECUTABLE_EXIT" \
|
||||
"$MOSAIC_FLEET_EXECUTABLE_OUTPUT"
|
||||
return 0
|
||||
fi
|
||||
printf 'pane_path\0%s\0status\0unexecutable\0binary_path\0%s\0dependency\0%s\0probe_command\0%s\0probe_exit\0%s\0probe_output\0%s\0' \
|
||||
"$pane_path" "$resolved" "$MOSAIC_FLEET_EXECUTABLE_DEPENDENCY" \
|
||||
"$MOSAIC_FLEET_EXECUTABLE_PROBE" "$MOSAIC_FLEET_EXECUTABLE_EXIT" \
|
||||
"$MOSAIC_FLEET_EXECUTABLE_OUTPUT"
|
||||
return 70
|
||||
fi
|
||||
|
||||
printf 'pane_path\0%s\0status\0present\0binary_path\0%s\0dependency\0\0probe_command\0\0probe_exit\0\0probe_output\0\0' \
|
||||
"$pane_path" "$resolved"
|
||||
return 0
|
||||
}
|
||||
|
||||
if [[ "${BASH_SOURCE[0]}" == "$0" ]]; then
|
||||
set -euo pipefail
|
||||
mosaic_fleet_runtime_path_main "$@"
|
||||
fi
|
||||
@@ -258,46 +258,22 @@ if _tmux has-session -t "=${AGENT_NAME}:0.0" 2>/dev/null; then
|
||||
fi
|
||||
|
||||
# Systemd passes HOME as %h, and the installed service fixes MOSAIC_HOME under
|
||||
# that home. Derive the pane home from the canonical path when available so an
|
||||
# inherited pane/session HOME cannot become runtime authority.
|
||||
PANE_HOME=$HOME
|
||||
case "$MOSAIC_HOME" in
|
||||
*/.config/mosaic) PANE_HOME=${MOSAIC_HOME%/.config/mosaic} ;;
|
||||
esac
|
||||
# that home. The provisioning preflight executes this same helper under the
|
||||
# unit's clean launcher environment, so operator PATH cannot produce a false
|
||||
# green result for a binary the pane will never see.
|
||||
SCRIPT_DIR=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)
|
||||
# shellcheck source=pane-runtime-path.sh
|
||||
. "$SCRIPT_DIR/pane-runtime-path.sh"
|
||||
PANE_HOME=$(mosaic_fleet_pane_home "$MOSAIC_HOME" "$HOME")
|
||||
PANE_PATH=$(mosaic_fleet_build_pane_path "$PANE_HOME" "$MOSAIC_RUNTIME_BIN")
|
||||
|
||||
_build_runtime_bin_prefix() {
|
||||
local candidates=()
|
||||
if [ -n "$MOSAIC_RUNTIME_BIN" ]; then candidates+=("$MOSAIC_RUNTIME_BIN"); fi
|
||||
if command -v npm >/dev/null 2>&1; then
|
||||
local npm_prefix
|
||||
npm_prefix=$(npm config get prefix 2>/dev/null) || true
|
||||
if [ -n "$npm_prefix" ]; then candidates+=("${npm_prefix}/bin"); fi
|
||||
fi
|
||||
candidates+=("$PANE_HOME/.npm-global/bin" "$PANE_HOME/.local/bin")
|
||||
|
||||
local prefix="" dir
|
||||
for dir in "${candidates[@]}"; do
|
||||
[ -d "$dir" ] || continue
|
||||
case ":${prefix}:" in *":${dir}:"*) ;; *) prefix="${prefix:+$prefix:}$dir" ;; esac
|
||||
done
|
||||
printf '%s' "$prefix"
|
||||
}
|
||||
|
||||
MOSAIC_RUNTIME_BIN_PREFIX=$(_build_runtime_bin_prefix)
|
||||
PANE_PATH=${MOSAIC_RUNTIME_BIN_PREFIX:+${MOSAIC_RUNTIME_BIN_PREFIX}:}/usr/local/bin:/usr/bin:/bin
|
||||
|
||||
# #1241. The pane runs `mosaic yolo <runtime>` under PANE_PATH with a cleared
|
||||
# environment. A binary missing from *that* path is a pane that dies in under a
|
||||
# second, inside a session nobody is attached to, with its diagnostic scrolled
|
||||
# into a pane tmux then destroys. Resolve both here, before any effect, where
|
||||
# the failure is still attributable to the thing that caused it.
|
||||
#
|
||||
# `mosaic yolo <runtime>` runs checkRuntime(runtime) and the binary it looks for
|
||||
# is named exactly like the runtime, so resolving the runtime name is the same
|
||||
# question the pane will ask a moment later — asked while an operator can still
|
||||
# see the answer.
|
||||
# #1241/#1256. The pane runs `mosaic yolo <runtime>` under PANE_PATH with a
|
||||
# cleared environment. Resolve both names and validate any shebang interpreter
|
||||
# here, before an effect, where the failure remains attributable. Name
|
||||
# resolution alone is insufficient: an `#!/usr/bin/env node` script resolves
|
||||
# even when the pane cannot execute it because Node is absent.
|
||||
_resolve_in_pane_path() {
|
||||
PATH="$PANE_PATH" command -v -- "$1" 2>/dev/null
|
||||
mosaic_fleet_resolve_in_pane_path "$PANE_PATH" "$1"
|
||||
}
|
||||
|
||||
# Exit 69 (EX_UNAVAILABLE): the seat cannot be provided. Distinguished from the
|
||||
@@ -312,8 +288,15 @@ fail_launch() {
|
||||
}
|
||||
|
||||
for required_binary in mosaic "$MOSAIC_AGENT_RUNTIME"; do
|
||||
_resolve_in_pane_path "$required_binary" >/dev/null ||
|
||||
resolved_binary=$(_resolve_in_pane_path "$required_binary") ||
|
||||
fail_launch missing-binary "'${required_binary}' is not on the pane PATH (${PANE_PATH})"
|
||||
if mosaic_fleet_check_resolved_executable "$PANE_PATH" "$resolved_binary"; then
|
||||
continue
|
||||
else
|
||||
executable_exit=$?
|
||||
fi
|
||||
fail_launch unexecutable-binary \
|
||||
"'${required_binary}' resolves to '${resolved_binary}' but dependency '${MOSAIC_FLEET_EXECUTABLE_DEPENDENCY:-unknown}' is not executable on the pane PATH (${PANE_PATH}); check_exit=${executable_exit} detail=${MOSAIC_FLEET_EXECUTABLE_OUTPUT:-unavailable}"
|
||||
done
|
||||
|
||||
_ensure_claude_workdir_trusted() {
|
||||
|
||||
@@ -484,6 +484,27 @@ assert_missing_pane_binary_rejected() {
|
||||
assert_missing_pane_binary_rejected mosaic
|
||||
assert_missing_pane_binary_rejected pi
|
||||
|
||||
# #1256. Name resolution is not executable reachability. A script can resolve
|
||||
# while its /usr/bin/env shebang command is absent from PANE_PATH; reject that
|
||||
# before tmux creates the doomed session.
|
||||
: > "$TMUX_CALLS"
|
||||
HOME_UNEXECUTABLE="$ROOT/unexecutable-shebang"
|
||||
write_generated "$HOME_UNEXECUTABLE" "coder-unexecutable"
|
||||
rm -f "$HOME_UNEXECUTABLE/.npm-global/bin/mosaic"
|
||||
printf '#!/usr/bin/env mosaic-test-absent-interpreter\n' > \
|
||||
"$HOME_UNEXECUTABLE/.npm-global/bin/mosaic"
|
||||
chmod +x "$HOME_UNEXECUTABLE/.npm-global/bin/mosaic"
|
||||
if output=$(MOSAIC_TEST_PANE_PID=$$ run_start "$HOME_UNEXECUTABLE" coder-unexecutable 2>&1); then
|
||||
fail "launcher accepted a resolved mosaic script with an absent shebang command"
|
||||
fi
|
||||
echo "$output" | grep -qF 'code=unexecutable-binary' || \
|
||||
fail "unexecutable shebang diagnostic missing: $output"
|
||||
echo "$output" | grep -qF 'mosaic-test-absent-interpreter' || \
|
||||
fail "unexecutable shebang diagnostic did not name the missing dependency"
|
||||
if tr '\0' '\n' < "$TMUX_CALLS" | grep -qF new-session; then
|
||||
fail "launcher created a session after its shebang dependency check failed"
|
||||
fi
|
||||
|
||||
# #1241. tmux destroys a session when its pane command exits, so no pane PID a
|
||||
# second after new-session means the runtime died on startup. This used to be a
|
||||
# WARNING about the heartbeat sidecar followed by exit 0 — three layers above it
|
||||
|
||||
@@ -39,20 +39,3 @@ packages/mosaic/framework/tools/tmux/test-send-message-verdict.sh | requires rea
|
||||
# recorded judgement. These lines ARE that judgement, signed.)
|
||||
packages/mosaic/framework/tools/orchestrator/smoke-test.sh | behavior smoke checks for coord continue/run workflows, run manually by orchestrator seats; unmeasured in CI; #1017 burndown
|
||||
packages/mosaic/framework/tools/wake/validate-973/microtest-wake-assert.sh | #973 instrument self-test, run as a precondition of the validate-973 evidence procedure rather than as a standing CI suite; #1017 burndown candidate
|
||||
|
||||
# --- tools/fleet: precondition is unsatisfiable in the CI image (#1271) ---
|
||||
# Signed by fred (sb-it-1-dt, 2026-08-16) at origin/next 476db12.
|
||||
# This suite asserts the launcher's behaviour when `mosaic` and `pi` are MISSING.
|
||||
# It shims fakes into $FAKE_BIN, but the constructed PANE_PATH always ends in the
|
||||
# real system path, so on a host that installs those binaries the missing-binary
|
||||
# cases cannot be measured at all. The suite's own guard (line 103) says so and
|
||||
# fails rather than reporting a pass it cannot back. That guard is correct.
|
||||
# The error was wiring the suite into CI: #1017 (c56483eb) enumerated it and
|
||||
# dropped this exclusion, and the CI image provides `pi` in the system path, so
|
||||
# it has failed on every pipeline since. Measured 2026-08-16 across pipelines
|
||||
# 2444 (#1256), 2438 (#1240) and 2441 (#1017-quality): exactly one FAIL line in
|
||||
# each full log, identical, this assertion; control `zzz-not-present-zzz` -> 0.
|
||||
# Burn-down and the full measurement are tracked in #1271; unwired by PR #1270.
|
||||
# Because test:framework-shell is one && chain and this sat at position 44 of 48,
|
||||
# the four suites after it had not run at all since the merge.
|
||||
packages/mosaic/framework/tools/fleet/test-start-agent-session.sh | precondition unsatisfiable in the CI image: asserts missing-binary behaviour, but PANE_PATH always ends in the system path and the image provides `pi` there; guard at line 103 fails by design rather than passing unmeasured. Burn down by controlling the tail of PANE_PATH inside the test. NOT by removing `pi` from the image: the CI image installs @earendil-works/[email protected] deliberately (measured in pipeline 2444's test-step log), and other suites depend on that pin. Burn-down tracked in #1271
|
||||
|
||||
@@ -25,7 +25,7 @@
|
||||
"lint": "eslint src",
|
||||
"typecheck": "tsc --noEmit",
|
||||
"test": "vitest run --passWithNoTests && pnpm run test:framework-shell",
|
||||
"test:framework-shell": "bash framework/tools/quality/scripts/check-test-enumeration.sh && bash framework/tools/quality/scripts/test-check-test-enumeration.sh && python3 src/lease-broker/daemon_deadline_unittest.py && python3 src/lease-broker/normative_fragments_unittest.py && python3 src/lease-broker/promotion_binding_unittest.py && python3 src/lease-broker/promotion_trigger_unittest.py && python3 src/lease-broker/receipt_challenge_unittest.py && python3 src/lease-broker/context_recovery_unittest.py && python3 src/lease-broker/recovery_runtime_unittest.py && python3 src/lease-broker/recovery_b1_adversarial_unittest.py && python3 src/lease-broker/receipt_observer_client_unittest.py && python3 src/lease-broker/invariant_r_unittest.py && python3 src/lease-broker/framework_skill_portability_unittest.py && python3 src/mutator-gate/runtime_tools_unittest.py && python3 src/mutator-gate/runtime_launch_guard_unittest.py && python3 src/mutator-gate/version_coupling_unittest.py && python3 framework/tools/lease-broker/check-runtime-launches.py --root ../.. && bash framework/tools/codex/test-pr-diff-context.sh && bash framework/tools/qa/test-deps-preflight.sh && bash framework/tools/git/test-pr-review-gitea-comment.sh && bash framework/tools/git/test-pr-review-repo-host-override.sh && bash framework/tools/git/test-ci-queue-wait-branch-absent.sh && bash framework/tools/git/test-ci-queue-wait-tristate.sh && bash framework/tools/git/test-ci-queue-wait-github-checks.sh && bash framework/tools/git/test-pr-merge-queue-branch.sh && bash framework/tools/git/test-pr-merge-head-pin.sh && bash framework/tools/git/test-pr-merge-message-field.sh && bash framework/tools/git/test-git-credential-mosaic.sh && bash framework/tools/git/test-gitea-token-identity.sh && bash framework/tools/woodpecker/test-terminal-green-contract.sh && bash framework/tools/_scripts/test-install-ordering-guard.sh && bash framework/tools/_scripts/test-mosaic-init-rce.sh && bash framework/tools/tmux/agent-send.test.sh && bash framework/tools/wake/test-wake-store-ack.sh && bash framework/tools/wake/test-wake-store-enqueue-race.sh && bash framework/tools/wake/test-wake-digest-hmac.sh && bash framework/tools/wake/test-wake-digest-quarantine.sh && bash framework/tools/wake/test-wake-detector.sh && bash framework/tools/wake/test-wake-fn-oracle.sh && bash framework/tools/wake/test-wake-reconcile.sh && bash framework/tools/wake/test-wake-beacon.sh && bash framework/tools/wake/test-wake-preimage.sh && bash framework/tools/wake/test-wake-install.sh && bash framework/tools/glpi/test-list-http-status.sh && bash framework/tools/orchestrator/test-board-roll.sh && bash framework/tools/woodpecker/test-ci-wait-exit-matrix.sh && bash framework/tools/_scripts/test-fleet-transport-check.sh"
|
||||
"test:framework-shell": "bash framework/tools/quality/scripts/check-test-enumeration.sh && bash framework/tools/quality/scripts/test-check-test-enumeration.sh && python3 src/lease-broker/daemon_deadline_unittest.py && python3 src/lease-broker/normative_fragments_unittest.py && python3 src/lease-broker/promotion_binding_unittest.py && python3 src/lease-broker/promotion_trigger_unittest.py && python3 src/lease-broker/receipt_challenge_unittest.py && python3 src/lease-broker/context_recovery_unittest.py && python3 src/lease-broker/recovery_runtime_unittest.py && python3 src/lease-broker/recovery_b1_adversarial_unittest.py && python3 src/lease-broker/receipt_observer_client_unittest.py && python3 src/lease-broker/invariant_r_unittest.py && python3 src/lease-broker/framework_skill_portability_unittest.py && python3 src/mutator-gate/runtime_tools_unittest.py && python3 src/mutator-gate/runtime_launch_guard_unittest.py && python3 src/mutator-gate/version_coupling_unittest.py && python3 framework/tools/lease-broker/check-runtime-launches.py --root ../.. && bash framework/tools/codex/test-pr-diff-context.sh && bash framework/tools/qa/test-deps-preflight.sh && bash framework/tools/git/test-pr-review-gitea-comment.sh && bash framework/tools/git/test-pr-review-repo-host-override.sh && bash framework/tools/git/test-ci-queue-wait-branch-absent.sh && bash framework/tools/git/test-ci-queue-wait-tristate.sh && bash framework/tools/git/test-ci-queue-wait-github-checks.sh && bash framework/tools/git/test-pr-merge-queue-branch.sh && bash framework/tools/git/test-pr-merge-head-pin.sh && bash framework/tools/git/test-pr-merge-message-field.sh && bash framework/tools/git/test-git-credential-mosaic.sh && bash framework/tools/git/test-gitea-token-identity.sh && bash framework/tools/woodpecker/test-terminal-green-contract.sh && bash framework/tools/_scripts/test-install-ordering-guard.sh && bash framework/tools/_scripts/test-mosaic-init-rce.sh && bash framework/tools/tmux/agent-send.test.sh && bash framework/tools/wake/test-wake-store-ack.sh && bash framework/tools/wake/test-wake-store-enqueue-race.sh && bash framework/tools/wake/test-wake-digest-hmac.sh && bash framework/tools/wake/test-wake-digest-quarantine.sh && bash framework/tools/wake/test-wake-detector.sh && bash framework/tools/wake/test-wake-fn-oracle.sh && bash framework/tools/wake/test-wake-reconcile.sh && bash framework/tools/wake/test-wake-beacon.sh && bash framework/tools/wake/test-wake-preimage.sh && bash framework/tools/wake/test-wake-install.sh && bash framework/tools/fleet/test-start-agent-session.sh && bash framework/tools/glpi/test-list-http-status.sh && bash framework/tools/orchestrator/test-board-roll.sh && bash framework/tools/woodpecker/test-ci-wait-exit-matrix.sh && bash framework/tools/_scripts/test-fleet-transport-check.sh"
|
||||
},
|
||||
"dependencies": {
|
||||
"@mosaicstack/brain": "workspace:*",
|
||||
|
||||
@@ -1,9 +1,13 @@
|
||||
import { chmod, mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
|
||||
import { tmpdir } from 'node:os';
|
||||
import { join } from 'node:path';
|
||||
import { join, resolve } from 'node:path';
|
||||
import { Command } from 'commander';
|
||||
import { afterEach, describe, expect, it, vi } from 'vitest';
|
||||
import { type FleetReconcileDeps } from '../fleet/fleet-reconciler.js';
|
||||
import {
|
||||
type FleetRuntimeProbeResult,
|
||||
type FleetRuntimeProbeRunner,
|
||||
} from '../fleet/fleet-runtime-preflight.js';
|
||||
import { registerFleetCommand, type CommandResult, type FleetCommandDeps } from './fleet.js';
|
||||
|
||||
const roster = `
|
||||
@@ -65,12 +69,15 @@ function program(
|
||||
mosaicHome: string,
|
||||
runner: FleetCommandDeps['runner'],
|
||||
reconcileOverrides: Partial<FleetReconcileDeps> = {},
|
||||
runtimeProbeRunner: FleetRuntimeProbeRunner = runtimeProbe('present'),
|
||||
): Command {
|
||||
const result = new Command();
|
||||
result.exitOverride();
|
||||
registerFleetCommand(result, {
|
||||
mosaicHome,
|
||||
runner,
|
||||
frameworkRoot: resolve(process.cwd(), 'framework'),
|
||||
runtimeProbeRunner,
|
||||
reconcileDeps: {
|
||||
homeDirectory: '/home/mosaic',
|
||||
readHolderIdentity: async () => '11111111-1111-4111-8111-111111111111',
|
||||
@@ -83,6 +90,24 @@ function program(
|
||||
return result;
|
||||
}
|
||||
|
||||
function runtimeProbe(status: 'present' | 'missing'): FleetRuntimeProbeRunner {
|
||||
return async (_command, args): Promise<FleetRuntimeProbeResult> => {
|
||||
const binaryFlag = args.indexOf('--binary');
|
||||
const binary = binaryFlag >= 0 ? args[binaryFlag + 1] : undefined;
|
||||
const effectiveStatus = binary === 'mosaic' ? 'present' : status;
|
||||
return {
|
||||
stdout:
|
||||
`pane_path\u0000/fixture/runtime-bin:/usr/bin:/bin\u0000status\u0000${effectiveStatus}\u0000` +
|
||||
`binary_path\u0000${effectiveStatus === 'present' ? `/fixture/runtime-bin/${binary ?? 'unknown'}` : ''}\u0000` +
|
||||
`dependency\u0000${effectiveStatus === 'present' ? 'node' : ''}\u0000` +
|
||||
`probe_command\u0000${effectiveStatus === 'present' ? 'node --version' : ''}\u0000` +
|
||||
`probe_exit\u0000${effectiveStatus === 'present' ? '0' : ''}\u0000probe_output\u0000\u0000`,
|
||||
stderr: '',
|
||||
exitCode: effectiveStatus === 'present' ? 0 : 69,
|
||||
};
|
||||
};
|
||||
}
|
||||
|
||||
function capture(): string[] {
|
||||
const lines: string[] = [];
|
||||
vi.spyOn(console, 'log').mockImplementation((value: string): void => {
|
||||
@@ -152,13 +177,64 @@ describe('mosaic fleet reconciler commands', (): void => {
|
||||
|
||||
expect(lines.map((line: string): unknown => JSON.parse(line))).toMatchObject([
|
||||
{ applied: false, lifecycle: 'not-applied' },
|
||||
{ applied: false, lifecycle: 'not-applied' },
|
||||
{
|
||||
applied: false,
|
||||
lifecycle: 'not-applied',
|
||||
checks: {
|
||||
fleetCliExecutable: [
|
||||
{
|
||||
check: 'fleet-cli-executable',
|
||||
status: 'ok',
|
||||
requestedBy: ['coder0'],
|
||||
dependency: 'node',
|
||||
probeCommand: 'node --version',
|
||||
},
|
||||
],
|
||||
fleetRuntimeAvailability: [
|
||||
{
|
||||
check: 'fleet-runtime-available',
|
||||
runtime: 'pi',
|
||||
status: 'ok',
|
||||
requestedBy: ['coder0'],
|
||||
},
|
||||
],
|
||||
},
|
||||
},
|
||||
]);
|
||||
expect(
|
||||
calls.every((call: string[]): boolean => call[0] !== 'systemctl' || call[2] === 'show'),
|
||||
).toBe(true);
|
||||
});
|
||||
|
||||
it('reports a missing roster runtime as a named non-green doctor check', async (): Promise<void> => {
|
||||
const home = await fleetHome();
|
||||
const lines = capture();
|
||||
|
||||
await program(home, ownedRunner([]), {}, runtimeProbe('missing')).parseAsync([
|
||||
'node',
|
||||
'mosaic',
|
||||
'fleet',
|
||||
'doctor',
|
||||
]);
|
||||
|
||||
expect(JSON.parse(lines.pop() ?? '')).toMatchObject({
|
||||
applied: false,
|
||||
checks: {
|
||||
fleetRuntimeAvailability: [
|
||||
{
|
||||
check: 'fleet-runtime-available',
|
||||
runtime: 'pi',
|
||||
status: 'missing',
|
||||
requestedBy: ['coder0'],
|
||||
panePath: '/fixture/runtime-bin:/usr/bin:/bin',
|
||||
installCommand: 'npm install -g @earendil-works/pi-coding-agent',
|
||||
},
|
||||
],
|
||||
},
|
||||
});
|
||||
expect(process.exitCode).toBe(1);
|
||||
});
|
||||
|
||||
it.each(['start', 'stop', 'restart'] as const)(
|
||||
'uses exact roster-owned systemd targeting for %s',
|
||||
async (operation: 'start' | 'stop' | 'restart'): Promise<void> => {
|
||||
|
||||
@@ -8,10 +8,18 @@ import {
|
||||
type FleetReconcileCommand,
|
||||
type FleetReconcileDeps,
|
||||
} from '../fleet/fleet-reconciler.js';
|
||||
import {
|
||||
inspectFleetRuntimeAvailability,
|
||||
type FleetRuntimeInspection,
|
||||
type FleetRuntimePreflightCheck,
|
||||
type FleetRuntimeProbeRunner,
|
||||
} from '../fleet/fleet-runtime-preflight.js';
|
||||
import { parseRosterV2 } from '../fleet/roster-v2.js';
|
||||
|
||||
export interface FleetReconcilerCommandDeps {
|
||||
readonly runner: CommandRunner;
|
||||
readonly runtimeProbeRunner?: FleetRuntimeProbeRunner;
|
||||
readonly frameworkRoot?: string;
|
||||
readonly mosaicHome?: string;
|
||||
readonly reconcileDeps?: Omit<FleetReconcileDeps, 'runner' | 'mosaicHome'>;
|
||||
}
|
||||
@@ -71,6 +79,10 @@ export async function executeReconcilerCommand(
|
||||
const mosaicHome = resolveMosaicHome(fleetCommand, deps);
|
||||
const rosterPath = resolveRosterPath(fleetCommand, mosaicHome);
|
||||
const roster = parseRosterV2(await readFile(rosterPath, 'utf8'), 'yaml');
|
||||
const runtimeInspection =
|
||||
operation === 'doctor'
|
||||
? await inspectRuntimeAvailability(roster.agents, mosaicHome, deps)
|
||||
: undefined;
|
||||
const mutating = operation === 'apply' || operation === 'reconcile' || isLifecycle(operation);
|
||||
const expectedGeneration = mutating
|
||||
? parseExpectedGeneration(opts.expectedGeneration)
|
||||
@@ -90,8 +102,31 @@ export async function executeReconcilerCommand(
|
||||
...(deps.reconcileDeps ?? {}),
|
||||
},
|
||||
});
|
||||
printJson(result);
|
||||
process.exitCode = result.recovery === undefined && result.cleanup === undefined ? 0 : 1;
|
||||
printJson(operation === 'doctor' ? { ...result, checks: runtimeInspection } : result);
|
||||
const executableFailure =
|
||||
runtimeInspection !== undefined &&
|
||||
[...runtimeInspection.fleetCliExecutable, ...runtimeInspection.fleetRuntimeAvailability].some(
|
||||
(check: FleetRuntimePreflightCheck): boolean => check.status !== 'ok',
|
||||
);
|
||||
process.exitCode =
|
||||
result.recovery === undefined && result.cleanup === undefined && !executableFailure ? 0 : 1;
|
||||
}
|
||||
|
||||
async function inspectRuntimeAvailability(
|
||||
agents: readonly { readonly name: string; readonly runtime: string }[],
|
||||
mosaicHome: string,
|
||||
deps: FleetReconcilerCommandDeps,
|
||||
): Promise<FleetRuntimeInspection> {
|
||||
if (deps.frameworkRoot === undefined || deps.runtimeProbeRunner === undefined) {
|
||||
throw new Error('Fleet doctor runtime preflight dependencies are unavailable.');
|
||||
}
|
||||
return inspectFleetRuntimeAvailability({
|
||||
mosaicHome,
|
||||
agentEnvDir: join(mosaicHome, 'fleet', 'agents'),
|
||||
helperPath: join(deps.frameworkRoot, 'tools', 'fleet', 'pane-runtime-path.sh'),
|
||||
agents,
|
||||
runner: deps.runtimeProbeRunner,
|
||||
});
|
||||
}
|
||||
|
||||
function isLifecycle(operation: FleetReconcileCommand): boolean {
|
||||
|
||||
@@ -4,6 +4,7 @@ import { tmpdir } from 'node:os';
|
||||
import { join, resolve } from 'node:path';
|
||||
import { Command } from 'commander';
|
||||
import { afterEach, describe, expect, it, vi } from 'vitest';
|
||||
import type { FleetRuntimeProbeRunner } from '../fleet/fleet-runtime-preflight.js';
|
||||
import { registerFleetCommand, type CommandResult, type CommandRunner } from './fleet.js';
|
||||
|
||||
/**
|
||||
@@ -69,6 +70,7 @@ agents:
|
||||
let tempHome: string | undefined;
|
||||
const savedHome = process.env.HOME;
|
||||
const savedMosaicHome = process.env.MOSAIC_HOME;
|
||||
const savedPath = process.env.PATH;
|
||||
|
||||
afterEach(async (): Promise<void> => {
|
||||
vi.restoreAllMocks();
|
||||
@@ -77,6 +79,8 @@ afterEach(async (): Promise<void> => {
|
||||
else process.env.HOME = savedHome;
|
||||
if (savedMosaicHome === undefined) delete process.env.MOSAIC_HOME;
|
||||
else process.env.MOSAIC_HOME = savedMosaicHome;
|
||||
if (savedPath === undefined) delete process.env.PATH;
|
||||
else process.env.PATH = savedPath;
|
||||
if (tempHome) await rm(tempHome, { recursive: true, force: true });
|
||||
tempHome = undefined;
|
||||
});
|
||||
@@ -85,7 +89,7 @@ afterEach(async (): Promise<void> => {
|
||||
* A HOME with a roster-v2 fleet and nothing else — the greenfield shape, before
|
||||
* anything has been installed, applied or started.
|
||||
*/
|
||||
async function v2Home(): Promise<string> {
|
||||
async function v2Home(options: { withPaneRuntime?: boolean } = {}): Promise<string> {
|
||||
tempHome = await mkdtemp(join(tmpdir(), 'mosaic-fleet-v2-dispatch-'));
|
||||
process.env.HOME = tempHome;
|
||||
delete process.env.MOSAIC_HOME;
|
||||
@@ -97,6 +101,12 @@ async function v2Home(): Promise<string> {
|
||||
await writeFile(join(mosaicHome, 'fleet', 'roles', 'code.md'), '`class: code`\n\n# code\n', {
|
||||
mode: 0o600,
|
||||
});
|
||||
const runtimeDir = join(tempHome, '.npm-global', 'bin');
|
||||
await mkdir(runtimeDir, { recursive: true });
|
||||
await writeFile(join(runtimeDir, 'mosaic'), '#!/bin/sh\nexit 0\n', { mode: 0o755 });
|
||||
if (options.withPaneRuntime !== false) {
|
||||
await writeFile(join(runtimeDir, 'pi'), '#!/bin/sh\nexit 0\n', { mode: 0o755 });
|
||||
}
|
||||
return mosaicHome;
|
||||
}
|
||||
|
||||
@@ -113,10 +123,17 @@ const greenfieldRunner: CommandRunner = async (command): Promise<CommandResult>
|
||||
return { stdout: '', stderr: '', exitCode: 1 };
|
||||
};
|
||||
|
||||
function program(runner: CommandRunner = greenfieldRunner): Command {
|
||||
function program(
|
||||
runner: CommandRunner = greenfieldRunner,
|
||||
runtimeProbeRunner?: FleetRuntimeProbeRunner,
|
||||
): Command {
|
||||
const result = new Command();
|
||||
result.exitOverride();
|
||||
registerFleetCommand(result, { runner, frameworkRoot: resolve(process.cwd(), 'framework') });
|
||||
registerFleetCommand(result, {
|
||||
runner,
|
||||
frameworkRoot: resolve(process.cwd(), 'framework'),
|
||||
...(runtimeProbeRunner === undefined ? {} : { runtimeProbeRunner }),
|
||||
});
|
||||
return result;
|
||||
}
|
||||
|
||||
@@ -166,6 +183,93 @@ describe('mosaic fleet ps — roster v2', (): void => {
|
||||
});
|
||||
|
||||
describe('mosaic fleet install — roster v2', (): void => {
|
||||
it('rejects a roster runtime missing from the pane PATH before installing any files', async (): Promise<void> => {
|
||||
const mosaicHome = await v2Home({ withPaneRuntime: false });
|
||||
const operatorBin = join(tempHome!, 'operator-bin');
|
||||
await mkdir(operatorBin, { recursive: true });
|
||||
await writeFile(join(operatorBin, 'pi'), '#!/bin/sh\nexit 0\n', { mode: 0o755 });
|
||||
process.env.PATH = `${operatorBin}:${savedPath ?? '/usr/bin:/bin'}`;
|
||||
|
||||
let message = '';
|
||||
try {
|
||||
await program().parseAsync([
|
||||
'node',
|
||||
'mosaic',
|
||||
'fleet',
|
||||
'--mosaic-home',
|
||||
mosaicHome,
|
||||
'install',
|
||||
'--no-enable',
|
||||
]);
|
||||
} catch (error: unknown) {
|
||||
message = error instanceof Error ? error.message : String(error);
|
||||
}
|
||||
|
||||
expect(message).toContain('runtime=pi');
|
||||
expect(message).toContain('requested_by=coder0,coder1');
|
||||
expect(message).toContain('pane_path=');
|
||||
expect(message).toContain('npm install -g @earendil-works/pi-coding-agent');
|
||||
expect(message).not.toContain(operatorBin);
|
||||
expect(
|
||||
await exists(join(tempHome!, '.config', 'systemd', 'user', '[email protected]')),
|
||||
).toBe(false);
|
||||
expect(await exists(join(mosaicHome, 'fleet', 'holder.id'))).toBe(false);
|
||||
expect(await exists(join(mosaicHome, 'tools'))).toBe(false);
|
||||
});
|
||||
|
||||
it('rejects resolved Node-shebang commands when Node is absent from the pane PATH', async (): Promise<void> => {
|
||||
const mosaicHome = await v2Home();
|
||||
const runtimeDir = join(tempHome!, '.npm-global', 'bin');
|
||||
const nodeScript = '#!/usr/bin/env node\nconsole.log("should-not-run");\n';
|
||||
await writeFile(join(runtimeDir, 'mosaic'), nodeScript, { mode: 0o755 });
|
||||
await writeFile(join(runtimeDir, 'pi'), nodeScript, { mode: 0o755 });
|
||||
await writeFile(join(tempHome!, '.npmrc'), `prefix=${join(tempHome!, 'absent-prefix')}\n`);
|
||||
const isolatedSystemPath = join(tempHome!, 'system-bin');
|
||||
await mkdir(isolatedSystemPath, { recursive: true });
|
||||
const isolatedProbeRunner: FleetRuntimeProbeRunner = async (
|
||||
command,
|
||||
args,
|
||||
): Promise<CommandResult> =>
|
||||
new Promise((settle) => {
|
||||
const child = execFile(
|
||||
command,
|
||||
[...args, '--system-path', isolatedSystemPath],
|
||||
{ encoding: 'utf8' },
|
||||
(error, stdout, stderr) => {
|
||||
settle({
|
||||
stdout,
|
||||
stderr,
|
||||
exitCode: child.exitCode ?? (error === null ? 0 : 1),
|
||||
});
|
||||
},
|
||||
);
|
||||
});
|
||||
|
||||
let message = '';
|
||||
try {
|
||||
await program(greenfieldRunner, isolatedProbeRunner).parseAsync([
|
||||
'node',
|
||||
'mosaic',
|
||||
'fleet',
|
||||
'--mosaic-home',
|
||||
mosaicHome,
|
||||
'install',
|
||||
'--no-enable',
|
||||
]);
|
||||
} catch (error: unknown) {
|
||||
message = error instanceof Error ? error.message : String(error);
|
||||
}
|
||||
|
||||
expect(message).toContain('check=fleet-cli-executable');
|
||||
expect(message).toContain('binary=mosaic');
|
||||
expect(message).toContain('dependency=node');
|
||||
expect(message).toContain('check=fleet-runtime-available');
|
||||
expect(message).toContain('runtime=pi');
|
||||
expect(message).not.toContain('/usr/bin');
|
||||
expect(await exists(join(mosaicHome, 'fleet', 'holder.id'))).toBe(false);
|
||||
expect(await exists(join(mosaicHome, 'tools'))).toBe(false);
|
||||
});
|
||||
|
||||
it('places the tool files and unit templates', async (): Promise<void> => {
|
||||
const mosaicHome = await v2Home();
|
||||
capture();
|
||||
@@ -183,9 +287,11 @@ describe('mosaic fleet install — roster v2', (): void => {
|
||||
]) {
|
||||
expect(await exists(join(systemdUserDir, unit))).toBe(true);
|
||||
}
|
||||
const launcher = join(mosaicHome, 'tools', 'fleet', 'start-agent-session.sh');
|
||||
expect(await exists(launcher)).toBe(true);
|
||||
expect((await stat(launcher)).mode & 0o777).toBe(0o755);
|
||||
for (const tool of ['start-agent-session.sh', 'pane-runtime-path.sh']) {
|
||||
const toolPath = join(mosaicHome, 'tools', 'fleet', tool);
|
||||
expect(await exists(toolPath)).toBe(true);
|
||||
expect((await stat(toolPath)).mode & 0o777).toBe(0o755);
|
||||
}
|
||||
});
|
||||
|
||||
it('writes NO generated env — that file belongs to the reconciler (#791)', async (): Promise<void> => {
|
||||
|
||||
@@ -1277,6 +1277,10 @@ describe('fleet command construction', () => {
|
||||
const home = await tempDir();
|
||||
process.env.HOME = home;
|
||||
delete process.env.MOSAIC_HOME;
|
||||
const runtimeDir = join(home, '.npm-global', 'bin');
|
||||
await mkdir(runtimeDir, { recursive: true });
|
||||
await writeFile(join(runtimeDir, 'pi'), '#!/bin/sh\nexit 0\n', { mode: 0o755 });
|
||||
await writeFile(join(runtimeDir, 'mosaic'), '#!/bin/sh\nexit 0\n', { mode: 0o755 });
|
||||
const mosaicHome = join(home, '.config', 'mosaic');
|
||||
const program = new Command();
|
||||
program.exitOverride();
|
||||
@@ -1315,6 +1319,10 @@ describe('fleet command construction', () => {
|
||||
const originalHome = process.env.HOME;
|
||||
const home = await tempDir();
|
||||
process.env.HOME = home;
|
||||
const runtimeDir = join(home, '.npm-global', 'bin');
|
||||
await mkdir(runtimeDir, { recursive: true });
|
||||
await writeFile(join(runtimeDir, 'pi'), '#!/bin/sh\nexit 0\n', { mode: 0o755 });
|
||||
await writeFile(join(runtimeDir, 'mosaic'), '#!/bin/sh\nexit 0\n', { mode: 0o755 });
|
||||
const mosaicHome = join(home, '.config', 'mosaic');
|
||||
const agentEnvDir = join(mosaicHome, 'fleet', 'agents');
|
||||
const fleetDir = join(mosaicHome, 'fleet');
|
||||
|
||||
@@ -60,6 +60,12 @@ import {
|
||||
writeAgentEnvironmentProjection,
|
||||
writeManagedFleetRoster,
|
||||
} from '../fleet/generated-env-boundary.js';
|
||||
import {
|
||||
assertFleetRuntimeAvailability,
|
||||
FleetRuntimePreflightError,
|
||||
inspectFleetRuntimeAvailability,
|
||||
type FleetRuntimeProbeRunner,
|
||||
} from '../fleet/fleet-runtime-preflight.js';
|
||||
import { registerFleetBacklogCommand } from './fleet-backlog.js';
|
||||
import { registerFleetPersonaCommand } from './fleet-personas.js';
|
||||
import { registerFleetProfileCommand } from './fleet-profiles.js';
|
||||
@@ -89,6 +95,8 @@ export type SleepFn = (ms: number) => Promise<void>;
|
||||
|
||||
export interface FleetCommandDeps {
|
||||
runner?: CommandRunner;
|
||||
/** Executes the pane-PATH helper under a clean launcher environment. */
|
||||
runtimeProbeRunner?: FleetRuntimeProbeRunner;
|
||||
/** Injectable interactive runner for commands needing inherited TTY (e.g., `tmux attach`). */
|
||||
interactiveRunner?: InteractiveRunner;
|
||||
/**
|
||||
@@ -1429,6 +1437,10 @@ export function isSendAccepted(capturedOutput: string): SendVerifyResult {
|
||||
|
||||
export function registerFleetCommand(program: Command, deps: FleetCommandDeps = {}): Command {
|
||||
const runner = deps.runner ?? runCommand;
|
||||
const runtimeProbeRunner: FleetRuntimeProbeRunner =
|
||||
deps.runtimeProbeRunner ??
|
||||
(async (command: string, args: readonly string[]): Promise<CommandResult> =>
|
||||
runCommand(command, [...args]));
|
||||
const sleepFn = deps.sleepFn ?? defaultSleep;
|
||||
const paths = resolveFleetPaths(deps.mosaicHome);
|
||||
const frameworkRoot = deps.frameworkRoot ?? resolveFrameworkRoot();
|
||||
@@ -1527,7 +1539,7 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
|
||||
.description('Install local fleet tools and user systemd units')
|
||||
.option('--no-enable', 'Skip enabling units for boot-survival')
|
||||
.action(async (opts: { enable?: boolean }) => {
|
||||
await installFleet(cmd, frameworkRoot);
|
||||
await installFleet(cmd, frameworkRoot, runtimeProbeRunner);
|
||||
// Unit enablement needs agent names only, so it reads either version.
|
||||
const roster = await loadRosterReadModel(cmd);
|
||||
await enableFleetUnits(runner, roster, opts);
|
||||
@@ -1538,7 +1550,7 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
|
||||
.description('Install local fleet tools and user systemd units')
|
||||
.option('--no-enable', 'Skip enabling units for boot-survival')
|
||||
.action(async (opts: { enable?: boolean }) => {
|
||||
await installFleet(cmd, frameworkRoot);
|
||||
await installFleet(cmd, frameworkRoot, runtimeProbeRunner);
|
||||
// Unit enablement needs agent names only, so it reads either version.
|
||||
const roster = await loadRosterReadModel(cmd);
|
||||
await enableFleetUnits(runner, roster, opts);
|
||||
@@ -2084,6 +2096,8 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
|
||||
});
|
||||
registerFleetReconcilerCommands(cmd, {
|
||||
runner,
|
||||
runtimeProbeRunner,
|
||||
frameworkRoot,
|
||||
mosaicHome: deps.mosaicHome,
|
||||
reconcileDeps: deps.reconcileDeps,
|
||||
});
|
||||
@@ -2349,18 +2363,68 @@ export function registerFleetAgentCommands(
|
||||
});
|
||||
}
|
||||
|
||||
async function installFleet(cmd: Command, frameworkRoot: string): Promise<void> {
|
||||
async function installFleet(
|
||||
cmd: Command,
|
||||
frameworkRoot: string,
|
||||
runtimeProbeRunner: FleetRuntimeProbeRunner,
|
||||
): Promise<void> {
|
||||
const activePaths = resolveFleetPaths(cmd.opts<{ mosaicHome: string }>().mosaicHome);
|
||||
assertDefaultMosaicHomeForSystemd(activePaths.mosaicHome);
|
||||
// Read model first: every file this function places is roster-independent, and
|
||||
// the v1 parser would reject a v2 roster before any of them were written.
|
||||
// Read and preflight before the first mkdir/copy/chmod/write. A successful
|
||||
// install must mean every roster runtime is executable in the eventual pane,
|
||||
// not merely visible to the operator who invoked this command.
|
||||
const roster = await loadRosterReadModel(cmd);
|
||||
const v1Roster = roster.version === 1 ? await loadRosterForCommand(cmd) : undefined;
|
||||
const preflightV1Projections =
|
||||
v1Roster === undefined
|
||||
? []
|
||||
: await Promise.all(
|
||||
v1Roster.agents.map((agent: FleetAgent) =>
|
||||
prepareAgentEnvironmentProjection({
|
||||
mosaicHome: activePaths.mosaicHome,
|
||||
agentEnvDir: activePaths.agentEnvDir,
|
||||
agentName: agent.name,
|
||||
generated: generateAgentEnvValues(v1Roster, agent),
|
||||
}),
|
||||
),
|
||||
);
|
||||
const preflightAgents =
|
||||
v1Roster === undefined
|
||||
? roster.agents
|
||||
: v1Roster.agents.map((agent: FleetAgent, index: number) => {
|
||||
const prepared = preflightV1Projections[index];
|
||||
if (prepared === undefined) {
|
||||
throw new Error(`Missing prepared environment projection for ${agent.name}.`);
|
||||
}
|
||||
const local = parseAgentEnvironment(prepared.local, 'local');
|
||||
return {
|
||||
name: agent.name,
|
||||
runtime: agent.runtime,
|
||||
runtimeBin: local['MOSAIC_RUNTIME_BIN'] ?? '',
|
||||
};
|
||||
});
|
||||
const runtimeInspection = await inspectFleetRuntimeAvailability({
|
||||
mosaicHome: activePaths.mosaicHome,
|
||||
agentEnvDir: activePaths.agentEnvDir,
|
||||
helperPath: join(frameworkRoot, 'tools', 'fleet', 'pane-runtime-path.sh'),
|
||||
agents: preflightAgents,
|
||||
runner: runtimeProbeRunner,
|
||||
});
|
||||
try {
|
||||
assertFleetRuntimeAvailability(runtimeInspection);
|
||||
} catch (error: unknown) {
|
||||
if (error instanceof FleetRuntimePreflightError) {
|
||||
cmd.error(error.message, { code: 'fleet.runtime-preflight', exitCode: 1 });
|
||||
}
|
||||
throw error;
|
||||
}
|
||||
await ensureFleetHolderIdentity(activePaths.mosaicHome);
|
||||
await mkdir(activePaths.fleetToolsDir, { recursive: true });
|
||||
await mkdir(activePaths.tmuxToolsDir, { recursive: true });
|
||||
await mkdir(activePaths.systemdUserDir, { recursive: true });
|
||||
|
||||
const startAgentSessionPath = join(activePaths.fleetToolsDir, 'start-agent-session.sh');
|
||||
const paneRuntimePath = join(activePaths.fleetToolsDir, 'pane-runtime-path.sh');
|
||||
const startInteractionServicePath = join(
|
||||
activePaths.fleetToolsDir,
|
||||
'start-interaction-service.sh',
|
||||
@@ -2374,6 +2438,7 @@ async function installFleet(cmd: Command, frameworkRoot: string): Promise<void>
|
||||
const agentSendPath = join(activePaths.tmuxToolsDir, 'agent-send.sh');
|
||||
const executableToolPaths = [
|
||||
startAgentSessionPath,
|
||||
paneRuntimePath,
|
||||
startInteractionServicePath,
|
||||
startTmuxHolderPath,
|
||||
printInteractionPolicyPath,
|
||||
@@ -2384,6 +2449,7 @@ async function installFleet(cmd: Command, frameworkRoot: string): Promise<void>
|
||||
join(frameworkRoot, 'tools', 'fleet', 'start-agent-session.sh'),
|
||||
startAgentSessionPath,
|
||||
);
|
||||
await copyFile(join(frameworkRoot, 'tools', 'fleet', 'pane-runtime-path.sh'), paneRuntimePath);
|
||||
await copyFile(
|
||||
join(frameworkRoot, 'tools', 'fleet', 'start-interaction-service.sh'),
|
||||
startInteractionServicePath,
|
||||
@@ -2427,7 +2493,9 @@ async function installFleet(cmd: Command, frameworkRoot: string): Promise<void>
|
||||
return;
|
||||
}
|
||||
|
||||
const v1Roster = await loadRosterForCommand(cmd);
|
||||
if (v1Roster === undefined) {
|
||||
throw new Error('Roster version changed while installing fleet files.');
|
||||
}
|
||||
for (const agent of v1Roster.agents) {
|
||||
await writeAgentEnvironmentProjection({
|
||||
mosaicHome: activePaths.mosaicHome,
|
||||
|
||||
@@ -0,0 +1,328 @@
|
||||
import { spawn } from 'node:child_process';
|
||||
import { chmod, mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
|
||||
import { tmpdir } from 'node:os';
|
||||
import { join, resolve } from 'node:path';
|
||||
import { afterEach, describe, expect, it } from 'vitest';
|
||||
import {
|
||||
inspectFleetRuntimeAvailability,
|
||||
type FleetRuntimeProbeResult,
|
||||
type FleetRuntimeProbeRunner,
|
||||
} from './fleet-runtime-preflight.js';
|
||||
|
||||
const helperPath = resolve(process.cwd(), 'framework', 'tools', 'fleet', 'pane-runtime-path.sh');
|
||||
let cleanup: string | undefined;
|
||||
|
||||
afterEach(async (): Promise<void> => {
|
||||
if (cleanup !== undefined) await rm(cleanup, { recursive: true, force: true });
|
||||
cleanup = undefined;
|
||||
});
|
||||
|
||||
interface FleetFixture {
|
||||
readonly root: string;
|
||||
readonly mosaicHome: string;
|
||||
readonly agentEnvDir: string;
|
||||
readonly runtimeDir: string;
|
||||
}
|
||||
|
||||
async function fleetHome(): Promise<FleetFixture> {
|
||||
const root = await mkdtemp(join(tmpdir(), 'mosaic-fleet-runtime-preflight-'));
|
||||
cleanup = root;
|
||||
const mosaicHome = join(root, '.config', 'mosaic');
|
||||
const agentEnvDir = join(mosaicHome, 'fleet', 'agents');
|
||||
const runtimeDir = join(root, '.npm-global', 'bin');
|
||||
await mkdir(agentEnvDir, { recursive: true, mode: 0o700 });
|
||||
await mkdir(runtimeDir, { recursive: true });
|
||||
for (const directory of [mosaicHome, join(mosaicHome, 'fleet'), agentEnvDir]) {
|
||||
await chmod(directory, 0o700);
|
||||
}
|
||||
await writeExecutable(runtimeDir, 'mosaic', '#!/bin/sh\nexit 0\n');
|
||||
return { root, mosaicHome, agentEnvDir, runtimeDir };
|
||||
}
|
||||
|
||||
async function writeExecutable(directory: string, name: string, content: string): Promise<void> {
|
||||
await mkdir(directory, { recursive: true });
|
||||
await writeFile(join(directory, name), content, { mode: 0o755 });
|
||||
}
|
||||
|
||||
const processRunner: FleetRuntimeProbeRunner = async (
|
||||
command: string,
|
||||
args: readonly string[],
|
||||
): Promise<FleetRuntimeProbeResult> =>
|
||||
new Promise((settle) => {
|
||||
const child = spawn(command, [...args], { stdio: ['ignore', 'pipe', 'pipe'] });
|
||||
let stdout = '';
|
||||
let stderr = '';
|
||||
child.stdout.setEncoding('utf8');
|
||||
child.stderr.setEncoding('utf8');
|
||||
child.stdout.on('data', (chunk: string): void => {
|
||||
stdout += chunk;
|
||||
});
|
||||
child.stderr.on('data', (chunk: string): void => {
|
||||
stderr += chunk;
|
||||
});
|
||||
child.on('error', (error: Error): void => {
|
||||
settle({ stdout, stderr: `${stderr}${error.message}`, exitCode: 127 });
|
||||
});
|
||||
child.on('close', (code: number | null): void => {
|
||||
settle({ stdout, stderr, exitCode: code ?? 1 });
|
||||
});
|
||||
});
|
||||
|
||||
describe('fleet runtime preflight', (): void => {
|
||||
it('executes one distinct pane runtime and aggregates every requesting roster row', async (): Promise<void> => {
|
||||
const fixture = await fleetHome();
|
||||
await writeExecutable(fixture.runtimeDir, 'pi', '#!/bin/sh\nexit 0\n');
|
||||
let probes = 0;
|
||||
|
||||
const inspection = await inspectFleetRuntimeAvailability({
|
||||
mosaicHome: fixture.mosaicHome,
|
||||
agentEnvDir: fixture.agentEnvDir,
|
||||
helperPath,
|
||||
agents: [
|
||||
{ name: 'coder1', runtime: 'pi' },
|
||||
{ name: 'coder0', runtime: 'pi' },
|
||||
],
|
||||
runner: async (command, args): Promise<FleetRuntimeProbeResult> => {
|
||||
probes += 1;
|
||||
return processRunner(command, args);
|
||||
},
|
||||
});
|
||||
|
||||
expect(probes).toBe(2);
|
||||
expect(inspection.fleetCliExecutable).toEqual([
|
||||
expect.objectContaining({
|
||||
check: 'fleet-cli-executable',
|
||||
status: 'ok',
|
||||
requestedBy: ['coder0', 'coder1'],
|
||||
binaryPath: join(fixture.runtimeDir, 'mosaic'),
|
||||
dependency: '/bin/sh',
|
||||
}),
|
||||
]);
|
||||
expect(inspection.fleetRuntimeAvailability).toEqual([
|
||||
expect.objectContaining({
|
||||
check: 'fleet-runtime-available',
|
||||
runtime: 'pi',
|
||||
status: 'ok',
|
||||
requestedBy: ['coder0', 'coder1'],
|
||||
binaryPath: join(fixture.runtimeDir, 'pi'),
|
||||
dependency: '/bin/sh',
|
||||
installCommand: 'npm install -g @earendil-works/pi-coding-agent',
|
||||
}),
|
||||
]);
|
||||
expect(inspection.fleetRuntimeAvailability[0]?.panePath).toContain(fixture.runtimeDir);
|
||||
});
|
||||
|
||||
it('returns an actionable non-green check when the pane PATH lacks the runtime', async (): Promise<void> => {
|
||||
const fixture = await fleetHome();
|
||||
|
||||
const inspection = await inspectFleetRuntimeAvailability({
|
||||
mosaicHome: fixture.mosaicHome,
|
||||
agentEnvDir: fixture.agentEnvDir,
|
||||
helperPath,
|
||||
agents: [{ name: 'coder0', runtime: 'pi' }],
|
||||
runner: processRunner,
|
||||
});
|
||||
|
||||
expect(inspection.fleetCliExecutable[0]?.status).toBe('ok');
|
||||
expect(inspection.fleetRuntimeAvailability).toEqual([
|
||||
expect.objectContaining({
|
||||
check: 'fleet-runtime-available',
|
||||
runtime: 'pi',
|
||||
status: 'missing',
|
||||
requestedBy: ['coder0'],
|
||||
installCommand: 'npm install -g @earendil-works/pi-coding-agent',
|
||||
}),
|
||||
]);
|
||||
expect(inspection.fleetRuntimeAvailability[0]?.panePath).not.toContain(
|
||||
process.env['PATH'] ?? 'operator-path-absent',
|
||||
);
|
||||
});
|
||||
|
||||
it('executes the side-effect-free Node version probe for Node-shebang commands', async (): Promise<void> => {
|
||||
const fixture = await fleetHome();
|
||||
const nodeScript = '#!/usr/bin/env node\nconsole.log("should-not-run");\n';
|
||||
await writeExecutable(fixture.runtimeDir, 'mosaic', nodeScript);
|
||||
await writeExecutable(fixture.runtimeDir, 'pi', nodeScript);
|
||||
await writeExecutable(
|
||||
fixture.runtimeDir,
|
||||
'node',
|
||||
'#!/bin/sh\n[ "$1" = --version ] || exit 9\nprintf "v-fixture-node\\n"\n',
|
||||
);
|
||||
|
||||
const inspection = await inspectFleetRuntimeAvailability({
|
||||
mosaicHome: fixture.mosaicHome,
|
||||
agentEnvDir: fixture.agentEnvDir,
|
||||
helperPath,
|
||||
agents: [{ name: 'coder0', runtime: 'pi' }],
|
||||
runner: processRunner,
|
||||
});
|
||||
|
||||
for (const check of [
|
||||
...inspection.fleetCliExecutable,
|
||||
...inspection.fleetRuntimeAvailability,
|
||||
]) {
|
||||
expect(check).toMatchObject({
|
||||
status: 'ok',
|
||||
dependency: 'node',
|
||||
probeCommand: 'node --version',
|
||||
probeExit: 0,
|
||||
probeOutput: 'v-fixture-node',
|
||||
});
|
||||
}
|
||||
});
|
||||
|
||||
it('reddens when resolved Node-shebang commands cannot execute without pane Node', async (): Promise<void> => {
|
||||
const fixture = await fleetHome();
|
||||
const isolatedSystemPath = join(fixture.root, 'system-bin');
|
||||
await mkdir(isolatedSystemPath, { recursive: true });
|
||||
await writeFile(
|
||||
join(fixture.root, '.npmrc'),
|
||||
`prefix=${join(fixture.root, 'absent-prefix')}\n`,
|
||||
);
|
||||
const nodeScript = '#!/usr/bin/env node\nconsole.log("should-not-run");\n';
|
||||
await writeExecutable(fixture.runtimeDir, 'mosaic', nodeScript);
|
||||
await writeExecutable(fixture.runtimeDir, 'pi', nodeScript);
|
||||
|
||||
const inspection = await inspectFleetRuntimeAvailability({
|
||||
mosaicHome: fixture.mosaicHome,
|
||||
agentEnvDir: fixture.agentEnvDir,
|
||||
helperPath,
|
||||
agents: [{ name: 'coder0', runtime: 'pi' }],
|
||||
runner: processRunner,
|
||||
systemPath: isolatedSystemPath,
|
||||
});
|
||||
|
||||
expect(inspection.fleetCliExecutable).toEqual([
|
||||
expect.objectContaining({
|
||||
check: 'fleet-cli-executable',
|
||||
status: 'unexecutable',
|
||||
binaryPath: join(fixture.runtimeDir, 'mosaic'),
|
||||
dependency: 'node',
|
||||
probeCommand: 'node --version',
|
||||
}),
|
||||
]);
|
||||
expect(inspection.fleetRuntimeAvailability).toEqual([
|
||||
expect.objectContaining({
|
||||
check: 'fleet-runtime-available',
|
||||
runtime: 'pi',
|
||||
status: 'unexecutable',
|
||||
binaryPath: join(fixture.runtimeDir, 'pi'),
|
||||
dependency: 'node',
|
||||
probeCommand: 'node --version',
|
||||
}),
|
||||
]);
|
||||
expect(inspection.fleetCliExecutable[0]?.probeOutput).toBe(
|
||||
'shebang command is not on the pane PATH',
|
||||
);
|
||||
expect(inspection.fleetCliExecutable[0]?.panePath).not.toContain('/usr/bin');
|
||||
});
|
||||
|
||||
it('keeps distinct effective local runtime-bin paths as distinct checks', async (): Promise<void> => {
|
||||
const fixture = await fleetHome();
|
||||
const firstBin = join(fixture.root, 'first-bin');
|
||||
const secondBin = join(fixture.root, 'second-bin');
|
||||
for (const override of [
|
||||
{ agent: 'coder0', runtimeBin: firstBin },
|
||||
{ agent: 'coder1', runtimeBin: secondBin },
|
||||
]) {
|
||||
await writeExecutable(override.runtimeBin, 'pi', '#!/bin/sh\nexit 0\n');
|
||||
await writeFile(
|
||||
join(fixture.agentEnvDir, `${override.agent}.env.local`),
|
||||
`MOSAIC_RUNTIME_BIN=${override.runtimeBin}\n`,
|
||||
{ mode: 0o600 },
|
||||
);
|
||||
}
|
||||
|
||||
const inspection = await inspectFleetRuntimeAvailability({
|
||||
mosaicHome: fixture.mosaicHome,
|
||||
agentEnvDir: fixture.agentEnvDir,
|
||||
helperPath,
|
||||
agents: [
|
||||
{ name: 'coder0', runtime: 'pi' },
|
||||
{ name: 'coder1', runtime: 'pi' },
|
||||
],
|
||||
runner: processRunner,
|
||||
});
|
||||
|
||||
expect(inspection.fleetCliExecutable).toHaveLength(2);
|
||||
expect(inspection.fleetRuntimeAvailability).toHaveLength(2);
|
||||
expect(inspection.fleetRuntimeAvailability.map((check) => check.requestedBy)).toEqual([
|
||||
['coder0'],
|
||||
['coder1'],
|
||||
]);
|
||||
expect(inspection.fleetRuntimeAvailability.map((check) => check.binaryPath)).toEqual([
|
||||
join(firstBin, 'pi'),
|
||||
join(secondBin, 'pi'),
|
||||
]);
|
||||
});
|
||||
|
||||
it('reports each distinct roster runtime with its exact install command', async (): Promise<void> => {
|
||||
const fixture = await fleetHome();
|
||||
let probes = 0;
|
||||
|
||||
const inspection = await inspectFleetRuntimeAvailability({
|
||||
mosaicHome: fixture.mosaicHome,
|
||||
agentEnvDir: fixture.agentEnvDir,
|
||||
helperPath,
|
||||
agents: [
|
||||
{ name: 'pi-seat', runtime: 'pi' },
|
||||
{ name: 'claude-seat', runtime: 'claude' },
|
||||
{ name: 'codex-seat', runtime: 'codex' },
|
||||
{ name: 'opencode-seat', runtime: 'opencode' },
|
||||
],
|
||||
runner: async (): Promise<FleetRuntimeProbeResult> => {
|
||||
probes += 1;
|
||||
return {
|
||||
stdout:
|
||||
'pane_path\u0000/fixture/bin:/usr/bin:/bin\u0000status\u0000missing\u0000' +
|
||||
'binary_path\u0000\u0000probe_exit\u0000\u0000probe_output\u0000\u0000',
|
||||
stderr: '',
|
||||
exitCode: 69,
|
||||
};
|
||||
},
|
||||
});
|
||||
|
||||
expect(probes).toBe(5);
|
||||
expect(
|
||||
inspection.fleetRuntimeAvailability.map((check) => ({
|
||||
runtime: check.runtime,
|
||||
installCommand: check.installCommand,
|
||||
})),
|
||||
).toEqual([
|
||||
{
|
||||
runtime: 'claude',
|
||||
installCommand: 'curl -fsSL https://claude.ai/install.sh | bash',
|
||||
},
|
||||
{
|
||||
runtime: 'codex',
|
||||
installCommand: 'npm install -g @openai/codex',
|
||||
},
|
||||
{
|
||||
runtime: 'opencode',
|
||||
installCommand: 'npm install -g opencode-ai',
|
||||
},
|
||||
{
|
||||
runtime: 'pi',
|
||||
installCommand: 'npm install -g @earendil-works/pi-coding-agent',
|
||||
},
|
||||
]);
|
||||
});
|
||||
|
||||
it('fails closed when the shared helper returns malformed evidence', async (): Promise<void> => {
|
||||
const fixture = await fleetHome();
|
||||
|
||||
await expect(
|
||||
inspectFleetRuntimeAvailability({
|
||||
mosaicHome: fixture.mosaicHome,
|
||||
agentEnvDir: fixture.agentEnvDir,
|
||||
helperPath,
|
||||
agents: [{ name: 'coder0', runtime: 'pi' }],
|
||||
runner: async (): Promise<FleetRuntimeProbeResult> => ({
|
||||
stdout: 'not-a-field-protocol',
|
||||
stderr: '',
|
||||
exitCode: 0,
|
||||
}),
|
||||
}),
|
||||
).rejects.toThrow('malformed field output');
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,362 @@
|
||||
import { homedir } from 'node:os';
|
||||
import { getInstallInstructions } from '../runtime/detector.js';
|
||||
import type { RuntimeName } from '../types.js';
|
||||
import { compareCodePoints } from './deterministic-order.js';
|
||||
import {
|
||||
GENERATED_AGENT_ENV_SUPPORTED_RUNTIMES,
|
||||
readAgentLocalEnvironment,
|
||||
} from './generated-env-boundary.js';
|
||||
|
||||
const RUNTIME_SET = new Set<string>(GENERATED_AGENT_ENV_SUPPORTED_RUNTIMES);
|
||||
|
||||
export interface FleetRuntimeRequestedAgent {
|
||||
readonly name: string;
|
||||
readonly runtime: string;
|
||||
/** Planned effective local override, when provisioning has already prepared it. */
|
||||
readonly runtimeBin?: string;
|
||||
}
|
||||
|
||||
export interface FleetRuntimeProbeResult {
|
||||
readonly stdout: string;
|
||||
readonly stderr: string;
|
||||
readonly exitCode: number;
|
||||
}
|
||||
|
||||
export type FleetRuntimeProbeRunner = (
|
||||
command: string,
|
||||
args: readonly string[],
|
||||
) => Promise<FleetRuntimeProbeResult>;
|
||||
|
||||
export interface FleetRuntimePreflightOptions {
|
||||
readonly mosaicHome: string;
|
||||
readonly agentEnvDir: string;
|
||||
readonly helperPath: string;
|
||||
readonly agents: readonly FleetRuntimeRequestedAgent[];
|
||||
readonly runner: FleetRuntimeProbeRunner;
|
||||
/** Test-only system suffix; production and the launcher use the helper default. */
|
||||
readonly systemPath?: string;
|
||||
}
|
||||
|
||||
export type FleetExecutableStatus = 'ok' | 'missing' | 'unexecutable';
|
||||
|
||||
interface FleetExecutableEvidence {
|
||||
readonly status: FleetExecutableStatus;
|
||||
readonly panePath: string;
|
||||
readonly binaryPath?: string;
|
||||
readonly dependency?: string;
|
||||
readonly probeCommand?: string;
|
||||
readonly probeExit?: number;
|
||||
readonly probeOutput?: string;
|
||||
}
|
||||
|
||||
export interface FleetCliExecutableCheck extends FleetExecutableEvidence {
|
||||
readonly check: 'fleet-cli-executable';
|
||||
readonly binary: 'mosaic';
|
||||
readonly requestedBy: readonly string[];
|
||||
}
|
||||
|
||||
export interface FleetRuntimeCheck extends FleetExecutableEvidence {
|
||||
readonly check: 'fleet-runtime-available';
|
||||
readonly runtime: RuntimeName;
|
||||
readonly requestedBy: readonly string[];
|
||||
readonly installCommand: string;
|
||||
}
|
||||
|
||||
export type FleetRuntimePreflightCheck = FleetCliExecutableCheck | FleetRuntimeCheck;
|
||||
|
||||
export interface FleetRuntimeInspection {
|
||||
readonly fleetCliExecutable: readonly FleetCliExecutableCheck[];
|
||||
readonly fleetRuntimeAvailability: readonly FleetRuntimeCheck[];
|
||||
}
|
||||
|
||||
interface EffectiveAgent {
|
||||
readonly name: string;
|
||||
readonly runtime: RuntimeName;
|
||||
readonly runtimeBin: string;
|
||||
}
|
||||
|
||||
interface PaneProbeGroup {
|
||||
readonly runtimeBin: string;
|
||||
readonly requestedBy: string[];
|
||||
}
|
||||
|
||||
interface RuntimeProbeGroup extends PaneProbeGroup {
|
||||
readonly runtime: RuntimeName;
|
||||
}
|
||||
|
||||
interface BinaryProbeRequest {
|
||||
readonly binary: string;
|
||||
readonly runtimeBin: string;
|
||||
}
|
||||
|
||||
export class FleetRuntimePreflightError extends Error {
|
||||
readonly checks: readonly FleetRuntimePreflightCheck[];
|
||||
|
||||
constructor(checks: readonly FleetRuntimePreflightCheck[]) {
|
||||
super(formatFleetRuntimePreflightError(checks));
|
||||
this.name = FleetRuntimePreflightError.name;
|
||||
this.checks = checks;
|
||||
}
|
||||
}
|
||||
|
||||
export class FleetRuntimeProbeError extends Error {
|
||||
constructor(message: string) {
|
||||
super(message);
|
||||
this.name = FleetRuntimeProbeError.name;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Proves the fleet CLI and every distinct runtime/effective-bin pair resolve
|
||||
* with an executable shebang interpreter through the eventual pane PATH. The
|
||||
* helper runs under the unit's clean launcher environment, so operator PATH can
|
||||
* neither create a false green nor provide a hidden interpreter.
|
||||
*/
|
||||
export async function inspectFleetRuntimeAvailability(
|
||||
options: FleetRuntimePreflightOptions,
|
||||
): Promise<FleetRuntimeInspection> {
|
||||
const agents = await resolveEffectiveAgents(options);
|
||||
const paneGroups = groupPaneRequests(agents);
|
||||
const runtimeGroups = groupRuntimeRequests(agents);
|
||||
|
||||
const fleetCliExecutable: FleetCliExecutableCheck[] = [];
|
||||
for (const group of paneGroups) {
|
||||
const evidence = await probeBinary(options, {
|
||||
binary: 'mosaic',
|
||||
runtimeBin: group.runtimeBin,
|
||||
});
|
||||
fleetCliExecutable.push({
|
||||
check: 'fleet-cli-executable',
|
||||
binary: 'mosaic',
|
||||
requestedBy: sortedRequestedBy(group.requestedBy),
|
||||
...evidence,
|
||||
});
|
||||
}
|
||||
|
||||
const fleetRuntimeAvailability: FleetRuntimeCheck[] = [];
|
||||
for (const group of runtimeGroups) {
|
||||
const evidence = await probeBinary(options, {
|
||||
binary: group.runtime,
|
||||
runtimeBin: group.runtimeBin,
|
||||
});
|
||||
fleetRuntimeAvailability.push({
|
||||
check: 'fleet-runtime-available',
|
||||
runtime: group.runtime,
|
||||
requestedBy: sortedRequestedBy(group.requestedBy),
|
||||
installCommand: getInstallInstructions(group.runtime),
|
||||
...evidence,
|
||||
});
|
||||
}
|
||||
|
||||
return Object.freeze({
|
||||
fleetCliExecutable: Object.freeze(fleetCliExecutable),
|
||||
fleetRuntimeAvailability: Object.freeze(fleetRuntimeAvailability),
|
||||
});
|
||||
}
|
||||
|
||||
export function assertFleetRuntimeAvailability(inspection: FleetRuntimeInspection): void {
|
||||
const checks: FleetRuntimePreflightCheck[] = [
|
||||
...inspection.fleetCliExecutable,
|
||||
...inspection.fleetRuntimeAvailability,
|
||||
];
|
||||
const failures = checks.filter(
|
||||
(check: FleetRuntimePreflightCheck): boolean => check.status !== 'ok',
|
||||
);
|
||||
if (failures.length > 0) throw new FleetRuntimePreflightError(failures);
|
||||
}
|
||||
|
||||
export function formatFleetRuntimePreflightError(
|
||||
checks: readonly FleetRuntimePreflightCheck[],
|
||||
): string {
|
||||
const lines = ['Fleet runtime preflight failed:'];
|
||||
for (const check of checks) {
|
||||
const dependency = check.dependency === undefined ? '' : ` dependency=${check.dependency}`;
|
||||
const probe = check.probeCommand === undefined ? '' : ` dependency_probe=${check.probeCommand}`;
|
||||
const execution =
|
||||
check.status === 'unexecutable'
|
||||
? ` probe_exit=${check.probeExit?.toString() ?? 'not-run'} ` +
|
||||
`probe_output=${JSON.stringify(check.probeOutput ?? '')}`
|
||||
: '';
|
||||
if (check.check === 'fleet-cli-executable') {
|
||||
lines.push(
|
||||
`check=${check.check} binary=${check.binary} ` +
|
||||
`requested_by=${check.requestedBy.join(',')} pane_path=${check.panePath}` +
|
||||
`${dependency}${probe}${execution} ` +
|
||||
'action=repair the Mosaic installation until its pane dependencies resolve',
|
||||
);
|
||||
continue;
|
||||
}
|
||||
lines.push(
|
||||
`check=${check.check} runtime=${check.runtime} ` +
|
||||
`requested_by=${check.requestedBy.join(',')} pane_path=${check.panePath}` +
|
||||
`${dependency}${probe}${execution} install_command=${check.installCommand}`,
|
||||
);
|
||||
}
|
||||
return lines.join('\n');
|
||||
}
|
||||
|
||||
async function resolveEffectiveAgents(
|
||||
options: FleetRuntimePreflightOptions,
|
||||
): Promise<readonly EffectiveAgent[]> {
|
||||
const agents: EffectiveAgent[] = [];
|
||||
for (const agent of options.agents) {
|
||||
if (!isRuntimeName(agent.runtime)) {
|
||||
throw new FleetRuntimeProbeError(`Unsupported fleet runtime: ${agent.runtime}`);
|
||||
}
|
||||
const runtimeBin =
|
||||
agent.runtimeBin ??
|
||||
(
|
||||
await readAgentLocalEnvironment({
|
||||
mosaicHome: options.mosaicHome,
|
||||
agentEnvDir: options.agentEnvDir,
|
||||
agentName: agent.name,
|
||||
})
|
||||
)['MOSAIC_RUNTIME_BIN'] ??
|
||||
'';
|
||||
agents.push({ name: agent.name, runtime: agent.runtime, runtimeBin });
|
||||
}
|
||||
return agents;
|
||||
}
|
||||
|
||||
function groupPaneRequests(agents: readonly EffectiveAgent[]): readonly PaneProbeGroup[] {
|
||||
const groups = new Map<string, PaneProbeGroup>();
|
||||
for (const agent of agents) {
|
||||
const current = groups.get(agent.runtimeBin);
|
||||
if (current === undefined) {
|
||||
groups.set(agent.runtimeBin, { runtimeBin: agent.runtimeBin, requestedBy: [agent.name] });
|
||||
} else {
|
||||
current.requestedBy.push(agent.name);
|
||||
}
|
||||
}
|
||||
return [...groups.values()].sort((left, right): number =>
|
||||
compareCodePoints(left.runtimeBin, right.runtimeBin),
|
||||
);
|
||||
}
|
||||
|
||||
function groupRuntimeRequests(agents: readonly EffectiveAgent[]): readonly RuntimeProbeGroup[] {
|
||||
const groups = new Map<string, RuntimeProbeGroup>();
|
||||
for (const agent of agents) {
|
||||
const key = JSON.stringify([agent.runtime, agent.runtimeBin]);
|
||||
const current = groups.get(key);
|
||||
if (current === undefined) {
|
||||
groups.set(key, {
|
||||
runtime: agent.runtime,
|
||||
runtimeBin: agent.runtimeBin,
|
||||
requestedBy: [agent.name],
|
||||
});
|
||||
} else {
|
||||
current.requestedBy.push(agent.name);
|
||||
}
|
||||
}
|
||||
return [...groups.values()].sort((left, right): number =>
|
||||
compareCodePoints(
|
||||
`${left.runtime}\u0000${left.runtimeBin}`,
|
||||
`${right.runtime}\u0000${right.runtimeBin}`,
|
||||
),
|
||||
);
|
||||
}
|
||||
|
||||
async function probeBinary(
|
||||
options: FleetRuntimePreflightOptions,
|
||||
probe: BinaryProbeRequest,
|
||||
): Promise<FleetExecutableEvidence> {
|
||||
const args = [
|
||||
'-i',
|
||||
`HOME=${process.env['HOME'] ?? homedir()}`,
|
||||
'PATH=/usr/bin:/bin',
|
||||
`MOSAIC_HOME=${options.mosaicHome}`,
|
||||
'/bin/bash',
|
||||
'--noprofile',
|
||||
'--norc',
|
||||
options.helperPath,
|
||||
'--mosaic-home',
|
||||
options.mosaicHome,
|
||||
'--binary',
|
||||
probe.binary,
|
||||
'--check-executable',
|
||||
];
|
||||
if (probe.runtimeBin !== '') args.push('--runtime-bin', probe.runtimeBin);
|
||||
if (options.systemPath !== undefined) args.push('--system-path', options.systemPath);
|
||||
|
||||
const result = await options.runner('/usr/bin/env', args);
|
||||
const fields = parseNulFields(result.stdout);
|
||||
const panePath = requiredField(fields, 'pane_path');
|
||||
const status = requiredField(fields, 'status');
|
||||
if (result.exitCode === 0 && status === 'present') {
|
||||
return executableEvidence('ok', panePath, fields);
|
||||
}
|
||||
if (result.exitCode === 69 && status === 'missing') {
|
||||
return { status: 'missing', panePath };
|
||||
}
|
||||
if (result.exitCode === 70 && status === 'unexecutable') {
|
||||
return executableEvidence('unexecutable', panePath, fields);
|
||||
}
|
||||
throw new FleetRuntimeProbeError(
|
||||
`Fleet executable probe failed: binary=${probe.binary} exit=${result.exitCode.toString()} ` +
|
||||
`stderr=${JSON.stringify(result.stderr.trim())}`,
|
||||
);
|
||||
}
|
||||
|
||||
function executableEvidence(
|
||||
status: 'ok' | 'unexecutable',
|
||||
panePath: string,
|
||||
fields: ReadonlyMap<string, string>,
|
||||
): FleetExecutableEvidence {
|
||||
const dependency = requiredField(fields, 'dependency');
|
||||
const probeCommand = requiredField(fields, 'probe_command');
|
||||
const probeExit = requiredField(fields, 'probe_exit');
|
||||
const probeOutput = requiredField(fields, 'probe_output');
|
||||
return {
|
||||
status,
|
||||
panePath,
|
||||
binaryPath: requiredField(fields, 'binary_path'),
|
||||
...(dependency === '' ? {} : { dependency }),
|
||||
...(probeCommand === '' ? {} : { probeCommand }),
|
||||
...(probeExit === '' ? {} : { probeExit: parseProbeExit(probeExit) }),
|
||||
...(probeOutput === '' ? {} : { probeOutput }),
|
||||
};
|
||||
}
|
||||
|
||||
function sortedRequestedBy(requestedBy: readonly string[]): readonly string[] {
|
||||
return Object.freeze(
|
||||
[...requestedBy].sort((left: string, right: string): number => compareCodePoints(left, right)),
|
||||
);
|
||||
}
|
||||
|
||||
function parseNulFields(source: string): ReadonlyMap<string, string> {
|
||||
const parts = source.split('\u0000');
|
||||
if (parts.at(-1) === '') parts.pop();
|
||||
if (parts.length % 2 !== 0) {
|
||||
throw new FleetRuntimeProbeError('Fleet runtime probe returned malformed field output.');
|
||||
}
|
||||
const fields = new Map<string, string>();
|
||||
for (let index = 0; index < parts.length; index += 2) {
|
||||
const key = parts[index];
|
||||
const value = parts[index + 1];
|
||||
if (key === undefined || value === undefined || key === '' || fields.has(key)) {
|
||||
throw new FleetRuntimeProbeError('Fleet runtime probe returned malformed field output.');
|
||||
}
|
||||
fields.set(key, value);
|
||||
}
|
||||
return fields;
|
||||
}
|
||||
|
||||
function requiredField(fields: ReadonlyMap<string, string>, key: string): string {
|
||||
const value = fields.get(key);
|
||||
if (value === undefined) {
|
||||
throw new FleetRuntimeProbeError(`Fleet runtime probe omitted ${key}.`);
|
||||
}
|
||||
return value;
|
||||
}
|
||||
|
||||
function parseProbeExit(value: string): number {
|
||||
const exitCode = Number(value);
|
||||
if (!Number.isSafeInteger(exitCode) || exitCode < 0) {
|
||||
throw new FleetRuntimeProbeError('Fleet runtime probe returned an invalid execution status.');
|
||||
}
|
||||
return exitCode;
|
||||
}
|
||||
|
||||
function isRuntimeName(value: string): value is RuntimeName {
|
||||
return RUNTIME_SET.has(value);
|
||||
}
|
||||
@@ -25,6 +25,12 @@ export interface AgentGeneratedProjectionDeletionOptions {
|
||||
readonly agentName: string;
|
||||
}
|
||||
|
||||
export interface AgentLocalEnvironmentReadOptions {
|
||||
readonly mosaicHome: string;
|
||||
readonly agentEnvDir: string;
|
||||
readonly agentName: string;
|
||||
}
|
||||
|
||||
export interface AgentEnvironmentProjectionResult {
|
||||
readonly generatedPath: string;
|
||||
readonly localPath: string;
|
||||
@@ -145,6 +151,23 @@ export function parseAgentEnvironment(
|
||||
return Object.freeze(values);
|
||||
}
|
||||
|
||||
/**
|
||||
* Reads one agent's optional local overrides through the same path, file-type,
|
||||
* permission, key, and value boundary used by projection/launch handling.
|
||||
*/
|
||||
export async function readAgentLocalEnvironment(
|
||||
options: AgentLocalEnvironmentReadOptions,
|
||||
): Promise<Readonly<Record<string, string>>> {
|
||||
if (!AGENT_NAME.test(options.agentName)) {
|
||||
throw new AgentEnvBoundaryError('unsafe-agent-name', 'MOSAIC_AGENT_NAME', options.agentName);
|
||||
}
|
||||
await validatePrivateProjectionDirectory(options.mosaicHome, options.agentEnvDir);
|
||||
const source = await readOptionalPrivateFile(
|
||||
join(options.agentEnvDir, `${options.agentName}.env.local`),
|
||||
);
|
||||
return source === undefined ? Object.freeze({}) : parseAgentEnvironment(source, 'local');
|
||||
}
|
||||
|
||||
/** Renders the roster-derived generated projection in a stable, complete key order. */
|
||||
export function renderGeneratedAgentEnvironment(values: Readonly<Record<string, string>>): string {
|
||||
const normalized = normalizeGeneratedValues(values);
|
||||
|
||||
@@ -19,7 +19,7 @@ const RUNTIME_DEFS: Record<
|
||||
label: 'Claude Code',
|
||||
command: 'claude',
|
||||
versionFlag: '--version',
|
||||
installHint: 'npm install -g @anthropic-ai/claude-code',
|
||||
installHint: 'curl -fsSL https://claude.ai/install.sh | bash',
|
||||
},
|
||||
codex: {
|
||||
label: 'Codex',
|
||||
@@ -31,13 +31,13 @@ const RUNTIME_DEFS: Record<
|
||||
label: 'OpenCode',
|
||||
command: 'opencode',
|
||||
versionFlag: 'version',
|
||||
installHint: 'See https://opencode.ai for install instructions',
|
||||
installHint: 'npm install -g opencode-ai',
|
||||
},
|
||||
pi: {
|
||||
label: 'Pi',
|
||||
command: 'pi',
|
||||
versionFlag: '--version',
|
||||
installHint: 'curl -fsSL https://pi.dev/install.sh | sh',
|
||||
installHint: 'npm install -g @earendil-works/pi-coding-agent',
|
||||
},
|
||||
};
|
||||
|
||||
|
||||
Reference in New Issue
Block a user