Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
 jason.woltje
|
3100dfd66d |
@@ -22,9 +22,9 @@ steps:
|
||||
image: gcr.io/kaniko-project/executor:debug
|
||||
environment:
|
||||
REGISTRY_USER:
|
||||
from_secret: REGISTRY_USERNAME
|
||||
from_secret: gitea_username
|
||||
REGISTRY_PASS:
|
||||
from_secret: REGISTRY_PASSWORD
|
||||
from_secret: gitea_password
|
||||
CI_COMMIT_BRANCH: ${CI_COMMIT_BRANCH}
|
||||
CI_COMMIT_TAG: ${CI_COMMIT_TAG}
|
||||
CI_COMMIT_SHA: ${CI_COMMIT_SHA}
|
||||
|
||||
@@ -270,9 +270,9 @@ steps:
|
||||
when: *image_build_when
|
||||
environment:
|
||||
REGISTRY_USER:
|
||||
from_secret: REGISTRY_USERNAME
|
||||
from_secret: gitea_username
|
||||
REGISTRY_PASS:
|
||||
from_secret: REGISTRY_PASSWORD
|
||||
from_secret: gitea_password
|
||||
CI_COMMIT_BRANCH: ${CI_COMMIT_BRANCH}
|
||||
CI_COMMIT_TAG: ${CI_COMMIT_TAG}
|
||||
CI_COMMIT_SHA: ${CI_COMMIT_SHA}
|
||||
@@ -306,9 +306,9 @@ steps:
|
||||
when: *main_image_build_when
|
||||
environment:
|
||||
REGISTRY_USER:
|
||||
from_secret: REGISTRY_USERNAME
|
||||
from_secret: gitea_username
|
||||
REGISTRY_PASS:
|
||||
from_secret: REGISTRY_PASSWORD
|
||||
from_secret: gitea_password
|
||||
CI_COMMIT_BRANCH: ${CI_COMMIT_BRANCH}
|
||||
CI_COMMIT_TAG: ${CI_COMMIT_TAG}
|
||||
CI_COMMIT_SHA: ${CI_COMMIT_SHA}
|
||||
@@ -333,9 +333,9 @@ steps:
|
||||
when: *main_image_build_when
|
||||
environment:
|
||||
REGISTRY_USER:
|
||||
from_secret: REGISTRY_USERNAME
|
||||
from_secret: gitea_username
|
||||
REGISTRY_PASS:
|
||||
from_secret: REGISTRY_PASSWORD
|
||||
from_secret: gitea_password
|
||||
CI_COMMIT_BRANCH: ${CI_COMMIT_BRANCH}
|
||||
CI_COMMIT_TAG: ${CI_COMMIT_TAG}
|
||||
CI_COMMIT_SHA: ${CI_COMMIT_SHA}
|
||||
|
||||
@@ -190,13 +190,7 @@ beforeEach((ctx) => {
|
||||
});
|
||||
|
||||
afterAll(async () => {
|
||||
// Cleanup only when the fixture actually installed rows. `handle` is set
|
||||
// before the first query (createDb connects lazily), so on an unreachable
|
||||
// database `handle` is truthy while nothing was inserted — cleanup must
|
||||
// honor `dbAvailable` or the skip path fails the file with ECONNREFUSED in
|
||||
// afterAll (caught live by the publish pipeline's no-DATABASE_URL verify
|
||||
// step, pipeline 2486).
|
||||
if (!handle || !dbAvailable) return;
|
||||
if (!handle) return;
|
||||
const db = handle.db;
|
||||
|
||||
// Delete in dependency order (FK constraints)
|
||||
|
||||
@@ -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 ? (
|
||||
|
||||
@@ -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.
|
||||
@@ -34,7 +34,6 @@ export default tseslint.config(
|
||||
'packages/storage/vitest.config.ts',
|
||||
'packages/mosaic/vitest.config.ts',
|
||||
'packages/mosaic/__tests__/*.ts',
|
||||
'packages/forge/__tests__/*.ts',
|
||||
'tools/federation-harness/*.ts',
|
||||
],
|
||||
},
|
||||
|
||||
@@ -539,43 +539,3 @@ Not every brief needs full Board of Directors review. The classification system
|
||||
### Backward compatibility
|
||||
|
||||
Existing briefs without a `class` field are auto-classified. The default (no matching keywords) is `strategic`, so all existing runs get the full pipeline unless keywords trigger `technical`.
|
||||
|
||||
---
|
||||
|
||||
## Fail-Closed Execution & Explicit Simulation (SDLC-D-035)
|
||||
|
||||
**Added:** 2026-08-17
|
||||
|
||||
Forge fails closed when a required capability is missing. It never runs a
|
||||
pipeline with a stub executor and reports success.
|
||||
|
||||
### Normal mode (default)
|
||||
|
||||
- No task executor wired → the CLI exits nonzero with the typed capability
|
||||
error `FORGE_NO_EXECUTOR`. No run is created.
|
||||
- A stage whose gate is approval-based (board approval, planning approvals,
|
||||
remediation re-review, discovery/analysis attestations) records a typed
|
||||
`waiting-for-authority` stage result and raises `FORGE_AUTHORITY_REQUIRED`.
|
||||
It never passes vacuously.
|
||||
- A stage whose gate requires an unwired provider (AI reviewer, CI pipeline)
|
||||
records a typed `blocked` stage result and raises `FORGE_NO_REVIEWER` /
|
||||
`FORGE_NO_CI_PIPELINE`. The synthetic echo-review approval in `06-review`
|
||||
and all vacuous `true` gates were removed.
|
||||
|
||||
### Explicit simulation (`--simulate`)
|
||||
|
||||
Opts into stub/synthetic execution. Every stage result, every gate result, and
|
||||
the run manifest carry the distinct typed status `simulated` (manifest also
|
||||
records `mode: "simulated"`). `simulated` is a non-satisfying outcome:
|
||||
`isSatisfyingOutcome()` and all completion/gate consumers treat only `passed`
|
||||
as satisfying. The CLI exits 0 for a simulated run only because the caller
|
||||
explicitly passed `--simulate`, and prints a loud SIMULATED banner.
|
||||
|
||||
### Typed outcome model
|
||||
|
||||
Every gate/task outcome is one of the closed set
|
||||
`passed | failed | blocked | error | waiting-for-authority | simulated |
|
||||
not-applicable`, with the reason recorded on the stage status and each gate
|
||||
result in `manifest.json`. Missing implementations, missing gate evidence,
|
||||
unknown stages, process errors, and timeouts map to fail-closed members —
|
||||
never to `passed`.
|
||||
|
||||
@@ -1,319 +0,0 @@
|
||||
import fs from 'node:fs';
|
||||
import os from 'node:os';
|
||||
import path from 'node:path';
|
||||
import { describe, it, expect, beforeEach, afterEach } from 'vitest';
|
||||
|
||||
import { generateBoardTasks } from '../src/board-tasks.js';
|
||||
import { STAGE_SPECS } from '../src/constants.js';
|
||||
import { ForgeCapabilityError } from '../src/errors.js';
|
||||
import {
|
||||
evaluateStageGates,
|
||||
gateLabel,
|
||||
isCommandGate,
|
||||
isSatisfyingOutcome,
|
||||
} from '../src/outcomes.js';
|
||||
import { loadManifest, runPipeline } from '../src/pipeline-runner.js';
|
||||
import type { ForgeTask, ForgeTaskResult, TaskExecutor } from '../src/types.js';
|
||||
|
||||
/**
|
||||
* Mock real executor that returns typed results.
|
||||
*
|
||||
* Command gates are "verified" by the mock so normal-mode runs can pass
|
||||
* mechanically gated stages; authority/provider gates are never reported
|
||||
* because they have no mechanical implementation.
|
||||
*/
|
||||
function createTypedExecutor(options?: {
|
||||
failStage?: string;
|
||||
gateOutcomes?: Record<string, 'passed' | 'failed' | 'simulated' | 'error' | 'blocked'>;
|
||||
}): TaskExecutor & { submittedTasks: ForgeTask[] } {
|
||||
const submittedTasks: ForgeTask[] = [];
|
||||
return {
|
||||
submittedTasks,
|
||||
async submitTask(task: ForgeTask) {
|
||||
submittedTasks.push(task);
|
||||
},
|
||||
async waitForCompletion(taskId: string): Promise<ForgeTaskResult> {
|
||||
const task = submittedTasks.find((t) => t.id === taskId);
|
||||
const stageName = task?.metadata?.['stageName'] as string | undefined;
|
||||
|
||||
if (options?.failStage && stageName === options.failStage) {
|
||||
return {
|
||||
task_id: taskId,
|
||||
outcome: 'failed',
|
||||
reason: 'mock task failure',
|
||||
completed_at: new Date().toISOString(),
|
||||
exit_code: 1,
|
||||
gate_results: [],
|
||||
};
|
||||
}
|
||||
|
||||
const gateResults = (task?.qualityGates ?? [])
|
||||
.filter((gate) => isCommandGate(gate))
|
||||
.map((gate) => {
|
||||
const label = gateLabel(gate);
|
||||
const outcome = options?.gateOutcomes?.[label] ?? 'passed';
|
||||
return {
|
||||
gate: label,
|
||||
outcome,
|
||||
reason: outcome === 'passed' ? 'mock verified' : `mock gate outcome: ${outcome}`,
|
||||
};
|
||||
});
|
||||
|
||||
return {
|
||||
task_id: taskId,
|
||||
outcome: 'passed',
|
||||
reason: 'mock verified',
|
||||
completed_at: new Date().toISOString(),
|
||||
exit_code: 0,
|
||||
gate_results: gateResults,
|
||||
};
|
||||
},
|
||||
async getTaskStatus() {
|
||||
return 'completed' as const;
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
describe('fail-closed: no executor wired', () => {
|
||||
let tmpDir: string;
|
||||
let briefPath: string;
|
||||
|
||||
beforeEach(() => {
|
||||
tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'forge-failclosed-'));
|
||||
briefPath = path.join(tmpDir, 'brief.md');
|
||||
fs.writeFileSync(briefPath, '# Fix bug\n\nA bugfix for lint cleanup.');
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
fs.rmSync(tmpDir, { recursive: true, force: true });
|
||||
});
|
||||
|
||||
it('throws a typed FORGE_NO_EXECUTOR capability error without --simulate', async () => {
|
||||
await expect(
|
||||
runPipeline(briefPath, tmpDir, {
|
||||
// no executor, no simulate — must fail closed, never run with a stub
|
||||
stages: ['00-intake'],
|
||||
}),
|
||||
).rejects.toMatchObject({
|
||||
name: 'ForgeCapabilityError',
|
||||
code: 'FORGE_NO_EXECUTOR',
|
||||
capability: 'task-executor',
|
||||
});
|
||||
});
|
||||
|
||||
it('does not create a run directory when failing closed on a missing executor', async () => {
|
||||
try {
|
||||
await runPipeline(briefPath, tmpDir, { stages: ['00-intake'] });
|
||||
} catch {
|
||||
// expected
|
||||
}
|
||||
expect(fs.existsSync(path.join(tmpDir, '.forge', 'runs'))).toBe(false);
|
||||
});
|
||||
|
||||
it('completes with every result typed simulated when simulate is set', async () => {
|
||||
const result = await runPipeline(briefPath, tmpDir, {
|
||||
simulate: true,
|
||||
stages: ['00-intake', '00b-discovery', '02-planning-1', '06-review'],
|
||||
});
|
||||
|
||||
expect(result.manifest.mode).toBe('simulated');
|
||||
expect(result.manifest.status).toBe('simulated');
|
||||
|
||||
for (const stage of result.stages) {
|
||||
const stageStatus = result.manifest.stages[stage];
|
||||
expect(stageStatus?.status, `stage ${stage}`).toBe('simulated');
|
||||
expect(stageStatus?.status, `stage ${stage}`).not.toBe('passed');
|
||||
expect(stageStatus?.reason, `stage ${stage}`).toBeTruthy();
|
||||
for (const gateResult of stageStatus?.gateResults ?? []) {
|
||||
expect(gateResult.outcome, `gate ${gateResult.gate} of ${stage}`).toBe('simulated');
|
||||
expect(gateResult.outcome, `gate ${gateResult.gate} of ${stage}`).not.toBe('passed');
|
||||
}
|
||||
}
|
||||
|
||||
// The persisted manifest agrees.
|
||||
const persisted = loadManifest(result.runDir);
|
||||
expect(persisted.mode).toBe('simulated');
|
||||
expect(persisted.status).toBe('simulated');
|
||||
expect(persisted.stages['02-planning-1']?.status).toBe('simulated');
|
||||
});
|
||||
});
|
||||
|
||||
describe('fail-closed: typed outcome model', () => {
|
||||
it('only passed satisfies the gate/dependency predicate', () => {
|
||||
expect(isSatisfyingOutcome('passed')).toBe(true);
|
||||
expect(isSatisfyingOutcome('failed')).toBe(false);
|
||||
expect(isSatisfyingOutcome('blocked')).toBe(false);
|
||||
expect(isSatisfyingOutcome('error')).toBe(false);
|
||||
expect(isSatisfyingOutcome('waiting-for-authority')).toBe(false);
|
||||
expect(isSatisfyingOutcome('simulated')).toBe(false);
|
||||
expect(isSatisfyingOutcome('not-applicable')).toBe(false);
|
||||
});
|
||||
|
||||
it('a simulated gate result cannot satisfy the stage gate evaluation', () => {
|
||||
const evaluation = evaluateStageGates('05-coding', STAGE_SPECS['05-coding']!.qualityGates, {
|
||||
task_id: 'FORGE-x-05',
|
||||
outcome: 'passed',
|
||||
reason: 'executor claims success',
|
||||
completed_at: new Date().toISOString(),
|
||||
exit_code: 0,
|
||||
gate_results: [{ gate: 'pnpm lint', outcome: 'simulated', reason: 'simulated gate' }],
|
||||
});
|
||||
expect(isSatisfyingOutcome(evaluation.outcome)).toBe(false);
|
||||
expect(evaluation.outcome).toBe('error');
|
||||
});
|
||||
|
||||
it('a simulated task outcome cannot satisfy evaluation in normal mode', () => {
|
||||
const evaluation = evaluateStageGates('00-intake', [], {
|
||||
task_id: 'FORGE-x-00',
|
||||
outcome: 'simulated',
|
||||
reason: 'executor reported simulated',
|
||||
completed_at: new Date().toISOString(),
|
||||
exit_code: 0,
|
||||
gate_results: [],
|
||||
});
|
||||
expect(isSatisfyingOutcome(evaluation.outcome)).toBe(false);
|
||||
});
|
||||
|
||||
it('a missing gate result blocks the stage instead of passing vacuously', () => {
|
||||
const evaluation = evaluateStageGates('05-coding', STAGE_SPECS['05-coding']!.qualityGates, {
|
||||
task_id: 'FORGE-x-05',
|
||||
outcome: 'passed',
|
||||
reason: 'executor claims success',
|
||||
completed_at: new Date().toISOString(),
|
||||
exit_code: 0,
|
||||
gate_results: [],
|
||||
});
|
||||
expect(evaluation.outcome).toBe('blocked');
|
||||
});
|
||||
});
|
||||
|
||||
describe('fail-closed: authority and provider gates', () => {
|
||||
let tmpDir: string;
|
||||
let briefPath: string;
|
||||
|
||||
beforeEach(() => {
|
||||
tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'forge-authority-'));
|
||||
briefPath = path.join(tmpDir, 'brief.md');
|
||||
fs.writeFileSync(briefPath, '# Fix bug\n\nA bugfix for lint cleanup.');
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
fs.rmSync(tmpDir, { recursive: true, force: true });
|
||||
});
|
||||
|
||||
it.each(['02-planning-1', '03-planning-2', '04-planning-3', '07-remediate'])(
|
||||
'planning/remediation stage %s yields waiting-for-authority (not passed) in normal mode',
|
||||
async (stage) => {
|
||||
const executor = createTypedExecutor();
|
||||
let runDir: string | undefined;
|
||||
|
||||
try {
|
||||
await runPipeline(briefPath, tmpDir, {
|
||||
executor,
|
||||
stages: [stage as string],
|
||||
});
|
||||
expect.unreachable('runPipeline should have failed closed');
|
||||
} catch (err) {
|
||||
expect(err).toBeInstanceOf(ForgeCapabilityError);
|
||||
expect((err as ForgeCapabilityError).code).toBe('FORGE_AUTHORITY_REQUIRED');
|
||||
runDir = path.join(tmpDir, '.forge', 'runs');
|
||||
}
|
||||
|
||||
const runIds = fs.readdirSync(runDir!);
|
||||
expect(runIds).toHaveLength(1);
|
||||
const manifest = loadManifest(path.join(runDir!, runIds[0]!));
|
||||
expect(manifest.stages[stage]?.status).toBe('waiting-for-authority');
|
||||
expect(manifest.stages[stage]?.status).not.toBe('passed');
|
||||
expect(manifest.status).toBe('waiting-for-authority');
|
||||
},
|
||||
);
|
||||
|
||||
it('review stage fails closed with a typed FORGE_NO_REVIEWER error in normal mode', async () => {
|
||||
const executor = createTypedExecutor();
|
||||
|
||||
try {
|
||||
await runPipeline(briefPath, tmpDir, {
|
||||
executor,
|
||||
stages: ['06-review'],
|
||||
});
|
||||
expect.unreachable('runPipeline should have failed closed');
|
||||
} catch (err) {
|
||||
expect(err).toBeInstanceOf(ForgeCapabilityError);
|
||||
expect((err as ForgeCapabilityError).code).toBe('FORGE_NO_REVIEWER');
|
||||
expect((err as ForgeCapabilityError).capability).toBe('reviewer');
|
||||
}
|
||||
|
||||
const runsDir = path.join(tmpDir, '.forge', 'runs');
|
||||
const runIds = fs.readdirSync(runsDir);
|
||||
const manifest = loadManifest(path.join(runsDir, runIds[0]!));
|
||||
expect(manifest.stages['06-review']?.status).toBe('blocked');
|
||||
expect(manifest.stages['06-review']?.status).not.toBe('passed');
|
||||
expect(manifest.status).toBe('failed');
|
||||
});
|
||||
|
||||
it('review stage produces simulated results under --simulate', async () => {
|
||||
const result = await runPipeline(briefPath, tmpDir, {
|
||||
simulate: true,
|
||||
stages: ['06-review'],
|
||||
});
|
||||
|
||||
expect(result.manifest.mode).toBe('simulated');
|
||||
expect(result.manifest.stages['06-review']?.status).toBe('simulated');
|
||||
for (const gateResult of result.manifest.stages['06-review']?.gateResults ?? []) {
|
||||
expect(gateResult.outcome).toBe('simulated');
|
||||
}
|
||||
});
|
||||
|
||||
it('deploy stage fails closed without a wired ci-pipeline provider in normal mode', async () => {
|
||||
const executor = createTypedExecutor();
|
||||
|
||||
await expect(
|
||||
runPipeline(briefPath, tmpDir, {
|
||||
executor,
|
||||
stages: ['09-deploy'],
|
||||
}),
|
||||
).rejects.toMatchObject({
|
||||
name: 'ForgeCapabilityError',
|
||||
code: 'FORGE_NO_CI_PIPELINE',
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe('fail-closed: no vacuous gate commands remain', () => {
|
||||
it('stage constants contain no echo/synthetic-approval, vacuous true, or empty gate commands', () => {
|
||||
for (const [stageName, spec] of Object.entries(STAGE_SPECS)) {
|
||||
for (const gate of spec.qualityGates) {
|
||||
const serialized = JSON.stringify(gate);
|
||||
// The echo-review synthetic approval must be gone.
|
||||
expect(serialized, `stage ${stageName} gate ${serialized}`).not.toContain('echo');
|
||||
expect(serialized, `stage ${stageName} gate ${serialized}`).not.toMatch(/"verdict"\s*:/);
|
||||
expect(serialized, `stage ${stageName} gate ${serialized}`).not.toMatch(
|
||||
/"summary"\s*:\s*"review-pass"/,
|
||||
);
|
||||
// No vacuous literal `true` gate.
|
||||
expect(gate, `stage ${stageName}`).not.toBe('true');
|
||||
// Command gates must carry a real, non-empty command.
|
||||
if (isCommandGate(gate)) {
|
||||
const command = typeof gate === 'string' ? gate : gate.command;
|
||||
expect(command.trim().length, `stage ${stageName} gate ${serialized}`).toBeGreaterThan(0);
|
||||
}
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
it('board tasks contain no vacuous true gates', () => {
|
||||
const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'forge-board-gates-'));
|
||||
try {
|
||||
const tasks = generateBoardTasks('# Brief', [], tmpDir, 'BOARD-TEST');
|
||||
for (const task of tasks) {
|
||||
for (const gate of task.qualityGates) {
|
||||
expect(gate, `task ${task.id}`).not.toBe('true');
|
||||
const serialized = JSON.stringify(gate);
|
||||
expect(serialized, `task ${task.id} gate ${serialized}`).not.toContain('echo');
|
||||
}
|
||||
}
|
||||
} finally {
|
||||
fs.rmSync(tmpDir, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
});
|
||||
@@ -12,10 +12,10 @@ import {
|
||||
resumePipeline,
|
||||
getPipelineStatus,
|
||||
} from '../src/pipeline-runner.js';
|
||||
import type { ForgeTask, ForgeTaskResult, RunManifest, TaskExecutor } from '../src/types.js';
|
||||
import { gateLabel, isCommandGate } from '../src/outcomes.js';
|
||||
import type { ForgeTask, RunManifest, TaskExecutor } from '../src/types.js';
|
||||
import type { TaskResult } from '@mosaicstack/macp';
|
||||
|
||||
/** Mock TaskExecutor that records submitted tasks and returns typed results. */
|
||||
/** Mock TaskExecutor that records submitted tasks and returns success. */
|
||||
function createMockExecutor(options?: {
|
||||
failStage?: string;
|
||||
}): TaskExecutor & { submittedTasks: ForgeTask[] } {
|
||||
@@ -25,7 +25,7 @@ function createMockExecutor(options?: {
|
||||
async submitTask(task: ForgeTask) {
|
||||
submittedTasks.push(task);
|
||||
},
|
||||
async waitForCompletion(taskId: string): Promise<ForgeTaskResult> {
|
||||
async waitForCompletion(taskId: string): Promise<TaskResult> {
|
||||
const failStage = options?.failStage;
|
||||
const task = submittedTasks.find((t) => t.id === taskId);
|
||||
const stageName = task?.metadata?.['stageName'] as string | undefined;
|
||||
@@ -33,8 +33,7 @@ function createMockExecutor(options?: {
|
||||
if (failStage && stageName === failStage) {
|
||||
return {
|
||||
task_id: taskId,
|
||||
outcome: 'failed',
|
||||
reason: 'mock task failure',
|
||||
status: 'failed',
|
||||
completed_at: new Date().toISOString(),
|
||||
exit_code: 1,
|
||||
gate_results: [],
|
||||
@@ -42,17 +41,10 @@ function createMockExecutor(options?: {
|
||||
}
|
||||
return {
|
||||
task_id: taskId,
|
||||
outcome: 'passed',
|
||||
reason: 'mock verified',
|
||||
status: 'completed',
|
||||
completed_at: new Date().toISOString(),
|
||||
exit_code: 0,
|
||||
gate_results: (task?.qualityGates ?? [])
|
||||
.filter((gate) => isCommandGate(gate))
|
||||
.map((gate) => ({
|
||||
gate: gateLabel(gate),
|
||||
outcome: 'passed' as const,
|
||||
reason: 'mock verified',
|
||||
})),
|
||||
gate_results: [],
|
||||
};
|
||||
},
|
||||
async getTaskStatus() {
|
||||
@@ -164,13 +156,12 @@ describe('runPipeline', () => {
|
||||
const executor = createMockExecutor();
|
||||
const result = await runPipeline(briefPath, tmpDir, {
|
||||
executor,
|
||||
stages: ['00-intake', '05-coding'],
|
||||
stages: ['00-intake', '00b-discovery'],
|
||||
});
|
||||
|
||||
expect(result.runId).toMatch(/^\d{8}-\d{6}$/);
|
||||
expect(result.stages).toEqual(['00-intake', '05-coding']);
|
||||
expect(result.stages).toEqual(['00-intake', '00b-discovery']);
|
||||
expect(result.manifest.status).toBe('completed');
|
||||
expect(result.manifest.mode).toBe('normal');
|
||||
expect(executor.submittedTasks).toHaveLength(2);
|
||||
});
|
||||
|
||||
@@ -189,17 +180,12 @@ describe('runPipeline', () => {
|
||||
const executor = createMockExecutor();
|
||||
const result = await runPipeline(briefPath, tmpDir, {
|
||||
executor,
|
||||
stages: ['00-intake', '05-coding'],
|
||||
stages: ['00-intake', '00b-discovery'],
|
||||
});
|
||||
|
||||
const manifest = loadManifest(result.runDir);
|
||||
expect(manifest.stages['00-intake']?.status).toBe('passed');
|
||||
expect(manifest.stages['05-coding']?.status).toBe('passed');
|
||||
expect(manifest.stages['05-coding']?.gateResults?.map((g) => g.outcome)).toEqual([
|
||||
'passed',
|
||||
'passed',
|
||||
'passed',
|
||||
]);
|
||||
expect(manifest.stages['00b-discovery']?.status).toBe('passed');
|
||||
});
|
||||
|
||||
it('respects CLI class override', async () => {
|
||||
@@ -229,7 +215,7 @@ describe('runPipeline', () => {
|
||||
const executor = createMockExecutor();
|
||||
await runPipeline(briefPath, tmpDir, {
|
||||
executor,
|
||||
stages: ['00-intake', '05-coding', '08-test'],
|
||||
stages: ['00-intake', '00b-discovery', '02-planning-1'],
|
||||
});
|
||||
|
||||
expect(executor.submittedTasks[0]!.dependsOn).toBeUndefined();
|
||||
@@ -238,14 +224,14 @@ describe('runPipeline', () => {
|
||||
});
|
||||
|
||||
it('handles stage failure', async () => {
|
||||
const executor = createMockExecutor({ failStage: '05-coding' });
|
||||
const executor = createMockExecutor({ failStage: '00b-discovery' });
|
||||
|
||||
await expect(
|
||||
runPipeline(briefPath, tmpDir, {
|
||||
executor,
|
||||
stages: ['00-intake', '05-coding'],
|
||||
stages: ['00-intake', '00b-discovery'],
|
||||
}),
|
||||
).rejects.toThrow('Stage 05-coding failed');
|
||||
).rejects.toThrow('Stage 00b-discovery failed');
|
||||
});
|
||||
|
||||
it('marks manifest as failed on stage failure', async () => {
|
||||
@@ -284,143 +270,30 @@ describe('resumePipeline', () => {
|
||||
fs.rmSync(tmpDir, { recursive: true, force: true });
|
||||
});
|
||||
|
||||
it('resumes from first incomplete stage and fails closed at the next provider gate', async () => {
|
||||
// Simulate a run whose authority stages were approved out-of-band
|
||||
// (recorded as passed) and whose coding stage failed mechanically.
|
||||
const runId = '20260101-000000';
|
||||
const runDir = path.join(tmpDir, '.forge', 'runs', runId);
|
||||
fs.mkdirSync(runDir, { recursive: true });
|
||||
const passed = { status: 'passed' as const, startedAt: '2026-01-01T00:00:00Z' };
|
||||
saveManifest(runDir, {
|
||||
runId,
|
||||
brief: briefPath,
|
||||
codebase: tmpDir,
|
||||
briefClass: 'hotfix',
|
||||
classSource: 'frontmatter',
|
||||
forceBoard: false,
|
||||
mode: 'normal',
|
||||
createdAt: '2026-01-01T00:00:00Z',
|
||||
updatedAt: '2026-01-01T00:00:00Z',
|
||||
currentStage: '05-coding',
|
||||
status: 'failed',
|
||||
stages: {
|
||||
'00-intake': passed,
|
||||
'00b-discovery': passed,
|
||||
'02-planning-1': passed,
|
||||
'03-planning-2': passed,
|
||||
'04-planning-3': passed,
|
||||
'05-coding': { status: 'failed', reason: 'gate failed' },
|
||||
},
|
||||
});
|
||||
it('resumes from first incomplete stage', async () => {
|
||||
// First run fails on discovery
|
||||
const executor1 = createMockExecutor({ failStage: '00b-discovery' });
|
||||
let runDir: string;
|
||||
|
||||
// Resume re-runs 05-coding (the first non-passed stage), then fails
|
||||
// closed at 06-review because no reviewer provider is wired.
|
||||
const executor = createMockExecutor();
|
||||
await expect(resumePipeline(runDir, executor)).rejects.toMatchObject({
|
||||
name: 'ForgeCapabilityError',
|
||||
code: 'FORGE_NO_REVIEWER',
|
||||
});
|
||||
|
||||
const manifest = loadManifest(runDir);
|
||||
expect(manifest.stages['05-coding']?.status).toBe('passed');
|
||||
expect(manifest.stages['06-review']?.status).toBe('blocked');
|
||||
expect(manifest.status).toBe('failed');
|
||||
});
|
||||
|
||||
it('resumes to completion as simulated under explicit simulate', async () => {
|
||||
const runId = '20260101-000003';
|
||||
const runDir = path.join(tmpDir, '.forge', 'runs', runId);
|
||||
fs.mkdirSync(runDir, { recursive: true });
|
||||
const passed = { status: 'passed' as const, startedAt: '2026-01-01T00:00:00Z' };
|
||||
saveManifest(runDir, {
|
||||
runId,
|
||||
brief: briefPath,
|
||||
codebase: tmpDir,
|
||||
briefClass: 'hotfix',
|
||||
classSource: 'frontmatter',
|
||||
forceBoard: false,
|
||||
mode: 'normal',
|
||||
createdAt: '2026-01-01T00:00:00Z',
|
||||
updatedAt: '2026-01-01T00:00:00Z',
|
||||
currentStage: '05-coding',
|
||||
status: 'failed',
|
||||
stages: {
|
||||
'00-intake': passed,
|
||||
'00b-discovery': passed,
|
||||
'02-planning-1': passed,
|
||||
'03-planning-2': passed,
|
||||
'04-planning-3': passed,
|
||||
'05-coding': { status: 'failed', reason: 'gate failed' },
|
||||
},
|
||||
});
|
||||
|
||||
const result = await resumePipeline(runDir, undefined, { simulate: true });
|
||||
|
||||
expect(result.manifest.status).toBe('simulated');
|
||||
expect(result.manifest.mode).toBe('simulated');
|
||||
expect(result.stages[0]).toBe('05-coding');
|
||||
for (const stage of result.stages) {
|
||||
expect(result.manifest.stages[stage]?.status).toBe('simulated');
|
||||
try {
|
||||
await runPipeline(briefPath, tmpDir, {
|
||||
executor: executor1,
|
||||
stages: ['00-intake', '00b-discovery', '02-planning-1'],
|
||||
});
|
||||
} catch {
|
||||
// expected
|
||||
}
|
||||
});
|
||||
|
||||
it('fails closed on resume when the next stage needs authority sign-off', async () => {
|
||||
const runId = '20260101-000001';
|
||||
const runDir = path.join(tmpDir, '.forge', 'runs', runId);
|
||||
fs.mkdirSync(runDir, { recursive: true });
|
||||
saveManifest(runDir, {
|
||||
runId,
|
||||
brief: briefPath,
|
||||
codebase: tmpDir,
|
||||
briefClass: 'hotfix',
|
||||
classSource: 'frontmatter',
|
||||
forceBoard: false,
|
||||
mode: 'normal',
|
||||
createdAt: '2026-01-01T00:00:00Z',
|
||||
updatedAt: '2026-01-01T00:00:00Z',
|
||||
currentStage: '00-intake',
|
||||
status: 'in_progress',
|
||||
stages: {
|
||||
'00-intake': { status: 'passed' },
|
||||
},
|
||||
});
|
||||
const runsDir = path.join(tmpDir, '.forge', 'runs');
|
||||
runDir = path.join(runsDir, fs.readdirSync(runsDir)[0]!);
|
||||
|
||||
const executor = createMockExecutor();
|
||||
await expect(resumePipeline(runDir, executor)).rejects.toMatchObject({
|
||||
name: 'ForgeCapabilityError',
|
||||
code: 'FORGE_AUTHORITY_REQUIRED',
|
||||
});
|
||||
// Resume should pick up from 00b-discovery
|
||||
const executor2 = createMockExecutor();
|
||||
const result = await resumePipeline(runDir, executor2);
|
||||
|
||||
const manifest = loadManifest(runDir);
|
||||
expect(manifest.stages['00b-discovery']?.status).toBe('waiting-for-authority');
|
||||
expect(manifest.status).toBe('waiting-for-authority');
|
||||
});
|
||||
|
||||
it('fails closed on resume without an executor or --simulate', async () => {
|
||||
const runId = '20260101-000002';
|
||||
const runDir = path.join(tmpDir, '.forge', 'runs', runId);
|
||||
fs.mkdirSync(runDir, { recursive: true });
|
||||
saveManifest(runDir, {
|
||||
runId,
|
||||
brief: briefPath,
|
||||
codebase: tmpDir,
|
||||
briefClass: 'hotfix',
|
||||
classSource: 'frontmatter',
|
||||
forceBoard: false,
|
||||
mode: 'normal',
|
||||
createdAt: '2026-01-01T00:00:00Z',
|
||||
updatedAt: '2026-01-01T00:00:00Z',
|
||||
currentStage: '00-intake',
|
||||
status: 'in_progress',
|
||||
stages: {
|
||||
'00-intake': { status: 'passed' },
|
||||
},
|
||||
});
|
||||
|
||||
await expect(resumePipeline(runDir)).rejects.toMatchObject({
|
||||
name: 'ForgeCapabilityError',
|
||||
code: 'FORGE_NO_EXECUTOR',
|
||||
});
|
||||
expect(result.manifest.status).toBe('completed');
|
||||
// Should have re-run from 00b-discovery onward
|
||||
expect(result.stages[0]).toBe('00b-discovery');
|
||||
});
|
||||
});
|
||||
|
||||
|
||||
@@ -95,14 +95,7 @@ export function generateBoardTasks(
|
||||
briefPath,
|
||||
resultPath: resultRelPath,
|
||||
timeoutSeconds: 120,
|
||||
qualityGates: [
|
||||
{
|
||||
kind: 'authority',
|
||||
capability: 'board-approval',
|
||||
reason:
|
||||
'persona evaluation is judged by board synthesis (authority review); no mechanical gate exists',
|
||||
},
|
||||
],
|
||||
qualityGates: ['true'],
|
||||
metadata: {
|
||||
personaName: persona.name,
|
||||
personaSlug: persona.slug,
|
||||
@@ -128,13 +121,7 @@ export function generateBoardTasks(
|
||||
timeoutSeconds: 120,
|
||||
dependsOn: personaTaskIds,
|
||||
dependsOnPolicy: 'all_terminal',
|
||||
qualityGates: [
|
||||
{
|
||||
kind: 'authority',
|
||||
capability: 'board-approval',
|
||||
reason: 'board synthesis is an authority decision; no mechanical gate exists',
|
||||
},
|
||||
],
|
||||
qualityGates: ['true'],
|
||||
metadata: {
|
||||
resultOutputPath: synthesisResult,
|
||||
inputResultPaths: personaResultPaths,
|
||||
|
||||
@@ -1,11 +1,7 @@
|
||||
import fs from 'node:fs';
|
||||
import os from 'node:os';
|
||||
import path from 'node:path';
|
||||
import { Command } from 'commander';
|
||||
import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
|
||||
import { describe, expect, it } from 'vitest';
|
||||
|
||||
import { registerForgeCommand } from './cli.js';
|
||||
import { loadManifest } from './pipeline-runner.js';
|
||||
|
||||
describe('registerForgeCommand', () => {
|
||||
it('registers a "forge" command on the parent program', () => {
|
||||
@@ -59,94 +55,3 @@ describe('registerForgeCommand', () => {
|
||||
}).not.toThrow();
|
||||
});
|
||||
});
|
||||
|
||||
describe('forge run fail-closed behavior (SDLC-D-035)', () => {
|
||||
let tmpDir: string;
|
||||
let briefPath: string;
|
||||
let errSpy: ReturnType<typeof vi.spyOn>;
|
||||
let logSpy: ReturnType<typeof vi.spyOn>;
|
||||
let prevExitCode: string | number | null | undefined;
|
||||
|
||||
const parse = (args: string[]) => {
|
||||
const program = new Command();
|
||||
registerForgeCommand(program);
|
||||
return program.parseAsync(['forge', ...args], { from: 'user' });
|
||||
};
|
||||
|
||||
beforeEach(() => {
|
||||
tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'forge-cli-failclosed-'));
|
||||
briefPath = path.join(tmpDir, 'brief.md');
|
||||
fs.writeFileSync(briefPath, '# Fix bug\n\nA bugfix for lint cleanup.');
|
||||
errSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
|
||||
logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
|
||||
prevExitCode = process.exitCode;
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
errSpy.mockRestore();
|
||||
logSpy.mockRestore();
|
||||
process.exitCode = prevExitCode;
|
||||
fs.rmSync(tmpDir, { recursive: true, force: true });
|
||||
});
|
||||
|
||||
it('exits nonzero with a typed FORGE_NO_EXECUTOR error when no executor is wired and --simulate is absent', async () => {
|
||||
await parse(['run', '--brief', briefPath, '--codebase', tmpDir]);
|
||||
|
||||
expect(process.exitCode).toBe(1);
|
||||
const errText = errSpy.mock.calls.map((c) => c.join(' ')).join('\n');
|
||||
expect(errText).toContain('FORGE_NO_EXECUTOR');
|
||||
// It must never run the pipeline with a stub and report success.
|
||||
expect(fs.existsSync(path.join(tmpDir, '.forge', 'runs'))).toBe(false);
|
||||
});
|
||||
|
||||
it('completes with typed simulated results and exit 0 under explicit --simulate', async () => {
|
||||
await parse(['run', '--brief', briefPath, '--codebase', tmpDir, '--simulate']);
|
||||
|
||||
expect(process.exitCode).toBeUndefined();
|
||||
|
||||
// Loud simulated-mode summary.
|
||||
const logText = logSpy.mock.calls.map((c) => c.join(' ')).join('\n');
|
||||
expect(logText).toContain('SIMULATED');
|
||||
|
||||
// Manifest records the mode and simulated per-result statuses.
|
||||
const runsDir = path.join(tmpDir, '.forge', 'runs');
|
||||
const runIds = fs.readdirSync(runsDir);
|
||||
expect(runIds).toHaveLength(1);
|
||||
const manifest = loadManifest(path.join(runsDir, runIds[0]!));
|
||||
expect(manifest.mode).toBe('simulated');
|
||||
expect(manifest.status).toBe('simulated');
|
||||
for (const stageStatus of Object.values(manifest.stages)) {
|
||||
expect(stageStatus?.status).toBe('simulated');
|
||||
for (const gateResult of stageStatus?.gateResults ?? []) {
|
||||
expect(gateResult.outcome).toBe('simulated');
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
it('resume exits nonzero with a typed FORGE_NO_EXECUTOR error without --simulate', async () => {
|
||||
const runDir = path.join(tmpDir, '.forge', 'runs', '20260101-000000');
|
||||
fs.mkdirSync(runDir, { recursive: true });
|
||||
fs.writeFileSync(
|
||||
path.join(runDir, 'manifest.json'),
|
||||
JSON.stringify({
|
||||
runId: '20260101-000000',
|
||||
brief: briefPath,
|
||||
codebase: tmpDir,
|
||||
briefClass: 'hotfix',
|
||||
classSource: 'frontmatter',
|
||||
forceBoard: false,
|
||||
createdAt: '2026-01-01T00:00:00Z',
|
||||
updatedAt: '2026-01-01T00:00:00Z',
|
||||
currentStage: '00-intake',
|
||||
status: 'in_progress',
|
||||
stages: { '00-intake': { status: 'passed' } },
|
||||
}),
|
||||
);
|
||||
|
||||
await parse(['resume', '20260101-000000', '--project', tmpDir]);
|
||||
|
||||
expect(process.exitCode).toBe(1);
|
||||
const errText = errSpy.mock.calls.map((c) => c.join(' ')).join('\n');
|
||||
expect(errText).toContain('FORGE_NO_EXECUTOR');
|
||||
});
|
||||
});
|
||||
|
||||
+48
-122
@@ -5,47 +5,37 @@ import type { Command } from 'commander';
|
||||
|
||||
import { classifyBrief } from './brief-classifier.js';
|
||||
import { STAGE_LABELS, STAGE_SEQUENCE } from './constants.js';
|
||||
import { ForgeCapabilityError } from './errors.js';
|
||||
import { getEffectivePersonas, loadBoardPersonas } from './persona-loader.js';
|
||||
import { generateRunId, getPipelineStatus, loadManifest, runPipeline } from './pipeline-runner.js';
|
||||
import { createSimulatedExecutor } from './simulated-executor.js';
|
||||
import type { PipelineOptions, RunManifest, RunMode } from './types.js';
|
||||
import type { PipelineOptions, RunManifest, TaskExecutor } from './types.js';
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Stub executor — used when no real executor is wired at CLI invocation time.
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
const stubExecutor: TaskExecutor = {
|
||||
async submitTask(task) {
|
||||
console.log(` [forge] stage submitted: ${task.id} (${task.title})`);
|
||||
},
|
||||
async waitForCompletion(taskId, _timeoutMs) {
|
||||
console.log(` [forge] stage complete: ${taskId}`);
|
||||
return {
|
||||
task_id: taskId,
|
||||
status: 'completed' as const,
|
||||
completed_at: new Date().toISOString(),
|
||||
exit_code: 0,
|
||||
gate_results: [],
|
||||
};
|
||||
},
|
||||
async getTaskStatus(_taskId) {
|
||||
return 'completed' as const;
|
||||
},
|
||||
};
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Helpers
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/** Resolve a run's effective mode, defaulting legacy manifests to normal. */
|
||||
function runModeOf(manifest: RunManifest): RunMode {
|
||||
return manifest.mode ?? 'normal';
|
||||
}
|
||||
|
||||
/** Print a loud banner so a simulated run can never be misread as verified. */
|
||||
function printSimulatedBanner(): void {
|
||||
console.log('');
|
||||
console.log('[forge] ===============================================================');
|
||||
console.log('[forge] MODE: SIMULATED — no stage or gate was really executed.');
|
||||
console.log('[forge] All results are synthetic and MUST NOT be read as verified');
|
||||
console.log('[forge] success. Wire a real executor/providers and re-run to verify.');
|
||||
console.log('[forge] ===============================================================');
|
||||
}
|
||||
|
||||
/** Print a typed error line for fail-closed capability errors. */
|
||||
function printCapabilityError(err: ForgeCapabilityError): void {
|
||||
console.error(`[forge] error ${err.code}: ${err.message}`);
|
||||
console.error(`[forge] missing capability: ${err.capability}`);
|
||||
}
|
||||
|
||||
/** Handle a pipeline error uniformly: typed capability errors get their code. */
|
||||
function handlePipelineError(err: unknown): void {
|
||||
if (err instanceof ForgeCapabilityError) {
|
||||
printCapabilityError(err);
|
||||
} else {
|
||||
console.error(`[forge] pipeline failed: ${err instanceof Error ? err.message : String(err)}`);
|
||||
}
|
||||
process.exitCode = 1;
|
||||
}
|
||||
|
||||
function formatDuration(startedAt?: string, completedAt?: string): string {
|
||||
if (!startedAt || !completedAt) return '-';
|
||||
const ms = new Date(completedAt).getTime() - new Date(startedAt).getTime();
|
||||
@@ -54,24 +44,19 @@ function formatDuration(startedAt?: string, completedAt?: string): string {
|
||||
}
|
||||
|
||||
function printManifestTable(manifest: RunManifest): void {
|
||||
const mode = runModeOf(manifest);
|
||||
console.log(`\nRun ID : ${manifest.runId}`);
|
||||
console.log(`Status : ${manifest.status}`);
|
||||
console.log(`Mode : ${mode}`);
|
||||
if (mode === 'simulated') {
|
||||
console.log('WARNING: SIMULATED RUN — results are synthetic, not verified success.');
|
||||
}
|
||||
console.log(`Brief : ${manifest.brief}`);
|
||||
console.log(`Class : ${manifest.briefClass} (${manifest.classSource})`);
|
||||
console.log(`Updated: ${manifest.updatedAt}`);
|
||||
console.log('');
|
||||
console.log('Stage'.padEnd(22) + 'Status'.padEnd(24) + 'Duration');
|
||||
console.log('-'.repeat(60));
|
||||
console.log('Stage'.padEnd(22) + 'Status'.padEnd(14) + 'Duration');
|
||||
console.log('-'.repeat(50));
|
||||
for (const stage of STAGE_SEQUENCE) {
|
||||
const s = manifest.stages[stage];
|
||||
if (!s) continue;
|
||||
const label = (STAGE_LABELS[stage] ?? stage).padEnd(22);
|
||||
const status = s.status.padEnd(24);
|
||||
const status = s.status.padEnd(14);
|
||||
const dur = formatDuration(s.startedAt, s.completedAt);
|
||||
console.log(`${label}${status}${dur}`);
|
||||
}
|
||||
@@ -105,58 +90,23 @@ function listRecentRuns(projectRoot?: string): void {
|
||||
}
|
||||
|
||||
console.log('\nRecent runs:');
|
||||
console.log('Run ID'.padEnd(22) + 'Status'.padEnd(24) + 'Mode'.padEnd(12) + 'Brief');
|
||||
console.log('-'.repeat(80));
|
||||
console.log('Run ID'.padEnd(22) + 'Status'.padEnd(14) + 'Brief');
|
||||
console.log('-'.repeat(70));
|
||||
|
||||
for (const runId of entries) {
|
||||
const runDir = path.join(runsDir, runId);
|
||||
try {
|
||||
const manifest = loadManifest(runDir);
|
||||
const status = manifest.status.padEnd(24);
|
||||
const mode = runModeOf(manifest).padEnd(12);
|
||||
const status = manifest.status.padEnd(14);
|
||||
const brief = path.basename(manifest.brief);
|
||||
console.log(`${runId.padEnd(22)}${status}${mode}${brief}`);
|
||||
console.log(`${runId.padEnd(22)}${status}${brief}`);
|
||||
} catch {
|
||||
console.log(`${runId.padEnd(22)}${'(unreadable)'.padEnd(24)}`);
|
||||
console.log(`${runId.padEnd(22)}${'(unreadable)'.padEnd(14)}`);
|
||||
}
|
||||
}
|
||||
console.log('');
|
||||
}
|
||||
|
||||
/**
|
||||
* Apply the exit-code policy for a finished pipeline run (SDLC-D-035):
|
||||
*
|
||||
* - exit 0 only for a verified `completed` normal run, or for an overall
|
||||
* `simulated` run when the caller explicitly passed --simulate;
|
||||
* - anything else exits nonzero so it can never be read as success.
|
||||
*/
|
||||
function applyRunExitPolicy(result: { manifest: RunManifest; runDir: string }, simulate: boolean) {
|
||||
const { manifest } = result;
|
||||
|
||||
if (runModeOf(manifest) === 'simulated') {
|
||||
if (!simulate || manifest.status !== 'simulated') {
|
||||
console.error(
|
||||
'[forge] error FORGE_MODE_MISMATCH: run reports simulated results without an explicit, ' +
|
||||
'consistent --simulate request; refusing to report success.',
|
||||
);
|
||||
process.exitCode = 1;
|
||||
return;
|
||||
}
|
||||
printSimulatedBanner();
|
||||
console.log(`[forge] run directory: ${result.runDir}`);
|
||||
return; // exit 0 — the caller explicitly opted into simulation
|
||||
}
|
||||
|
||||
if (manifest.status !== 'completed') {
|
||||
console.error(`[forge] run did not complete: terminal status '${manifest.status}'`);
|
||||
process.exitCode = 1;
|
||||
return;
|
||||
}
|
||||
|
||||
console.log(`[forge] pipeline complete (mode: normal): ${manifest.runId}`);
|
||||
console.log(`[forge] run directory: ${result.runDir}`);
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Register function
|
||||
// ---------------------------------------------------------------------------
|
||||
@@ -179,11 +129,6 @@ export function registerForgeCommand(parent: Command): void {
|
||||
.option('--config <path>', 'Path to forge config file (.forge/config.yaml)')
|
||||
.option('--codebase <path>', 'Codebase root to pass to the pipeline', process.cwd())
|
||||
.option('--dry-run', 'Print planned stages without executing', false)
|
||||
.option(
|
||||
'--simulate',
|
||||
'Simulate execution without real providers (every result is typed simulated, never verified)',
|
||||
false,
|
||||
)
|
||||
.action(
|
||||
async (opts: {
|
||||
brief: string;
|
||||
@@ -192,7 +137,6 @@ export function registerForgeCommand(parent: Command): void {
|
||||
config?: string;
|
||||
codebase: string;
|
||||
dryRun: boolean;
|
||||
simulate: boolean;
|
||||
}) => {
|
||||
const briefPath = path.resolve(opts.brief);
|
||||
|
||||
@@ -205,22 +149,14 @@ export function registerForgeCommand(parent: Command): void {
|
||||
const briefContent = fs.readFileSync(briefPath, 'utf-8');
|
||||
const briefClass = classifyBrief(briefContent);
|
||||
const projectRoot = opts.codebase;
|
||||
// A real executor is never wired at CLI invocation time today, so the
|
||||
// only executor we may construct is the explicitly-requested simulated
|
||||
// one. Normal mode fails closed with FORGE_NO_EXECUTOR.
|
||||
const executor = opts.simulate ? createSimulatedExecutor() : undefined;
|
||||
|
||||
if (opts.resume) {
|
||||
const runId = opts.runId ?? generateRunId();
|
||||
const runDir = resolveRunDir(runId, projectRoot);
|
||||
console.log(`[forge] resuming run: ${runId}`);
|
||||
try {
|
||||
const { resumePipeline } = await import('./pipeline-runner.js');
|
||||
const result = await resumePipeline(runDir, executor, { simulate: opts.simulate });
|
||||
applyRunExitPolicy(result, opts.simulate);
|
||||
} catch (err) {
|
||||
handlePipelineError(err);
|
||||
}
|
||||
const { resumePipeline } = await import('./pipeline-runner.js');
|
||||
const result = await resumePipeline(runDir, stubExecutor);
|
||||
console.log(`[forge] pipeline complete: ${result.runId}`);
|
||||
return;
|
||||
}
|
||||
|
||||
@@ -228,8 +164,7 @@ export function registerForgeCommand(parent: Command): void {
|
||||
briefClass,
|
||||
codebase: projectRoot,
|
||||
dryRun: opts.dryRun,
|
||||
executor,
|
||||
simulate: opts.simulate,
|
||||
executor: stubExecutor,
|
||||
};
|
||||
|
||||
if (opts.dryRun) {
|
||||
@@ -245,15 +180,16 @@ export function registerForgeCommand(parent: Command): void {
|
||||
|
||||
console.log(`[forge] starting pipeline for brief: ${briefPath}`);
|
||||
console.log(`[forge] classified as: ${briefClass}`);
|
||||
if (opts.simulate) {
|
||||
console.log('[forge] mode: SIMULATED (explicit --simulate)');
|
||||
}
|
||||
|
||||
try {
|
||||
const result = await runPipeline(briefPath, projectRoot, pipelineOptions);
|
||||
applyRunExitPolicy(result, opts.simulate);
|
||||
console.log(`[forge] pipeline complete: ${result.runId}`);
|
||||
console.log(`[forge] run directory: ${result.runDir}`);
|
||||
} catch (err) {
|
||||
handlePipelineError(err);
|
||||
console.error(
|
||||
`[forge] pipeline failed: ${err instanceof Error ? err.message : String(err)}`,
|
||||
);
|
||||
process.exitCode = 1;
|
||||
}
|
||||
},
|
||||
);
|
||||
@@ -288,12 +224,7 @@ export function registerForgeCommand(parent: Command): void {
|
||||
.command('resume <runId>')
|
||||
.description('Resume a stopped or failed pipeline run')
|
||||
.option('--project <path>', 'Project root (defaults to cwd)', process.cwd())
|
||||
.option(
|
||||
'--simulate',
|
||||
'Simulate execution without real providers (every result is typed simulated, never verified)',
|
||||
false,
|
||||
)
|
||||
.action(async (runId: string, opts: { project: string; simulate: boolean }) => {
|
||||
.action(async (runId: string, opts: { project: string }) => {
|
||||
const runDir = resolveRunDir(runId, opts.project);
|
||||
|
||||
if (!fs.existsSync(runDir)) {
|
||||
@@ -303,20 +234,15 @@ export function registerForgeCommand(parent: Command): void {
|
||||
}
|
||||
|
||||
console.log(`[forge] resuming run: ${runId}`);
|
||||
if (opts.simulate) {
|
||||
console.log('[forge] mode: SIMULATED (explicit --simulate)');
|
||||
}
|
||||
|
||||
// No real executor is wired at CLI invocation time; only the explicitly
|
||||
// requested simulated executor may be constructed (fail closed otherwise).
|
||||
const executor = opts.simulate ? createSimulatedExecutor() : undefined;
|
||||
|
||||
try {
|
||||
const { resumePipeline } = await import('./pipeline-runner.js');
|
||||
const result = await resumePipeline(runDir, executor, { simulate: opts.simulate });
|
||||
applyRunExitPolicy(result, opts.simulate);
|
||||
const result = await resumePipeline(runDir, stubExecutor);
|
||||
console.log(`[forge] pipeline complete: ${result.runId}`);
|
||||
console.log(`[forge] run directory: ${result.runDir}`);
|
||||
} catch (err) {
|
||||
handlePipelineError(err);
|
||||
console.error(`[forge] resume failed: ${err instanceof Error ? err.message : String(err)}`);
|
||||
process.exitCode = 1;
|
||||
}
|
||||
});
|
||||
|
||||
|
||||
@@ -9,16 +9,7 @@ export const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.
|
||||
/** Pipeline asset directory (stages, agents, rails, gates, templates). */
|
||||
export const PIPELINE_DIR = path.join(PACKAGE_ROOT, 'pipeline');
|
||||
|
||||
/** Stage specifications — defines every pipeline stage.
|
||||
*\n * Gate semantics (SDLC-D-035): every gate is one of
|
||||
* - a real command string / GateEntry a mechanical runner can execute,
|
||||
* - an `authority` gate (human/board sign-off; produces waiting-for-authority),
|
||||
* - a `provider` gate (requires a wired provider such as a reviewer or CI pipeline).
|
||||
*
|
||||
* Vacuous gates (`true`, echo'd synthetic approvals, placeholder ci-pipeline
|
||||
* commands) are forbidden: a stage whose gate has no real implementation
|
||||
* fails closed instead of passing.
|
||||
*/
|
||||
/** Stage specifications — defines every pipeline stage. */
|
||||
export const STAGE_SPECS: Record<string, StageSpec> = {
|
||||
'00-intake': {
|
||||
number: '00',
|
||||
@@ -36,13 +27,7 @@ export const STAGE_SPECS: Record<string, StageSpec> = {
|
||||
type: 'research',
|
||||
gate: 'discovery-complete',
|
||||
promptFile: '00b-discovery.md',
|
||||
qualityGates: [
|
||||
{
|
||||
kind: 'authority',
|
||||
capability: 'discovery-complete',
|
||||
reason: 'discovery completion is attested by an authority; no mechanical check exists',
|
||||
},
|
||||
],
|
||||
qualityGates: ['true'],
|
||||
},
|
||||
'01-board': {
|
||||
number: '01',
|
||||
@@ -51,13 +36,7 @@ export const STAGE_SPECS: Record<string, StageSpec> = {
|
||||
type: 'review',
|
||||
gate: 'board-approval',
|
||||
promptFile: '01-board.md',
|
||||
qualityGates: [
|
||||
{
|
||||
kind: 'authority',
|
||||
capability: 'board-approval',
|
||||
reason: 'board approval is a board/human decision; no mechanical gate exists',
|
||||
},
|
||||
],
|
||||
qualityGates: [{ type: 'ci-pipeline', command: 'board-approval (via board-tasks)' }],
|
||||
},
|
||||
'01b-brief-analyzer': {
|
||||
number: '01b',
|
||||
@@ -66,13 +45,7 @@ export const STAGE_SPECS: Record<string, StageSpec> = {
|
||||
type: 'research',
|
||||
gate: 'brief-analysis-complete',
|
||||
promptFile: '01-board.md',
|
||||
qualityGates: [
|
||||
{
|
||||
kind: 'authority',
|
||||
capability: 'brief-analysis-complete',
|
||||
reason: 'brief analysis completion is attested by an authority; no mechanical check exists',
|
||||
},
|
||||
],
|
||||
qualityGates: ['true'],
|
||||
},
|
||||
'02-planning-1': {
|
||||
number: '02',
|
||||
@@ -81,13 +54,7 @@ export const STAGE_SPECS: Record<string, StageSpec> = {
|
||||
type: 'research',
|
||||
gate: 'architecture-approval',
|
||||
promptFile: '02-planning-1-architecture.md',
|
||||
qualityGates: [
|
||||
{
|
||||
kind: 'authority',
|
||||
capability: 'architecture-approval',
|
||||
reason: 'ADR approval requires authority sign-off; no mechanical check exists',
|
||||
},
|
||||
],
|
||||
qualityGates: ['true'],
|
||||
},
|
||||
'03-planning-2': {
|
||||
number: '03',
|
||||
@@ -96,14 +63,7 @@ export const STAGE_SPECS: Record<string, StageSpec> = {
|
||||
type: 'research',
|
||||
gate: 'implementation-approval',
|
||||
promptFile: '03-planning-2-implementation.md',
|
||||
qualityGates: [
|
||||
{
|
||||
kind: 'authority',
|
||||
capability: 'implementation-approval',
|
||||
reason:
|
||||
'implementation spec approval requires authority sign-off; no mechanical check exists',
|
||||
},
|
||||
],
|
||||
qualityGates: ['true'],
|
||||
},
|
||||
'04-planning-3': {
|
||||
number: '04',
|
||||
@@ -112,14 +72,7 @@ export const STAGE_SPECS: Record<string, StageSpec> = {
|
||||
type: 'research',
|
||||
gate: 'decomposition-approval',
|
||||
promptFile: '04-planning-3-decomposition.md',
|
||||
qualityGates: [
|
||||
{
|
||||
kind: 'authority',
|
||||
capability: 'decomposition-approval',
|
||||
reason:
|
||||
'task decomposition approval requires authority sign-off; no mechanical check exists',
|
||||
},
|
||||
],
|
||||
qualityGates: ['true'],
|
||||
},
|
||||
'05-coding': {
|
||||
number: '05',
|
||||
@@ -139,10 +92,9 @@ export const STAGE_SPECS: Record<string, StageSpec> = {
|
||||
promptFile: '06-review.md',
|
||||
qualityGates: [
|
||||
{
|
||||
kind: 'provider',
|
||||
capability: 'reviewer',
|
||||
reason:
|
||||
'review verdicts require a wired reviewer provider; synthetic approvals are not permitted',
|
||||
type: 'ai-review',
|
||||
command:
|
||||
'echo \'{"summary":"review-pass","verdict":"approve","findings":[],"stats":{"blockers":0,"should_fix":0,"suggestions":0}}\'',
|
||||
},
|
||||
],
|
||||
},
|
||||
@@ -153,13 +105,7 @@ export const STAGE_SPECS: Record<string, StageSpec> = {
|
||||
type: 'coding',
|
||||
gate: 're-review',
|
||||
promptFile: '07-remediate.md',
|
||||
qualityGates: [
|
||||
{
|
||||
kind: 'authority',
|
||||
capability: 're-review',
|
||||
reason: 'remediation re-review is an approval-based gate; no mechanical check exists',
|
||||
},
|
||||
],
|
||||
qualityGates: ['true'],
|
||||
},
|
||||
'08-test': {
|
||||
number: '08',
|
||||
@@ -177,13 +123,7 @@ export const STAGE_SPECS: Record<string, StageSpec> = {
|
||||
type: 'deploy',
|
||||
gate: 'deploy-verification',
|
||||
promptFile: '09-deploy.md',
|
||||
qualityGates: [
|
||||
{
|
||||
kind: 'provider',
|
||||
capability: 'ci-pipeline',
|
||||
reason: 'deploy verification requires a wired CI pipeline provider',
|
||||
},
|
||||
],
|
||||
qualityGates: [{ type: 'ci-pipeline', command: 'deploy-verification' }],
|
||||
},
|
||||
};
|
||||
|
||||
|
||||
@@ -1,46 +0,0 @@
|
||||
/**
|
||||
* Typed fail-closed capability errors (SDLC-D-035).
|
||||
*
|
||||
* A Forge run must fail closed when a required capability (executor, reviewer
|
||||
* provider, CI pipeline, authority sign-off) is missing. These typed errors
|
||||
* name the missing capability so callers can distinguish "not wired" from
|
||||
* ordinary execution failures.
|
||||
*/
|
||||
|
||||
/** Closed set of typed Forge capability error codes. */
|
||||
export const FORGE_ERROR_CODES = [
|
||||
'FORGE_NO_EXECUTOR',
|
||||
'FORGE_NO_REVIEWER',
|
||||
'FORGE_NO_CI_PIPELINE',
|
||||
'FORGE_NO_PROVIDER',
|
||||
'FORGE_AUTHORITY_REQUIRED',
|
||||
] as const;
|
||||
|
||||
export type ForgeErrorCode = (typeof FORGE_ERROR_CODES)[number];
|
||||
|
||||
/** Raised when a required capability is missing and the pipeline must fail closed. */
|
||||
export class ForgeCapabilityError extends Error {
|
||||
/** Typed error code from the closed FORGE_ERROR_CODES set. */
|
||||
readonly code: ForgeErrorCode;
|
||||
/** The missing capability, e.g. `task-executor`, `reviewer`, `board-approval`. */
|
||||
readonly capability: string;
|
||||
|
||||
constructor(code: ForgeErrorCode, capability: string, message: string) {
|
||||
super(message);
|
||||
this.name = 'ForgeCapabilityError';
|
||||
this.code = code;
|
||||
this.capability = capability;
|
||||
}
|
||||
}
|
||||
|
||||
/** Map a provider gate capability to its typed error code. */
|
||||
export function providerErrorCode(capability: string): ForgeErrorCode {
|
||||
switch (capability) {
|
||||
case 'reviewer':
|
||||
return 'FORGE_NO_REVIEWER';
|
||||
case 'ci-pipeline':
|
||||
return 'FORGE_NO_CI_PIPELINE';
|
||||
default:
|
||||
return 'FORGE_NO_PROVIDER';
|
||||
}
|
||||
}
|
||||
@@ -5,13 +5,6 @@ export type {
|
||||
StageSpec,
|
||||
BriefClass,
|
||||
ClassSource,
|
||||
ForgeOutcome,
|
||||
AuthorityGate,
|
||||
ProviderGate,
|
||||
ForgeGate,
|
||||
ForgeGateResult,
|
||||
ForgeTaskResult,
|
||||
RunMode,
|
||||
StageStatus,
|
||||
RunManifest,
|
||||
ForgeTaskStatus,
|
||||
@@ -88,24 +81,5 @@ export {
|
||||
getPipelineStatus,
|
||||
} from './pipeline-runner.js';
|
||||
|
||||
// Fail-closed errors and typed outcome model (SDLC-D-035)
|
||||
export { FORGE_ERROR_CODES, ForgeCapabilityError, providerErrorCode } from './errors.js';
|
||||
export type { ForgeErrorCode } from './errors.js';
|
||||
export {
|
||||
isSatisfyingOutcome,
|
||||
isCapabilityGate,
|
||||
isCommandGate,
|
||||
gateLabel,
|
||||
uniformGateResults,
|
||||
simulatedGateResults,
|
||||
waitingGateResults,
|
||||
blockedGateResults,
|
||||
evaluateStageGates,
|
||||
} from './outcomes.js';
|
||||
export type { StageEvaluation } from './outcomes.js';
|
||||
|
||||
// Simulated executor (explicit --simulate only)
|
||||
export { createSimulatedExecutor } from './simulated-executor.js';
|
||||
|
||||
// CLI
|
||||
export { registerForgeCommand } from './cli.js';
|
||||
|
||||
@@ -1,147 +0,0 @@
|
||||
import type { GateEntry } from '@mosaicstack/macp';
|
||||
|
||||
import type {
|
||||
AuthorityGate,
|
||||
ForgeGate,
|
||||
ForgeGateResult,
|
||||
ForgeOutcome,
|
||||
ForgeTaskResult,
|
||||
ProviderGate,
|
||||
} from './types.js';
|
||||
|
||||
/**
|
||||
* Gate and dependency satisfaction predicate (SDLC-D-035).
|
||||
*
|
||||
* ONLY a verified `passed` outcome satisfies. Every other member of the closed
|
||||
* outcome set — including `simulated` — is non-satisfying, so a simulated or
|
||||
* authority-blocked result can never be read as success-by-verification.
|
||||
*/
|
||||
export function isSatisfyingOutcome(outcome: ForgeOutcome): boolean {
|
||||
return outcome === 'passed';
|
||||
}
|
||||
|
||||
/** Whether a gate is an authority or provider gate (capability-based, command-less). */
|
||||
export function isCapabilityGate(gate: ForgeGate): gate is AuthorityGate | ProviderGate {
|
||||
if (typeof gate !== 'object' || gate === null) return false;
|
||||
const kind = (gate as Record<string, unknown>)['kind'];
|
||||
return kind === 'authority' || kind === 'provider';
|
||||
}
|
||||
|
||||
/** Whether a gate definition carries a real command a mechanical runner can execute. */
|
||||
export function isCommandGate(gate: ForgeGate): gate is string | GateEntry {
|
||||
if (typeof gate === 'string') {
|
||||
return gate.trim().length > 0;
|
||||
}
|
||||
if (isCapabilityGate(gate)) {
|
||||
// Authority and provider gates are satisfied by a capability, not a command.
|
||||
return false;
|
||||
}
|
||||
return typeof gate.command === 'string' && gate.command.trim().length > 0;
|
||||
}
|
||||
|
||||
/** Typed label identifying a gate in results and logs. */
|
||||
export function gateLabel(gate: ForgeGate): string {
|
||||
if (typeof gate === 'string') return gate;
|
||||
if (isCapabilityGate(gate)) return `${gate.kind}:${gate.capability}`;
|
||||
return gate.command || gate.type || 'unnamed-gate';
|
||||
}
|
||||
|
||||
/** Reason string stamped on every simulated gate result. */
|
||||
export const SIMULATED_GATE_REASON =
|
||||
'simulated execution (--simulate): gate was not evaluated by a real implementation';
|
||||
|
||||
/** Build typed gate results with a uniform outcome for a stage's declared gates. */
|
||||
export function uniformGateResults(
|
||||
gates: ForgeGate[],
|
||||
outcome: ForgeOutcome,
|
||||
reason: string,
|
||||
): ForgeGateResult[] {
|
||||
return gates.map((gate) => ({ gate: gateLabel(gate), outcome, reason }));
|
||||
}
|
||||
|
||||
/** Typed simulated gate results — used exclusively in `--simulate` runs. */
|
||||
export function simulatedGateResults(gates: ForgeGate[]): ForgeGateResult[] {
|
||||
return uniformGateResults(gates, 'simulated', SIMULATED_GATE_REASON);
|
||||
}
|
||||
|
||||
/** Typed waiting-for-authority gate results for approval-based stages. */
|
||||
export function waitingGateResults(gates: ForgeGate[], reason: string): ForgeGateResult[] {
|
||||
return uniformGateResults(gates, 'waiting-for-authority', reason);
|
||||
}
|
||||
|
||||
/** Typed blocked gate results for stages whose provider capability is not wired. */
|
||||
export function blockedGateResults(gates: ForgeGate[], reason: string): ForgeGateResult[] {
|
||||
return uniformGateResults(gates, 'blocked', reason);
|
||||
}
|
||||
|
||||
/** Outcome of evaluating a completed stage in normal mode. */
|
||||
export interface StageEvaluation {
|
||||
outcome: ForgeOutcome;
|
||||
reason: string;
|
||||
gateResults: ForgeGateResult[];
|
||||
}
|
||||
|
||||
/**
|
||||
* Evaluate a stage's declared gates against the executor's typed result.
|
||||
*
|
||||
* Fail-closed mapping:
|
||||
* - a `simulated` task or gate outcome in normal mode maps to `error`
|
||||
* - a missing gate result for a required command gate maps to `blocked`
|
||||
* - a non-passing task outcome propagates as the stage outcome
|
||||
* - only verified `passed` task and gate outcomes yield a `passed` stage
|
||||
*/
|
||||
export function evaluateStageGates(
|
||||
stageName: string,
|
||||
gates: ForgeGate[],
|
||||
result: ForgeTaskResult,
|
||||
): StageEvaluation {
|
||||
const gateResults = result.gate_results ?? [];
|
||||
|
||||
if (result.outcome === 'simulated') {
|
||||
return {
|
||||
outcome: 'error',
|
||||
reason: `executor reported a simulated outcome for stage '${stageName}' in normal mode — refusing to treat simulated results as verified`,
|
||||
gateResults,
|
||||
};
|
||||
}
|
||||
|
||||
if (!isSatisfyingOutcome(result.outcome)) {
|
||||
return {
|
||||
outcome: result.outcome,
|
||||
reason: `task outcome is '${result.outcome}': ${result.reason}`,
|
||||
gateResults,
|
||||
};
|
||||
}
|
||||
|
||||
for (const gate of gates) {
|
||||
// Authority and provider gates are pre-flighted before execution; they have
|
||||
// no mechanical result to verify here.
|
||||
if (!isCommandGate(gate)) continue;
|
||||
|
||||
const label = gateLabel(gate);
|
||||
const gateResult = gateResults.find((r) => r.gate === label);
|
||||
if (!gateResult) {
|
||||
return {
|
||||
outcome: 'blocked',
|
||||
reason: `no gate result was reported for required gate '${label}' (stage '${stageName}')`,
|
||||
gateResults,
|
||||
};
|
||||
}
|
||||
if (!isSatisfyingOutcome(gateResult.outcome)) {
|
||||
return {
|
||||
outcome: gateResult.outcome === 'simulated' ? 'error' : gateResult.outcome,
|
||||
reason: `gate '${label}' outcome is '${gateResult.outcome}': ${gateResult.reason}`,
|
||||
gateResults,
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
return {
|
||||
outcome: 'passed',
|
||||
reason:
|
||||
gates.length === 0
|
||||
? "stage declares no gates; task outcome 'passed' accepted"
|
||||
: 'all declared gates verified passed',
|
||||
gateResults,
|
||||
};
|
||||
}
|
||||
@@ -1,33 +1,18 @@
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
|
||||
import { STAGE_SEQUENCE, STAGE_SPECS } from './constants.js';
|
||||
import { STAGE_SEQUENCE } from './constants.js';
|
||||
import { determineBriefClass, stagesForClass } from './brief-classifier.js';
|
||||
import { ForgeCapabilityError, providerErrorCode } from './errors.js';
|
||||
import {
|
||||
blockedGateResults,
|
||||
evaluateStageGates,
|
||||
isCapabilityGate,
|
||||
simulatedGateResults,
|
||||
waitingGateResults,
|
||||
} from './outcomes.js';
|
||||
import { mapStageToTask } from './stage-adapter.js';
|
||||
import { createSimulatedExecutor } from './simulated-executor.js';
|
||||
import type {
|
||||
ForgeTask,
|
||||
ForgeTaskResult,
|
||||
PipelineOptions,
|
||||
PipelineResult,
|
||||
RunManifest,
|
||||
RunMode,
|
||||
StageStatus,
|
||||
TaskExecutor,
|
||||
} from './types.js';
|
||||
|
||||
/** Reason stamped on stages that complete under explicit simulation. */
|
||||
const SIMULATED_STAGE_REASON =
|
||||
'simulated execution (--simulate): stage was not executed by a real executor';
|
||||
|
||||
/**
|
||||
* Generate a timestamp-based run ID.
|
||||
*/
|
||||
@@ -62,7 +47,6 @@ function createManifest(opts: {
|
||||
briefClass: RunManifest['briefClass'];
|
||||
classSource: RunManifest['classSource'];
|
||||
forceBoard: boolean;
|
||||
mode: RunMode;
|
||||
runDir: string;
|
||||
}): RunManifest {
|
||||
const ts = nowISO();
|
||||
@@ -73,7 +57,6 @@ function createManifest(opts: {
|
||||
briefClass: opts.briefClass,
|
||||
classSource: opts.classSource,
|
||||
forceBoard: opts.forceBoard,
|
||||
mode: opts.mode,
|
||||
createdAt: ts,
|
||||
updatedAt: ts,
|
||||
currentStage: '',
|
||||
@@ -125,199 +108,20 @@ export function selectStages(stages?: string[], skipTo?: string): string[] {
|
||||
return selected.slice(skipIndex);
|
||||
}
|
||||
|
||||
/**
|
||||
* Fail closed when the required executor capability is missing (SDLC-D-035).
|
||||
*/
|
||||
function requireExecutor(executor: TaskExecutor | undefined, simulate: boolean): TaskExecutor {
|
||||
if (executor) return executor;
|
||||
if (simulate) return createSimulatedExecutor({ log: false });
|
||||
throw new ForgeCapabilityError(
|
||||
'FORGE_NO_EXECUTOR',
|
||||
'task-executor',
|
||||
'no task executor is wired; refusing to run the pipeline with a stub executor (fail closed). ' +
|
||||
'Pass --simulate to opt into explicitly simulated execution.',
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Pre-flight a stage's gates in normal mode (fail closed, SDLC-D-035).
|
||||
*
|
||||
* - authority gates: record a typed `waiting-for-authority` stage result and
|
||||
* raise FORGE_AUTHORITY_REQUIRED — approval-based gates never pass vacuously.
|
||||
* - provider gates: record a typed `blocked` stage result and raise the typed
|
||||
* capability error for the missing provider.
|
||||
*
|
||||
* Returns the stage status to record when the pre-flight blocks, or undefined
|
||||
* when the stage may proceed.
|
||||
*/
|
||||
function preflightStageGates(
|
||||
stageName: string,
|
||||
manifest: RunManifest,
|
||||
): { status: StageStatus; error: ForgeCapabilityError } | undefined {
|
||||
const spec = STAGE_SPECS[stageName];
|
||||
if (!spec) throw new Error(`Unknown Forge stage: ${stageName}`);
|
||||
|
||||
for (const gate of spec.qualityGates) {
|
||||
if (!isCapabilityGate(gate)) continue;
|
||||
|
||||
const startedAt = manifest.stages[stageName]?.startedAt;
|
||||
const completedAt = nowISO();
|
||||
|
||||
if (gate.kind === 'authority') {
|
||||
const reason = `gate '${gate.capability}' requires authority sign-off; no mechanical implementation exists (${gate.reason})`;
|
||||
return {
|
||||
status: {
|
||||
status: 'waiting-for-authority',
|
||||
reason,
|
||||
startedAt,
|
||||
completedAt,
|
||||
gateResults: waitingGateResults(spec.qualityGates, reason),
|
||||
},
|
||||
error: new ForgeCapabilityError(
|
||||
'FORGE_AUTHORITY_REQUIRED',
|
||||
gate.capability,
|
||||
`stage '${stageName}' is blocked on authority gate '${gate.capability}': ${gate.reason}. ` +
|
||||
'The pipeline fails closed instead of passing vacuously. Record the approval out-of-band ' +
|
||||
'or run with --simulate for explicitly simulated execution.',
|
||||
),
|
||||
};
|
||||
}
|
||||
|
||||
const reason = `gate '${gate.capability}' requires provider '${gate.capability}' and none is wired (${gate.reason})`;
|
||||
return {
|
||||
status: {
|
||||
status: 'blocked',
|
||||
reason,
|
||||
startedAt,
|
||||
completedAt,
|
||||
gateResults: blockedGateResults(spec.qualityGates, reason),
|
||||
},
|
||||
error: new ForgeCapabilityError(
|
||||
providerErrorCode(gate.capability),
|
||||
gate.capability,
|
||||
`stage '${stageName}' requires provider '${gate.capability}' which is not wired: ${gate.reason}. ` +
|
||||
'The pipeline fails closed instead of passing vacuously.',
|
||||
),
|
||||
};
|
||||
}
|
||||
|
||||
return undefined;
|
||||
}
|
||||
|
||||
/**
|
||||
* Execute the given stage tasks sequentially, updating the manifest.
|
||||
*
|
||||
* Normal mode requires a real executor and evaluates every declared command
|
||||
* gate through the typed outcome model; any non-verified result fails closed.
|
||||
* Simulate mode types every stage and gate result as `simulated`.
|
||||
*/
|
||||
async function executeStages(opts: {
|
||||
manifest: RunManifest;
|
||||
runDir: string;
|
||||
tasks: ForgeTask[];
|
||||
stageNames: string[];
|
||||
executor: TaskExecutor;
|
||||
simulate: boolean;
|
||||
}): Promise<void> {
|
||||
const { manifest, runDir, tasks, stageNames, executor, simulate } = opts;
|
||||
|
||||
for (let i = 0; i < tasks.length; i++) {
|
||||
const task = tasks[i]!;
|
||||
const stageName = stageNames[i]!;
|
||||
const spec = STAGE_SPECS[stageName];
|
||||
if (!spec) throw new Error(`Unknown Forge stage: ${stageName}`);
|
||||
|
||||
// Update manifest: stage in progress
|
||||
manifest.currentStage = stageName;
|
||||
manifest.stages[stageName] = {
|
||||
status: 'in_progress',
|
||||
startedAt: nowISO(),
|
||||
};
|
||||
saveManifest(runDir, manifest);
|
||||
|
||||
// Fail-closed pre-flight (normal mode only): authority/provider gates have
|
||||
// no mechanical implementation and must never pass vacuously.
|
||||
if (!simulate) {
|
||||
const blocked = preflightStageGates(stageName, manifest);
|
||||
if (blocked) {
|
||||
manifest.stages[stageName] = blocked.status;
|
||||
manifest.status =
|
||||
blocked.status.status === 'waiting-for-authority' ? 'waiting-for-authority' : 'failed';
|
||||
saveManifest(runDir, manifest);
|
||||
throw blocked.error;
|
||||
}
|
||||
}
|
||||
|
||||
let result: ForgeTaskResult;
|
||||
try {
|
||||
await executor.submitTask(task);
|
||||
result = await executor.waitForCompletion(task.id, task.timeoutSeconds * 1000);
|
||||
} catch (error) {
|
||||
// Process errors (including timeouts) map to the fail-closed `error` outcome.
|
||||
const reason = error instanceof Error ? error.message : String(error);
|
||||
manifest.stages[stageName] = {
|
||||
status: 'error',
|
||||
reason: `executor error: ${reason}`,
|
||||
startedAt: manifest.stages[stageName]?.startedAt,
|
||||
completedAt: nowISO(),
|
||||
gateResults: [],
|
||||
};
|
||||
manifest.status = 'failed';
|
||||
saveManifest(runDir, manifest);
|
||||
throw error instanceof Error ? error : new Error(reason);
|
||||
}
|
||||
|
||||
if (simulate) {
|
||||
manifest.stages[stageName] = {
|
||||
status: 'simulated',
|
||||
reason: SIMULATED_STAGE_REASON,
|
||||
startedAt: manifest.stages[stageName]?.startedAt,
|
||||
completedAt: nowISO(),
|
||||
gateResults: simulatedGateResults(spec.qualityGates),
|
||||
};
|
||||
saveManifest(runDir, manifest);
|
||||
continue;
|
||||
}
|
||||
|
||||
const evaluation = evaluateStageGates(stageName, spec.qualityGates, result);
|
||||
manifest.stages[stageName] = {
|
||||
status: evaluation.outcome,
|
||||
reason: evaluation.reason,
|
||||
startedAt: manifest.stages[stageName]?.startedAt,
|
||||
completedAt: nowISO(),
|
||||
gateResults: evaluation.gateResults,
|
||||
};
|
||||
|
||||
if (evaluation.outcome !== 'passed') {
|
||||
manifest.status =
|
||||
evaluation.outcome === 'waiting-for-authority' ? 'waiting-for-authority' : 'failed';
|
||||
saveManifest(runDir, manifest);
|
||||
throw new Error(`Stage ${stageName} ${evaluation.outcome}: ${evaluation.reason}`);
|
||||
}
|
||||
|
||||
saveManifest(runDir, manifest);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Run the Forge pipeline.
|
||||
*
|
||||
* 1. Fail closed unless a real executor is wired or simulation is explicit
|
||||
* 2. Classify the brief
|
||||
* 3. Generate a run ID and create run directory
|
||||
* 4. Map stages to tasks and submit to TaskExecutor
|
||||
* 5. Track manifest with typed stage outcomes
|
||||
* 6. Return pipeline result
|
||||
* 1. Classify the brief
|
||||
* 2. Generate a run ID and create run directory
|
||||
* 3. Map stages to tasks and submit to TaskExecutor
|
||||
* 4. Track manifest with stage statuses
|
||||
* 5. Return pipeline result
|
||||
*/
|
||||
export async function runPipeline(
|
||||
briefPath: string,
|
||||
projectRoot: string,
|
||||
options: PipelineOptions,
|
||||
): Promise<PipelineResult> {
|
||||
const simulate = options.simulate ?? false;
|
||||
const executor = requireExecutor(options.executor, simulate);
|
||||
const mode: RunMode = simulate ? 'simulated' : 'normal';
|
||||
|
||||
const resolvedRoot = path.resolve(projectRoot);
|
||||
const resolvedBrief = path.resolve(briefPath);
|
||||
const briefContent = fs.readFileSync(resolvedBrief, 'utf-8');
|
||||
@@ -342,7 +146,6 @@ export async function runPipeline(
|
||||
briefClass,
|
||||
classSource,
|
||||
forceBoard: options.forceBoard ?? false,
|
||||
mode,
|
||||
runDir,
|
||||
});
|
||||
|
||||
@@ -369,10 +172,54 @@ export async function runPipeline(
|
||||
}
|
||||
|
||||
// Execute stages
|
||||
await executeStages({ manifest, runDir, tasks, stageNames: selectedStages, executor, simulate });
|
||||
const { executor } = options;
|
||||
for (let i = 0; i < tasks.length; i++) {
|
||||
const task = tasks[i]!;
|
||||
const stageName = selectedStages[i]!;
|
||||
|
||||
// All stages reached a terminal state for this mode
|
||||
manifest.status = simulate ? 'simulated' : 'completed';
|
||||
// Update manifest: stage in progress
|
||||
manifest.currentStage = stageName;
|
||||
manifest.stages[stageName] = {
|
||||
status: 'in_progress',
|
||||
startedAt: nowISO(),
|
||||
};
|
||||
saveManifest(runDir, manifest);
|
||||
|
||||
try {
|
||||
await executor.submitTask(task);
|
||||
const result = await executor.waitForCompletion(task.id, task.timeoutSeconds * 1000);
|
||||
|
||||
// Update manifest: stage completed or failed
|
||||
const stageStatus: StageStatus = {
|
||||
status: result.status === 'completed' ? 'passed' : 'failed',
|
||||
startedAt: manifest.stages[stageName]!.startedAt,
|
||||
completedAt: nowISO(),
|
||||
};
|
||||
manifest.stages[stageName] = stageStatus;
|
||||
|
||||
if (result.status !== 'completed') {
|
||||
manifest.status = 'failed';
|
||||
saveManifest(runDir, manifest);
|
||||
throw new Error(`Stage ${stageName} failed with status: ${result.status}`);
|
||||
}
|
||||
|
||||
saveManifest(runDir, manifest);
|
||||
} catch (error) {
|
||||
if (!manifest.stages[stageName]?.completedAt) {
|
||||
manifest.stages[stageName] = {
|
||||
status: 'failed',
|
||||
startedAt: manifest.stages[stageName]?.startedAt,
|
||||
completedAt: nowISO(),
|
||||
};
|
||||
}
|
||||
manifest.status = 'failed';
|
||||
saveManifest(runDir, manifest);
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
|
||||
// All stages passed
|
||||
manifest.status = 'completed';
|
||||
saveManifest(runDir, manifest);
|
||||
|
||||
return {
|
||||
@@ -387,30 +234,22 @@ export async function runPipeline(
|
||||
}
|
||||
|
||||
/**
|
||||
* Resume a pipeline from the last non-passed stage.
|
||||
* Resume a pipeline from the last incomplete stage.
|
||||
*/
|
||||
export async function resumePipeline(
|
||||
runDir: string,
|
||||
executor?: TaskExecutor,
|
||||
options?: { simulate?: boolean },
|
||||
executor: TaskExecutor,
|
||||
): Promise<PipelineResult> {
|
||||
const simulate = options?.simulate ?? false;
|
||||
const wiredExecutor = requireExecutor(executor, simulate);
|
||||
const mode: RunMode = simulate ? 'simulated' : 'normal';
|
||||
|
||||
const manifest = loadManifest(runDir);
|
||||
const resolvedRoot = path.dirname(path.dirname(path.dirname(runDir))); // .forge/runs/{id} → project root
|
||||
|
||||
const briefContent = fs.readFileSync(manifest.brief, 'utf-8');
|
||||
const allStages = stagesForClass(manifest.briefClass, manifest.forceBoard);
|
||||
|
||||
manifest.mode = mode;
|
||||
|
||||
// Find first non-satisfying stage (only a verified `passed` counts as done;
|
||||
// simulated and waiting-for-authority stages are re-run).
|
||||
// Find first non-passed stage
|
||||
const resumeFrom = allStages.find((s) => manifest.stages[s]?.status !== 'passed');
|
||||
if (!resumeFrom) {
|
||||
manifest.status = mode === 'simulated' ? 'simulated' : 'completed';
|
||||
manifest.status = 'completed';
|
||||
saveManifest(runDir, manifest);
|
||||
return {
|
||||
runId: manifest.runId,
|
||||
@@ -445,16 +284,49 @@ export async function resumePipeline(
|
||||
tasks.push(task);
|
||||
}
|
||||
|
||||
await executeStages({
|
||||
manifest,
|
||||
runDir,
|
||||
tasks,
|
||||
stageNames: remainingStages,
|
||||
executor: wiredExecutor,
|
||||
simulate,
|
||||
});
|
||||
for (let i = 0; i < tasks.length; i++) {
|
||||
const task = tasks[i]!;
|
||||
const stageName = remainingStages[i]!;
|
||||
|
||||
manifest.status = simulate ? 'simulated' : 'completed';
|
||||
manifest.currentStage = stageName;
|
||||
manifest.stages[stageName] = {
|
||||
status: 'in_progress',
|
||||
startedAt: nowISO(),
|
||||
};
|
||||
saveManifest(runDir, manifest);
|
||||
|
||||
try {
|
||||
await executor.submitTask(task);
|
||||
const result = await executor.waitForCompletion(task.id, task.timeoutSeconds * 1000);
|
||||
|
||||
manifest.stages[stageName] = {
|
||||
status: result.status === 'completed' ? 'passed' : 'failed',
|
||||
startedAt: manifest.stages[stageName]!.startedAt,
|
||||
completedAt: nowISO(),
|
||||
};
|
||||
|
||||
if (result.status !== 'completed') {
|
||||
manifest.status = 'failed';
|
||||
saveManifest(runDir, manifest);
|
||||
throw new Error(`Stage ${stageName} failed with status: ${result.status}`);
|
||||
}
|
||||
|
||||
saveManifest(runDir, manifest);
|
||||
} catch (error) {
|
||||
if (!manifest.stages[stageName]?.completedAt) {
|
||||
manifest.stages[stageName] = {
|
||||
status: 'failed',
|
||||
startedAt: manifest.stages[stageName]?.startedAt,
|
||||
completedAt: nowISO(),
|
||||
};
|
||||
}
|
||||
manifest.status = 'failed';
|
||||
saveManifest(runDir, manifest);
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
|
||||
manifest.status = 'completed';
|
||||
saveManifest(runDir, manifest);
|
||||
|
||||
return {
|
||||
|
||||
@@ -1,32 +0,0 @@
|
||||
import type { ForgeTask, ForgeTaskResult, TaskExecutor } from './types.js';
|
||||
|
||||
/**
|
||||
* Simulated executor — used ONLY when the caller explicitly passes --simulate.
|
||||
*
|
||||
* It submits no real work and returns typed `simulated` results so a simulated
|
||||
* run can never be confused with a verified one. In normal mode (no --simulate)
|
||||
* the CLI refuses to run at all with FORGE_NO_EXECUTOR instead of wiring this
|
||||
* stub (fail closed, SDLC-D-035).
|
||||
*/
|
||||
export function createSimulatedExecutor(options?: { log?: boolean }): TaskExecutor {
|
||||
const log = options?.log ?? true;
|
||||
return {
|
||||
async submitTask(task: ForgeTask) {
|
||||
if (log) console.log(` [forge:simulated] stage submitted: ${task.id} (${task.title})`);
|
||||
},
|
||||
async waitForCompletion(taskId: string): Promise<ForgeTaskResult> {
|
||||
if (log) console.log(` [forge:simulated] stage complete: ${taskId}`);
|
||||
return {
|
||||
task_id: taskId,
|
||||
outcome: 'simulated',
|
||||
reason: 'no executor wired; simulated execution requested via --simulate',
|
||||
completed_at: new Date().toISOString(),
|
||||
exit_code: 0,
|
||||
gate_results: [],
|
||||
};
|
||||
},
|
||||
async getTaskStatus() {
|
||||
return 'completed' as const;
|
||||
},
|
||||
};
|
||||
}
|
||||
@@ -1,4 +1,4 @@
|
||||
import type { GateEntry } from '@mosaicstack/macp';
|
||||
import type { GateEntry, TaskResult } from '@mosaicstack/macp';
|
||||
|
||||
/** Stage dispatch mode. */
|
||||
export type StageDispatch = 'exec' | 'yolo' | 'pi';
|
||||
@@ -6,58 +6,6 @@ export type StageDispatch = 'exec' | 'yolo' | 'pi';
|
||||
/** Stage type — determines agent selection and gate requirements. */
|
||||
export type StageType = 'research' | 'review' | 'coding' | 'deploy';
|
||||
|
||||
/**
|
||||
* Typed outcome for every gate and stage evaluation — closed set (SDLC-D-035).
|
||||
*
|
||||
* Only `passed` means "verified by a real implementation". `simulated` is
|
||||
* produced exclusively in explicit `--simulate` runs and is never satisfying.
|
||||
*/
|
||||
export type ForgeOutcome =
|
||||
| 'passed'
|
||||
| 'failed'
|
||||
| 'blocked'
|
||||
| 'error'
|
||||
| 'waiting-for-authority'
|
||||
| 'simulated'
|
||||
| 'not-applicable';
|
||||
|
||||
/** A gate that requires authority (human/board) sign-off; no mechanical command can satisfy it. */
|
||||
export interface AuthorityGate {
|
||||
kind: 'authority';
|
||||
capability: string;
|
||||
reason: string;
|
||||
}
|
||||
|
||||
/** A gate that requires a wired provider (e.g. an AI reviewer, CI pipeline) to evaluate. */
|
||||
export interface ProviderGate {
|
||||
kind: 'provider';
|
||||
capability: string;
|
||||
reason: string;
|
||||
}
|
||||
|
||||
/** Forge quality gate: a real command, an authority sign-off, or a provider-backed check. */
|
||||
export type ForgeGate = string | GateEntry | AuthorityGate | ProviderGate;
|
||||
|
||||
/** Typed result of evaluating a single quality gate. */
|
||||
export interface ForgeGateResult {
|
||||
gate: string;
|
||||
outcome: ForgeOutcome;
|
||||
reason: string;
|
||||
exitCode?: number;
|
||||
output?: string;
|
||||
timedOut?: boolean;
|
||||
}
|
||||
|
||||
/** Typed result of a task/stage execution returned by a TaskExecutor. */
|
||||
export interface ForgeTaskResult {
|
||||
task_id: string;
|
||||
outcome: ForgeOutcome;
|
||||
reason: string;
|
||||
completed_at: string;
|
||||
exit_code: number;
|
||||
gate_results: ForgeGateResult[];
|
||||
}
|
||||
|
||||
/** Stage specification — defines a single pipeline stage. */
|
||||
export interface StageSpec {
|
||||
number: string;
|
||||
@@ -66,7 +14,7 @@ export interface StageSpec {
|
||||
type: StageType;
|
||||
gate: string;
|
||||
promptFile: string;
|
||||
qualityGates: ForgeGate[];
|
||||
qualityGates: (string | GateEntry)[];
|
||||
}
|
||||
|
||||
/** Brief classification. */
|
||||
@@ -77,18 +25,11 @@ export type ClassSource = 'cli' | 'frontmatter' | 'auto';
|
||||
|
||||
/** Per-stage status within a run manifest. */
|
||||
export interface StageStatus {
|
||||
status: 'pending' | 'in_progress' | ForgeOutcome;
|
||||
/** Why the stage reached its current (terminal) outcome, when applicable. */
|
||||
reason?: string;
|
||||
status: 'pending' | 'in_progress' | 'passed' | 'failed';
|
||||
startedAt?: string;
|
||||
completedAt?: string;
|
||||
/** Typed per-gate results recorded alongside the stage outcome. */
|
||||
gateResults?: ForgeGateResult[];
|
||||
}
|
||||
|
||||
/** Execution mode of a run. */
|
||||
export type RunMode = 'normal' | 'simulated';
|
||||
|
||||
/** Run manifest — persisted to disk as manifest.json. */
|
||||
export interface RunManifest {
|
||||
runId: string;
|
||||
@@ -97,23 +38,10 @@ export interface RunManifest {
|
||||
briefClass: BriefClass;
|
||||
classSource: ClassSource;
|
||||
forceBoard: boolean;
|
||||
/**
|
||||
* Execution mode. `simulated` runs stub execution; their results are typed
|
||||
* `simulated` and must never be read as verified success. Optional because
|
||||
* manifests written before this field existed default to `normal`.
|
||||
*/
|
||||
mode?: RunMode;
|
||||
createdAt: string;
|
||||
updatedAt: string;
|
||||
currentStage: string;
|
||||
status:
|
||||
| 'in_progress'
|
||||
| 'completed'
|
||||
| 'failed'
|
||||
| 'interrupted'
|
||||
| 'rejected'
|
||||
| 'simulated'
|
||||
| 'waiting-for-authority';
|
||||
status: 'in_progress' | 'completed' | 'failed' | 'interrupted' | 'rejected';
|
||||
stages: Record<string, StageStatus>;
|
||||
}
|
||||
|
||||
@@ -137,7 +65,7 @@ export interface ForgeTask {
|
||||
briefPath: string;
|
||||
resultPath: string;
|
||||
timeoutSeconds: number;
|
||||
qualityGates: ForgeGate[];
|
||||
qualityGates: (string | GateEntry)[];
|
||||
worktree?: string;
|
||||
command?: string;
|
||||
dependsOn?: string[];
|
||||
@@ -148,7 +76,7 @@ export interface ForgeTask {
|
||||
/** Abstract task executor — decouples from packages/coord. */
|
||||
export interface TaskExecutor {
|
||||
submitTask(task: ForgeTask): Promise<void>;
|
||||
waitForCompletion(taskId: string, timeoutMs: number): Promise<ForgeTaskResult>;
|
||||
waitForCompletion(taskId: string, timeoutMs: number): Promise<TaskResult>;
|
||||
getTaskStatus(taskId: string): Promise<ForgeTaskStatus>;
|
||||
}
|
||||
|
||||
@@ -194,16 +122,7 @@ export interface PipelineOptions {
|
||||
stages?: string[];
|
||||
skipTo?: string;
|
||||
dryRun?: boolean;
|
||||
/**
|
||||
* Real task executor. Required in normal mode: the pipeline fails closed
|
||||
* with FORGE_NO_EXECUTOR when it is absent.
|
||||
*/
|
||||
executor?: TaskExecutor;
|
||||
/**
|
||||
* Explicit opt-in to simulated execution. Every stage and gate result is
|
||||
* typed `simulated` and is never satisfying.
|
||||
*/
|
||||
simulate?: boolean;
|
||||
executor: TaskExecutor;
|
||||
}
|
||||
|
||||
/** Pipeline run result. */
|
||||
|
||||
@@ -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;
|
||||
|
||||
@@ -255,68 +255,6 @@ fleet_declared_transport() {
|
||||
printf '%s\n' "${declared:-tmux}"
|
||||
}
|
||||
|
||||
# Brain-home fleet-state resolution (#1298; canon STRUCTURE-CANON §2).
|
||||
#
|
||||
# Seat launch envs, roles.local overrides, and profile working copies resolve
|
||||
# from the brain home when one is active; roster, baseline roles, run/, and
|
||||
# services stay under MOSAIC_HOME. This check surfaces which tree fleet state
|
||||
# resolves from and the drift a launch would otherwise hit at runtime:
|
||||
#
|
||||
# - a stale MOSAIC_BRAIN_HOME pointing at a directory with no fleet/agents is a
|
||||
# misconfiguration the resolver honors (explicit wins) — warn, don't pass;
|
||||
# - a symlinked brain or agents dir defeats the managed-directory boundary;
|
||||
# - a group/world-readable agents dir violates the 0700 projection boundary;
|
||||
# - env files left in the config-home tree while a brain is active are split
|
||||
# state — the write path rejects NEW split writes, but nothing would ever
|
||||
# tell the operator the old files are stranded.
|
||||
resolve_brain_home() {
|
||||
local explicit="${MOSAIC_BRAIN_HOME:-}"
|
||||
if [[ -n "$(printf '%s' "$explicit" | tr -d '[:space:]')" ]]; then
|
||||
printf '%s' "$explicit"
|
||||
return
|
||||
fi
|
||||
if [[ "$(cd "$MOSAIC_HOME" 2>/dev/null && pwd -P)" == "$HOME/.config/mosaic" \
|
||||
&& -d "$HOME/.mosaic/fleet/agents" ]]; then
|
||||
printf '%s' "$HOME/.mosaic"
|
||||
return
|
||||
fi
|
||||
printf '%s' "$MOSAIC_HOME"
|
||||
}
|
||||
|
||||
check_brain_home() {
|
||||
local brain agents mode
|
||||
brain="$(resolve_brain_home)"
|
||||
|
||||
if [[ "$brain" == "$MOSAIC_HOME" ]]; then
|
||||
pass "Fleet state home: $MOSAIC_HOME (legacy single-tree; no brain adopted)"
|
||||
return
|
||||
fi
|
||||
|
||||
agents="$brain/fleet/agents"
|
||||
if [[ ! -d "$agents" ]]; then
|
||||
warn "Brain home '$brain' has no fleet/agents — seat envs will not resolve from it. Point MOSAIC_BRAIN_HOME at a brain carrying fleet/agents, or unset it."
|
||||
return
|
||||
fi
|
||||
if [[ -L "$brain" || -L "$agents" ]]; then
|
||||
warn "Brain fleet-state path resolves through a symlink ($brain) — the managed-directory boundary requires regular directories."
|
||||
return
|
||||
fi
|
||||
|
||||
mode="$(stat -c '%a' -- "$agents" 2>/dev/null)" || mode=""
|
||||
if [[ -n "$mode" ]] && (( (8#$mode & 8#077) != 0 )); then
|
||||
warn "Brain agents dir '$agents' is group/world-accessible (mode $mode) — the projection boundary requires 0700."
|
||||
return
|
||||
fi
|
||||
|
||||
if [[ -d "$MOSAIC_HOME/fleet/agents" ]] \
|
||||
&& ls "$MOSAIC_HOME/fleet/agents/"*.env* >/dev/null 2>&1; then
|
||||
warn "Fleet env files exist in BOTH trees — brain '$brain' is active but '$MOSAIC_HOME/fleet/agents' still carries env files (split state). Migrate them (mosaic fleet regen) and remove the config-home copies."
|
||||
return
|
||||
fi
|
||||
|
||||
pass "Fleet state home: $brain (brain active); roster + templates: $MOSAIC_HOME"
|
||||
}
|
||||
|
||||
check_fleet_transport() {
|
||||
local transport
|
||||
transport="$(fleet_declared_transport)"
|
||||
@@ -335,8 +273,6 @@ check_fleet_transport() {
|
||||
|
||||
check_fleet_transport
|
||||
|
||||
check_brain_home
|
||||
|
||||
# Legacy migration surfaces should no longer contain symlink trees.
|
||||
legacy_paths=(
|
||||
"$HOME/.claude/agent-guides"
|
||||
|
||||
@@ -1,108 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
# Covers the brain-home fleet-state check in `mosaic-doctor` (#1298 follow-up).
|
||||
#
|
||||
# The functions are extracted from the shipped script rather than copied here
|
||||
# (same discipline as test-fleet-transport-check.sh): a test that carries its
|
||||
# own copy of the logic keeps passing after the shipped copy changes.
|
||||
# Extraction is by exact function header and a closing brace in column one.
|
||||
set -euo pipefail
|
||||
|
||||
SCRIPT_DIR=$(cd -- "$(dirname "$0")" && pwd)
|
||||
DOCTOR="$SCRIPT_DIR/mosaic-doctor"
|
||||
|
||||
fail() {
|
||||
echo "FAIL: $*" >&2
|
||||
exit 1
|
||||
}
|
||||
|
||||
[ -f "$DOCTOR" ] || fail "missing mosaic-doctor at $DOCTOR"
|
||||
|
||||
extract_function() {
|
||||
local name="$1"
|
||||
local extracted
|
||||
extracted=$(sed -n "/^${name}() {/,/^}/p" "$DOCTOR")
|
||||
[ -n "$extracted" ] || fail "could not extract ${name}() from mosaic-doctor — script reshaped?"
|
||||
printf '%s\n' "$extracted"
|
||||
}
|
||||
|
||||
for fn in resolve_brain_home check_brain_home; do
|
||||
extract_function "$fn" >/dev/null
|
||||
done
|
||||
|
||||
warn_count=0
|
||||
warn() { warn_count=$((warn_count + 1)); echo "[WARN] $*"; }
|
||||
pass() { echo "[OK] $*"; return 0; }
|
||||
|
||||
eval "$(extract_function resolve_brain_home)"
|
||||
eval "$(extract_function check_brain_home)"
|
||||
|
||||
ROOT=$(mktemp -d)
|
||||
trap 'rm -rf "$ROOT"' EXIT
|
||||
|
||||
run_case() {
|
||||
# label, expect (ok|warn), then env assignments as arguments.
|
||||
# The check runs under `env` in a subshell, so its warn() also prints a
|
||||
# sentinel the parent counts — a subshell counter would never be visible.
|
||||
local label="$1" expect="$2"
|
||||
shift 2
|
||||
local out warns
|
||||
out=$(env "$@" bash -c "warn() { echo \"[WARN] \$*\"; }; pass() { echo \"[OK] \$*\"; return 0; }; $(extract_function resolve_brain_home); $(extract_function check_brain_home); check_brain_home" 2>&1)
|
||||
warns=$(printf '%s\n' "$out" | grep -c '^\[WARN\]' || true)
|
||||
if [[ "$expect" == ok && "$warns" -eq 0 ]]; then
|
||||
echo "ok - $label"
|
||||
elif [[ "$expect" == warn && "$warns" -gt 0 ]]; then
|
||||
echo "ok - $label (warned)"
|
||||
else
|
||||
echo "output: $out" >&2
|
||||
fail "$label: expected $expect (warns=$warns)"
|
||||
fi
|
||||
}
|
||||
|
||||
# ── legacy: no brain, custom home never adopts ─────────────────────────────
|
||||
mkdir -p "$ROOT/legacy-mosaic/fleet/agents"
|
||||
run_case "custom home without brain stays legacy" ok \
|
||||
MOSAIC_HOME="$ROOT/legacy-mosaic" HOME="$ROOT"
|
||||
|
||||
# ── healthy brain at the default config home ───────────────────────────────
|
||||
mkdir -p "$ROOT/home/.config/mosaic" "$ROOT/home/.mosaic/fleet/agents"
|
||||
chmod 700 "$ROOT/home/.mosaic/fleet/agents"
|
||||
run_case "default home adopts healthy brain" ok \
|
||||
MOSAIC_HOME="$ROOT/home/.config/mosaic" HOME="$ROOT/home"
|
||||
|
||||
# ── explicit MOSAIC_BRAIN_HOME to a brain without fleet/agents → warn ──────
|
||||
mkdir -p "$ROOT/brain-noagents/fleet" "$ROOT/config"
|
||||
run_case "explicit brain without agents warns" warn \
|
||||
MOSAIC_HOME="$ROOT/config" HOME="$ROOT" MOSAIC_BRAIN_HOME="$ROOT/brain-noagents"
|
||||
|
||||
# ── explicit MOSAIC_BRAIN_HOME to a healthy brain → ok ─────────────────────
|
||||
mkdir -p "$ROOT/brain-ok/fleet/agents" "$ROOT/config2"
|
||||
chmod 700 "$ROOT/brain-ok/fleet/agents"
|
||||
run_case "explicit healthy brain passes" ok \
|
||||
MOSAIC_HOME="$ROOT/config2" HOME="$ROOT" MOSAIC_BRAIN_HOME="$ROOT/brain-ok"
|
||||
|
||||
# ── group-readable agents dir → warn (0700 boundary) ───────────────────────
|
||||
mkdir -p "$ROOT/brain-loose/fleet/agents" "$ROOT/config3"
|
||||
chmod 750 "$ROOT/brain-loose/fleet/agents"
|
||||
run_case "group-readable brain agents warns" warn \
|
||||
MOSAIC_HOME="$ROOT/config3" HOME="$ROOT" MOSAIC_BRAIN_HOME="$ROOT/brain-loose"
|
||||
|
||||
# ── symlinked agents dir → warn (managed-directory boundary) ───────────────
|
||||
mkdir -p "$ROOT/brain-link/real-agents" "$ROOT/brain-link/fleet" "$ROOT/config4"
|
||||
ln -s "$ROOT/brain-link/real-agents" "$ROOT/brain-link/fleet/agents"
|
||||
run_case "symlinked brain agents warns" warn \
|
||||
MOSAIC_HOME="$ROOT/config4" HOME="$ROOT" MOSAIC_BRAIN_HOME="$ROOT/brain-link"
|
||||
|
||||
# ── split state: envs in BOTH trees → warn ─────────────────────────────────
|
||||
mkdir -p "$ROOT/brain-split/fleet/agents" "$ROOT/config5/fleet/agents"
|
||||
chmod 700 "$ROOT/brain-split/fleet/agents" "$ROOT/config5/fleet/agents"
|
||||
touch "$ROOT/config5/fleet/agents/coder0.env.generated"
|
||||
run_case "env files in both trees warns (split state)" warn \
|
||||
MOSAIC_HOME="$ROOT/config5" HOME="$ROOT" MOSAIC_BRAIN_HOME="$ROOT/brain-split"
|
||||
|
||||
# ── config-home agents dir WITHOUT env files alongside a brain → ok ────────
|
||||
mkdir -p "$ROOT/brain-clean/fleet/agents" "$ROOT/config6/fleet/agents"
|
||||
chmod 700 "$ROOT/brain-clean/fleet/agents" "$ROOT/config6/fleet/agents"
|
||||
run_case "empty config-home agents dir alongside brain passes" ok \
|
||||
MOSAIC_HOME="$ROOT/config6" HOME="$ROOT" MOSAIC_BRAIN_HOME="$ROOT/brain-clean"
|
||||
|
||||
echo "ok - mosaic-doctor brain-home check"
|
||||
@@ -25,7 +25,7 @@
|
||||
"lint": "eslint src",
|
||||
"typecheck": "tsc --noEmit",
|
||||
"test": "vitest run --passWithNoTests && pnpm run test:framework-shell",
|
||||
"test:framework-shell": "bash framework/tools/quality/scripts/check-test-enumeration.sh && bash framework/tools/quality/scripts/test-check-test-enumeration.sh && python3 src/lease-broker/daemon_deadline_unittest.py && python3 src/lease-broker/normative_fragments_unittest.py && python3 src/lease-broker/promotion_binding_unittest.py && python3 src/lease-broker/promotion_trigger_unittest.py && python3 src/lease-broker/receipt_challenge_unittest.py && python3 src/lease-broker/context_recovery_unittest.py && python3 src/lease-broker/recovery_runtime_unittest.py && python3 src/lease-broker/recovery_b1_adversarial_unittest.py && python3 src/lease-broker/receipt_observer_client_unittest.py && python3 src/lease-broker/invariant_r_unittest.py && python3 src/lease-broker/framework_skill_portability_unittest.py && python3 src/mutator-gate/runtime_tools_unittest.py && python3 src/mutator-gate/runtime_launch_guard_unittest.py && python3 src/mutator-gate/version_coupling_unittest.py && python3 framework/tools/lease-broker/check-runtime-launches.py --root ../.. && bash framework/tools/codex/test-pr-diff-context.sh && bash framework/tools/qa/test-deps-preflight.sh && bash framework/tools/git/test-pr-review-gitea-comment.sh && bash framework/tools/git/test-pr-review-repo-host-override.sh && bash framework/tools/git/test-ci-queue-wait-branch-absent.sh && bash framework/tools/git/test-ci-queue-wait-tristate.sh && bash framework/tools/git/test-ci-queue-wait-github-checks.sh && bash framework/tools/git/test-pr-merge-queue-branch.sh && bash framework/tools/git/test-pr-merge-head-pin.sh && bash framework/tools/git/test-pr-merge-message-field.sh && bash framework/tools/git/test-git-credential-mosaic.sh && bash framework/tools/git/test-gitea-token-identity.sh && bash framework/tools/woodpecker/test-terminal-green-contract.sh && bash framework/tools/_scripts/test-install-ordering-guard.sh && bash framework/tools/_scripts/test-mosaic-init-rce.sh && bash framework/tools/tmux/agent-send.test.sh && bash framework/tools/wake/test-wake-store-ack.sh && bash framework/tools/wake/test-wake-store-enqueue-race.sh && bash framework/tools/wake/test-wake-digest-hmac.sh && bash framework/tools/wake/test-wake-digest-quarantine.sh && bash framework/tools/wake/test-wake-detector.sh && bash framework/tools/wake/test-wake-fn-oracle.sh && bash framework/tools/wake/test-wake-reconcile.sh && bash framework/tools/wake/test-wake-beacon.sh && bash framework/tools/wake/test-wake-preimage.sh && bash framework/tools/wake/test-wake-install.sh && bash framework/tools/glpi/test-list-http-status.sh && bash framework/tools/orchestrator/test-board-roll.sh && bash framework/tools/woodpecker/test-ci-wait-exit-matrix.sh && bash framework/tools/_scripts/test-fleet-transport-check.sh && bash framework/tools/_scripts/test-brain-home-check.sh"
|
||||
"test:framework-shell": "bash framework/tools/quality/scripts/check-test-enumeration.sh && bash framework/tools/quality/scripts/test-check-test-enumeration.sh && python3 src/lease-broker/daemon_deadline_unittest.py && python3 src/lease-broker/normative_fragments_unittest.py && python3 src/lease-broker/promotion_binding_unittest.py && python3 src/lease-broker/promotion_trigger_unittest.py && python3 src/lease-broker/receipt_challenge_unittest.py && python3 src/lease-broker/context_recovery_unittest.py && python3 src/lease-broker/recovery_runtime_unittest.py && python3 src/lease-broker/recovery_b1_adversarial_unittest.py && python3 src/lease-broker/receipt_observer_client_unittest.py && python3 src/lease-broker/invariant_r_unittest.py && python3 src/lease-broker/framework_skill_portability_unittest.py && python3 src/mutator-gate/runtime_tools_unittest.py && python3 src/mutator-gate/runtime_launch_guard_unittest.py && python3 src/mutator-gate/version_coupling_unittest.py && python3 framework/tools/lease-broker/check-runtime-launches.py --root ../.. && bash framework/tools/codex/test-pr-diff-context.sh && bash framework/tools/qa/test-deps-preflight.sh && bash framework/tools/git/test-pr-review-gitea-comment.sh && bash framework/tools/git/test-pr-review-repo-host-override.sh && bash framework/tools/git/test-ci-queue-wait-branch-absent.sh && bash framework/tools/git/test-ci-queue-wait-tristate.sh && bash framework/tools/git/test-ci-queue-wait-github-checks.sh && bash framework/tools/git/test-pr-merge-queue-branch.sh && bash framework/tools/git/test-pr-merge-head-pin.sh && bash framework/tools/git/test-pr-merge-message-field.sh && bash framework/tools/git/test-git-credential-mosaic.sh && bash framework/tools/git/test-gitea-token-identity.sh && bash framework/tools/woodpecker/test-terminal-green-contract.sh && bash framework/tools/_scripts/test-install-ordering-guard.sh && bash framework/tools/_scripts/test-mosaic-init-rce.sh && bash framework/tools/tmux/agent-send.test.sh && bash framework/tools/wake/test-wake-store-ack.sh && bash framework/tools/wake/test-wake-store-enqueue-race.sh && bash framework/tools/wake/test-wake-digest-hmac.sh && bash framework/tools/wake/test-wake-digest-quarantine.sh && bash framework/tools/wake/test-wake-detector.sh && bash framework/tools/wake/test-wake-fn-oracle.sh && bash framework/tools/wake/test-wake-reconcile.sh && bash framework/tools/wake/test-wake-beacon.sh && bash framework/tools/wake/test-wake-preimage.sh && bash framework/tools/wake/test-wake-install.sh && bash framework/tools/glpi/test-list-http-status.sh && bash framework/tools/orchestrator/test-board-roll.sh && bash framework/tools/woodpecker/test-ci-wait-exit-matrix.sh && bash framework/tools/_scripts/test-fleet-transport-check.sh"
|
||||
},
|
||||
"dependencies": {
|
||||
"@mosaicstack/brain": "workspace:*",
|
||||
|
||||
@@ -1,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,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
|
||||
Reference in New Issue
Block a user