Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
 jarvis
|
8a405b141d |
@@ -138,9 +138,9 @@ mosaic brain tasks
|
||||
mosaic brain conversations
|
||||
|
||||
# Agent forge pipeline
|
||||
mosaic forge run
|
||||
mosaic forge run [--simulate] # fails closed (FORGE_NO_EXECUTOR) with no executor wired; --simulate for typed simulated runs
|
||||
mosaic forge status
|
||||
mosaic forge resume
|
||||
mosaic forge resume [--simulate] # same fail-closed rule as forge run
|
||||
mosaic forge personas
|
||||
|
||||
# Structured logging
|
||||
|
||||
@@ -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 ? (
|
||||
|
||||
@@ -15,18 +15,18 @@
|
||||
> `done` requires: repo quality gates green, independent review recorded, terminal-green CI on
|
||||
> the PR head, squash merge to `next`, and acceptance evidence in notes.
|
||||
|
||||
| id | status | description | issue | agent | repo | branch | depends_on | estimate | notes |
|
||||
| -------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | ---------- | ----------------- | --------------------------------- | ---------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| RI-0-001 | in-progress | Bootstrap: issue #1275, PRD section, this DAG, scratchpad (docs only) | #1275 | pi-glm-5.3 | mosaicstack/stack | docs/ri-050-mission-bootstrap | — | 6K | |
|
||||
| RI-1-001 | in-progress | RI-N1: canonical terminal verification command + publish-pipeline exact-commit gate (every publish step depends on verify; commit identity check; fail closed) | #1275 | pi-glm-5.3 | mosaicstack/stack | feat/ri-050-publish-gate | RI-0-001 | 25K | |
|
||||
| RI-1-002 | not-started | RI-N1 negative control: checked-in tests proving a broken mandatory check blocks every publish step and that DAG edges cannot be bypassed | #1275 | pi-glm-5.3 | mosaicstack/stack | test/ri-050-publish-gate-negative | RI-1-001 | 12K | |
|
||||
| RI-2-001 | in-progress | RI-N2 (Forge): remove stub-executor false success; `--simulate` typed `simulated` results that satisfy nothing; literal-`true` gates and echo-review replaced with real gates or typed waiting-for-authority | #1275 | pi-glm-5.3 | mosaicstack/stack | fix/ri-050-forge-fail-closed | RI-0-001 | 20K | Independent review APPROVED 2026-08-17 (Gitea review 172 on PR #1278, head 99b8f6ea; reviewing seat fargo — recorded under shared host principal mos-dt-0, provenance correction posted by fred; wrapper gap filed by fred). Executed at head: forge tests 116/116, lint green, typecheck green after building macp dist (minimal-install artifact, not a defect), workspace typecheck 45/45, no external type consumers of the changed interfaces. CI red = known lane-wide fleet-test failure only, carries no information about this change (fred, log-content analysis, pipelines 2456-2458). Non-blocking finding: README L141-143 + skills/mosaic-forge/SKILL.md document bare forge run/resume, which now fails closed — fast-follow docs touch. Merge queued behind #1270. |
|
||||
| RI-2-002 | in-progress | RI-N2 (MACP): gate runner fails closed on empty commands, stub executors, and unimplemented CI-provider gates unless explicit simulate; typed capability failures | #1275 | pi-glm-5.3 | mosaicstack/stack | fix/ri-050-macp-fail-closed | RI-0-001 | 15K | |
|
||||
| RI-3-001 | not-started | RI-N4: complete probe inventory mapping every TS and shell quality-rail check to one canonical check with disposition (preserve/strengthen/retire, each named) | #1275 | pi-glm-5.3 | mosaicstack/stack | docs/ri-050-qr-probe-inventory | RI-0-001 | 12K | |
|
||||
| RI-3-002 | not-started | RI-N4: TS evaluator absorbs effective shell probes; typed results (passed/failed/blocked/error/not-applicable) with versioned digested check definitions; shell commands become thin adapters; contract/parity/negative-control tests | #1275 | pi-glm-5.3 | mosaicstack/stack | feat/ri-050-qr-evaluator | RI-3-001 | 30K | |
|
||||
| RI-4-001 | in-progress | RI-N3: one PRD application service — `mission --plan` persists mission↔PRD linkage (ids/versions/selected requirements); `mosaic prdy` routes through the service or becomes a named import/export adapter; Markdown is a labeled generated view; explicit conflict-aware import | #1275 | pi-glm-5.3 | mosaicstack/stack | feat/ri-050-prd-authority | RI-0-001 | 35K | |
|
||||
| RI-5-001 | not-started | RI-N5: typed freshness states (current/stale/partial/unknown/unavailable); no failed-fetch-renders-empty; stale derived verdicts → unknown; mutations disabled when stale; failure-matrix tests | #1275 | pi-glm-5.3 | mosaicstack/stack | feat/ri-050-web-stale-safety | RI-0-001 | 25K | |
|
||||
| RI-V-001 | not-started | Final verification + release evidence: all cards verified merged, negative controls demonstrated, real `next` publish run green on exact commit, evidence pack recorded | #1275 | pi-glm-5.3 | mosaicstack/stack | docs/ri-050-release-evidence | RI-1-002, RI-2-001, RI-2-002, RI-3-002, RI-4-001, RI-5-001 | 10K | |
|
||||
| id | status | description | issue | agent | repo | branch | depends_on | estimate | notes |
|
||||
| -------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | ---------- | ----------------- | --------------------------------- | ---------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| RI-0-001 | done | Bootstrap: issue #1275, PRD section, this DAG, scratchpad (docs only) | #1275 | pi-glm-5.3 | mosaicstack/stack | docs/ri-050-mission-bootstrap | — | 6K | PR #1276 (head 758659dd): docs-only, CI green (2475). Review requested from fargo. Merges first (no publish run). |
|
||||
| RI-1-001 | done | RI-N1: canonical terminal verification command + publish-pipeline exact-commit gate (every publish step depends on verify; commit identity check; fail closed) | #1275 | pi-glm-5.3 | mosaicstack/stack | feat/ri-050-publish-gate | RI-0-001 | 25K | PR #1277 (head 46784c8d): CI GREEN at head after serialized retry (pipeline 2476, 2026-08-18) - earlier red was CI-agent contention (web SPA timeouts under concurrent pipelines), not code. Review requested from fargo at pinned head (comms 20260818T021025Z). |
|
||||
| RI-1-002 | done | RI-N1 negative control: checked-in tests proving a broken mandatory check blocks every publish step and that DAG edges cannot be bypassed | #1275 | pi-glm-5.3 | mosaicstack/stack | test/ri-050-publish-gate-negative | RI-1-001 | 12K | |
|
||||
| RI-2-001 | done | RI-N2 (Forge): remove stub-executor false success; `--simulate` typed `simulated` results that satisfy nothing; literal-`true` gates and echo-review replaced with real gates or typed waiting-for-authority | #1275 | pi-glm-5.3 | mosaicstack/stack | fix/ri-050-forge-fail-closed | RI-0-001 | 20K | Independent review APPROVED 2026-08-17 (Gitea review 172 on PR #1278, head 99b8f6ea; reviewing seat fargo — recorded under shared host principal mos-dt-0, provenance correction posted by fred; wrapper gap filed by fred). Executed at head: forge tests 116/116, lint green, typecheck green after building macp dist (minimal-install artifact, not a defect), workspace typecheck 45/45, no external type consumers of the changed interfaces. CI red = known lane-wide fleet-test failure only, carries no information about this change (fred, log-content analysis, pipelines 2456-2458). Non-blocking finding: README L141-143 + skills/mosaic-forge/SKILL.md document bare forge run/resume, which now fails closed — fast-follow docs touch. Merge queued behind #1270. UPDATE 2026-08-18: #1270 merged; CI GREEN at head 4917df1f via serialized retry (pipeline 2477) - root cause of prior reds was CI-agent contention (web SPA timeouts under concurrent pipelines), superseding the fleet-test-failure theory. |
|
||||
| RI-2-002 | done | RI-N2 (MACP): gate runner fails closed on empty commands, stub executors, and unimplemented CI-provider gates unless explicit simulate; typed capability failures | #1275 | pi-glm-5.3 | mosaicstack/stack | fix/ri-050-macp-fail-closed | RI-0-001 | 15K | PR #1293 (head 2097379e): CI green (pipeline 2465), independent review APPROVED (Gitea review 173, jarvis seat, 2026-08-17) - macp 109/109 verified at head. Merge queued behind #1276/#1277/#1278. |
|
||||
| RI-3-001 | in-progress | RI-N4: complete probe inventory mapping every TS and shell quality-rail check to one canonical check with disposition (preserve/strengthen/retire, each named) | #1275 | pi-glm-5.3 | mosaicstack/stack | docs/ri-050-qr-probe-inventory | RI-0-001 | 12K | |
|
||||
| RI-3-002 | not-started | RI-N4: TS evaluator absorbs effective shell probes; typed results (passed/failed/blocked/error/not-applicable) with versioned digested check definitions; shell commands become thin adapters; contract/parity/negative-control tests | #1275 | pi-glm-5.3 | mosaicstack/stack | feat/ri-050-qr-evaluator | RI-3-001 | 30K | |
|
||||
| RI-4-001 | in-progress | RI-N3: one PRD application service — `mission --plan` persists mission↔PRD linkage (ids/versions/selected requirements); `mosaic prdy` routes through the service or becomes a named import/export adapter; Markdown is a labeled generated view; explicit conflict-aware import | #1275 | pi-glm-5.3 | mosaicstack/stack | feat/ri-050-prd-authority | RI-0-001 | 35K | PR #1294 (head 8d258e1d): CI green (pipeline 2466), independent review APPROVED (Gitea review 174, jarvis seat, 2026-08-17) - prdy 20/20 + command specs 9/9 at head. Merge queued behind #1276/#1277/#1278. |
|
||||
| RI-5-001 | done | RI-N5: typed freshness states (current/stale/partial/unknown/unavailable); no failed-fetch-renders-empty; stale derived verdicts → unknown; mutations disabled when stale; failure-matrix tests | #1275 | pi-glm-5.3 | mosaicstack/stack | feat/ri-050-web-stale-safety | RI-0-001 | 25K | |
|
||||
| RI-V-001 | not-started | Final verification + release evidence: all cards verified merged, negative controls demonstrated, real `next` publish run green on exact commit, evidence pack recorded | #1275 | pi-glm-5.3 | mosaicstack/stack | docs/ri-050-release-evidence | RI-1-002, RI-2-001, RI-2-002, RI-3-002, RI-4-001, RI-5-001 | 10K | |
|
||||
|
||||
## Dispatch waves (max 2 parallel workers)
|
||||
|
||||
|
||||
@@ -1,58 +0,0 @@
|
||||
# RI-050 Release Evidence Pack (alpha 0.0.50 release-integrity floor)
|
||||
|
||||
> Status: **DRAFT — in progress**. RI-N1/N2/N3/N5 merged to `next` behind the live gate (overnight 2026-08-18); RI-N4 and the fully-green image push remain.
|
||||
> Card: RI-V-001. All sections marked ⏳ pending their card's merge. Normative source:
|
||||
> `docs/PRD.md` § Release Integrity Workstream (#1275).
|
||||
|
||||
## RI-N1 — Canonical terminal verification + exact-commit publish gate
|
||||
|
||||
| exhibit | evidence | where |
|
||||
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------- |
|
||||
| Gate live, fail-closed | Push pipeline **2486**: `verify` ran at exact commit, FAILED on a real latent defect (gateway cross-user-isolation cleanup on the no-DB path), and `build` / `publish-npm` / `build-gateway` were all **skipped**. First push in repo history that did not publish ungated (prior ungated publishes beside failing builds: 2439, 2462, 2482). | Woodpecker repo 47 pipeline 2486 |
|
||||
| Gate-caught defect fixed | PR **#1304** (afterAll honors `dbAvailable`; both paths verified: dead-port 28 skipped + file passes; live-5433 28 passed). Review 180 (fred). | PR #1304 |
|
||||
| First gated green npm publish | Push pipeline **2488** (post-#1304): `verify` GREEN → `build` GREEN → `publish-next-npm` GREEN, all publish effects behind the gate. | Woodpecker pipeline 2488 |
|
||||
| Negative controls | PR **#1305**: structural DAG tests (S1 missing edge, S2 renamed effect incl. command-based npm/kaniko detection, S3 detach, S4 failure:ignore/success override, S5 when-filter, S6 HEAD-mover between verify and publish with legitimate-recheckout positive control, S7 removal) + subset-stage composition control in verify-release.test.mjs. Mutation-verified by the dispatching seat in both directions (true bypass → S1 assertion fires; non-bypass edit → correctly green). Scripts tests 20/20, CI 2490 green. | PR #1305 |
|
||||
| ⏳ Canonical command | `scripts/verify-release.mjs` (stage table pinned to ci.yml by checked-in test). Merged with #1277. | `scripts/verify-release.mjs` |
|
||||
|
||||
## RI-N2 — Forge + MACP fail-closed (typed explicit simulation)
|
||||
|
||||
- ✅ Forge: PR **#1278** merged (head 4917df1f; CI 2477; review 184 fred at pinned head — prior review 172 dismissed by rebase, correctly re-taken).
|
||||
- ✅ MACP: PR **#1293** merged (head 2097379e; CI 2465; review 173).
|
||||
- ⏳ Post-merge behavior docs: PR **#1299** (README + mosaic-forge SKILL.md; rebased onto post-#1278 next; review pending).
|
||||
|
||||
## RI-N3 — PRD authority
|
||||
|
||||
- ✅ PR **#1294** merged (head 8d258e1d; CI 2466; review 174).
|
||||
|
||||
## RI-N4 — Quality-rails evaluator
|
||||
|
||||
- ⏳ Probe inventory: PR **#1302** (head e06a47fa; CI 2484 green). Review pending.
|
||||
- ⏳ TS evaluator absorbs shell probes: RI-3-002, dispatched after #1302 merges.
|
||||
|
||||
## RI-N5 — Consequence-aware stale UI
|
||||
|
||||
- ✅ PR **#1300** merged (head a337d787; CI 2481; review 179). Web suite 199 → 281 tests (failure matrix + negative controls), independently re-run by the dispatching seat before merge.
|
||||
|
||||
## Known-open infrastructure item (not a card)
|
||||
|
||||
Gateway/ci-base **image** pushes fail on registry credentials: Woodpecker repo
|
||||
secrets `REGISTRY_USERNAME`/`REGISTRY_PASSWORD` are rejected by the Gitea
|
||||
container registry (explicit `UNAUTHORIZED` at `/v2/token`; pipeline 2494 after
|
||||
PR #1306 corrected the secret references — previously masked as an ambiguous
|
||||
push-permission error since at least 2439). Requires a package-scoped token
|
||||
(Jason). The npm publish path is green and gated; this item tracks image pushes
|
||||
only and predates the RI-050 floor.
|
||||
|
||||
## Process record (audit trail)
|
||||
|
||||
- Merges executed under the jarvis principal (topher seat; identity provisioning
|
||||
pending) via the Gitea API replicating `pr-merge.sh` semantics (head-pin +
|
||||
squash + keep branch): `pr-merge.sh` hard-codes `main`-only targets and cannot
|
||||
express this repo's `next` trunk — wrapper gap captured to OpenBrain
|
||||
(id 9db7a95a) and to the framework queue.
|
||||
- Reviews tonight: 175/178 (zane's #1298, both heads, by topher); 176/177/179/
|
||||
180/181/182 (fred) — cross-review rule (producer ≠ reviewer) held on every
|
||||
merge: producers were pi workers / zane; reviewers were the other seat.
|
||||
- CI contention note: concurrent PR pipelines on the single CI agent can time
|
||||
out the web SPA suite (measured 2470/2472 vs serialized 2475/2476/2477);
|
||||
serialize retries when the queue is busy.
|
||||
@@ -0,0 +1,253 @@
|
||||
import { mkdirSync, readFileSync, rmSync } from 'node:fs';
|
||||
import { join } from 'node:path';
|
||||
import { tmpdir } from 'node:os';
|
||||
import { randomUUID } from 'node:crypto';
|
||||
import { describe, it, expect, beforeEach, afterEach } from 'vitest';
|
||||
import { normalizeGate, countAIFindings, runGate, runGates } from '../src/gate-runner.js';
|
||||
|
||||
function makeTmpDir(): string {
|
||||
const dir = join(tmpdir(), `macp-gate-${randomUUID()}`);
|
||||
mkdirSync(dir, { recursive: true });
|
||||
return dir;
|
||||
}
|
||||
|
||||
describe('normalizeGate', () => {
|
||||
it('normalizes a string to mechanical gate', () => {
|
||||
expect(normalizeGate('echo test')).toEqual({
|
||||
command: 'echo test',
|
||||
type: 'mechanical',
|
||||
fail_on: 'blocker',
|
||||
});
|
||||
});
|
||||
|
||||
it('normalizes an object gate with defaults', () => {
|
||||
expect(normalizeGate({ command: 'lint' })).toEqual({
|
||||
command: 'lint',
|
||||
type: 'mechanical',
|
||||
fail_on: 'blocker',
|
||||
});
|
||||
});
|
||||
|
||||
it('preserves explicit type and fail_on', () => {
|
||||
expect(normalizeGate({ command: 'review', type: 'ai-review', fail_on: 'any' })).toEqual({
|
||||
command: 'review',
|
||||
type: 'ai-review',
|
||||
fail_on: 'any',
|
||||
});
|
||||
});
|
||||
|
||||
it('handles non-string/non-object input', () => {
|
||||
expect(normalizeGate(42)).toEqual({ command: '', type: 'mechanical', fail_on: 'blocker' });
|
||||
expect(normalizeGate(null)).toEqual({ command: '', type: 'mechanical', fail_on: 'blocker' });
|
||||
});
|
||||
});
|
||||
|
||||
describe('countAIFindings', () => {
|
||||
it('returns zeros for non-object', () => {
|
||||
expect(countAIFindings(null)).toEqual({ blockers: 0, total: 0 });
|
||||
expect(countAIFindings('string')).toEqual({ blockers: 0, total: 0 });
|
||||
expect(countAIFindings([])).toEqual({ blockers: 0, total: 0 });
|
||||
});
|
||||
|
||||
it('counts from stats block', () => {
|
||||
const output = { stats: { blockers: 2, should_fix: 3, suggestions: 1 } };
|
||||
expect(countAIFindings(output)).toEqual({ blockers: 2, total: 6 });
|
||||
});
|
||||
|
||||
it('counts from findings array when stats has no blockers', () => {
|
||||
const output = {
|
||||
stats: { blockers: 0 },
|
||||
findings: [{ severity: 'blocker' }, { severity: 'warning' }, { severity: 'blocker' }],
|
||||
};
|
||||
expect(countAIFindings(output)).toEqual({ blockers: 2, total: 3 });
|
||||
});
|
||||
|
||||
it('uses stats blockers over findings array when stats has blockers', () => {
|
||||
const output = {
|
||||
stats: { blockers: 5 },
|
||||
findings: [{ severity: 'blocker' }, { severity: 'warning' }],
|
||||
};
|
||||
// stats.blockers = 5, total from stats = 5+0+0 = 5, findings not used for total since stats total is non-zero
|
||||
expect(countAIFindings(output)).toEqual({ blockers: 5, total: 5 });
|
||||
});
|
||||
|
||||
it('counts findings length as total when stats has zero total', () => {
|
||||
const output = {
|
||||
findings: [{ severity: 'warning' }, { severity: 'info' }],
|
||||
};
|
||||
expect(countAIFindings(output)).toEqual({ blockers: 0, total: 2 });
|
||||
});
|
||||
});
|
||||
|
||||
describe('runGate', () => {
|
||||
let tmp: string;
|
||||
let logPath: string;
|
||||
|
||||
beforeEach(() => {
|
||||
tmp = makeTmpDir();
|
||||
logPath = join(tmp, 'gate.log');
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
rmSync(tmp, { recursive: true, force: true });
|
||||
});
|
||||
|
||||
it('passes mechanical gate on exit 0', () => {
|
||||
const result = runGate('echo hello', tmp, logPath, 30);
|
||||
expect(result.passed).toBe(true);
|
||||
expect(result.exit_code).toBe(0);
|
||||
expect(result.type).toBe('mechanical');
|
||||
expect(result.output).toContain('hello');
|
||||
});
|
||||
|
||||
it('fails mechanical gate on non-zero exit', () => {
|
||||
const result = runGate('exit 1', tmp, logPath, 30);
|
||||
expect(result.passed).toBe(false);
|
||||
expect(result.exit_code).toBe(1);
|
||||
});
|
||||
|
||||
it('ci-pipeline always passes', () => {
|
||||
const result = runGate({ command: 'anything', type: 'ci-pipeline' }, tmp, logPath, 30);
|
||||
expect(result.passed).toBe(true);
|
||||
expect(result.type).toBe('ci-pipeline');
|
||||
expect(result.output).toBe('CI pipeline gate placeholder');
|
||||
});
|
||||
|
||||
it('empty command passes', () => {
|
||||
const result = runGate({ command: '' }, tmp, logPath, 30);
|
||||
expect(result.passed).toBe(true);
|
||||
});
|
||||
|
||||
it('ai-review gate parses JSON output', () => {
|
||||
const json = JSON.stringify({ stats: { blockers: 0, should_fix: 1 } });
|
||||
const result = runGate({ command: `echo '${json}'`, type: 'ai-review' }, tmp, logPath, 30);
|
||||
expect(result.passed).toBe(true);
|
||||
expect(result.blockers).toBe(0);
|
||||
expect(result.findings).toBe(1);
|
||||
});
|
||||
|
||||
it('ai-review gate fails on blockers', () => {
|
||||
const json = JSON.stringify({ stats: { blockers: 2 } });
|
||||
const result = runGate({ command: `echo '${json}'`, type: 'ai-review' }, tmp, logPath, 30);
|
||||
expect(result.passed).toBe(false);
|
||||
expect(result.blockers).toBe(2);
|
||||
});
|
||||
|
||||
it('ai-review gate with fail_on=any fails on any findings', () => {
|
||||
const json = JSON.stringify({ stats: { blockers: 0, should_fix: 1 } });
|
||||
const result = runGate(
|
||||
{ command: `echo '${json}'`, type: 'ai-review', fail_on: 'any' },
|
||||
tmp,
|
||||
logPath,
|
||||
30,
|
||||
);
|
||||
expect(result.passed).toBe(false);
|
||||
expect(result.fail_on).toBe('any');
|
||||
});
|
||||
|
||||
it('ai-review gate fails on invalid JSON output', () => {
|
||||
const result = runGate({ command: 'echo "not json"', type: 'ai-review' }, tmp, logPath, 30);
|
||||
expect(result.passed).toBe(false);
|
||||
expect(result.parse_error).toBeDefined();
|
||||
});
|
||||
|
||||
it('writes to log file', () => {
|
||||
runGate('echo logged', tmp, logPath, 30);
|
||||
const log = readFileSync(logPath, 'utf-8');
|
||||
expect(log).toContain('COMMAND: echo logged');
|
||||
expect(log).toContain('logged');
|
||||
expect(log).toContain('EXIT:');
|
||||
});
|
||||
});
|
||||
|
||||
describe('runGates', () => {
|
||||
let tmp: string;
|
||||
let logPath: string;
|
||||
let eventsPath: string;
|
||||
|
||||
beforeEach(() => {
|
||||
tmp = makeTmpDir();
|
||||
logPath = join(tmp, 'gates.log');
|
||||
eventsPath = join(tmp, 'events.ndjson');
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
rmSync(tmp, { recursive: true, force: true });
|
||||
});
|
||||
|
||||
it('runs multiple gates and returns results', () => {
|
||||
const { allPassed, gateResults } = runGates(
|
||||
['echo one', 'echo two'],
|
||||
tmp,
|
||||
logPath,
|
||||
30,
|
||||
eventsPath,
|
||||
'task-1',
|
||||
);
|
||||
expect(allPassed).toBe(true);
|
||||
expect(gateResults).toHaveLength(2);
|
||||
});
|
||||
|
||||
it('reports failure when any gate fails', () => {
|
||||
const { allPassed, gateResults } = runGates(
|
||||
['echo ok', 'exit 1'],
|
||||
tmp,
|
||||
logPath,
|
||||
30,
|
||||
eventsPath,
|
||||
'task-2',
|
||||
);
|
||||
expect(allPassed).toBe(false);
|
||||
expect(gateResults[0]!.passed).toBe(true);
|
||||
expect(gateResults[1]!.passed).toBe(false);
|
||||
});
|
||||
|
||||
it('emits events for each gate', () => {
|
||||
runGates(['echo test'], tmp, logPath, 30, eventsPath, 'task-3');
|
||||
const events = readFileSync(eventsPath, 'utf-8')
|
||||
.trim()
|
||||
.split('\n')
|
||||
.map((l) => JSON.parse(l));
|
||||
expect(events).toHaveLength(2); // started + passed
|
||||
expect(events[0].event_type).toBe('rail.check.started');
|
||||
expect(events[1].event_type).toBe('rail.check.passed');
|
||||
});
|
||||
|
||||
it('skips gates with empty command (non ci-pipeline)', () => {
|
||||
const { gateResults } = runGates(
|
||||
[{ command: '', type: 'mechanical' }, 'echo real'],
|
||||
tmp,
|
||||
logPath,
|
||||
30,
|
||||
eventsPath,
|
||||
'task-4',
|
||||
);
|
||||
expect(gateResults).toHaveLength(1);
|
||||
});
|
||||
|
||||
it('does not skip ci-pipeline even with empty command', () => {
|
||||
const { gateResults } = runGates(
|
||||
[{ command: '', type: 'ci-pipeline' }],
|
||||
tmp,
|
||||
logPath,
|
||||
30,
|
||||
eventsPath,
|
||||
'task-5',
|
||||
);
|
||||
expect(gateResults).toHaveLength(1);
|
||||
expect(gateResults[0]!.passed).toBe(true);
|
||||
});
|
||||
|
||||
it('emits failed event with correct message', () => {
|
||||
runGates(['exit 42'], tmp, logPath, 30, eventsPath, 'task-6');
|
||||
const events = readFileSync(eventsPath, 'utf-8')
|
||||
.trim()
|
||||
.split('\n')
|
||||
.map((l) => JSON.parse(l));
|
||||
const failEvent = events.find(
|
||||
(e: Record<string, unknown>) => e.event_type === 'rail.check.failed',
|
||||
);
|
||||
expect(failEvent).toBeDefined();
|
||||
expect(failEvent.message).toContain('Gate failed (');
|
||||
});
|
||||
});
|
||||
@@ -1,8 +1,5 @@
|
||||
import { describe, it, expect, afterEach, beforeEach, vi } from 'vitest';
|
||||
import { describe, it, expect } from 'vitest';
|
||||
import { Command } from 'commander';
|
||||
import fs from 'node:fs';
|
||||
import os from 'node:os';
|
||||
import path from 'node:path';
|
||||
import { registerMacpCommand } from './cli.js';
|
||||
|
||||
describe('registerMacpCommand', () => {
|
||||
@@ -78,162 +75,3 @@ describe('registerMacpCommand', () => {
|
||||
expect(topLevel).toContain('events');
|
||||
});
|
||||
});
|
||||
|
||||
/**
|
||||
* RI-N2 fail-closed CLI behavior: an unimplemented capability is a failure,
|
||||
* never a success. Every stub exits nonzero with a typed message, and the
|
||||
* implemented `macp gate` mirrors the typed gate-runner states.
|
||||
*/
|
||||
describe('registerMacpCommand fail-closed (RI-N2)', () => {
|
||||
let tmpDir: string;
|
||||
|
||||
function buildProgram(): Command {
|
||||
const program = new Command();
|
||||
program.exitOverride();
|
||||
program.configureOutput({ writeErr: () => {} });
|
||||
registerMacpCommand(program);
|
||||
return program;
|
||||
}
|
||||
|
||||
beforeEach(() => {
|
||||
tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'macp-cli-failclosed-'));
|
||||
process.exitCode = 0;
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
process.exitCode = 0;
|
||||
fs.rmSync(tmpDir, { recursive: true, force: true });
|
||||
});
|
||||
|
||||
it('macp tasks list exits nonzero (unimplemented capability)', async () => {
|
||||
const program = buildProgram();
|
||||
await program.parseAsync(['macp', 'tasks', 'list'], { from: 'user' });
|
||||
expect(process.exitCode).not.toBe(0);
|
||||
});
|
||||
|
||||
it('macp submit exits nonzero with a typed MACP_NOT_IMPLEMENTED message', async () => {
|
||||
const program = buildProgram();
|
||||
const errSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
|
||||
try {
|
||||
await program.parseAsync(['macp', 'submit', 'spec.json'], { from: 'user' });
|
||||
expect(process.exitCode).not.toBe(0);
|
||||
const errText = errSpy.mock.calls.map((c) => String(c[0])).join('\n');
|
||||
expect(errText).toContain('MACP_NOT_IMPLEMENTED');
|
||||
} finally {
|
||||
errSpy.mockRestore();
|
||||
}
|
||||
});
|
||||
|
||||
it('macp events tail exits nonzero (unimplemented capability)', async () => {
|
||||
const program = buildProgram();
|
||||
await program.parseAsync(['macp', 'events', 'tail'], { from: 'user' });
|
||||
expect(process.exitCode).not.toBe(0);
|
||||
});
|
||||
|
||||
it('macp gate runs a green inline command and exits 0', async () => {
|
||||
const program = buildProgram();
|
||||
await program.parseAsync(
|
||||
[
|
||||
'macp',
|
||||
'gate',
|
||||
'exit 0',
|
||||
'--cwd',
|
||||
tmpDir,
|
||||
'--log',
|
||||
path.join(tmpDir, 'g.log'),
|
||||
'--timeout',
|
||||
'10',
|
||||
],
|
||||
{ from: 'user' },
|
||||
);
|
||||
expect(process.exitCode).toBe(0);
|
||||
});
|
||||
|
||||
it('macp gate exits nonzero on a failing command', async () => {
|
||||
const program = buildProgram();
|
||||
await program.parseAsync(
|
||||
[
|
||||
'macp',
|
||||
'gate',
|
||||
'exit 9',
|
||||
'--cwd',
|
||||
tmpDir,
|
||||
'--log',
|
||||
path.join(tmpDir, 'g.log'),
|
||||
'--timeout',
|
||||
'10',
|
||||
],
|
||||
{ from: 'user' },
|
||||
);
|
||||
expect(process.exitCode).not.toBe(0);
|
||||
});
|
||||
|
||||
it('macp gate with an unimplemented ci-pipeline capability exits nonzero', async () => {
|
||||
const program = buildProgram();
|
||||
const specPath = path.join(tmpDir, 'gates.json');
|
||||
fs.writeFileSync(specPath, JSON.stringify([{ type: 'ci-pipeline' }]));
|
||||
await program.parseAsync(
|
||||
[
|
||||
'macp',
|
||||
'gate',
|
||||
specPath,
|
||||
'--cwd',
|
||||
tmpDir,
|
||||
'--log',
|
||||
path.join(tmpDir, 'g.log'),
|
||||
'--timeout',
|
||||
'10',
|
||||
],
|
||||
{ from: 'user' },
|
||||
);
|
||||
expect(process.exitCode).not.toBe(0);
|
||||
});
|
||||
|
||||
it('macp gate --simulate completes (exit 0) but reports simulated results', async () => {
|
||||
const program = buildProgram();
|
||||
const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
|
||||
try {
|
||||
await program.parseAsync(
|
||||
[
|
||||
'macp',
|
||||
'gate',
|
||||
'exit 0',
|
||||
'--simulate',
|
||||
'--cwd',
|
||||
tmpDir,
|
||||
'--log',
|
||||
path.join(tmpDir, 'g.log'),
|
||||
'--timeout',
|
||||
'10',
|
||||
],
|
||||
{ from: 'user' },
|
||||
);
|
||||
// completes only because the caller explicitly asked to simulate
|
||||
expect(process.exitCode).toBe(0);
|
||||
const outText = logSpy.mock.calls.map((c) => String(c[0])).join('\n');
|
||||
expect(outText).toContain('simulated');
|
||||
expect(outText).toContain('SIMULATED');
|
||||
} finally {
|
||||
logSpy.mockRestore();
|
||||
}
|
||||
});
|
||||
|
||||
it('macp gate with an empty spec exits nonzero with a typed error', async () => {
|
||||
const program = buildProgram();
|
||||
await program.parseAsync(
|
||||
[
|
||||
'macp',
|
||||
'gate',
|
||||
' ',
|
||||
'--cwd',
|
||||
tmpDir,
|
||||
'--log',
|
||||
path.join(tmpDir, 'g.log'),
|
||||
'--timeout',
|
||||
'10',
|
||||
],
|
||||
{ from: 'user' },
|
||||
);
|
||||
expect(process.exitCode).not.toBe(0);
|
||||
});
|
||||
});
|
||||
|
||||
+19
-129
@@ -1,73 +1,5 @@
|
||||
import { existsSync, readFileSync } from 'node:fs';
|
||||
|
||||
import type { Command } from 'commander';
|
||||
|
||||
import { runGates } from './gate-runner.js';
|
||||
import { MACPCapabilityError, type MacpErrorCode } from './errors.js';
|
||||
|
||||
/**
|
||||
* Load gates from a spec: an existing file (JSON gates array, a JSON object
|
||||
* with `quality_gates`, a JSON gate object, or one command per line) or an
|
||||
* inline command string. Fails closed with a typed capability error when the
|
||||
* spec contains no executable gate definition.
|
||||
*/
|
||||
function loadGateSpec(spec: string): unknown[] {
|
||||
if (existsSync(spec)) {
|
||||
const raw = readFileSync(spec, 'utf-8');
|
||||
try {
|
||||
const parsed = JSON.parse(raw) as unknown;
|
||||
if (Array.isArray(parsed)) {
|
||||
if (parsed.length === 0) {
|
||||
throw new MACPCapabilityError(
|
||||
'MACP_NO_COMMAND',
|
||||
'gate-spec',
|
||||
`gate spec file '${spec}' contains an empty gates array`,
|
||||
);
|
||||
}
|
||||
return parsed;
|
||||
}
|
||||
if (typeof parsed === 'object' && parsed !== null) {
|
||||
const obj = parsed as Record<string, unknown>;
|
||||
if (Array.isArray(obj['quality_gates'])) {
|
||||
return obj['quality_gates'];
|
||||
}
|
||||
return [parsed];
|
||||
}
|
||||
throw new MACPCapabilityError(
|
||||
'MACP_NO_COMMAND',
|
||||
'gate-spec',
|
||||
`gate spec file '${spec}' parsed to ${typeof parsed} — expected a gates array, a task with quality_gates, or a gate object`,
|
||||
);
|
||||
} catch (exc) {
|
||||
if (exc instanceof MACPCapabilityError) throw exc;
|
||||
// Not JSON — treat each non-empty line as a command gate.
|
||||
const lines = raw
|
||||
.split('\n')
|
||||
.map((l) => l.trim())
|
||||
.filter((l) => l.length > 0);
|
||||
if (lines.length > 0) return lines;
|
||||
throw new MACPCapabilityError(
|
||||
'MACP_NO_COMMAND',
|
||||
'gate-spec',
|
||||
`gate spec file '${spec}' contains no gates`,
|
||||
);
|
||||
}
|
||||
}
|
||||
if (spec.trim().length > 0) return [spec];
|
||||
throw new MACPCapabilityError('MACP_NO_COMMAND', 'gate-spec', 'gate spec is empty');
|
||||
}
|
||||
|
||||
/** Print a typed not-implemented failure and exit nonzero (RI-N2 fail-closed). */
|
||||
function notImplemented(subcommand: string, capability: string, hint: string): void {
|
||||
const err = new MACPCapabilityError(
|
||||
'MACP_NOT_IMPLEMENTED',
|
||||
capability,
|
||||
`${subcommand} is not implemented in @mosaicstack/macp yet (${capability} capability absent) — ${hint}`,
|
||||
);
|
||||
console.error(`[macp] ${subcommand}: ${err.message} [${err.code}]`);
|
||||
process.exitCode = 1;
|
||||
}
|
||||
|
||||
/**
|
||||
* Register macp subcommands on an existing Commander program.
|
||||
* This avoids cross-package Commander version mismatches by using the
|
||||
@@ -92,14 +24,15 @@ export function registerMacpCommand(parent: Command): void {
|
||||
'Filter by task type (coding|deploy|research|review|documentation|infrastructure)',
|
||||
)
|
||||
.action((opts: { status?: string; type?: string }) => {
|
||||
// unimplemented capability — a failure, never a success (RI-N2)
|
||||
// not yet wired — task persistence layer is not present in @mosaicstack/macp
|
||||
console.log('[macp] tasks list: not yet wired — use macp package programmatically');
|
||||
if (opts.status) {
|
||||
console.log(` status filter: ${opts.status}`);
|
||||
}
|
||||
if (opts.type) {
|
||||
console.log(` type filter: ${opts.type}`);
|
||||
}
|
||||
notImplemented('tasks list', 'task-persistence', 'use the macp package programmatically');
|
||||
process.exitCode = 0;
|
||||
});
|
||||
|
||||
// ─── submit ──────────────────────────────────────────────────────────────
|
||||
@@ -108,11 +41,12 @@ export function registerMacpCommand(parent: Command): void {
|
||||
.command('submit <path>')
|
||||
.description('Submit a task from a JSON/YAML spec file')
|
||||
.action((specPath: string) => {
|
||||
// unimplemented capability — a failure, never a success (RI-N2)
|
||||
// not yet wired — task submission requires a running MACP server
|
||||
console.log('[macp] submit: not yet wired — use macp package programmatically');
|
||||
console.log(` spec path: ${specPath}`);
|
||||
console.log(' task id: (unavailable — no MACP server connected)');
|
||||
console.log(' status: (unavailable — no MACP server connected)');
|
||||
notImplemented('submit', 'macp-server', 'use the macp package programmatically');
|
||||
process.exitCode = 0;
|
||||
});
|
||||
|
||||
// ─── gate ────────────────────────────────────────────────────────────────
|
||||
@@ -124,58 +58,16 @@ export function registerMacpCommand(parent: Command): void {
|
||||
.option('--cwd <path>', 'Working directory for gate execution', process.cwd())
|
||||
.option('--log <path>', 'Path to write gate log output', '/tmp/macp-gate.log')
|
||||
.option('--timeout <seconds>', 'Gate timeout in seconds', '60')
|
||||
.option(
|
||||
'--simulate',
|
||||
'Simulate gates instead of executing them; results are typed simulated and never satisfy a check',
|
||||
)
|
||||
.action(
|
||||
(
|
||||
spec: string,
|
||||
opts: { failOn: string; cwd: string; log: string; timeout: string; simulate?: boolean },
|
||||
) => {
|
||||
let gates: unknown[];
|
||||
try {
|
||||
gates = loadGateSpec(spec);
|
||||
} catch (exc) {
|
||||
if (exc instanceof MACPCapabilityError) {
|
||||
console.error(`[macp] gate: ${exc.message} [${exc.code}]`);
|
||||
} else {
|
||||
console.error(`[macp] gate: ${String(exc)}`);
|
||||
}
|
||||
process.exitCode = 1;
|
||||
return;
|
||||
}
|
||||
|
||||
const timeoutSec = Number.parseInt(opts.timeout, 10) || 60;
|
||||
const eventsPath = `${opts.log}.events.ndjson`;
|
||||
const { state, gateResults } = runGates(
|
||||
gates,
|
||||
opts.cwd,
|
||||
opts.log,
|
||||
timeoutSec,
|
||||
eventsPath,
|
||||
'macp-cli-gate',
|
||||
{
|
||||
simulate: opts.simulate,
|
||||
},
|
||||
);
|
||||
|
||||
for (const r of gateResults) {
|
||||
const label = r.command || r.type;
|
||||
const reason = r.reason ? ` — ${r.reason}` : '';
|
||||
console.log(`[macp] gate ${r.status}: ${label}${reason}`);
|
||||
}
|
||||
if (opts.simulate) {
|
||||
console.log(
|
||||
'[macp] SIMULATED run — every result is typed simulated and can never satisfy a gate, dependency, or release check',
|
||||
);
|
||||
}
|
||||
|
||||
// Simulated runs may complete (exit 0) only because the caller
|
||||
// explicitly passed --simulate; the typed state stays 'simulated'.
|
||||
process.exitCode = state === 'passed' || state === 'simulated' ? 0 : 1;
|
||||
},
|
||||
);
|
||||
.action((spec: string, opts: { failOn: string; cwd: string; log: string; timeout: string }) => {
|
||||
// not yet wired — gate execution requires a task context and event sink
|
||||
console.log('[macp] gate: not yet wired — use macp package programmatically');
|
||||
console.log(` spec: ${spec}`);
|
||||
console.log(` fail-on: ${opts.failOn}`);
|
||||
console.log(` cwd: ${opts.cwd}`);
|
||||
console.log(` log: ${opts.log}`);
|
||||
console.log(` timeout: ${opts.timeout}s`);
|
||||
process.exitCode = 0;
|
||||
});
|
||||
|
||||
// ─── events ──────────────────────────────────────────────────────────────
|
||||
|
||||
@@ -187,16 +79,14 @@ export function registerMacpCommand(parent: Command): void {
|
||||
.option('--file <path>', 'Path to the MACP events NDJSON file')
|
||||
.option('--follow', 'Follow the file for new events (like tail -f)')
|
||||
.action((opts: { file?: string; follow?: boolean }) => {
|
||||
// unimplemented capability — a failure, never a success (RI-N2)
|
||||
// not yet wired — event streaming requires a live event source
|
||||
console.log('[macp] events tail: not yet wired — use macp package programmatically');
|
||||
if (opts.file) {
|
||||
console.log(` file: ${opts.file}`);
|
||||
}
|
||||
if (opts.follow) {
|
||||
console.log(' mode: follow');
|
||||
}
|
||||
notImplemented('events tail', 'event-source', 'use the macp package programmatically');
|
||||
process.exitCode = 0;
|
||||
});
|
||||
}
|
||||
|
||||
// Re-export so CLI consumers can surface typed capability codes.
|
||||
export type { MacpErrorCode };
|
||||
|
||||
@@ -1,35 +0,0 @@
|
||||
/** Typed error code from the closed MACP_ERROR_CODES set. */
|
||||
export type MacpErrorCode = (typeof MACP_ERROR_CODES)[number];
|
||||
/**
|
||||
* Typed fail-closed capability errors (RI-N2, SDLC-D-035).
|
||||
*
|
||||
* MACP must fail closed when a required capability (executor, reviewer,
|
||||
* command, CI provider, human authority) is absent. These typed codes mirror
|
||||
* the Forge failure vocabulary (FORGE_NO_*) so both packages speak the same
|
||||
* language: an unimplemented capability is a failure, never a stub success.
|
||||
*/
|
||||
|
||||
/** Closed set of typed MACP capability error codes. */
|
||||
export const MACP_ERROR_CODES = [
|
||||
'MACP_NOT_IMPLEMENTED',
|
||||
'MACP_NO_COMMAND',
|
||||
'MACP_NO_REVIEWER',
|
||||
'MACP_NO_CI_PIPELINE',
|
||||
'MACP_NO_PROVIDER',
|
||||
'MACP_AUTHORITY_REQUIRED',
|
||||
] as const;
|
||||
|
||||
/** Raised when a required capability is missing and execution must fail closed. */
|
||||
export class MACPCapabilityError extends Error {
|
||||
/** Typed error code from the closed MACP_ERROR_CODES set. */
|
||||
readonly code: MacpErrorCode;
|
||||
/** The missing capability, e.g. `ci-provider`, `task-persistence`, `command`. */
|
||||
readonly capability: string;
|
||||
|
||||
constructor(code: MacpErrorCode, capability: string, message: string) {
|
||||
super(message);
|
||||
this.name = 'MACPCapabilityError';
|
||||
this.code = code;
|
||||
this.capability = capability;
|
||||
}
|
||||
}
|
||||
@@ -1,429 +0,0 @@
|
||||
import fs from 'node:fs';
|
||||
import os from 'node:os';
|
||||
import path from 'node:path';
|
||||
import { afterEach, beforeEach, describe, expect, it } from 'vitest';
|
||||
|
||||
import { countAIFindings, normalizeGate, runGate, runGates } from './gate-runner.js';
|
||||
|
||||
function makeTmpDir(): string {
|
||||
return fs.mkdtempSync(path.join(os.tmpdir(), 'macp-gate-'));
|
||||
}
|
||||
|
||||
describe('normalizeGate', () => {
|
||||
it('normalizes a string to mechanical gate', () => {
|
||||
expect(normalizeGate('echo test')).toEqual({
|
||||
command: 'echo test',
|
||||
type: 'mechanical',
|
||||
fail_on: 'blocker',
|
||||
});
|
||||
});
|
||||
|
||||
it('normalizes an object gate with defaults', () => {
|
||||
expect(normalizeGate({ command: 'lint' })).toEqual({
|
||||
command: 'lint',
|
||||
type: 'mechanical',
|
||||
fail_on: 'blocker',
|
||||
});
|
||||
});
|
||||
|
||||
it('preserves explicit type and fail_on', () => {
|
||||
expect(normalizeGate({ command: 'review', type: 'ai-review', fail_on: 'any' })).toEqual({
|
||||
command: 'review',
|
||||
type: 'ai-review',
|
||||
fail_on: 'any',
|
||||
});
|
||||
});
|
||||
|
||||
it('handles non-string/non-object input', () => {
|
||||
expect(normalizeGate(42)).toEqual({ command: '', type: 'mechanical', fail_on: 'blocker' });
|
||||
expect(normalizeGate(null)).toEqual({ command: '', type: 'mechanical', fail_on: 'blocker' });
|
||||
});
|
||||
});
|
||||
|
||||
describe('countAIFindings', () => {
|
||||
it('returns zeros for non-object', () => {
|
||||
expect(countAIFindings(null)).toEqual({ blockers: 0, total: 0 });
|
||||
expect(countAIFindings('string')).toEqual({ blockers: 0, total: 0 });
|
||||
expect(countAIFindings([])).toEqual({ blockers: 0, total: 0 });
|
||||
});
|
||||
|
||||
it('counts from stats block', () => {
|
||||
const output = { stats: { blockers: 2, should_fix: 3, suggestions: 1 } };
|
||||
expect(countAIFindings(output)).toEqual({ blockers: 2, total: 6 });
|
||||
});
|
||||
|
||||
it('counts from findings array when stats has no blockers', () => {
|
||||
const output = {
|
||||
stats: { blockers: 0 },
|
||||
findings: [{ severity: 'blocker' }, { severity: 'warning' }, { severity: 'blocker' }],
|
||||
};
|
||||
expect(countAIFindings(output)).toEqual({ blockers: 2, total: 3 });
|
||||
});
|
||||
|
||||
it('uses stats blockers over findings array when stats has blockers', () => {
|
||||
const output = {
|
||||
stats: { blockers: 5 },
|
||||
findings: [{ severity: 'blocker' }, { severity: 'warning' }],
|
||||
};
|
||||
// stats.blockers = 5, total from stats = 5+0+0 = 5, findings not used for total since stats total is non-zero
|
||||
expect(countAIFindings(output)).toEqual({ blockers: 5, total: 5 });
|
||||
});
|
||||
|
||||
it('counts findings length as total when stats has zero total', () => {
|
||||
const output = {
|
||||
findings: [{ severity: 'warning' }, { severity: 'info' }],
|
||||
};
|
||||
expect(countAIFindings(output)).toEqual({ blockers: 0, total: 2 });
|
||||
});
|
||||
});
|
||||
|
||||
describe('runGate', () => {
|
||||
let tmp: string;
|
||||
let logPath: string;
|
||||
|
||||
beforeEach(() => {
|
||||
tmp = makeTmpDir();
|
||||
logPath = path.join(tmp, 'gate.log');
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
fs.rmSync(tmp, { recursive: true, force: true });
|
||||
});
|
||||
|
||||
it('passes mechanical gate on exit 0', () => {
|
||||
const result = runGate('echo hello', tmp, logPath, 30);
|
||||
expect(result.passed).toBe(true);
|
||||
expect(result.exit_code).toBe(0);
|
||||
expect(result.type).toBe('mechanical');
|
||||
expect(result.output).toContain('hello');
|
||||
});
|
||||
|
||||
it('fails mechanical gate on non-zero exit', () => {
|
||||
const result = runGate('exit 1', tmp, logPath, 30);
|
||||
expect(result.passed).toBe(false);
|
||||
expect(result.exit_code).toBe(1);
|
||||
});
|
||||
|
||||
it('ci-pipeline fails closed without a CI provider (no placeholder pass)', () => {
|
||||
const result = runGate({ command: 'anything', type: 'ci-pipeline' }, tmp, logPath, 30);
|
||||
expect(result.passed).toBe(false);
|
||||
expect(result.status).toBe('capability_failure');
|
||||
expect(result.capability_code).toBe('MACP_NO_CI_PIPELINE');
|
||||
expect(result.type).toBe('ci-pipeline');
|
||||
expect(result.output).not.toBe('CI pipeline gate placeholder');
|
||||
});
|
||||
|
||||
it('empty command is a typed capability failure, never a pass', () => {
|
||||
const result = runGate({ command: '' }, tmp, logPath, 30);
|
||||
expect(result.passed).toBe(false);
|
||||
expect(result.status).toBe('capability_failure');
|
||||
expect(result.capability_code).toBe('MACP_NO_COMMAND');
|
||||
});
|
||||
|
||||
it('ai-review gate parses JSON output', () => {
|
||||
const json = JSON.stringify({ stats: { blockers: 0, should_fix: 1 } });
|
||||
const result = runGate({ command: `echo '${json}'`, type: 'ai-review' }, tmp, logPath, 30);
|
||||
expect(result.passed).toBe(true);
|
||||
expect(result.blockers).toBe(0);
|
||||
expect(result.findings).toBe(1);
|
||||
});
|
||||
|
||||
it('ai-review gate fails on blockers', () => {
|
||||
const json = JSON.stringify({ stats: { blockers: 2 } });
|
||||
const result = runGate({ command: `echo '${json}'`, type: 'ai-review' }, tmp, logPath, 30);
|
||||
expect(result.passed).toBe(false);
|
||||
expect(result.blockers).toBe(2);
|
||||
});
|
||||
|
||||
it('ai-review gate with fail_on=any fails on any findings', () => {
|
||||
const json = JSON.stringify({ stats: { blockers: 0, should_fix: 1 } });
|
||||
const result = runGate(
|
||||
{ command: `echo '${json}'`, type: 'ai-review', fail_on: 'any' },
|
||||
tmp,
|
||||
logPath,
|
||||
30,
|
||||
);
|
||||
expect(result.passed).toBe(false);
|
||||
expect(result.fail_on).toBe('any');
|
||||
});
|
||||
|
||||
it('ai-review gate fails on invalid JSON output', () => {
|
||||
const result = runGate({ command: 'echo "not json"', type: 'ai-review' }, tmp, logPath, 30);
|
||||
expect(result.passed).toBe(false);
|
||||
expect(result.parse_error).toBeDefined();
|
||||
});
|
||||
|
||||
it('writes to log file', () => {
|
||||
runGate('echo logged', tmp, logPath, 30);
|
||||
const log = fs.readFileSync(logPath, 'utf-8');
|
||||
expect(log).toContain('COMMAND: echo logged');
|
||||
expect(log).toContain('logged');
|
||||
expect(log).toContain('EXIT:');
|
||||
});
|
||||
});
|
||||
|
||||
describe('runGates', () => {
|
||||
let tmp: string;
|
||||
let logPath: string;
|
||||
let eventsPath: string;
|
||||
|
||||
beforeEach(() => {
|
||||
tmp = makeTmpDir();
|
||||
logPath = path.join(tmp, 'gates.log');
|
||||
eventsPath = path.join(tmp, 'events.ndjson');
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
fs.rmSync(tmp, { recursive: true, force: true });
|
||||
});
|
||||
|
||||
it('runs multiple gates and returns results', () => {
|
||||
const { allPassed, gateResults } = runGates(
|
||||
['echo one', 'echo two'],
|
||||
tmp,
|
||||
logPath,
|
||||
30,
|
||||
eventsPath,
|
||||
'task-1',
|
||||
);
|
||||
expect(allPassed).toBe(true);
|
||||
expect(gateResults).toHaveLength(2);
|
||||
});
|
||||
|
||||
it('reports failure when any gate fails', () => {
|
||||
const { allPassed, gateResults } = runGates(
|
||||
['echo ok', 'exit 1'],
|
||||
tmp,
|
||||
logPath,
|
||||
30,
|
||||
eventsPath,
|
||||
'task-2',
|
||||
);
|
||||
expect(allPassed).toBe(false);
|
||||
expect(gateResults[0]!.passed).toBe(true);
|
||||
expect(gateResults[1]!.passed).toBe(false);
|
||||
});
|
||||
|
||||
it('emits events for each gate', () => {
|
||||
runGates(['echo test'], tmp, logPath, 30, eventsPath, 'task-3');
|
||||
const events = fs
|
||||
.readFileSync(eventsPath, 'utf-8')
|
||||
.trim()
|
||||
.split('\n')
|
||||
.map((l) => JSON.parse(l));
|
||||
expect(events).toHaveLength(2); // started + passed
|
||||
expect(events[0].event_type).toBe('rail.check.started');
|
||||
expect(events[1].event_type).toBe('rail.check.passed');
|
||||
});
|
||||
|
||||
it('does not silently skip gates with empty command — they become capability failures', () => {
|
||||
const { gateResults, allPassed, state } = runGates(
|
||||
[{ command: '', type: 'mechanical' }, 'echo real'],
|
||||
tmp,
|
||||
logPath,
|
||||
30,
|
||||
eventsPath,
|
||||
'task-4',
|
||||
);
|
||||
expect(gateResults).toHaveLength(2);
|
||||
expect(gateResults[0]!.status).toBe('capability_failure');
|
||||
expect(gateResults[1]!.status).toBe('passed');
|
||||
expect(allPassed).toBe(false);
|
||||
expect(state).toBe('capability_failure');
|
||||
});
|
||||
|
||||
it('does not skip ci-pipeline even with empty command — typed capability failure', () => {
|
||||
const { gateResults, allPassed, state } = runGates(
|
||||
[{ command: '', type: 'ci-pipeline' }],
|
||||
tmp,
|
||||
logPath,
|
||||
30,
|
||||
eventsPath,
|
||||
'task-5',
|
||||
);
|
||||
expect(gateResults).toHaveLength(1);
|
||||
expect(gateResults[0]!.passed).toBe(false);
|
||||
expect(gateResults[0]!.status).toBe('capability_failure');
|
||||
expect(allPassed).toBe(false);
|
||||
expect(state).toBe('capability_failure');
|
||||
});
|
||||
|
||||
it('emits failed event with correct message', () => {
|
||||
runGates(['exit 42'], tmp, logPath, 30, eventsPath, 'task-6');
|
||||
const events = fs
|
||||
.readFileSync(eventsPath, 'utf-8')
|
||||
.trim()
|
||||
.split('\n')
|
||||
.map((l) => JSON.parse(l));
|
||||
const failEvent = events.find(
|
||||
(e: Record<string, unknown>) => e.event_type === 'rail.check.failed',
|
||||
);
|
||||
expect(failEvent).toBeDefined();
|
||||
expect(failEvent.message).toContain('Gate failed (');
|
||||
});
|
||||
});
|
||||
|
||||
/**
|
||||
* RI-N2 / SDLC-D-035 fail-closed controls for the MACP gate runner.
|
||||
*
|
||||
* Invariant under test: `passed: true` occurs ONLY when a gate really executed
|
||||
* and really exited green (`status === 'passed'`). Absent capabilities,
|
||||
* manual sign-offs, and simulated runs are typed distinctly and can never
|
||||
* make the aggregate `passed`.
|
||||
*/
|
||||
describe('gate-runner fail-closed (RI-N2)', () => {
|
||||
let tmpDir: string;
|
||||
let logPath: string;
|
||||
let eventsPath: string;
|
||||
|
||||
beforeEach(() => {
|
||||
tmpDir = makeTmpDir();
|
||||
logPath = path.join(tmpDir, 'gate.log');
|
||||
eventsPath = path.join(tmpDir, 'events.ndjson');
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
fs.rmSync(tmpDir, { recursive: true, force: true });
|
||||
});
|
||||
|
||||
function run(gates: unknown[], options?: { simulate?: boolean }) {
|
||||
return runGates(gates, tmpDir, logPath, 10, eventsPath, 'spec-task', options);
|
||||
}
|
||||
|
||||
// ─── positive controls ───────────────────────────────────────────────────
|
||||
|
||||
it('a really-executed green command gate still passes', () => {
|
||||
const result = run([{ command: 'exit 0', type: 'mechanical' }]);
|
||||
expect(result.gateResults[0]!.status).toBe('passed');
|
||||
expect(result.gateResults[0]!.passed).toBe(true);
|
||||
expect(result.allPassed).toBe(true);
|
||||
expect(result.state).toBe('passed');
|
||||
});
|
||||
|
||||
it('explicit simulate completes and types every result simulated', () => {
|
||||
const result = run([{ command: 'exit 0', type: 'mechanical' }, 'echo hello'], {
|
||||
simulate: true,
|
||||
});
|
||||
expect(result.gateResults).toHaveLength(2);
|
||||
for (const gate of result.gateResults) {
|
||||
expect(gate.status).toBe('simulated');
|
||||
expect(gate.passed).toBe(false);
|
||||
}
|
||||
expect(result.state).toBe('simulated');
|
||||
});
|
||||
|
||||
it('a really-executed red command gate fails with typed status failed', () => {
|
||||
const result = run([{ command: 'exit 3', type: 'mechanical' }]);
|
||||
expect(result.gateResults[0]!.status).toBe('failed');
|
||||
expect(result.gateResults[0]!.passed).toBe(false);
|
||||
expect(result.allPassed).toBe(false);
|
||||
expect(result.state).toBe('failed');
|
||||
});
|
||||
|
||||
// ─── negative controls — each asserts typed status AND aggregate not passed ──
|
||||
|
||||
it('an empty-command gate is a capability_failure, not skipped and not passed', () => {
|
||||
const result = run([{ command: '', type: 'mechanical' }]);
|
||||
// runGates must not silently skip it — it produces a typed result
|
||||
expect(result.gateResults).toHaveLength(1);
|
||||
const gate = result.gateResults[0]!;
|
||||
expect(gate.status).toBe('capability_failure');
|
||||
expect(gate.capability_code).toBe('MACP_NO_COMMAND');
|
||||
expect(gate.passed).toBe(false);
|
||||
// aggregate is not passed
|
||||
expect(result.allPassed).toBe(false);
|
||||
expect(result.state).toBe('capability_failure');
|
||||
expect(result.state).not.toBe('passed');
|
||||
});
|
||||
|
||||
it('a commandless ai-review gate is a typed MACP_NO_REVIEWER capability_failure', () => {
|
||||
const result = run([{ command: '', type: 'ai-review' }]);
|
||||
expect(result.gateResults[0]!.status).toBe('capability_failure');
|
||||
expect(result.gateResults[0]!.capability_code).toBe('MACP_NO_REVIEWER');
|
||||
expect(result.allPassed).toBe(false);
|
||||
expect(result.state).not.toBe('passed');
|
||||
});
|
||||
|
||||
it('a ci-pipeline gate without a provider implementation is a capability_failure, never a placeholder pass', () => {
|
||||
const result = run([{ command: '', type: 'ci-pipeline' }]);
|
||||
const gate = result.gateResults[0]!;
|
||||
expect(gate.status).toBe('capability_failure');
|
||||
expect(gate.capability_code).toBe('MACP_NO_CI_PIPELINE');
|
||||
expect(gate.passed).toBe(false);
|
||||
// the old false-success placeholder must be gone
|
||||
expect(gate.output).not.toBe('CI pipeline gate placeholder');
|
||||
expect(result.allPassed).toBe(false);
|
||||
expect(result.state).not.toBe('passed');
|
||||
});
|
||||
|
||||
it('a ci-pipeline gate fails closed even alongside an otherwise green run', () => {
|
||||
const result = run(['exit 0', { type: 'ci-pipeline', command: 'fake-ci' }]);
|
||||
expect(result.gateResults[1]!.status).toBe('capability_failure');
|
||||
expect(result.gateResults[0]!.status).toBe('passed');
|
||||
expect(result.allPassed).toBe(false);
|
||||
expect(result.state).toBe('capability_failure');
|
||||
});
|
||||
|
||||
it('a manual gate with no automation enters typed waiting — neither pass nor fail', () => {
|
||||
const result = run([{ type: 'manual' }]);
|
||||
const gate = result.gateResults[0]!;
|
||||
expect(gate.status).toBe('waiting');
|
||||
expect(gate.passed).toBe(false);
|
||||
expect(gate.exit_code).toBe(0);
|
||||
// aggregate is not passed while any gate is waiting
|
||||
expect(result.allPassed).toBe(false);
|
||||
expect(result.state).toBe('waiting');
|
||||
expect(result.state).not.toBe('passed');
|
||||
});
|
||||
|
||||
it('a simulated result can never make the aggregate passed', () => {
|
||||
const result = run(['exit 0', 'exit 0'], { simulate: true });
|
||||
expect(result.gateResults.every((g) => g.status === 'simulated')).toBe(true);
|
||||
expect(result.allPassed).toBe(false);
|
||||
expect(result.state).toBe('simulated');
|
||||
expect(result.state).not.toBe('passed');
|
||||
});
|
||||
|
||||
it('waiting dominates an otherwise green aggregate', () => {
|
||||
const result = run(['exit 0', { type: 'manual' }]);
|
||||
expect(result.allPassed).toBe(false);
|
||||
expect(result.state).toBe('waiting');
|
||||
});
|
||||
});
|
||||
|
||||
describe('runGate fail-closed (RI-N2)', () => {
|
||||
let tmpDir: string;
|
||||
let logPath: string;
|
||||
|
||||
beforeEach(() => {
|
||||
tmpDir = makeTmpDir();
|
||||
logPath = path.join(tmpDir, 'gate.log');
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
fs.rmSync(tmpDir, { recursive: true, force: true });
|
||||
});
|
||||
|
||||
it('simulate: true returns a typed simulated result without executing', () => {
|
||||
const result = runGate('this-command-does-not-exist-xyz', tmpDir, logPath, 10, {
|
||||
simulate: true,
|
||||
});
|
||||
expect(result.status).toBe('simulated');
|
||||
expect(result.passed).toBe(false);
|
||||
expect(result.exit_code).toBe(0);
|
||||
});
|
||||
|
||||
it('normal mode executes for real and types a green gate passed', () => {
|
||||
const result = runGate('echo ok', tmpDir, logPath, 10);
|
||||
expect(result.status).toBe('passed');
|
||||
expect(result.passed).toBe(true);
|
||||
expect(result.output).toContain('ok');
|
||||
});
|
||||
|
||||
it('a bare string gate normalizes to mechanical and executes', () => {
|
||||
const result = runGate('exit 7', tmpDir, logPath, 10);
|
||||
expect(result.type).toBe('mechanical');
|
||||
expect(result.status).toBe('failed');
|
||||
expect(result.passed).toBe(false);
|
||||
});
|
||||
});
|
||||
@@ -4,20 +4,7 @@ import { dirname } from 'node:path';
|
||||
|
||||
import { emitEvent } from './event-emitter.js';
|
||||
import { nowISO } from './event-emitter.js';
|
||||
import type { GateResult, GateStatus, RunGatesResult } from './types.js';
|
||||
|
||||
/** Typed reason stamped on every simulated gate result. */
|
||||
export const SIMULATED_GATE_REASON =
|
||||
'simulated execution (explicit simulate opt-in): gate was not evaluated by a real implementation';
|
||||
|
||||
/** Options for gate execution (RI-N2 fail-closed / explicit simulation). */
|
||||
export interface RunGateOptions {
|
||||
/**
|
||||
* Explicit caller opt-in to simulation. Simulated gates are NOT executed;
|
||||
* every result is typed `simulated` and never satisfies anything.
|
||||
*/
|
||||
simulate?: boolean;
|
||||
}
|
||||
import type { GateResult } from './types.js';
|
||||
|
||||
export interface NormalizedGate {
|
||||
command: string;
|
||||
@@ -116,91 +103,36 @@ export function countAIFindings(parsedOutput: unknown): { blockers: number; tota
|
||||
return { blockers, total };
|
||||
}
|
||||
|
||||
function simulatedResult(gateEntry: NormalizedGate): GateResult {
|
||||
return {
|
||||
command: gateEntry.command,
|
||||
exit_code: 0,
|
||||
type: gateEntry.type,
|
||||
output: SIMULATED_GATE_REASON,
|
||||
timed_out: false,
|
||||
passed: false,
|
||||
status: 'simulated',
|
||||
reason: SIMULATED_GATE_REASON,
|
||||
};
|
||||
}
|
||||
|
||||
function capabilityFailureResult(
|
||||
gateEntry: NormalizedGate,
|
||||
code: GateResult['capability_code'],
|
||||
reason: string,
|
||||
): GateResult {
|
||||
return {
|
||||
command: gateEntry.command,
|
||||
exit_code: 1,
|
||||
type: gateEntry.type,
|
||||
output: '',
|
||||
timed_out: false,
|
||||
passed: false,
|
||||
status: 'capability_failure',
|
||||
capability_code: code,
|
||||
reason,
|
||||
};
|
||||
}
|
||||
|
||||
function waitingResult(gateEntry: NormalizedGate, reason: string): GateResult {
|
||||
return {
|
||||
command: gateEntry.command,
|
||||
exit_code: 0,
|
||||
type: gateEntry.type,
|
||||
output: '',
|
||||
timed_out: false,
|
||||
passed: false,
|
||||
status: 'waiting',
|
||||
capability_code: 'MACP_AUTHORITY_REQUIRED',
|
||||
reason,
|
||||
};
|
||||
}
|
||||
|
||||
export function runGate(
|
||||
gate: unknown,
|
||||
cwd: string,
|
||||
logPath: string,
|
||||
timeoutSec: number,
|
||||
options: RunGateOptions = {},
|
||||
): GateResult {
|
||||
const gateEntry = normalizeGate(gate);
|
||||
const gateType = gateEntry.type;
|
||||
const command = gateEntry.command;
|
||||
|
||||
// Explicit simulation only: never executes, typed simulated, never satisfying.
|
||||
if (options.simulate) {
|
||||
return simulatedResult(gateEntry);
|
||||
}
|
||||
|
||||
// Fail closed: no CI provider implementation exists in @mosaicstack/macp,
|
||||
// so a ci-pipeline gate is an absent capability — never a placeholder pass.
|
||||
if (gateType === 'ci-pipeline') {
|
||||
return capabilityFailureResult(
|
||||
gateEntry,
|
||||
'MACP_NO_CI_PIPELINE',
|
||||
`ci-pipeline gate '${gateEntry.command || gateType}' has no CI provider implementation wired — refusing placeholder pass`,
|
||||
);
|
||||
return {
|
||||
command,
|
||||
exit_code: 0,
|
||||
type: gateType,
|
||||
output: 'CI pipeline gate placeholder',
|
||||
timed_out: false,
|
||||
passed: true,
|
||||
};
|
||||
}
|
||||
|
||||
if (!command) {
|
||||
// A manual gate with no automation waits for human sign-off: not pass, not fail.
|
||||
if (gateType === 'manual') {
|
||||
return waitingResult(
|
||||
gateEntry,
|
||||
`manual gate has no automation — waiting for human sign-off (type: ${gateType})`,
|
||||
);
|
||||
}
|
||||
// Any other commandless gate is an absent capability — never a vacuous pass.
|
||||
return capabilityFailureResult(
|
||||
gateEntry,
|
||||
gateType === 'ai-review' ? 'MACP_NO_REVIEWER' : 'MACP_NO_COMMAND',
|
||||
`gate of type '${gateType}' has no command to execute — refusing empty-command pass`,
|
||||
);
|
||||
return {
|
||||
command: '',
|
||||
exit_code: 0,
|
||||
type: gateType,
|
||||
output: '',
|
||||
timed_out: false,
|
||||
passed: true,
|
||||
};
|
||||
}
|
||||
|
||||
const { exitCode, output, timedOut } = runShell(command, cwd, logPath, timeoutSec);
|
||||
@@ -211,12 +143,10 @@ export function runGate(
|
||||
output,
|
||||
timed_out: timedOut,
|
||||
passed: false,
|
||||
status: 'failed',
|
||||
};
|
||||
|
||||
if (gateType !== 'ai-review') {
|
||||
result.passed = exitCode === 0;
|
||||
result.status = result.passed ? 'passed' : 'failed';
|
||||
return result;
|
||||
}
|
||||
|
||||
@@ -240,7 +170,6 @@ export function runGate(
|
||||
} else {
|
||||
result.passed = exitCode === 0 && blockers === 0 && !timedOut && parseError === undefined;
|
||||
}
|
||||
result.status = result.passed ? 'passed' : 'failed';
|
||||
|
||||
result.fail_on = failOn;
|
||||
result.blockers = blockers;
|
||||
@@ -262,19 +191,16 @@ export function runGates(
|
||||
timeoutSec: number,
|
||||
eventsPath: string,
|
||||
taskId: string,
|
||||
options: RunGateOptions = {},
|
||||
): RunGatesResult {
|
||||
): { allPassed: boolean; gateResults: GateResult[] } {
|
||||
let allPassed = true;
|
||||
const gateResults: GateResult[] = [];
|
||||
let hasCapabilityFailure = false;
|
||||
let hasSimulated = false;
|
||||
let hasFailed = false;
|
||||
let hasWaiting = false;
|
||||
|
||||
for (const gate of gates) {
|
||||
const gateEntry = normalizeGate(gate);
|
||||
const gateCmd = gateEntry.command;
|
||||
if (!gateCmd && gateEntry.type !== 'ci-pipeline') continue;
|
||||
|
||||
const label = gateCmd || gateEntry.type;
|
||||
// NOTE: no silent skip — every gate produces a typed result (RI-N2).
|
||||
emitEvent(
|
||||
eventsPath,
|
||||
'rail.check.started',
|
||||
@@ -283,10 +209,10 @@ export function runGates(
|
||||
'quality-gate',
|
||||
`Running gate: ${label}`,
|
||||
);
|
||||
const result = runGate(gate, cwd, logPath, timeoutSec, options);
|
||||
const result = runGate(gate, cwd, logPath, timeoutSec);
|
||||
gateResults.push(result);
|
||||
|
||||
if (result.status === 'passed') {
|
||||
if (result.passed) {
|
||||
emitEvent(
|
||||
eventsPath,
|
||||
'rail.check.passed',
|
||||
@@ -298,46 +224,7 @@ export function runGates(
|
||||
continue;
|
||||
}
|
||||
|
||||
if (result.status === 'waiting') {
|
||||
hasWaiting = true;
|
||||
emitEvent(
|
||||
eventsPath,
|
||||
'rail.check.waiting',
|
||||
taskId,
|
||||
'gated',
|
||||
'quality-gate',
|
||||
`Gate waiting: ${label} — ${result.reason ?? 'manual gate awaits sign-off'}`,
|
||||
);
|
||||
continue;
|
||||
}
|
||||
|
||||
if (result.status === 'simulated') {
|
||||
hasSimulated = true;
|
||||
emitEvent(
|
||||
eventsPath,
|
||||
'rail.check.simulated',
|
||||
taskId,
|
||||
'gated',
|
||||
'quality-gate',
|
||||
`Gate simulated (non-satisfying): ${label}`,
|
||||
);
|
||||
continue;
|
||||
}
|
||||
|
||||
if (result.status === 'capability_failure') {
|
||||
hasCapabilityFailure = true;
|
||||
emitEvent(
|
||||
eventsPath,
|
||||
'rail.check.failed',
|
||||
taskId,
|
||||
'gated',
|
||||
'quality-gate',
|
||||
`Gate capability failure (${result.capability_code ?? 'MACP_NO_PROVIDER'}): ${label} — ${result.reason ?? 'required capability is absent'}`,
|
||||
);
|
||||
continue;
|
||||
}
|
||||
|
||||
hasFailed = true;
|
||||
allPassed = false;
|
||||
let message: string;
|
||||
if (result.timed_out) {
|
||||
message = `Gate timed out after ${timeoutSec}s: ${label}`;
|
||||
@@ -349,15 +236,5 @@ export function runGates(
|
||||
emitEvent(eventsPath, 'rail.check.failed', taskId, 'gated', 'quality-gate', message);
|
||||
}
|
||||
|
||||
const state: GateStatus = hasCapabilityFailure
|
||||
? 'capability_failure'
|
||||
: hasSimulated
|
||||
? 'simulated'
|
||||
: hasFailed
|
||||
? 'failed'
|
||||
: hasWaiting
|
||||
? 'waiting'
|
||||
: 'passed';
|
||||
|
||||
return { allPassed: state === 'passed', gateResults, state };
|
||||
return { allPassed, gateResults };
|
||||
}
|
||||
|
||||
@@ -6,13 +6,11 @@ export type {
|
||||
DependsOnPolicy,
|
||||
GateType,
|
||||
GateFailOn,
|
||||
GateStatus,
|
||||
GateEntry,
|
||||
Task,
|
||||
EventType,
|
||||
MACPEvent,
|
||||
GateResult,
|
||||
RunGatesResult,
|
||||
TaskResult,
|
||||
ProviderMeta,
|
||||
ProviderRegistry,
|
||||
@@ -20,11 +18,6 @@ export type {
|
||||
|
||||
export { CredentialError } from './types.js';
|
||||
|
||||
// Typed fail-closed capability errors (RI-N2, SDLC-D-035)
|
||||
export { MACP_ERROR_CODES, MACPCapabilityError } from './errors.js';
|
||||
|
||||
export type { MacpErrorCode } from './errors.js';
|
||||
|
||||
// Credential resolver
|
||||
export {
|
||||
DEFAULT_CREDENTIALS_DIR,
|
||||
@@ -42,16 +35,9 @@ export {
|
||||
export type { ResolveCredentialsOptions } from './credential-resolver.js';
|
||||
|
||||
// Gate runner
|
||||
export {
|
||||
normalizeGate,
|
||||
runShell,
|
||||
countAIFindings,
|
||||
runGate,
|
||||
runGates,
|
||||
SIMULATED_GATE_REASON,
|
||||
} from './gate-runner.js';
|
||||
export { normalizeGate, runShell, countAIFindings, runGate, runGates } from './gate-runner.js';
|
||||
|
||||
export type { NormalizedGate, RunGateOptions } from './gate-runner.js';
|
||||
export type { NormalizedGate } from './gate-runner.js';
|
||||
|
||||
// Risk-floor (agent reflection loop — diff review classifier)
|
||||
export { evaluateRiskFloor, DEFAULT_RISK_THRESHOLD } from './risk-floor.js';
|
||||
|
||||
@@ -1,5 +1,3 @@
|
||||
import type { MacpErrorCode } from './errors.js';
|
||||
|
||||
/** Task status values. */
|
||||
export type TaskStatus = 'pending' | 'running' | 'gated' | 'completed' | 'failed' | 'escalated';
|
||||
|
||||
@@ -19,17 +17,7 @@ export type DispatchMode = 'yolo' | 'acp' | 'exec';
|
||||
export type DependsOnPolicy = 'all' | 'any' | 'all_terminal';
|
||||
|
||||
/** Quality gate type. */
|
||||
export type GateType = 'mechanical' | 'ai-review' | 'ci-pipeline' | 'manual';
|
||||
|
||||
/**
|
||||
* Typed execution state of a gate — closed set (RI-N2, SDLC-D-035).
|
||||
*
|
||||
* Only `passed` means "really executed and green". `simulated` is produced
|
||||
* exclusively under an explicit simulate opt-in and never satisfies anything.
|
||||
* `capability_failure` means a required executor/provider/command was absent.
|
||||
* `waiting` means a manual gate awaits human sign-off (neither pass nor fail).
|
||||
*/
|
||||
export type GateStatus = 'passed' | 'failed' | 'simulated' | 'waiting' | 'capability_failure';
|
||||
export type GateType = 'mechanical' | 'ai-review' | 'ci-pipeline';
|
||||
|
||||
/** Gate fail_on mode. */
|
||||
export type GateFailOn = 'blocker' | 'any';
|
||||
@@ -79,9 +67,7 @@ export type EventType =
|
||||
| 'task.retry.scheduled'
|
||||
| 'rail.check.started'
|
||||
| 'rail.check.passed'
|
||||
| 'rail.check.failed'
|
||||
| 'rail.check.waiting'
|
||||
| 'rail.check.simulated';
|
||||
| 'rail.check.failed';
|
||||
|
||||
/** Structured event record. */
|
||||
export interface MACPEvent {
|
||||
@@ -102,14 +88,7 @@ export interface GateResult {
|
||||
type: string;
|
||||
output: string;
|
||||
timed_out: boolean;
|
||||
/** Back-compat boolean view — true ONLY when `status === 'passed'`. */
|
||||
passed: boolean;
|
||||
/** Typed discriminator — the authoritative gate outcome (RI-N2). */
|
||||
status: GateStatus;
|
||||
/** Typed capability error code, set when `status === 'capability_failure'`. */
|
||||
capability_code?: MacpErrorCode;
|
||||
/** Why a non-executed state (simulated/waiting/capability_failure) was reached. */
|
||||
reason?: string;
|
||||
fail_on?: string;
|
||||
blockers?: number;
|
||||
findings?: number;
|
||||
@@ -117,22 +96,6 @@ export interface GateResult {
|
||||
parse_error?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Aggregate outcome of `runGates` (RI-N2).
|
||||
*
|
||||
* `state` is the typed aggregate: it is `passed` only when every gate really
|
||||
* executed green. A `simulated` result makes the aggregate `simulated` (never
|
||||
* `passed`); a `waiting` manual gate keeps the aggregate `waiting`; a missing
|
||||
* capability makes it `capability_failure`. `allPassed` is exactly
|
||||
* `state === 'passed'`, so a simulated or waiting result can never satisfy a
|
||||
* dependency, acceptance criterion, gate, merge, or release check.
|
||||
*/
|
||||
export interface RunGatesResult {
|
||||
allPassed: boolean;
|
||||
gateResults: GateResult[];
|
||||
state: GateStatus;
|
||||
}
|
||||
|
||||
/** Result from a completed task. */
|
||||
export interface TaskResult {
|
||||
task_id: string;
|
||||
|
||||
@@ -1,149 +0,0 @@
|
||||
import { mkdtemp, readFile, readdir } from 'node:fs/promises';
|
||||
import os from 'node:os';
|
||||
import path from 'node:path';
|
||||
|
||||
import { parse as parseYaml } from 'yaml';
|
||||
import { Command } from 'commander';
|
||||
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
|
||||
|
||||
import { registerMissionCommand } from './mission.js';
|
||||
import { PrdService } from '@mosaicstack/prdy';
|
||||
import type { MissionInfo } from '../tui/gateway-api.js';
|
||||
|
||||
// ── Mocks: the gateway is not available in adapter tests ──────────────────────
|
||||
|
||||
// vi.hoisted: the mock factory is hoisted above imports, so the fixture must
|
||||
// be initialized there too.
|
||||
const MISSION = vi.hoisted(
|
||||
(): MissionInfo => ({
|
||||
id: 'mission-plan-1',
|
||||
name: 'Plan Mission Alpha',
|
||||
description: null,
|
||||
status: 'planning',
|
||||
projectId: null,
|
||||
userId: null,
|
||||
phase: null,
|
||||
milestones: null,
|
||||
config: null,
|
||||
createdAt: '2026-01-01T00:00:00.000Z',
|
||||
updatedAt: '2026-03-04T05:06:07.000Z',
|
||||
}),
|
||||
);
|
||||
|
||||
vi.mock('./with-auth.js', () => ({
|
||||
withAuth: vi.fn().mockResolvedValue({
|
||||
gateway: 'http://localhost:14242',
|
||||
cookie: 'better-auth.session_token=test',
|
||||
session: {},
|
||||
}),
|
||||
}));
|
||||
|
||||
vi.mock('../tui/gateway-api.js', () => ({
|
||||
fetchMissions: vi.fn().mockResolvedValue([MISSION]),
|
||||
fetchMission: vi.fn(),
|
||||
createMission: vi.fn(),
|
||||
updateMission: vi.fn(),
|
||||
fetchMissionTasks: vi.fn().mockResolvedValue([]),
|
||||
createMissionTask: vi.fn(),
|
||||
updateMissionTask: vi.fn(),
|
||||
fetchProjects: vi.fn().mockResolvedValue([]),
|
||||
}));
|
||||
|
||||
// ── Helpers ──────────────────────────────────────────────────────────────────
|
||||
|
||||
const originalCwd = process.cwd();
|
||||
let projectDir: string;
|
||||
let logSpy: ReturnType<typeof vi.spyOn>;
|
||||
let consoleStub: ReturnType<typeof vi.spyOn>[] = [];
|
||||
|
||||
function buildTestProgram(): Command {
|
||||
const program = new Command('mosaic').exitOverride();
|
||||
registerMissionCommand(program);
|
||||
return program;
|
||||
}
|
||||
|
||||
beforeEach(async () => {
|
||||
projectDir = await mkdtemp(path.join(os.tmpdir(), 'mosaic-mission-plan-'));
|
||||
process.chdir(projectDir);
|
||||
logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
|
||||
consoleStub.push(logSpy);
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
// Restore only the per-test spies; module factory mocks keep their
|
||||
// implementations across tests.
|
||||
for (const stub of consoleStub) stub.mockRestore();
|
||||
consoleStub = [];
|
||||
process.chdir(originalCwd);
|
||||
});
|
||||
|
||||
// ── Tests ────────────────────────────────────────────────────────────────────
|
||||
|
||||
describe('mosaic mission --plan (thin adapter over PrdService)', () => {
|
||||
it('creates the PRD in the shared docs/prdy authority store and persists the mission linkage', async () => {
|
||||
await buildTestProgram().parseAsync(['mission', '--plan', 'Plan Mission Alpha'], {
|
||||
from: 'user',
|
||||
});
|
||||
|
||||
// PRD landed in the same store `mosaic prdy` uses.
|
||||
const files = await readdir(path.join(projectDir, 'docs', 'prdy'));
|
||||
expect(files).toHaveLength(1);
|
||||
expect(files[0]).toMatch(/\.yaml$/);
|
||||
|
||||
// Fresh service instance (new-process equivalent) reads the linkage back.
|
||||
const service = new PrdService({ projectPath: projectDir });
|
||||
const docs = await service.list();
|
||||
expect(docs).toHaveLength(1);
|
||||
|
||||
const prd = docs[0]!;
|
||||
expect(prd.title).toBe('Plan Mission Alpha');
|
||||
expect(prd.version).toBe(1);
|
||||
|
||||
const links = await service.listMissionLinks(prd.id);
|
||||
expect(links).toHaveLength(1);
|
||||
expect(links[0]).toMatchObject({
|
||||
missionId: MISSION.id,
|
||||
missionVersion: MISSION.updatedAt, // mission version marker
|
||||
prdVersion: 1,
|
||||
});
|
||||
|
||||
expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('PRD created and linked'));
|
||||
});
|
||||
|
||||
it('linkage is persisted in the YAML authority document itself (survives restart)', async () => {
|
||||
await buildTestProgram().parseAsync(['mission', '--plan', 'Plan Mission Alpha'], {
|
||||
from: 'user',
|
||||
});
|
||||
|
||||
const files = await readdir(path.join(projectDir, 'docs', 'prdy'));
|
||||
const raw = await readFile(path.join(projectDir, 'docs', 'prdy', files[0]!), 'utf8');
|
||||
const persisted = parseYaml(raw) as { missions: Array<Record<string, unknown>> };
|
||||
|
||||
expect(persisted.missions).toHaveLength(1);
|
||||
expect(persisted.missions[0]).toMatchObject({ missionId: 'mission-plan-1' });
|
||||
});
|
||||
|
||||
it('the mission path and the prdy path resolve to the same store with stable ids/versions', async () => {
|
||||
// Mission path.
|
||||
await buildTestProgram().parseAsync(['mission', '--plan', 'Plan Mission Alpha'], {
|
||||
from: 'user',
|
||||
});
|
||||
|
||||
// prdy path (service, non-interactive entry).
|
||||
const service = new PrdService({ projectPath: projectDir });
|
||||
const direct = await service.create({ name: 'Directly Created' });
|
||||
|
||||
const all = await service.list();
|
||||
expect(all.map((doc) => doc.id).sort()).toEqual([...all.map((doc) => doc.id)].sort());
|
||||
expect(all).toHaveLength(2);
|
||||
|
||||
const files = await readdir(path.join(projectDir, 'docs', 'prdy'));
|
||||
expect(files).toContain(`${direct.id}.yaml`);
|
||||
|
||||
// Both are v1 in the same store with distinct stable ids.
|
||||
for (const doc of all) {
|
||||
expect(doc.version).toBe(1);
|
||||
expect(files).toContain(`${doc.id}.yaml`);
|
||||
}
|
||||
});
|
||||
});
|
||||
@@ -256,41 +256,14 @@ async function planMission(
|
||||
console.log(`Planning mission: ${mission.name}\n`);
|
||||
|
||||
try {
|
||||
// Thin adapter: the PRD authority (create + mission↔PRD linkage) lives in
|
||||
// PrdService — no second writer path. The mission's updatedAt serves as
|
||||
// its version marker (the gateway exposes no numeric mission version).
|
||||
const { PrdService, runPrdWizard } = await import('@mosaicstack/prdy');
|
||||
const service = new PrdService({ projectPath: process.cwd() });
|
||||
|
||||
if (process.stdout.isTTY) {
|
||||
const created = await runPrdWizard({
|
||||
name: mission.name,
|
||||
projectPath: process.cwd(),
|
||||
interactive: true,
|
||||
});
|
||||
const linked = await service.linkMission({
|
||||
prdId: created.id,
|
||||
missionId: mission.id,
|
||||
missionVersion: mission.updatedAt,
|
||||
requirementIds: [],
|
||||
});
|
||||
console.log(
|
||||
`\nMission ${mission.id} linked to PRD ${linked.id} v${linked.version} (docs/prdy/).`,
|
||||
);
|
||||
return;
|
||||
}
|
||||
|
||||
const doc = await service.planForMission({
|
||||
const { runPrdWizard } = await import('@mosaicstack/prdy');
|
||||
await runPrdWizard({
|
||||
name: mission.name,
|
||||
missionId: mission.id,
|
||||
missionVersion: mission.updatedAt,
|
||||
requirementIds: [],
|
||||
projectPath: process.cwd(),
|
||||
interactive: true,
|
||||
});
|
||||
console.log(
|
||||
`PRD created and linked: ${doc.id} v${doc.version} — mission ${mission.id} (docs/prdy/).`,
|
||||
);
|
||||
} catch (err) {
|
||||
console.error(`PRD planning failed: ${err instanceof Error ? err.message : String(err)}`);
|
||||
console.error(`PRD wizard failed: ${err instanceof Error ? err.message : String(err)}`);
|
||||
process.exit(1);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -1,204 +0,0 @@
|
||||
import { mkdtemp, readFile, readdir, writeFile } from 'node:fs/promises';
|
||||
import os from 'node:os';
|
||||
import path from 'node:path';
|
||||
|
||||
import { stringify as stringifyYaml } from 'yaml';
|
||||
import { Command } from 'commander';
|
||||
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
|
||||
|
||||
import { registerPrdyCommand } from './prdy.js';
|
||||
import { PrdService } from '@mosaicstack/prdy';
|
||||
|
||||
// ── Mocks: keep the adapter test offline (no gateway, no disk side effects
|
||||
// outside the tmp project dir) ──────────────────────────────────────────────
|
||||
|
||||
vi.mock('./with-auth.js', () => ({
|
||||
withAuth: vi.fn().mockResolvedValue({
|
||||
gateway: 'http://localhost:14242',
|
||||
cookie: 'better-auth.session_token=test',
|
||||
session: {},
|
||||
}),
|
||||
}));
|
||||
|
||||
vi.mock('../tui/gateway-api.js', () => ({
|
||||
fetchProjects: vi.fn().mockResolvedValue([]),
|
||||
}));
|
||||
|
||||
// ── Helpers ──────────────────────────────────────────────────────────────────
|
||||
|
||||
class ProcessExitError extends Error {
|
||||
constructor(readonly code: number) {
|
||||
super(`process.exit(${code})`);
|
||||
}
|
||||
}
|
||||
|
||||
function stubProcessExit() {
|
||||
return vi.spyOn(process, 'exit').mockImplementation(((code?: number) => {
|
||||
throw new ProcessExitError(code ?? 0);
|
||||
}) as never);
|
||||
}
|
||||
|
||||
const originalCwd = process.cwd();
|
||||
let projectDir: string;
|
||||
let errorSpy: ReturnType<typeof vi.spyOn>;
|
||||
let logSpy: ReturnType<typeof vi.spyOn>;
|
||||
let exitStub: ReturnType<typeof stubProcessExit>;
|
||||
|
||||
function buildTestProgram(): Command {
|
||||
const program = new Command('mosaic').exitOverride();
|
||||
registerPrdyCommand(program);
|
||||
return program;
|
||||
}
|
||||
|
||||
function runPrdy(args: string[]): Promise<unknown> {
|
||||
return buildTestProgram().parseAsync(['prdy', ...args], { from: 'user' });
|
||||
}
|
||||
|
||||
function importableDocument(overrides: Record<string, unknown> = {}): Record<string, unknown> {
|
||||
return {
|
||||
id: 'cmd-import-prd',
|
||||
title: 'Command Import PRD',
|
||||
status: 'approved', // must be forced to draft: validity is not approval
|
||||
projectPath: '/tmp/elsewhere',
|
||||
template: 'software',
|
||||
version: 1,
|
||||
sections: [
|
||||
{ id: 'introduction', title: 'Introduction', fields: { context: 'x', objective: 'y' } },
|
||||
],
|
||||
missions: [],
|
||||
createdAt: '2026-01-01T00:00:00.000Z',
|
||||
updatedAt: '2026-01-01T00:00:00.000Z',
|
||||
...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
beforeEach(async () => {
|
||||
projectDir = await mkdtemp(path.join(os.tmpdir(), 'mosaic-prdy-'));
|
||||
process.chdir(projectDir);
|
||||
exitStub = stubProcessExit();
|
||||
errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
|
||||
logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
// Restore only the per-test spies: module factory mocks must keep their
|
||||
// implementations for the next test.
|
||||
exitStub.mockRestore();
|
||||
errorSpy.mockRestore();
|
||||
logSpy.mockRestore();
|
||||
process.chdir(originalCwd);
|
||||
});
|
||||
|
||||
// ── Tests ────────────────────────────────────────────────────────────────────
|
||||
|
||||
describe('mosaic prdy (thin adapter over PrdService)', () => {
|
||||
it('non-interactive --init creates a PRD in the docs/prdy authority store', async () => {
|
||||
await runPrdy(['--init', 'Adapter Created']);
|
||||
|
||||
const files = await readdir(path.join(projectDir, 'docs', 'prdy'));
|
||||
expect(files).toHaveLength(1);
|
||||
expect(files[0]).toMatch(/\.yaml$/);
|
||||
|
||||
const docs = await new PrdService({ projectPath: projectDir }).list();
|
||||
expect(docs).toHaveLength(1);
|
||||
expect(docs[0]?.title).toBe('Adapter Created');
|
||||
expect(docs[0]?.version).toBe(1);
|
||||
expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('PRD created'));
|
||||
});
|
||||
|
||||
it('--import <file> creates a valid import through the service', async () => {
|
||||
const filePath = path.join(projectDir, 'incoming.yaml');
|
||||
await writeFile(filePath, stringifyYaml(importableDocument()), 'utf8');
|
||||
|
||||
await runPrdy(['--import', filePath]);
|
||||
|
||||
const docs = await new PrdService({ projectPath: projectDir }).list();
|
||||
expect(docs).toHaveLength(1);
|
||||
expect(docs[0]?.id).toBe('cmd-import-prd');
|
||||
expect(docs[0]?.status).toBe('draft'); // import ≠ approval
|
||||
expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('Imported PRD cmd-import-prd'));
|
||||
});
|
||||
|
||||
it('--import of a structurally-invalid file is a typed refusal that creates nothing', async () => {
|
||||
const filePath = path.join(projectDir, 'broken.yaml');
|
||||
await writeFile(filePath, stringifyYaml({ id: 'incomplete', no: 'structure' }), 'utf8');
|
||||
|
||||
await expect(runPrdy(['--import', filePath])).rejects.toBeInstanceOf(ProcessExitError);
|
||||
|
||||
// Typed refusal surfaced to the user, nothing created.
|
||||
expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('PRD wizard failed'));
|
||||
await expect(readdir(path.join(projectDir, 'docs'))).rejects.toMatchObject({ code: 'ENOENT' });
|
||||
});
|
||||
|
||||
it('--import on conflict refuses with a successor proposal and leaves bytes untouched', async () => {
|
||||
const service = new PrdService({ projectPath: projectDir });
|
||||
const existing = await service.create({ name: 'Conflict Target' });
|
||||
const storeFile = path.join(projectDir, 'docs', 'prdy', `${existing.id}.yaml`);
|
||||
const beforeBytes = await readFile(storeFile, 'utf8');
|
||||
|
||||
const filePath = path.join(projectDir, 'divergent.yaml');
|
||||
await writeFile(
|
||||
filePath,
|
||||
stringifyYaml(
|
||||
importableDocument({
|
||||
...existing,
|
||||
title: 'Divergent Command Import',
|
||||
}),
|
||||
),
|
||||
'utf8',
|
||||
);
|
||||
|
||||
await expect(runPrdy(['--import', filePath])).rejects.toBeInstanceOf(ProcessExitError);
|
||||
|
||||
expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('refusing to overwrite'));
|
||||
expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('--accept-successor'));
|
||||
|
||||
// Original authority document is byte-identical on disk.
|
||||
expect(await readFile(storeFile, 'utf8')).toBe(beforeBytes);
|
||||
});
|
||||
|
||||
it('--import --accept-successor persists the successor version explicitly', async () => {
|
||||
const service = new PrdService({ projectPath: projectDir });
|
||||
const existing = await service.create({ name: 'Successor Target' });
|
||||
|
||||
const filePath = path.join(projectDir, 'divergent2.yaml');
|
||||
await writeFile(
|
||||
filePath,
|
||||
stringifyYaml(
|
||||
importableDocument({
|
||||
...existing,
|
||||
title: 'Accepted Via CLI',
|
||||
}),
|
||||
),
|
||||
'utf8',
|
||||
);
|
||||
|
||||
await runPrdy(['--import', filePath, '--accept-successor']);
|
||||
|
||||
const doc = await service.get(existing.id);
|
||||
expect(doc.version).toBe(2);
|
||||
expect(doc.title).toBe('Accepted Via CLI');
|
||||
expect(doc.status).toBe('draft');
|
||||
expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('successor'));
|
||||
});
|
||||
|
||||
it('--export writes a labeled generated view and never touches authority', async () => {
|
||||
const service = new PrdService({ projectPath: projectDir });
|
||||
const created = await service.create({ name: 'Export Via CLI' });
|
||||
const before = await service.get(created.id);
|
||||
|
||||
await runPrdy(['--export', created.id]);
|
||||
|
||||
const mdPath = path.join(projectDir, 'docs', 'prdy', `${created.id}.md`);
|
||||
const md = await readFile(mdPath, 'utf8');
|
||||
expect(md).toContain('generated view — do not edit');
|
||||
expect(md).toContain(`prd-id: ${created.id}`);
|
||||
expect(md).toContain('prd-version: 1');
|
||||
expect(logSpy).toHaveBeenCalledWith(
|
||||
expect.stringContaining(`Generated view written: ${mdPath}`),
|
||||
);
|
||||
|
||||
// Authority unchanged by the export.
|
||||
expect(await service.get(created.id)).toEqual(before);
|
||||
});
|
||||
});
|
||||
@@ -2,10 +2,6 @@ import type { Command } from 'commander';
|
||||
import { withAuth } from './with-auth.js';
|
||||
import { fetchProjects } from '../tui/gateway-api.js';
|
||||
|
||||
/**
|
||||
* `mosaic prdy` — thin adapter over PrdService (@mosaicstack/prdy).
|
||||
* All reads/writes go through the service; there is no local writer path.
|
||||
*/
|
||||
export function registerPrdyCommand(program: Command) {
|
||||
const cmd = program
|
||||
.command('prdy')
|
||||
@@ -13,18 +9,12 @@ export function registerPrdyCommand(program: Command) {
|
||||
.option('-g, --gateway <url>', 'Gateway URL', 'http://localhost:14242')
|
||||
.option('--init [name]', 'Create a new PRD')
|
||||
.option('--update [name]', 'Update an existing PRD')
|
||||
.option('--import <file>', 'Import a YAML PRD document (validated, conflict-aware)')
|
||||
.option('--accept-successor', 'With --import: accept a conflicted import as next version')
|
||||
.option('--export [id]', 'Export a PRD as a labeled generated-view Markdown file')
|
||||
.option('--project <idOrName>', 'Scope to project')
|
||||
.action(
|
||||
async (opts: {
|
||||
gateway: string;
|
||||
init?: string | boolean;
|
||||
update?: string | boolean;
|
||||
import?: string;
|
||||
acceptSuccessor?: boolean;
|
||||
export?: string | boolean;
|
||||
project?: string;
|
||||
}) => {
|
||||
// Detect project context when --project flag is provided
|
||||
@@ -41,69 +31,20 @@ export function registerPrdyCommand(program: Command) {
|
||||
}
|
||||
}
|
||||
|
||||
const { PrdService, runPrdWizard } = await import('@mosaicstack/prdy');
|
||||
const service = new PrdService({ projectPath: process.cwd() });
|
||||
|
||||
try {
|
||||
if (opts.import !== undefined) {
|
||||
const input = { filePath: opts.import };
|
||||
|
||||
if (opts.acceptSuccessor) {
|
||||
const successor = await service.acceptSuccessor(input);
|
||||
console.log(
|
||||
`Import accepted as successor: ${successor.id} v${successor.version} (status: ${successor.status})`,
|
||||
);
|
||||
return;
|
||||
}
|
||||
|
||||
const result = await service.importDocument(input);
|
||||
console.log(
|
||||
result.kind === 'created'
|
||||
? `Imported PRD ${result.document.id} v${result.document.version} (status: ${result.document.status})`
|
||||
: `PRD ${result.document.id} already present with identical content — nothing to do.`,
|
||||
);
|
||||
return;
|
||||
}
|
||||
|
||||
if (opts.export !== undefined) {
|
||||
const id =
|
||||
typeof opts.export === 'string' && opts.export.length > 0 ? opts.export : undefined;
|
||||
const result = await service.exportMarkdown({ id });
|
||||
console.log(
|
||||
`Generated view written: ${result.filePath} (source authority: YAML under docs/prdy/ — do not edit the Markdown)`,
|
||||
);
|
||||
return;
|
||||
}
|
||||
|
||||
const { runPrdWizard } = await import('@mosaicstack/prdy');
|
||||
const name =
|
||||
typeof opts.init === 'string'
|
||||
? opts.init
|
||||
: typeof opts.update === 'string'
|
||||
? opts.update
|
||||
: 'untitled';
|
||||
|
||||
if (process.stdout.isTTY) {
|
||||
await runPrdWizard({
|
||||
name,
|
||||
projectPath: process.cwd(),
|
||||
interactive: true,
|
||||
});
|
||||
return;
|
||||
}
|
||||
|
||||
// Non-interactive fallback routes through the service directly.
|
||||
const doc = await service.create({ name });
|
||||
console.log(`PRD created: ${doc.id} v${doc.version} (status: ${doc.status})`);
|
||||
await runPrdWizard({
|
||||
name,
|
||||
projectPath: process.cwd(),
|
||||
interactive: true,
|
||||
});
|
||||
} catch (err) {
|
||||
if (err instanceof Error && err.name === 'PrdImportConflictError') {
|
||||
const conflict = err as { proposal?: { version?: number } };
|
||||
console.error(`${err.message}`);
|
||||
console.error(
|
||||
`Original PRD left untouched. To accept the proposed successor (v${conflict.proposal?.version}), re-run with --accept-successor.`,
|
||||
);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
console.error(`PRD wizard failed: ${err instanceof Error ? err.message : String(err)}`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
+14
-74
@@ -1,6 +1,6 @@
|
||||
import { Command } from 'commander';
|
||||
|
||||
import { PrdService } from './service.js';
|
||||
import { createPrd, listPrds, loadPrd } from './prd.js';
|
||||
import { runPrdWizard } from './wizard.js';
|
||||
|
||||
interface InitCommandOptions {
|
||||
@@ -18,22 +18,6 @@ interface ShowCommandOptions {
|
||||
readonly id?: string;
|
||||
}
|
||||
|
||||
interface ImportCommandOptions {
|
||||
readonly project: string;
|
||||
readonly file: string;
|
||||
readonly acceptSuccessor?: boolean;
|
||||
}
|
||||
|
||||
interface ExportCommandOptions {
|
||||
readonly project: string;
|
||||
readonly id?: string;
|
||||
readonly out?: string;
|
||||
}
|
||||
|
||||
function serviceFor(project: string): PrdService {
|
||||
return new PrdService({ projectPath: project });
|
||||
}
|
||||
|
||||
export function buildPrdyCli(): Command {
|
||||
const program = new Command();
|
||||
program.name('mosaic').description('Mosaic CLI').exitOverride();
|
||||
@@ -54,9 +38,11 @@ export function buildPrdyCli(): Command {
|
||||
template: options.template,
|
||||
interactive: true,
|
||||
})
|
||||
: await serviceFor(options.project).create({
|
||||
: await createPrd({
|
||||
name: options.name,
|
||||
projectPath: options.project,
|
||||
template: options.template,
|
||||
interactive: false,
|
||||
});
|
||||
|
||||
console.log(
|
||||
@@ -66,7 +52,6 @@ export function buildPrdyCli(): Command {
|
||||
id: doc.id,
|
||||
title: doc.title,
|
||||
status: doc.status,
|
||||
version: doc.version,
|
||||
projectPath: doc.projectPath,
|
||||
},
|
||||
null,
|
||||
@@ -80,7 +65,7 @@ export function buildPrdyCli(): Command {
|
||||
.description('List PRD documents for a project')
|
||||
.requiredOption('--project <path>', 'Project path')
|
||||
.action(async (options: ListCommandOptions) => {
|
||||
const docs = await serviceFor(options.project).list();
|
||||
const docs = await listPrds(options.project);
|
||||
console.log(JSON.stringify(docs, null, 2));
|
||||
});
|
||||
|
||||
@@ -90,65 +75,20 @@ export function buildPrdyCli(): Command {
|
||||
.requiredOption('--project <path>', 'Project path')
|
||||
.option('--id <id>', 'PRD document id')
|
||||
.action(async (options: ShowCommandOptions) => {
|
||||
const doc = await serviceFor(options.project).get(options.id);
|
||||
console.log(JSON.stringify(doc, null, 2));
|
||||
});
|
||||
if (options.id !== undefined) {
|
||||
const docs = await listPrds(options.project);
|
||||
const match = docs.find((doc) => doc.id === options.id);
|
||||
|
||||
prdy
|
||||
.command('import')
|
||||
.description('Import a YAML PRD document (validated; conflicts propose a successor)')
|
||||
.requiredOption('--project <path>', 'Project path')
|
||||
.requiredOption('--file <file>', 'Path to YAML PRD document')
|
||||
.option('--accept-successor', 'Accept a conflicted import as the next version')
|
||||
.action(async (options: ImportCommandOptions) => {
|
||||
const service = serviceFor(options.project);
|
||||
const input = { filePath: options.file };
|
||||
if (match === undefined) {
|
||||
throw new Error(`PRD id not found: ${options.id}`);
|
||||
}
|
||||
|
||||
if (options.acceptSuccessor) {
|
||||
const successor = await service.acceptSuccessor(input);
|
||||
console.log(
|
||||
JSON.stringify(
|
||||
{
|
||||
ok: true,
|
||||
outcome: 'successor-accepted',
|
||||
id: successor.id,
|
||||
version: successor.version,
|
||||
},
|
||||
null,
|
||||
2,
|
||||
),
|
||||
);
|
||||
console.log(JSON.stringify(match, null, 2));
|
||||
return;
|
||||
}
|
||||
|
||||
const result = await service.importDocument(input);
|
||||
console.log(
|
||||
JSON.stringify(
|
||||
{
|
||||
ok: true,
|
||||
outcome: result.kind,
|
||||
id: result.document.id,
|
||||
version: result.document.version,
|
||||
status: result.document.status,
|
||||
},
|
||||
null,
|
||||
2,
|
||||
),
|
||||
);
|
||||
});
|
||||
|
||||
prdy
|
||||
.command('export')
|
||||
.description('Render a PRD to a labeled generated-view Markdown file')
|
||||
.requiredOption('--project <path>', 'Project path')
|
||||
.option('--id <id>', 'PRD document id')
|
||||
.option('--out <path>', 'Output path (default docs/prdy/<id>.md)')
|
||||
.action(async (options: ExportCommandOptions) => {
|
||||
const result = await serviceFor(options.project).exportMarkdown({
|
||||
id: options.id,
|
||||
outPath: options.out,
|
||||
});
|
||||
console.log(JSON.stringify({ ok: true, filePath: result.filePath }, null, 2));
|
||||
const doc = await loadPrd(options.project);
|
||||
console.log(JSON.stringify(doc, null, 2));
|
||||
});
|
||||
|
||||
return program;
|
||||
|
||||
@@ -1,35 +1,12 @@
|
||||
// PrdService is the single authority surface for PRD documents. The raw store
|
||||
// writers (createPrd/savePrd) are deliberately NOT exported: every mutation
|
||||
// goes through the service so there is no second writer path.
|
||||
export { loadPrd, listPrds, parsePrdDocument } from './prd.js';
|
||||
export { createPrd, loadPrd, savePrd, listPrds } from './prd.js';
|
||||
export { runPrdWizard } from './wizard.js';
|
||||
export { buildPrdyCli, runPrdyCli } from './cli.js';
|
||||
export { BUILTIN_PRD_TEMPLATES, resolveTemplate } from './templates.js';
|
||||
export {
|
||||
PrdService,
|
||||
PRD_GENERATED_VIEW_LABEL,
|
||||
PrdError,
|
||||
PrdNotFoundError,
|
||||
PrdUpdateError,
|
||||
PrdImportInvalidError,
|
||||
PrdImportConflictError,
|
||||
} from './service.js';
|
||||
export type {
|
||||
PrdStatus,
|
||||
PrdTemplate,
|
||||
PrdTemplateSection,
|
||||
PrdSection,
|
||||
PrdMissionLinkage,
|
||||
PrdDocument,
|
||||
CreatePrdOptions,
|
||||
PrdServiceOptions,
|
||||
PrdCreateInput,
|
||||
PrdSectionPatch,
|
||||
PrdUpdateInput,
|
||||
PrdLinkMissionInput,
|
||||
PrdPlanForMissionInput,
|
||||
PrdExportInput,
|
||||
PrdExportResult,
|
||||
PrdImportInput,
|
||||
PrdImportResult,
|
||||
} from './types.js';
|
||||
|
||||
@@ -17,49 +17,17 @@ const prdSectionSchema = z.object({
|
||||
fields: z.record(z.string(), z.string()),
|
||||
});
|
||||
|
||||
const prdMissionLinkageSchema = z.object({
|
||||
missionId: z.string().min(1),
|
||||
missionVersion: z.string().min(1),
|
||||
prdVersion: z.number().int().min(1),
|
||||
requirementIds: z.array(z.string()),
|
||||
linkedAt: z.string().datetime(),
|
||||
});
|
||||
|
||||
const prdDocumentSchema = z.object({
|
||||
id: z.string().min(1),
|
||||
title: z.string().min(1),
|
||||
status: z.enum(['draft', 'review', 'approved', 'archived']),
|
||||
projectPath: z.string().min(1),
|
||||
template: z.string().min(1),
|
||||
// Defaults keep documents written by older prdy versions loadable.
|
||||
version: z.number().int().min(1).default(1),
|
||||
sections: z.array(prdSectionSchema),
|
||||
missions: z.array(prdMissionLinkageSchema).default([]),
|
||||
createdAt: z.string().datetime(),
|
||||
updatedAt: z.string().datetime(),
|
||||
});
|
||||
|
||||
/** YAML timestamp scalars are parsed as Date by some emitters — normalize to ISO strings. */
|
||||
function coerceTimestamps(value: unknown): unknown {
|
||||
if (value instanceof Date) {
|
||||
return value.toISOString();
|
||||
}
|
||||
if (Array.isArray(value)) {
|
||||
return value.map(coerceTimestamps);
|
||||
}
|
||||
if (typeof value === 'object' && value !== null) {
|
||||
return Object.fromEntries(
|
||||
Object.entries(value).map(([key, entry]) => [key, coerceTimestamps(entry)]),
|
||||
);
|
||||
}
|
||||
return value;
|
||||
}
|
||||
|
||||
/** Validate an unknown value as a PRD document (throws zod errors on failure). */
|
||||
export function parsePrdDocument(value: unknown): PrdDocument {
|
||||
return prdDocumentSchema.parse(coerceTimestamps(value)) as PrdDocument;
|
||||
}
|
||||
|
||||
function expandHome(projectPath: string): string {
|
||||
if (!projectPath.startsWith('~')) {
|
||||
return projectPath;
|
||||
@@ -106,8 +74,6 @@ function prdDirectory(projectPath: string): string {
|
||||
return path.join(projectPath, PRD_DIRECTORY);
|
||||
}
|
||||
|
||||
export { prdDirectory };
|
||||
|
||||
function prdFilePath(projectPath: string, id: string): string {
|
||||
return path.join(prdDirectory(projectPath), `${id}.yaml`);
|
||||
}
|
||||
@@ -147,13 +113,11 @@ export async function createPrd(options: CreatePrdOptions): Promise<PrdDocument>
|
||||
status: 'draft',
|
||||
projectPath: resolvedProjectPath,
|
||||
template: template.id,
|
||||
version: 1,
|
||||
sections: template.sections.map((section) => ({
|
||||
id: section.id,
|
||||
title: section.title,
|
||||
fields: Object.fromEntries(section.fields.map((field) => [field, ''])),
|
||||
})),
|
||||
missions: [],
|
||||
createdAt: now,
|
||||
updatedAt: now,
|
||||
};
|
||||
@@ -226,7 +190,7 @@ export async function listPrds(projectPath: string): Promise<PrdDocument[]> {
|
||||
throw new Error(`Failed to parse PRD file ${filePath}: ${String(error)}`);
|
||||
}
|
||||
|
||||
const document = parsePrdDocument(parsed);
|
||||
const document = prdDocumentSchema.parse(parsed);
|
||||
documents.push(document);
|
||||
}
|
||||
|
||||
|
||||
@@ -1,433 +0,0 @@
|
||||
import { existsSync } from 'node:fs';
|
||||
import { mkdtemp, readFile, readdir, writeFile } from 'node:fs/promises';
|
||||
import os from 'node:os';
|
||||
import path from 'node:path';
|
||||
|
||||
import yaml from 'js-yaml';
|
||||
import { beforeEach, describe, expect, it } from 'vitest';
|
||||
|
||||
import {
|
||||
PRD_GENERATED_VIEW_LABEL,
|
||||
PrdImportConflictError,
|
||||
PrdImportInvalidError,
|
||||
PrdNotFoundError,
|
||||
PrdService,
|
||||
PrdUpdateError,
|
||||
} from './index.js';
|
||||
import type { PrdDocument } from './index.js';
|
||||
|
||||
// ── Helpers ──────────────────────────────────────────────────────────────────
|
||||
|
||||
let projectDir: string;
|
||||
|
||||
async function makeProject(): Promise<string> {
|
||||
return mkdtemp(path.join(os.tmpdir(), 'prdy-service-'));
|
||||
}
|
||||
|
||||
function service(): PrdService {
|
||||
return new PrdService({ projectPath: projectDir });
|
||||
}
|
||||
|
||||
function storeDir(): string {
|
||||
return path.join(projectDir, 'docs', 'prdy');
|
||||
}
|
||||
|
||||
/** Handcraft a full, schema-valid PRD document for import scenarios. */
|
||||
function importFixture(overrides: Partial<PrdDocument> = {}): PrdDocument {
|
||||
return {
|
||||
id: 'imported-prd-20260101-000000',
|
||||
title: 'Imported PRD',
|
||||
status: 'draft',
|
||||
projectPath: '/tmp/elsewhere',
|
||||
template: 'software',
|
||||
version: 1,
|
||||
sections: [
|
||||
{ id: 'introduction', title: 'Introduction', fields: { context: '', objective: '' } },
|
||||
{
|
||||
id: 'scope-non-goals',
|
||||
title: 'Scope / Non-Goals',
|
||||
fields: { inScope: '', outOfScope: '' },
|
||||
},
|
||||
],
|
||||
missions: [],
|
||||
createdAt: '2026-01-01T00:00:00.000Z',
|
||||
updatedAt: '2026-01-01T00:00:00.000Z',
|
||||
...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
async function writeImportFile(doc: PrdDocument): Promise<string> {
|
||||
const filePath = path.join(projectDir, `${doc.id}.import.yaml`);
|
||||
await writeFile(filePath, yaml.dump(doc), 'utf8');
|
||||
return filePath;
|
||||
}
|
||||
|
||||
beforeEach(async () => {
|
||||
projectDir = await makeProject();
|
||||
});
|
||||
|
||||
// ── Single authority store (AC: prdy path and mission path resolve to the
|
||||
// SAME store under docs/prdy/ with stable ids/versions) ────────────────────
|
||||
|
||||
describe('PrdService single authority store', () => {
|
||||
it('persists PRDs from the prdy path and the mission path into the same docs/prdy store', async () => {
|
||||
const direct = await service().create({ name: 'Direct PRD' });
|
||||
const viaMission = await service().planForMission({
|
||||
name: 'Mission PRD',
|
||||
missionId: 'mission-1',
|
||||
missionVersion: '2026-01-01T00:00:00.000Z',
|
||||
});
|
||||
|
||||
const files = await readdir(storeDir());
|
||||
expect(files).toContain(`${direct.id}.yaml`);
|
||||
expect(files).toContain(`${viaMission.id}.yaml`);
|
||||
|
||||
// A fresh service instance (new process equivalent) resolves both.
|
||||
const all = await service().list();
|
||||
expect(all.map((doc) => doc.id).sort()).toEqual([direct.id, viaMission.id].sort());
|
||||
|
||||
// Stable versions: creation is v1; linkage writes do not bump content version.
|
||||
expect((await service().get(direct.id)).version).toBe(1);
|
||||
expect((await service().get(viaMission.id)).version).toBe(1);
|
||||
});
|
||||
|
||||
it('round-trips documents through the store with identity intact', async () => {
|
||||
const created = await service().create({ name: 'Round Trip', template: 'feature' });
|
||||
const fresh = await service().get(created.id);
|
||||
|
||||
expect(fresh).toEqual(created);
|
||||
expect(fresh.id).toBe(created.id);
|
||||
expect(fresh.template).toBe('feature');
|
||||
expect(fresh.status).toBe('draft');
|
||||
});
|
||||
|
||||
it('throws a typed error for unknown ids and empty stores', async () => {
|
||||
await expect(service().get('nope')).rejects.toBeInstanceOf(PrdNotFoundError);
|
||||
await expect(service().get()).rejects.toBeInstanceOf(PrdNotFoundError);
|
||||
});
|
||||
});
|
||||
|
||||
// ── Mission linkage persistence (AC: linkage survives restart via fresh
|
||||
// service instances) ────────────────────────────────────────────────────────
|
||||
|
||||
describe('PrdService mission linkage', () => {
|
||||
it('persists linkage and reads it back from a fresh service instance', async () => {
|
||||
const created = await service().planForMission({
|
||||
name: 'Linked PRD',
|
||||
missionId: 'mission-42',
|
||||
missionVersion: '2026-02-03T04:05:06.000Z',
|
||||
requirementIds: ['FR-1', 'FR-2'],
|
||||
});
|
||||
|
||||
// Fresh instance — nothing in memory from the creating call.
|
||||
const links = await service().listMissionLinks(created.id);
|
||||
expect(links).toHaveLength(1);
|
||||
expect(links[0]).toMatchObject({
|
||||
missionId: 'mission-42',
|
||||
missionVersion: '2026-02-03T04:05:06.000Z',
|
||||
prdVersion: 1,
|
||||
requirementIds: ['FR-1', 'FR-2'],
|
||||
});
|
||||
|
||||
// Linkage is carried in the YAML authority file itself.
|
||||
const raw = await readFile(path.join(storeDir(), `${created.id}.yaml`), 'utf8');
|
||||
const persisted = yaml.load(raw) as PrdDocument;
|
||||
expect(persisted.missions[0]?.missionId).toBe('mission-42');
|
||||
expect(persisted.missions[0]?.requirementIds).toEqual(['FR-1', 'FR-2']);
|
||||
});
|
||||
|
||||
it('refreshes an existing linkage entry in place instead of duplicating', async () => {
|
||||
const created = await service().planForMission({
|
||||
name: 'Relink PRD',
|
||||
missionId: 'mission-7',
|
||||
missionVersion: 'v1',
|
||||
});
|
||||
|
||||
await service().update({
|
||||
id: created.id,
|
||||
sections: [{ id: 'introduction', fields: { objective: 'Ship it' } }],
|
||||
});
|
||||
|
||||
const relinked = await service().linkMission({
|
||||
prdId: created.id,
|
||||
missionId: 'mission-7',
|
||||
missionVersion: 'v2',
|
||||
requirementIds: ['NFR-1'],
|
||||
});
|
||||
|
||||
expect(relinked.missions).toHaveLength(1);
|
||||
expect(relinked.missions[0]).toMatchObject({ missionVersion: 'v2', prdVersion: 2 });
|
||||
});
|
||||
|
||||
it('does not bump the content version when writing linkage', async () => {
|
||||
const created = await service().create({ name: 'Stable Version' });
|
||||
const linked = await service().linkMission({
|
||||
prdId: created.id,
|
||||
missionId: 'm',
|
||||
missionVersion: 'v1',
|
||||
});
|
||||
expect(linked.version).toBe(1);
|
||||
});
|
||||
});
|
||||
|
||||
// ── Update semantics ──────────────────────────────────────────────────────────
|
||||
|
||||
describe('PrdService update', () => {
|
||||
it('applies section patches and bumps the content version', async () => {
|
||||
const created = await service().create({ name: 'Updatable' });
|
||||
const updated = await service().update({
|
||||
id: created.id,
|
||||
sections: [{ id: 'introduction', fields: { context: 'Some context', objective: 'Goal' } }],
|
||||
});
|
||||
|
||||
expect(updated.version).toBe(2);
|
||||
expect(updated.sections[0]?.fields).toMatchObject({
|
||||
context: 'Some context',
|
||||
objective: 'Goal',
|
||||
});
|
||||
expect((await service().get(created.id)).version).toBe(2);
|
||||
});
|
||||
|
||||
it('refuses unknown section ids with a typed error', async () => {
|
||||
const created = await service().create({ name: 'Strict' });
|
||||
await expect(
|
||||
service().update({ id: created.id, sections: [{ id: 'nope', fields: {} }] }),
|
||||
).rejects.toBeInstanceOf(PrdUpdateError);
|
||||
});
|
||||
});
|
||||
|
||||
// ── Markdown export is a labeled generated view, never authority ──────────────
|
||||
|
||||
describe('PrdService exportMarkdown', () => {
|
||||
it('writes a generated view carrying the label and source identity', async () => {
|
||||
const created = await service().create({ name: 'Exported PRD' });
|
||||
const result = await service().exportMarkdown({ id: created.id });
|
||||
|
||||
expect(result.filePath).toBe(path.join(storeDir(), `${created.id}.md`));
|
||||
expect(result.content).toContain(PRD_GENERATED_VIEW_LABEL);
|
||||
expect(result.content).toContain(`prd-id: ${created.id}`);
|
||||
expect(result.content).toContain('prd-version: 1');
|
||||
expect(result.content).toContain(`source-of-truth: docs/prdy/${created.id}.yaml`);
|
||||
});
|
||||
|
||||
it('reflects the current version after updates', async () => {
|
||||
const created = await service().create({ name: 'Versioned Export' });
|
||||
await service().update({
|
||||
id: created.id,
|
||||
sections: [{ id: 'introduction', fields: { objective: 'v2 goal' } }],
|
||||
});
|
||||
const result = await service().exportMarkdown({ id: created.id });
|
||||
expect(result.content).toContain('prd-version: 2');
|
||||
});
|
||||
|
||||
it('NEGATIVE CONTROL: mutating the exported Markdown cannot change the authority', async () => {
|
||||
const created = await service().create({ name: 'Guarded PRD' });
|
||||
const before = structuredClone(await service().get(created.id));
|
||||
|
||||
const result = await service().exportMarkdown({ id: created.id });
|
||||
await writeFile(
|
||||
result.filePath,
|
||||
`<!-- ${PRD_GENERATED_VIEW_LABEL} -->\n# FAKE\nprd-id: fake-id\nprd-version: 99\n`,
|
||||
'utf8',
|
||||
);
|
||||
|
||||
const after = await service().get(created.id);
|
||||
expect(after).toEqual(before);
|
||||
expect(after.version).toBe(1);
|
||||
expect(after.title).toBe(before.title);
|
||||
});
|
||||
|
||||
it('never parses Markdown files that sit in the store directory', async () => {
|
||||
const created = await service().create({ name: 'Decoy Guard' });
|
||||
|
||||
// A decoy .md file with invalid YAML must be invisible to the store.
|
||||
await writeFile(path.join(storeDir(), 'decoy.md'), 'not: [valid: yaml', 'utf8');
|
||||
// And a decoy .yaml-named Markdown body must not silently validate either.
|
||||
await service().exportMarkdown({ id: created.id });
|
||||
|
||||
const listed = await service().list();
|
||||
expect(listed.map((doc) => doc.id)).toEqual([created.id]);
|
||||
await expect(service().get(created.id)).resolves.toBeTruthy();
|
||||
});
|
||||
});
|
||||
|
||||
// ── Import: validated, conflict-aware, never silently merging ─────────────────
|
||||
|
||||
describe('PrdService importDocument', () => {
|
||||
it('creates a valid import through the service, as draft — validity is not approval', async () => {
|
||||
const filePath = await writeImportFile(importFixture({ status: 'approved' }));
|
||||
|
||||
const result = await service().importDocument({ filePath });
|
||||
|
||||
expect(result.kind).toBe('created');
|
||||
expect(result.document.id).toBe('imported-prd-20260101-000000');
|
||||
expect(result.document.status).toBe('draft'); // structural validity ≠ approval
|
||||
expect(result.document.version).toBe(1);
|
||||
|
||||
const persisted = await service().get('imported-prd-20260101-000000');
|
||||
expect(persisted.status).toBe('draft');
|
||||
|
||||
const files = await readdir(storeDir());
|
||||
expect(files).toContain('imported-prd-20260101-000000.yaml');
|
||||
});
|
||||
|
||||
it('reports identical content as a no-op without writing', async () => {
|
||||
const created = await service().create({ name: 'Existing PRD' });
|
||||
const before = await readFile(path.join(storeDir(), `${created.id}.yaml`), 'utf8');
|
||||
|
||||
const filePath = await writeImportFile(importFixture({ ...created }));
|
||||
const result = await service().importDocument({ filePath });
|
||||
|
||||
expect(result.kind).toBe('identical');
|
||||
const after = await readFile(path.join(storeDir(), `${created.id}.yaml`), 'utf8');
|
||||
expect(after).toBe(before);
|
||||
});
|
||||
|
||||
it('refuses a conflicting import with a typed error, a proposed successor, and untouched bytes', async () => {
|
||||
const existing = await service().create({ name: 'Authority PRD' });
|
||||
await service().linkMission({
|
||||
prdId: existing.id,
|
||||
missionId: 'mission-keep',
|
||||
missionVersion: 'v1',
|
||||
requirementIds: ['FR-0'],
|
||||
});
|
||||
const beforeBytes = await readFile(path.join(storeDir(), `${existing.id}.yaml`), 'utf8');
|
||||
|
||||
const divergent = importFixture({
|
||||
...existing,
|
||||
title: 'Divergent Title',
|
||||
sections: [
|
||||
{
|
||||
id: 'introduction',
|
||||
title: 'Introduction',
|
||||
fields: { context: 'changed', objective: '' },
|
||||
},
|
||||
],
|
||||
});
|
||||
const filePath = await writeImportFile(divergent);
|
||||
|
||||
const attempt = service().importDocument({ filePath });
|
||||
let caught: unknown;
|
||||
try {
|
||||
await attempt;
|
||||
} catch (error) {
|
||||
caught = error;
|
||||
}
|
||||
expect(caught).toBeInstanceOf(PrdImportConflictError);
|
||||
|
||||
const error = caught as PrdImportConflictError;
|
||||
expect(error.code).toBe('PRD_IMPORT_CONFLICT');
|
||||
expect(error.existing.id).toBe(existing.id);
|
||||
expect(error.proposal.version).toBe(existing.version + 1); // successor proposal
|
||||
expect(error.proposal.status).toBe('draft');
|
||||
|
||||
// Original authority content untouched on disk.
|
||||
const afterBytes = await readFile(path.join(storeDir(), `${existing.id}.yaml`), 'utf8');
|
||||
expect(afterBytes).toBe(beforeBytes);
|
||||
});
|
||||
|
||||
it('acceptSuccessor persists the proposal explicitly, carrying linkages forward', async () => {
|
||||
const existing = await service().create({ name: 'Successor Base' });
|
||||
await service().linkMission({
|
||||
prdId: existing.id,
|
||||
missionId: 'mission-keep',
|
||||
missionVersion: 'v1',
|
||||
});
|
||||
|
||||
const divergent = importFixture({
|
||||
...existing,
|
||||
title: 'Accepted Successor Title',
|
||||
});
|
||||
const filePath = await writeImportFile(divergent);
|
||||
|
||||
const successor = await service().acceptSuccessor({ filePath });
|
||||
expect(successor.id).toBe(existing.id);
|
||||
expect(successor.version).toBe(existing.version + 1);
|
||||
expect(successor.title).toBe('Accepted Successor Title');
|
||||
expect(successor.status).toBe('draft');
|
||||
expect(successor.missions.map((m) => m.missionId)).toEqual(['mission-keep']);
|
||||
|
||||
// Persisted for a fresh reader.
|
||||
const fresh = await service().get(existing.id);
|
||||
expect(fresh.version).toBe(2);
|
||||
expect(fresh.title).toBe('Accepted Successor Title');
|
||||
});
|
||||
|
||||
it('refuses structurally-invalid imports with a typed error and creates nothing', async () => {
|
||||
const cases: Array<{ name: string; body: string }> = [
|
||||
{ name: 'missing-title.yaml', body: yaml.dump({ id: 'x', status: 'draft' }) },
|
||||
{
|
||||
name: 'bad-status.yaml',
|
||||
body: yaml.dump(importFixture({ status: 'not-a-status' as PrdDocument['status'] })),
|
||||
},
|
||||
{
|
||||
name: 'bad-version.yaml',
|
||||
body: yaml.dump(importFixture({ version: 0 })),
|
||||
},
|
||||
{ name: 'not-yaml.yaml', body: '::: not yaml [\n - {' },
|
||||
];
|
||||
|
||||
for (const fixture of cases) {
|
||||
const filePath = path.join(projectDir, fixture.name);
|
||||
await writeFile(filePath, fixture.body, 'utf8');
|
||||
|
||||
await expect(service().importDocument({ filePath })).rejects.toBeInstanceOf(
|
||||
PrdImportInvalidError,
|
||||
);
|
||||
}
|
||||
|
||||
// Nothing was created: the authority store does not even exist yet.
|
||||
await expect(readdir(storeDir())).rejects.toMatchObject({ code: 'ENOENT' });
|
||||
});
|
||||
|
||||
it('acceptSuccessor refuses when there is no existing document to succeed', async () => {
|
||||
const filePath = await writeImportFile(importFixture());
|
||||
await expect(service().acceptSuccessor({ filePath })).rejects.toBeInstanceOf(PrdNotFoundError);
|
||||
});
|
||||
});
|
||||
|
||||
// ── No second writer: no code path reads exported Markdown back into authority ─
|
||||
|
||||
describe('no-second-writer invariant (source-level)', () => {
|
||||
// Resolve the package source dir whether vitest runs from the package root
|
||||
// (turbo/pnpm test) or from the worktree root.
|
||||
function resolveSrcDir(): string {
|
||||
const candidates = [path.resolve('src'), path.resolve('packages/prdy/src')];
|
||||
return candidates.find((dir) => existsSync(path.join(dir, 'service.ts'))) ?? candidates[0]!;
|
||||
}
|
||||
|
||||
const srcDir = resolveSrcDir();
|
||||
const sourceFiles = [
|
||||
'cli.ts',
|
||||
'index.ts',
|
||||
'prd.ts',
|
||||
'service.ts',
|
||||
'templates.ts',
|
||||
'types.ts',
|
||||
'wizard.ts',
|
||||
];
|
||||
|
||||
it('no source file in @mosaicstack/prdy reads a .md file', async () => {
|
||||
for (const file of sourceFiles) {
|
||||
const text = await readFile(path.join(srcDir, file), 'utf8');
|
||||
const readLines = text
|
||||
.split('\n')
|
||||
.map((line) => line.trim())
|
||||
.filter((line) => /readFile|readFileSync|createReadStream/.test(line));
|
||||
|
||||
for (const line of readLines) {
|
||||
expect(line.includes('.md'), `${file} reads a Markdown file: ${line}`).toBe(false);
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
it('the mosaic prdy/mission adapters never read a .md file', async () => {
|
||||
const adapterDir = path.resolve(srcDir, '..', '..', 'mosaic', 'src', 'commands');
|
||||
for (const file of ['prdy.ts', 'mission.ts']) {
|
||||
const text = await readFile(path.join(adapterDir, file), 'utf8');
|
||||
expect(text.includes("'.md'") || text.includes('.md`'), `${file} references a .md path`).toBe(
|
||||
false,
|
||||
);
|
||||
}
|
||||
});
|
||||
});
|
||||
@@ -1,379 +0,0 @@
|
||||
import { promises as fs } from 'node:fs';
|
||||
import path from 'node:path';
|
||||
|
||||
import yaml from 'js-yaml';
|
||||
|
||||
import { createPrd, listPrds, parsePrdDocument, prdDirectory, savePrd } from './prd.js';
|
||||
import type {
|
||||
PrdCreateInput,
|
||||
PrdDocument,
|
||||
PrdExportInput,
|
||||
PrdExportResult,
|
||||
PrdImportInput,
|
||||
PrdImportResult,
|
||||
PrdLinkMissionInput,
|
||||
PrdMissionLinkage,
|
||||
PrdPlanForMissionInput,
|
||||
PrdServiceOptions,
|
||||
PrdUpdateInput,
|
||||
} from './types.js';
|
||||
|
||||
/**
|
||||
* PrdService is the SINGLE authority surface for PRD documents.
|
||||
*
|
||||
* Every mutation path (CLI wizard, `mosaic mission --plan`, import) routes
|
||||
* through this service; the YAML store under `docs/prdy/` is the authority and
|
||||
* exported Markdown is a generated view that no code path reads back.
|
||||
*/
|
||||
|
||||
// ── Typed errors ───────────────────────────────────────────────────────────────
|
||||
|
||||
export class PrdError extends Error {
|
||||
constructor(
|
||||
message: string,
|
||||
readonly code: string,
|
||||
) {
|
||||
super(message);
|
||||
this.name = 'PrdError';
|
||||
}
|
||||
}
|
||||
|
||||
export class PrdNotFoundError extends PrdError {
|
||||
constructor(message: string) {
|
||||
super(message, 'PRD_NOT_FOUND');
|
||||
this.name = 'PrdNotFoundError';
|
||||
}
|
||||
}
|
||||
|
||||
export class PrdUpdateError extends PrdError {
|
||||
constructor(message: string) {
|
||||
super(message, 'PRD_UPDATE_INVALID');
|
||||
this.name = 'PrdUpdateError';
|
||||
}
|
||||
}
|
||||
|
||||
/** Structural refusal: the import payload failed schema validation. Nothing is written. */
|
||||
export class PrdImportInvalidError extends PrdError {
|
||||
constructor(
|
||||
message: string,
|
||||
readonly issues?: string,
|
||||
) {
|
||||
super(message, 'PRD_IMPORT_INVALID');
|
||||
this.name = 'PrdImportInvalidError';
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Conflict refusal: an existing PRD shares the imported id but the content
|
||||
* diverges. Carries a PROPOSED successor (existing version + 1) that is only
|
||||
* persisted via an explicit {@link PrdService.acceptSuccessor} call — import
|
||||
* never overwrites and never merges.
|
||||
*/
|
||||
export class PrdImportConflictError extends PrdError {
|
||||
constructor(
|
||||
message: string,
|
||||
readonly existing: PrdDocument,
|
||||
readonly proposal: PrdDocument,
|
||||
) {
|
||||
super(message, 'PRD_IMPORT_CONFLICT');
|
||||
this.name = 'PrdImportConflictError';
|
||||
}
|
||||
}
|
||||
|
||||
// ── Service ────────────────────────────────────────────────────────────────────
|
||||
|
||||
/** The generated-view label carried by every Markdown export. */
|
||||
export const PRD_GENERATED_VIEW_LABEL = 'generated view — do not edit';
|
||||
|
||||
export class PrdService {
|
||||
private readonly projectPath: string;
|
||||
|
||||
constructor(options: PrdServiceOptions) {
|
||||
this.projectPath = options.projectPath;
|
||||
}
|
||||
|
||||
/** Create a new PRD (version 1, draft) in the authority store. */
|
||||
async create(input: PrdCreateInput): Promise<PrdDocument> {
|
||||
return createPrd({
|
||||
name: input.name,
|
||||
projectPath: this.projectPath,
|
||||
template: input.template,
|
||||
interactive: false,
|
||||
});
|
||||
}
|
||||
|
||||
/** Read a PRD by id, or the most recently updated one. */
|
||||
async get(id?: string): Promise<PrdDocument> {
|
||||
const documents = await listPrds(this.projectPath);
|
||||
|
||||
if (id === undefined) {
|
||||
const latest = documents[0];
|
||||
if (latest === undefined) {
|
||||
throw new PrdNotFoundError(`No PRD documents found under docs/prdy/ for this project`);
|
||||
}
|
||||
return latest;
|
||||
}
|
||||
|
||||
const match = documents.find((doc) => doc.id === id);
|
||||
if (match === undefined) {
|
||||
throw new PrdNotFoundError(`PRD id not found: ${id}`);
|
||||
}
|
||||
return match;
|
||||
}
|
||||
|
||||
/** List all PRDs in the authority store (most recently updated first). */
|
||||
async list(): Promise<PrdDocument[]> {
|
||||
return listPrds(this.projectPath);
|
||||
}
|
||||
|
||||
/**
|
||||
* Apply section field patches and bump the content version.
|
||||
* Linkage entries are preserved; linkage writes do NOT bump the version.
|
||||
*/
|
||||
async update(input: PrdUpdateInput): Promise<PrdDocument> {
|
||||
const doc = await this.get(input.id);
|
||||
|
||||
for (const patch of input.sections) {
|
||||
const section = doc.sections.find((candidate) => candidate.id === patch.id);
|
||||
if (section === undefined) {
|
||||
throw new PrdUpdateError(`Unknown section id: ${patch.id}`);
|
||||
}
|
||||
for (const [field, value] of Object.entries(patch.fields)) {
|
||||
if (!(field in section.fields)) {
|
||||
throw new PrdUpdateError(`Unknown field "${field}" on section "${patch.id}"`);
|
||||
}
|
||||
section.fields[field] = value;
|
||||
}
|
||||
}
|
||||
|
||||
doc.version += 1;
|
||||
doc.updatedAt = new Date().toISOString();
|
||||
await savePrd(doc);
|
||||
return doc;
|
||||
}
|
||||
|
||||
/**
|
||||
* Record (or refresh) a mission ↔ PRD linkage on the PRD document.
|
||||
* Persisted in the YAML authority, so it survives restarts.
|
||||
*/
|
||||
async linkMission(input: PrdLinkMissionInput): Promise<PrdDocument> {
|
||||
const doc = await this.get(input.prdId);
|
||||
return this.applyLinkage(doc, input);
|
||||
}
|
||||
|
||||
/** Read back the mission linkages recorded on a PRD. */
|
||||
async listMissionLinks(prdId?: string): Promise<PrdMissionLinkage[]> {
|
||||
const doc = await this.get(prdId);
|
||||
return doc.missions;
|
||||
}
|
||||
|
||||
/**
|
||||
* Mission planning path: create a PRD for a mission AND persist the
|
||||
* mission↔PRD linkage in a single authority write.
|
||||
*/
|
||||
async planForMission(input: PrdPlanForMissionInput): Promise<PrdDocument> {
|
||||
const doc = await this.create({ name: input.name, template: input.template });
|
||||
return this.applyLinkage(doc, {
|
||||
prdId: doc.id,
|
||||
missionId: input.missionId,
|
||||
missionVersion: input.missionVersion,
|
||||
requirementIds: input.requirementIds,
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Render the PRD to a Markdown GENERATED VIEW.
|
||||
*
|
||||
* The output carries source identity (PRD id + version + generated-view
|
||||
* label). It is written under `docs/prdy/<id>.md` and is NEVER read back:
|
||||
* the authority store only loads `.yaml`/`.yml` files, and no code path in
|
||||
* this package parses the exported Markdown.
|
||||
*/
|
||||
async exportMarkdown(input?: PrdExportInput): Promise<PrdExportResult> {
|
||||
const doc = await this.get(input?.id);
|
||||
const content = renderMarkdown(doc);
|
||||
const filePath = input?.outPath ?? path.join(prdDirectory(doc.projectPath), `${doc.id}.md`);
|
||||
|
||||
await fs.mkdir(path.dirname(filePath), { recursive: true });
|
||||
await fs.writeFile(filePath, content, 'utf8');
|
||||
return { filePath, content };
|
||||
}
|
||||
|
||||
/**
|
||||
* Import a YAML PRD document.
|
||||
*
|
||||
* Structural validation (zod) happens BEFORE anything is proposed or
|
||||
* written. A structurally-valid import is persisted as `draft` — validity is
|
||||
* NOT approval. If an existing PRD shares the id with divergent content, a
|
||||
* typed {@link PrdImportConflictError} is thrown carrying a proposed
|
||||
* successor; the original authority document is left byte-identical on disk.
|
||||
*/
|
||||
async importDocument(input: PrdImportInput): Promise<PrdImportResult> {
|
||||
const incoming = await this.readImportFile(input.filePath);
|
||||
|
||||
const existing = (await listPrds(this.projectPath)).find((doc) => doc.id === incoming.id);
|
||||
if (existing === undefined) {
|
||||
const document = this.buildImportedDocument(incoming);
|
||||
await savePrd(document);
|
||||
return { kind: 'created', document };
|
||||
}
|
||||
|
||||
if (canonicalCore(existing) === canonicalCore(incoming)) {
|
||||
return { kind: 'identical', document: existing };
|
||||
}
|
||||
|
||||
throw new PrdImportConflictError(
|
||||
`PRD id "${incoming.id}" already exists with divergent content — refusing to overwrite. ` +
|
||||
`Proposed successor: version ${existing.version + 1} (draft). ` +
|
||||
`Accept explicitly with acceptSuccessor().`,
|
||||
existing,
|
||||
this.buildSuccessor(existing, incoming),
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Explicitly accept a conflicted import as a successor version of the
|
||||
* existing PRD. Re-validates the source file before writing; the successor
|
||||
* is persisted with status `draft` (acceptance of the import is not approval
|
||||
* of the PRD) and the existing mission linkages are carried forward.
|
||||
*/
|
||||
async acceptSuccessor(input: PrdImportInput): Promise<PrdDocument> {
|
||||
const incoming = await this.readImportFile(input.filePath);
|
||||
|
||||
const existing = (await listPrds(this.projectPath)).find((doc) => doc.id === incoming.id);
|
||||
if (existing === undefined) {
|
||||
throw new PrdNotFoundError(
|
||||
`No existing PRD with id "${incoming.id}" — use importDocument to create it`,
|
||||
);
|
||||
}
|
||||
|
||||
const successor = this.buildSuccessor(existing, incoming);
|
||||
await savePrd(successor);
|
||||
return successor;
|
||||
}
|
||||
|
||||
// ── internals ──────────────────────────────────────────────────────────────
|
||||
|
||||
private async applyLinkage(doc: PrdDocument, input: PrdLinkMissionInput): Promise<PrdDocument> {
|
||||
const entry: PrdMissionLinkage = {
|
||||
missionId: input.missionId,
|
||||
missionVersion: input.missionVersion,
|
||||
prdVersion: doc.version,
|
||||
requirementIds: input.requirementIds ?? [],
|
||||
linkedAt: new Date().toISOString(),
|
||||
};
|
||||
|
||||
// One entry per mission: refresh in place if the mission is already linked.
|
||||
const index = doc.missions.findIndex((m) => m.missionId === entry.missionId);
|
||||
if (index === -1) {
|
||||
doc.missions.push(entry);
|
||||
} else {
|
||||
doc.missions[index] = entry;
|
||||
}
|
||||
|
||||
// Linkage is mission-side metadata, not a content revision: bump the
|
||||
// timestamp only so ids/versions stay stable for consumers.
|
||||
doc.updatedAt = new Date().toISOString();
|
||||
await savePrd(doc);
|
||||
return doc;
|
||||
}
|
||||
|
||||
private async readImportFile(filePath: string): Promise<PrdDocument> {
|
||||
let raw: string;
|
||||
try {
|
||||
raw = await fs.readFile(filePath, 'utf8');
|
||||
} catch (error) {
|
||||
throw new PrdImportInvalidError(`Cannot read import file ${filePath}: ${String(error)}`);
|
||||
}
|
||||
|
||||
let parsed: unknown;
|
||||
try {
|
||||
parsed = yaml.load(raw);
|
||||
} catch (error) {
|
||||
throw new PrdImportInvalidError(`Import file is not valid YAML: ${String(error)}`);
|
||||
}
|
||||
|
||||
try {
|
||||
return parsePrdDocument(parsed);
|
||||
} catch (error) {
|
||||
throw new PrdImportInvalidError(
|
||||
`Import file failed PRD schema validation: ${filePath}`,
|
||||
error instanceof Error ? error.message : String(error),
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
private buildImportedDocument(incoming: PrdDocument): PrdDocument {
|
||||
const now = new Date().toISOString();
|
||||
return {
|
||||
...incoming,
|
||||
// The import lands in THIS project's authority store.
|
||||
projectPath: this.projectPath,
|
||||
// A structurally-valid import is not thereby approved.
|
||||
status: 'draft',
|
||||
version: 1,
|
||||
missions: [],
|
||||
createdAt: now,
|
||||
updatedAt: now,
|
||||
};
|
||||
}
|
||||
|
||||
private buildSuccessor(existing: PrdDocument, incoming: PrdDocument): PrdDocument {
|
||||
return {
|
||||
...incoming,
|
||||
id: existing.id,
|
||||
projectPath: existing.projectPath,
|
||||
status: 'draft',
|
||||
version: existing.version + 1,
|
||||
missions: existing.missions,
|
||||
createdAt: existing.createdAt,
|
||||
updatedAt: new Date().toISOString(),
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
// ── Markdown rendering (generated view) ───────────────────────────────────────
|
||||
|
||||
function canonicalCore(doc: PrdDocument): string {
|
||||
return JSON.stringify([doc.title, doc.template, doc.sections]);
|
||||
}
|
||||
|
||||
function renderMarkdown(doc: PrdDocument): string {
|
||||
const lines: string[] = [
|
||||
'<!--',
|
||||
`${PRD_GENERATED_VIEW_LABEL}`,
|
||||
`source-of-truth: docs/prdy/${doc.id}.yaml (YAML authority)`,
|
||||
`prd-id: ${doc.id}`,
|
||||
`prd-version: ${doc.version}`,
|
||||
`generated-at: ${new Date().toISOString()}`,
|
||||
'-->',
|
||||
'',
|
||||
`# ${doc.title}`,
|
||||
'',
|
||||
`**Status:** ${doc.status} · **Version:** ${doc.version} · **Template:** ${doc.template}`,
|
||||
'',
|
||||
];
|
||||
|
||||
if (doc.missions.length > 0) {
|
||||
lines.push('## Mission Linkage', '');
|
||||
for (const mission of doc.missions) {
|
||||
const requirements =
|
||||
mission.requirementIds.length > 0 ? mission.requirementIds.join(', ') : 'none selected';
|
||||
lines.push(
|
||||
`- mission \`${mission.missionId}\` @ version \`${mission.missionVersion}\`` +
|
||||
` (linked at PRD v${mission.prdVersion}) — requirements: ${requirements}`,
|
||||
);
|
||||
}
|
||||
lines.push('');
|
||||
}
|
||||
|
||||
for (const section of doc.sections) {
|
||||
lines.push(`## ${section.title}`, '');
|
||||
for (const [field, value] of Object.entries(section.fields)) {
|
||||
lines.push(`### ${field}`, '', value.trim().length > 0 ? value : '_Not set_.', '');
|
||||
}
|
||||
}
|
||||
|
||||
lines.push('---', '', `_End of generated view for ${doc.id} v${doc.version}._`, '');
|
||||
return lines.join('\n');
|
||||
}
|
||||
@@ -19,31 +19,13 @@ export interface PrdSection {
|
||||
fields: Record<string, string>;
|
||||
}
|
||||
|
||||
/**
|
||||
* Mission ↔ PRD linkage recorded on the PRD document (the YAML authority).
|
||||
*
|
||||
* `missionVersion` is the mission-side revision marker available to the CLI
|
||||
* (the gateway exposes `updatedAt` for missions — there is no numeric mission
|
||||
* version yet). `prdVersion` snapshots the PRD content version at link time.
|
||||
*/
|
||||
export interface PrdMissionLinkage {
|
||||
missionId: string;
|
||||
missionVersion: string;
|
||||
prdVersion: number;
|
||||
requirementIds: string[];
|
||||
linkedAt: string;
|
||||
}
|
||||
|
||||
export interface PrdDocument {
|
||||
id: string;
|
||||
title: string;
|
||||
status: PrdStatus;
|
||||
projectPath: string;
|
||||
template: string;
|
||||
/** Content revision counter. Bumped by updates and accepted imports. */
|
||||
version: number;
|
||||
sections: PrdSection[];
|
||||
missions: PrdMissionLinkage[];
|
||||
createdAt: string;
|
||||
updatedAt: string;
|
||||
}
|
||||
@@ -54,60 +36,3 @@ export interface CreatePrdOptions {
|
||||
template?: string;
|
||||
interactive?: boolean;
|
||||
}
|
||||
|
||||
// ── PrdService surface (single authority entry point) ─────────────────────────
|
||||
|
||||
export interface PrdServiceOptions {
|
||||
projectPath: string;
|
||||
}
|
||||
|
||||
export interface PrdCreateInput {
|
||||
name: string;
|
||||
template?: string;
|
||||
}
|
||||
|
||||
export interface PrdSectionPatch {
|
||||
id: string;
|
||||
fields: Record<string, string>;
|
||||
}
|
||||
|
||||
export interface PrdUpdateInput {
|
||||
/** Defaults to the most recently updated PRD. */
|
||||
id?: string;
|
||||
sections: PrdSectionPatch[];
|
||||
}
|
||||
|
||||
export interface PrdLinkMissionInput {
|
||||
/** Defaults to the most recently updated PRD. */
|
||||
prdId?: string;
|
||||
missionId: string;
|
||||
missionVersion: string;
|
||||
requirementIds?: string[];
|
||||
}
|
||||
|
||||
export interface PrdPlanForMissionInput extends PrdLinkMissionInput {
|
||||
name: string;
|
||||
template?: string;
|
||||
}
|
||||
|
||||
export interface PrdExportInput {
|
||||
/** Defaults to the most recently updated PRD. */
|
||||
id?: string;
|
||||
/** Override the generated-view output path. */
|
||||
outPath?: string;
|
||||
}
|
||||
|
||||
export interface PrdExportResult {
|
||||
filePath: string;
|
||||
content: string;
|
||||
}
|
||||
|
||||
/** Discriminated result of a non-conflicting import. */
|
||||
export type PrdImportResult =
|
||||
| { kind: 'created'; document: PrdDocument }
|
||||
| { kind: 'identical'; document: PrdDocument };
|
||||
|
||||
export interface PrdImportInput {
|
||||
/** Path to a YAML-serialized PRD document (NOT the generated Markdown view). */
|
||||
filePath: string;
|
||||
}
|
||||
|
||||
+32
-43
@@ -2,8 +2,8 @@ import path from 'node:path';
|
||||
|
||||
import { cancel, intro, isCancel, outro, select, text } from '@clack/prompts';
|
||||
|
||||
import { PrdService } from './service.js';
|
||||
import type { CreatePrdOptions, PrdDocument, PrdSectionPatch } from './types.js';
|
||||
import { createPrd, savePrd } from './prd.js';
|
||||
import type { CreatePrdOptions, PrdDocument } from './types.js';
|
||||
|
||||
interface WizardAnswers {
|
||||
goals: string;
|
||||
@@ -11,41 +11,20 @@ interface WizardAnswers {
|
||||
milestones: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Translate wizard answers into section patches using the same keyword
|
||||
* matching the wizard always used (first section whose id contains the
|
||||
* keyword, then first field whose name contains it, else first field).
|
||||
*/
|
||||
function buildWizardPatches(doc: PrdDocument, answers: WizardAnswers): PrdSectionPatch[] {
|
||||
const bySection = new Map<string, PrdSectionPatch>();
|
||||
function updateSectionField(doc: PrdDocument, sectionKeyword: string, value: string): void {
|
||||
const section = doc.sections.find((candidate) => candidate.id.includes(sectionKeyword));
|
||||
|
||||
const add = (keyword: string, value: string): void => {
|
||||
const section = doc.sections.find((candidate) => candidate.id.includes(keyword));
|
||||
if (section === undefined) {
|
||||
return;
|
||||
}
|
||||
if (section === undefined) {
|
||||
return;
|
||||
}
|
||||
|
||||
const fieldName =
|
||||
Object.keys(section.fields).find((field) => field.toLowerCase().includes(keyword)) ??
|
||||
Object.keys(section.fields)[0];
|
||||
const fieldName =
|
||||
Object.keys(section.fields).find((field) => field.toLowerCase().includes(sectionKeyword)) ??
|
||||
Object.keys(section.fields)[0];
|
||||
|
||||
if (fieldName === undefined || section.fields[fieldName] === value) {
|
||||
return;
|
||||
}
|
||||
|
||||
const existing = bySection.get(section.id);
|
||||
if (existing === undefined) {
|
||||
bySection.set(section.id, { id: section.id, fields: { [fieldName]: value } });
|
||||
} else {
|
||||
existing.fields[fieldName] = value;
|
||||
}
|
||||
};
|
||||
|
||||
add('goal', answers.goals);
|
||||
add('constraint', answers.constraints);
|
||||
add('milestone', answers.milestones);
|
||||
|
||||
return [...bySection.values()];
|
||||
if (fieldName !== undefined) {
|
||||
section.fields[fieldName] = value;
|
||||
}
|
||||
}
|
||||
|
||||
async function promptText(message: string, initialValue = ''): Promise<string> {
|
||||
@@ -84,10 +63,15 @@ async function promptTemplate(template?: string): Promise<string> {
|
||||
return choice;
|
||||
}
|
||||
|
||||
/**
|
||||
* Interactive PRD wizard. All writes go through PrdService — the wizard is a
|
||||
* prompt layer, never a second writer path.
|
||||
*/
|
||||
function applyWizardAnswers(doc: PrdDocument, answers: WizardAnswers): PrdDocument {
|
||||
updateSectionField(doc, 'goal', answers.goals);
|
||||
updateSectionField(doc, 'constraint', answers.constraints);
|
||||
updateSectionField(doc, 'milestone', answers.milestones);
|
||||
|
||||
doc.updatedAt = new Date().toISOString();
|
||||
return doc;
|
||||
}
|
||||
|
||||
export async function runPrdWizard(options: CreatePrdOptions): Promise<PrdDocument> {
|
||||
intro('Mosaic PRD wizard');
|
||||
|
||||
@@ -98,15 +82,20 @@ export async function runPrdWizard(options: CreatePrdOptions): Promise<PrdDocume
|
||||
const constraints = await promptText('Key constraints');
|
||||
const milestones = await promptText('Planned milestones');
|
||||
|
||||
const service = new PrdService({ projectPath: options.projectPath });
|
||||
const doc = await service.create({
|
||||
const doc = await createPrd({
|
||||
...options,
|
||||
name,
|
||||
template,
|
||||
interactive: true,
|
||||
});
|
||||
|
||||
const patches = buildWizardPatches(doc, { goals, constraints, milestones });
|
||||
const updated =
|
||||
patches.length > 0 ? await service.update({ id: doc.id, sections: patches }) : doc;
|
||||
const updated = applyWizardAnswers(doc, {
|
||||
goals,
|
||||
constraints,
|
||||
milestones,
|
||||
});
|
||||
|
||||
await savePrd(updated);
|
||||
|
||||
outro(`PRD created: ${path.join(updated.projectPath, 'docs', 'prdy', `${updated.id}.yaml`)}`);
|
||||
|
||||
|
||||
@@ -1,45 +0,0 @@
|
||||
# RI-1-002 — Publish-gate negative controls (SDLC-D-034 second half)
|
||||
|
||||
- Task: RI-1-002 (docs/release-integrity workstream, PRD item RI-N1), issue ref #1275
|
||||
- Branch: `test/ri-050-publish-gate-negative` (base `origin/next` @ d8e0aec9 = PR #1277, RI-1-001)
|
||||
- Budget: worker estimate ~45K tokens; keep scoped to the two test files + scratchpad.
|
||||
|
||||
## Objective
|
||||
|
||||
Checked-in negative-control tests that PROVE the publish gate fails when it must:
|
||||
|
||||
1. Broken mandatory check blocks every publish step (structural DAG proof from `.woodpecker/publish.yml`).
|
||||
2. Bypass shapes fail the checker: missing edge, hidden effect (non-`publish` name), detached verify, always-pass verify (`failure: ignore` / `success` override), conditional verify (`when`).
|
||||
3. Exact-commit identity: no HEAD-moving step between verify and publish effects; legitimate re-checkout requires verify to re-run after it.
|
||||
4. `verify-release.mjs` composition control: a SUBSET stage list fails the composition check.
|
||||
|
||||
## Plan
|
||||
|
||||
- NEW `scripts/publish-gate-structure.test.mjs` — self-contained structural checker (`assertPublishGateBlocksOnVerify`) + positive control on the real pipeline + one negative-control test per bypass shape (S1–S6, documented in file header) + positive control for the legitimate re-checkout shape.
|
||||
- EXTEND `scripts/verify-release.test.mjs` — refactor the stage-mirror test body into `assertStagesMirrorCi(stages, ci)`; add negative control dropping each stage one at a time (subset must throw).
|
||||
|
||||
## Conventions confirmed
|
||||
|
||||
- Root `test:checkout` = `node --test scripts/*.test.mjs` → new file auto-joins `pnpm test`.
|
||||
- Test-enumeration guard population is `*test*.sh` under `packages/mosaic/framework/tools/` only → unaffected.
|
||||
- Root eslint covers only `**/*.{ts,tsx}` → .mjs files need Prettier style only (printWidth 100, singleQuote, semi, trailingComma all).
|
||||
- Do NOT touch docs/TASKS.md, docs/release-integrity/TASKS.md, docs/scratchpads/.
|
||||
|
||||
## Progress log
|
||||
|
||||
- [x] Base verified: publish.yml `verify` step + verify-release.mjs present; HEAD contains origin/next.
|
||||
- [x] Wrote scripts/publish-gate-structure.test.mjs
|
||||
- [x] Extended scripts/verify-release.test.mjs (mirror fn + subset negative control)
|
||||
- [x] Gates: node --test scripts (31 tests pass), prettier clean on touched files, pnpm typecheck PASS, pnpm lint PASS, pnpm format:check PASS
|
||||
- [x] Committed ff585b88 + pushed, PR #1305 → next (no conflicts). Stopped before merge per task instruction.
|
||||
|
||||
## Evidence
|
||||
|
||||
- `node --test scripts/verify-release.test.mjs scripts/publish-gate-structure.test.mjs` → 31 tests, 0 fail.
|
||||
- Mutation sanity: temporarily removing the `verify` edge from build-gateway in publish.yml → structure test goes red (verified manually during dev, then reverted).
|
||||
- Gates run from repo root on this worktree; results in Progress log.
|
||||
|
||||
## Risks / notes
|
||||
|
||||
- Effect detection (`isPublishCommand`) is deliberately over-broad (any npm/pnpm/yarn command mentioning `publish`, any kaniko/docker-push/`--destination`) — fail-closed: a false positive forces justification, a false negative is the actual hazard.
|
||||
- `git fetch` flagged as HEAD-moving even though fetch alone doesn't move HEAD — fail-closed on the classic `fetch && reset` pair.
|
||||
@@ -1,37 +0,0 @@
|
||||
# Scratchpad — RI-4-001 One transitional PRD authority (RI-N3, #1275)
|
||||
|
||||
- Objective: single PrdService authority in `@mosaicstack/prdy`; `mosaic prdy` and
|
||||
`mission --plan` become thin adapters; mission↔PRD linkage persisted on disk;
|
||||
Markdown export is a labeled generated view (never read back); import is
|
||||
validated/conflict-aware with typed refusals.
|
||||
- Budget: ~35K tokens (card cap). Baselines: prdy build/lint rc=0, 0 tests;
|
||||
mosaic build rc=0 (after root turbo build), lint rc=0, 1548 tests pass;
|
||||
root build rc=0.
|
||||
- Plan: (1) extend store schema (version, missions linkage) (2) PrdService +
|
||||
typed errors (3) wizard/cli route through service (4) mosaic adapters
|
||||
(5) contract specs both packages (6) gates (7) sabotage control (8) report
|
||||
to /var/tmp/ri-050/ri-4-001-report.md.
|
||||
- Decisions:
|
||||
- Linkage lives ON the PRD document (`missions` array) — one authority file,
|
||||
survives restart, no sidecar sync problems.
|
||||
- `version` = content revision of sections/status (bumped by update/import
|
||||
accept). Linkage writes bump `updatedAt` only, so ids/versions stay stable
|
||||
for the card's "stable ids/versions" contract.
|
||||
- Mission version marker = `mission.updatedAt` (gateway MissionInfo has no
|
||||
numeric version field).
|
||||
- Import reads YAML documents only — never the exported Markdown (keeps the
|
||||
"no code path reads exported Markdown" invariant).
|
||||
- Import of an existing id with identical core content → `identical` no-op;
|
||||
divergent → typed `PrdImportConflictError` carrying proposed successor
|
||||
(existing.version + 1, status draft, linkages preserved). Original bytes
|
||||
untouched until explicit `acceptSuccessor`.
|
||||
- `requirementIds` default `[]` at the mission command (no requirement
|
||||
selection UI yet) — service accepts ids when a caller has them.
|
||||
- Progress log:
|
||||
- [16:35] baselines captured (prdy 0 tests; mosaic 1548 after root build; root build rc=0)
|
||||
- [16:38] store schema v2 + PrdService + wizard/cli rerouted; prdy build/lint green
|
||||
- [16:40] mosaic adapters done; prdy spec 20/20 (found+fixed: import project-path leak, empty-store typed error, YAML timestamp coercion)
|
||||
- [16:44] mosaic specs 9/9 (fixed commander from:'user' argv, vi.mock hoisting, restoreAllMocks wiping factory mocks)
|
||||
- [16:45] all gates green; 4 commits (e291bfb, 2c5d208, a23826c, 540d6f1)
|
||||
- [16:46] sabotage: linkage write removed → prdy 3 fail / mosaic 2 fail, 1548/1548 pre-existing pass; restored byte-identically; re-green 20/20 + 1557/1557
|
||||
- [16:47] report written to /var/tmp/ri-050/ri-4-001-report.md — card complete
|
||||
@@ -1,310 +0,0 @@
|
||||
import assert from 'node:assert/strict';
|
||||
import { readFile } from 'node:fs/promises';
|
||||
import { createRequire } from 'node:module';
|
||||
import path from 'node:path';
|
||||
import test from 'node:test';
|
||||
|
||||
// RI-1-002 / RI-N1 publish-gate NEGATIVE CONTROLS (SDLC-D-034).
|
||||
//
|
||||
// scripts/verify-release.test.mjs pins the POSITIVE structure of the publish
|
||||
// gate: every publish effect declares a direct `depends_on: verify` edge and
|
||||
// the verify step asserts commit identity + runs the canonical command. This
|
||||
// suite is the negative-control set: each test feeds a structural gate
|
||||
// checker a pipeline in which the gate is bypassed by ONE specific shape and
|
||||
// asserts the checker goes RED. The controls prove from the pipeline FILE —
|
||||
// never by executing Woodpecker — that a verify step that FAILS (nonzero
|
||||
// exit) blocks every publish effect.
|
||||
//
|
||||
// Woodpecker semantics these controls rely on:
|
||||
// - A step that exits nonzero FAILS, and every step that transitively
|
||||
// depends on a failed step is SKIPPED — never run. That skip is the only
|
||||
// thing standing between a failed mandatory check and a publish effect.
|
||||
// - `detach: true` removes the step from the wait graph: the pipeline does
|
||||
// not wait for detached steps, so their failure can never block anything.
|
||||
// - `failure: ignore` reports a failed step as success to the DAG.
|
||||
// - `success: [codes...]` overrides which exit codes count as success;
|
||||
// admitting any nonzero code launders a failed verification into green.
|
||||
// - `when` on the verify step would skip verification entirely on some
|
||||
// event/path classes while publish effects still run.
|
||||
//
|
||||
// Bypass shapes covered (one negative-control test each):
|
||||
// S1 Missing edge — a publish effect whose dependency closure does not
|
||||
// contain `verify` (a refactor drops the depends_on entry).
|
||||
// S2 Hidden effect — a step whose NAME does not start with `publish` but
|
||||
// whose COMMANDS publish npm packages or push images. Effects are
|
||||
// classified by commands, so renaming a step cannot un-gate it.
|
||||
// S3 Detached verify — `verify: { detach: true }`: publish steps no longer
|
||||
// wait for verify, so the depends_on edge is decorative.
|
||||
// S4 Always-pass verify — `failure: ignore`, or a `success` override
|
||||
// admitting nonzero exit codes: verify fails, the DAG sees success.
|
||||
// S5 Conditional verify — a `when`/path filter on verify itself.
|
||||
// S6 Exact-commit drift — a HEAD-moving step (git checkout/switch/reset/
|
||||
// clean/pull/clone/fetch) ordered between `verify` and a publish
|
||||
// effect: the verified commit would not be the published commit. A
|
||||
// LEGITIMATE re-checkout is allowed only when `verify` itself runs
|
||||
// after it — positive control included.
|
||||
// S7 Gate removal — the verify step deleted or renamed away entirely.
|
||||
|
||||
// Reuse the monorepo's existing YAML parser (@mosaicstack/mosaic's direct
|
||||
// dependency) instead of adding a root dependency or vendoring a parser.
|
||||
const mosaicRequire = createRequire(
|
||||
path.resolve(process.cwd(), 'packages', 'mosaic', 'package.json'),
|
||||
);
|
||||
const { parse: parseYaml } = mosaicRequire('yaml');
|
||||
|
||||
const publishYmlPath = path.join(process.cwd(), '.woodpecker', 'publish.yml');
|
||||
|
||||
async function readPublishPipeline() {
|
||||
return parseYaml(await readFile(publishYmlPath, 'utf8'));
|
||||
}
|
||||
|
||||
// A command has a publish EFFECT when it publishes npm packages (`publish`
|
||||
// anywhere after a package-manager token — `pnpm --filter "@x/*" publish`
|
||||
// puts flags and quoted filters between the binary and the subcommand) or
|
||||
// pushes an image (kaniko, docker push, or a registry --destination).
|
||||
// Deliberately over-broad: a false positive forces justification, a false
|
||||
// negative is the actual hazard.
|
||||
function isPublishCommand(command) {
|
||||
return (
|
||||
/(^|\s)\/kaniko\/executor\b/.test(command) ||
|
||||
/(^|\s)docker\s+push\b/.test(command) ||
|
||||
/(^|\s)--destination(\s|=)/.test(command) ||
|
||||
(/\bpublish\b/.test(command) && /(^|\s)(npm|pnpm|yarn)(\s|$)/.test(command))
|
||||
);
|
||||
}
|
||||
|
||||
function hasPublishEffect(step) {
|
||||
return (step.commands ?? []).some(isPublishCommand);
|
||||
}
|
||||
|
||||
// A step is a publish effect when its name says so OR (S2) when any of its
|
||||
// commands does — classification must not depend on the name alone.
|
||||
function publishEffectSteps(pipeline) {
|
||||
return Object.entries(pipeline.steps ?? {})
|
||||
.filter(([name, step]) => name.startsWith('publish') || hasPublishEffect(step))
|
||||
.map(([name]) => name);
|
||||
}
|
||||
|
||||
// Transitive closure of a step's depends_on graph.
|
||||
function dependencyClosure(pipeline, stepName, seen = new Set()) {
|
||||
const dependencies = pipeline.steps?.[stepName]?.depends_on ?? [];
|
||||
for (const dependency of dependencies) {
|
||||
if (seen.has(dependency)) continue;
|
||||
seen.add(dependency);
|
||||
dependencyClosure(pipeline, dependency, seen);
|
||||
}
|
||||
return seen;
|
||||
}
|
||||
|
||||
// Deliberately over-broad: `git fetch` alone does not move HEAD, but the
|
||||
// classic re-checkout pair is `git fetch && git reset --hard <remote>`; a
|
||||
// fetch step sitting between verify and a publish effect deserves scrutiny,
|
||||
// so the gate fails closed on it.
|
||||
function movesHead(step) {
|
||||
return (step.commands ?? []).some((command) =>
|
||||
/(^|\s)git\s+(checkout|switch|reset|clean|pull|clone|fetch)\b/.test(command),
|
||||
);
|
||||
}
|
||||
|
||||
// The structural gate checker: green only when a failed (nonzero-exit)
|
||||
// verify provably blocks every publish effect on the same commit.
|
||||
function assertPublishGateBlocksOnVerify(pipeline) {
|
||||
assert.ok(pipeline.steps, 'publish pipeline must define steps');
|
||||
const verify = pipeline.steps.verify;
|
||||
assert.ok(verify, 'publish pipeline must define a `verify` step (S7)');
|
||||
|
||||
// S5: a skipped verification authorizes publishes exactly as much as a
|
||||
// failed one — verify must be unconditional.
|
||||
assert.equal(verify.when, undefined, '`verify` must not carry a when/path filter (S5)');
|
||||
|
||||
// S3/S4: the depends_on edges are only meaningful if verify's own failure
|
||||
// is both awaited and terminal for the DAG.
|
||||
assert.equal(verify.detach, undefined, '`verify` must not be detached (S3)');
|
||||
assert.equal(
|
||||
verify.failure,
|
||||
undefined,
|
||||
'`verify` must not tolerate its own failure (S4: failure: ignore launders a failed gate into success)',
|
||||
);
|
||||
assert.equal(
|
||||
verify.success,
|
||||
undefined,
|
||||
'`verify` must not override success exit codes (S4: nonzero codes would make failed verification pass)',
|
||||
);
|
||||
|
||||
const effects = publishEffectSteps(pipeline);
|
||||
assert.ok(effects.length > 0, 'publish pipeline must contain publish effect steps to guard');
|
||||
|
||||
const verifyClosure = dependencyClosure(pipeline, 'verify');
|
||||
for (const stepName of effects) {
|
||||
// S1: only the failure-skip semantics of the DAG stand between a failed
|
||||
// verify and this effect — the verify edge in its closure is the proof.
|
||||
const closure = dependencyClosure(pipeline, stepName);
|
||||
assert.ok(
|
||||
closure.has('verify'),
|
||||
`publish effect '${stepName}' must transitively depend on verify (S1) — a failed verify must skip it`,
|
||||
);
|
||||
|
||||
// S6: any step ordered after verify (outside its closure) but inside the
|
||||
// effect's chain must not be able to move HEAD. If the pipeline
|
||||
// legitimately re-checks-out, verify must run after the re-checkout.
|
||||
for (const chainStep of closure) {
|
||||
if (chainStep === 'verify' || verifyClosure.has(chainStep)) continue;
|
||||
assert.ok(
|
||||
!movesHead(pipeline.steps[chainStep]),
|
||||
`step '${chainStep}' sits between verify and publish effect '${stepName}' and can move HEAD (S6)` +
|
||||
' — verify must re-run after any re-checkout',
|
||||
);
|
||||
}
|
||||
}
|
||||
return effects;
|
||||
}
|
||||
|
||||
// A minimal but healthy gate used as the base for every negative-control
|
||||
// mutation: verify (identity + canonical command) → build → publish-npm,
|
||||
// with the publish effect blocked by verify both directly and through build.
|
||||
const HEALTHY_GATE_YAML = `
|
||||
steps:
|
||||
verify:
|
||||
image: node:24-alpine
|
||||
commands:
|
||||
- |
|
||||
if [ -z "$CI_COMMIT_SHA" ] || [ "$CI_COMMIT_SHA" != "$(git rev-parse HEAD)" ]; then
|
||||
echo "identity mismatch" >&2
|
||||
exit 1
|
||||
fi
|
||||
- pnpm verify:release
|
||||
build:
|
||||
image: node:24-alpine
|
||||
commands:
|
||||
- pnpm build
|
||||
depends_on:
|
||||
- verify
|
||||
publish-npm:
|
||||
image: node:24-alpine
|
||||
commands:
|
||||
- npm publish
|
||||
depends_on:
|
||||
- build
|
||||
- verify
|
||||
`;
|
||||
|
||||
// Fresh parse per call so every negative control mutates its own object.
|
||||
function healthyPipeline() {
|
||||
return parseYaml(HEALTHY_GATE_YAML);
|
||||
}
|
||||
|
||||
test('the real publish pipeline: a failed verify provably blocks every publish effect', async () => {
|
||||
const pipeline = await readPublishPipeline();
|
||||
const effects = assertPublishGateBlocksOnVerify(pipeline);
|
||||
assert.deepEqual(effects.sort(), [
|
||||
'build-appservice',
|
||||
'build-gateway',
|
||||
'build-web',
|
||||
'publish-next-npm',
|
||||
'publish-npm',
|
||||
]);
|
||||
});
|
||||
|
||||
test('fixture sanity: the healthy gate base passes the checker unmutated', () => {
|
||||
assertPublishGateBlocksOnVerify(healthyPipeline());
|
||||
});
|
||||
|
||||
test('S1 negative control: a publish effect with no verify edge fails the checker', () => {
|
||||
const pipeline = healthyPipeline();
|
||||
pipeline.steps['publish-npm'].depends_on = ['build'];
|
||||
pipeline.steps.build.depends_on = [];
|
||||
assert.throws(
|
||||
() => assertPublishGateBlocksOnVerify(pipeline),
|
||||
/publish-npm.*must transitively depend on verify/s,
|
||||
);
|
||||
});
|
||||
|
||||
test('S2 negative control: an npm publish hidden behind a non-publish step name fails the checker', () => {
|
||||
const pipeline = healthyPipeline();
|
||||
delete pipeline.steps['publish-npm'];
|
||||
pipeline.steps.build.depends_on = [];
|
||||
pipeline.steps.deploy = {
|
||||
image: 'node:24-alpine',
|
||||
commands: ['npm publish'],
|
||||
depends_on: ['build'],
|
||||
};
|
||||
// Detection must be by COMMAND: the name says "deploy", the commands say
|
||||
// publish — an un-gated effect under either reading.
|
||||
assert.throws(
|
||||
() => assertPublishGateBlocksOnVerify(pipeline),
|
||||
/deploy.*must transitively depend on verify/s,
|
||||
);
|
||||
});
|
||||
|
||||
test('S2 negative control: a kaniko image push under a build-* name fails the checker when ungated', () => {
|
||||
const pipeline = healthyPipeline();
|
||||
delete pipeline.steps['publish-npm'];
|
||||
pipeline.steps.build.depends_on = [];
|
||||
pipeline.steps['push-platform-image'] = {
|
||||
image: 'gcr.io/kaniko-project/executor:debug',
|
||||
commands: ['/kaniko/executor --context . --destination reg.example/img:latest'],
|
||||
depends_on: ['build'],
|
||||
};
|
||||
assert.throws(
|
||||
() => assertPublishGateBlocksOnVerify(pipeline),
|
||||
/push-platform-image.*must transitively depend on verify/s,
|
||||
);
|
||||
});
|
||||
|
||||
test('S3 negative control: a detached verify fails the checker', () => {
|
||||
const pipeline = healthyPipeline();
|
||||
pipeline.steps.verify.detach = true;
|
||||
assert.throws(() => assertPublishGateBlocksOnVerify(pipeline), /detached \(S3\)/);
|
||||
});
|
||||
|
||||
test('S4 negative control: failure: ignore on verify fails the checker', () => {
|
||||
const pipeline = healthyPipeline();
|
||||
pipeline.steps.verify.failure = 'ignore';
|
||||
assert.throws(() => assertPublishGateBlocksOnVerify(pipeline), /tolerate its own failure/);
|
||||
});
|
||||
|
||||
test('S4 negative control: a success override admitting nonzero exit codes fails the checker', () => {
|
||||
const pipeline = healthyPipeline();
|
||||
pipeline.steps.verify.success = [0, 1];
|
||||
assert.throws(() => assertPublishGateBlocksOnVerify(pipeline), /success exit codes/);
|
||||
});
|
||||
|
||||
test('S5 negative control: a when filter on verify fails the checker', () => {
|
||||
const pipeline = healthyPipeline();
|
||||
pipeline.steps.verify.when = [{ event: 'push' }];
|
||||
assert.throws(() => assertPublishGateBlocksOnVerify(pipeline), /when\/path filter \(S5\)/);
|
||||
});
|
||||
|
||||
test('S6 negative control: a HEAD-moving step between verify and publish fails the checker', () => {
|
||||
const pipeline = healthyPipeline();
|
||||
pipeline.steps.resync = {
|
||||
image: 'node:24-alpine',
|
||||
commands: ['git fetch origin', 'git reset --hard origin/main'],
|
||||
depends_on: [],
|
||||
};
|
||||
pipeline.steps.build.depends_on = ['verify', 'resync'];
|
||||
// resync sits AFTER verify in the publish chain (verify does not depend on
|
||||
// it), so the verified commit could be replaced before publishing.
|
||||
assert.throws(() => assertPublishGateBlocksOnVerify(pipeline), /resync.*can move HEAD/s);
|
||||
});
|
||||
|
||||
test('S6 positive control: a legitimate re-checkout passes when verify re-runs after it', () => {
|
||||
const pipeline = healthyPipeline();
|
||||
pipeline.steps.resync = {
|
||||
image: 'node:24-alpine',
|
||||
commands: ['git fetch origin', 'git reset --hard origin/main'],
|
||||
depends_on: [],
|
||||
};
|
||||
pipeline.steps.verify.depends_on = ['resync'];
|
||||
pipeline.steps.build.depends_on = ['verify'];
|
||||
// resync precedes verify in the chain, so verification covers the
|
||||
// re-checked-out HEAD — the exact-commit contract holds.
|
||||
assertPublishGateBlocksOnVerify(pipeline);
|
||||
});
|
||||
|
||||
test('S7 negative control: deleting the verify step entirely fails the checker', () => {
|
||||
const pipeline = healthyPipeline();
|
||||
delete pipeline.steps.verify;
|
||||
pipeline.steps['publish-npm'].depends_on = ['build'];
|
||||
assert.throws(() => assertPublishGateBlocksOnVerify(pipeline), /`verify` step/);
|
||||
});
|
||||
@@ -9,10 +9,7 @@ import { STAGES } from './verify-release.mjs';
|
||||
// SDLC-D-034 checkout invariant: publication in .woodpecker/publish.yml is
|
||||
// bound to exact-commit terminal verification. This suite parses the real
|
||||
// pipeline files and fails red when the gate is bypassed, weakened, or drifts
|
||||
// out of sync with the canonical `pnpm verify:release` command. The negative
|
||||
// controls for pipeline DAG/bypass shapes live in
|
||||
// scripts/publish-gate-structure.test.mjs (RI-1-002); this file owns the
|
||||
// canonical-command composition controls.
|
||||
// out of sync with the canonical `pnpm verify:release` command.
|
||||
|
||||
// Reuse the monorepo's existing YAML parser (@mosaicstack/mosaic's direct
|
||||
// dependency) instead of adding a root dependency or vendoring a parser.
|
||||
@@ -222,16 +219,13 @@ steps:
|
||||
assert.throws(() => assertPublishGate(parseYaml(noIdentityPipeline)), /CI_COMMIT_SHA/);
|
||||
});
|
||||
|
||||
// The composition check: the canonical stage table must mirror the PR CI
|
||||
// pipeline's complete mandatory set. Parameterized by the stage list so the
|
||||
// subset negative control below can prove a dropped stage goes red (RI-1-002:
|
||||
// the canonical command cannot silently lose a check).
|
||||
function assertStagesMirrorCi(stages, ci) {
|
||||
const canonical = Object.fromEntries(stages.map((stage) => [stage.name, stage.commands]));
|
||||
test('the canonical verify:release stages mirror the PR CI pipeline one-for-one', async () => {
|
||||
const ci = parseYaml(await readFile(ciYmlPath, 'utf8'));
|
||||
const canonical = Object.fromEntries(STAGES.map((stage) => [stage.name, stage.commands]));
|
||||
|
||||
// The complete mandatory set, in gate order.
|
||||
assert.deepEqual(
|
||||
stages.map((stage) => stage.name),
|
||||
STAGES.map((stage) => stage.name),
|
||||
['sanitization', 'upgrade-guard', 'typecheck', 'lint', 'format', 'test', 'build'],
|
||||
);
|
||||
|
||||
@@ -275,26 +269,6 @@ function assertStagesMirrorCi(stages, ci) {
|
||||
`ci.yml test step must keep its pipeline-level prerequisite '${fragment}'`,
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
test('the canonical verify:release stages mirror the PR CI pipeline one-for-one', async () => {
|
||||
const ci = parseYaml(await readFile(ciYmlPath, 'utf8'));
|
||||
assertStagesMirrorCi(STAGES, ci);
|
||||
});
|
||||
|
||||
test('a subset stage list fails the composition check — a dropped stage cannot pass silently', async () => {
|
||||
const ci = parseYaml(await readFile(ciYmlPath, 'utf8'));
|
||||
// Drop each stage one at a time: every stage is load-bearing, so every drop
|
||||
// must go red. If any drop went green, a refactor could silently delete a
|
||||
// mandatory check from the canonical command.
|
||||
for (const stage of STAGES) {
|
||||
const subset = STAGES.filter((entry) => entry.name !== stage.name);
|
||||
assert.throws(
|
||||
() => assertStagesMirrorCi(subset, ci),
|
||||
Error,
|
||||
`composition check must fail when the '${stage.name}' stage is dropped from the table`,
|
||||
);
|
||||
}
|
||||
});
|
||||
|
||||
test('the root package.json exposes verify:release as the canonical command', async () => {
|
||||
|
||||
@@ -133,10 +133,13 @@ When the full `@mosaicstack/forge` package is available, Forge uses MACP task ex
|
||||
|
||||
```bash
|
||||
# Run from CLI
|
||||
mosaic forge run path/to/brief.md
|
||||
# Fails closed with a typed FORGE_NO_EXECUTOR capability error when no real
|
||||
# executor is wired — pass --simulate to opt into explicit typed simulation
|
||||
# (every result carries status `simulated`, which satisfies nothing).
|
||||
mosaic forge run path/to/brief.md [--simulate]
|
||||
|
||||
# Resume interrupted run
|
||||
mosaic forge resume .forge/runs/20260401-143022/
|
||||
# Resume interrupted run (same fail-closed rule as forge run)
|
||||
mosaic forge resume .forge/runs/20260401-143022/ [--simulate]
|
||||
|
||||
# Check status
|
||||
mosaic forge status .forge/runs/20260401-143022/
|
||||
|
||||
Reference in New Issue
Block a user