@dailephd/my-frontend-observer 0.8.1

package/dist/application/frontendContractPersistenceService.d.ts

@@ -0,0 +1,56 @@
+import type { Diagnostic } from '../domain/diagnostics.js';
+import type { WriteFrontendContractArtifactOptions } from '../artifacts/frontendContractArtifactWriter.js';
+export interface PersistFrontendContractOptions {
+    outputLocation: string;
+    cwd?: WriteFrontendContractArtifactOptions['cwd'];
+}
+export type ApplicationApproveBaselineResult = {
+    ok: true;
+    baselineId: string;
+    supersedesBaselineId?: string;
+    artifactRoot: string;
+    manifestPath: string;
+    clauseCount: number;
+} | {
+    ok: false;
+    diagnostics: Diagnostic[];
+};
+export type ApplicationPersistChangeContractResult = {
+    ok: true;
+    contractId: string;
+    artifactRoot: string;
+    manifestPath: string;
+    clauseCount: number;
+    supersedesBaselineClauseCount: number;
+} | {
+    ok: false;
+    diagnostics: Diagnostic[];
+};
+/**
+ * The one canonical application-level baseline-approval use case: `approve-baseline`
+ * is the *only* place a baseline is ever approved (see governing scope) - this
+ * function is never called from `observe`/`compare`/`evaluate-contract`, and a
+ * `PASS` evaluation never triggers it. Validates the raw (still-`unknown`,
+ * freshly-parsed-JSON) baseline through the existing frozen
+ * `isValidPersistentBaselineContract` structural gate (never a second
+ * validator), reads the supplied observation through the existing
+ * `readObservationArtifact` reader, verifies the baseline's frozen
+ * `sourceObservation` reference actually corresponds to that observation's
+ * stable identity, and - only then - persists exactly once through the
+ * existing contract writer. Never mutates the observation. Never infers,
+ * creates, or removes `supersedesBaselineId` - whatever the caller already
+ * authored is preserved exactly.
+ */
+export declare function approveAndPersistBaseline(rawContract: unknown, observationRoot: string, options: PersistFrontendContractOptions): Promise<ApplicationApproveBaselineResult>;
+/**
+ * The one canonical application-level per-change-contract persistence use
+ * case (`save-change-contract`) - persistence only, never approval
+ * terminology or semantics. Validates the raw contract through the existing
+ * frozen `isValidPerChangeContract` gate (which already rejects a
+ * `PersistentBaselineContract` passed here, an authored `category:
+ * "unexpected"`, and every other structural rule - never duplicated here),
+ * then persists exactly once. `supersedesBaselineClauseIds` is preserved
+ * exactly as authored; this function performs no baseline-reference
+ * resolution (that remains the evaluator's responsibility).
+ */
+export declare function persistPerChangeContract(rawContract: unknown, options: PersistFrontendContractOptions): Promise<ApplicationPersistChangeContractResult>;

package/dist/application/frontendContractPersistenceService.js

@@ -0,0 +1,91 @@
+import path from 'node:path';
+import { isValidPersistentBaselineContract, isValidPerChangeContract } from '../domain/frontendContracts.js';
+import { DIAGNOSTIC_SEVERITY } from '../domain/diagnostics.js';
+import { normalizeOutputLocation } from '../request/paths.js';
+import { writePersistentBaselineContract, writePerChangeContract } from '../artifacts/frontendContractArtifactWriter.js';
+import { readObservationArtifact } from '../artifacts/artifactReader.js';
+import { MANIFEST_FILENAME as OBSERVATION_MANIFEST_FILENAME } from '../artifacts/artifactWriter.js';
+function invalidRequest(message) {
+    return { ok: false, diagnostics: [{ code: 'invalid-request', severity: DIAGNOSTIC_SEVERITY['invalid-request'], message }] };
+}
+/**
+ * The one canonical application-level baseline-approval use case: `approve-baseline`
+ * is the *only* place a baseline is ever approved (see governing scope) - this
+ * function is never called from `observe`/`compare`/`evaluate-contract`, and a
+ * `PASS` evaluation never triggers it. Validates the raw (still-`unknown`,
+ * freshly-parsed-JSON) baseline through the existing frozen
+ * `isValidPersistentBaselineContract` structural gate (never a second
+ * validator), reads the supplied observation through the existing
+ * `readObservationArtifact` reader, verifies the baseline's frozen
+ * `sourceObservation` reference actually corresponds to that observation's
+ * stable identity, and - only then - persists exactly once through the
+ * existing contract writer. Never mutates the observation. Never infers,
+ * creates, or removes `supersedesBaselineId` - whatever the caller already
+ * authored is preserved exactly.
+ */
+export async function approveAndPersistBaseline(rawContract, observationRoot, options) {
+    const validation = isValidPersistentBaselineContract(rawContract);
+    if (!validation.valid)
+        return invalidRequest(`baseline contract is invalid: ${validation.reason}`);
+    const contract = rawContract;
+    const observationRead = await readObservationArtifact(path.join(observationRoot, OBSERVATION_MANIFEST_FILENAME));
+    if (!observationRead.ok)
+        return invalidRequest(`observation artifact: ${observationRead.reason}`);
+    const observation = observationRead.artifact;
+    const ref = contract.sourceObservation;
+    const matchesObservation = ref.observationId === observation.observationId &&
+        ref.requestId === observation.requestId &&
+        ref.producer.name === observation.producer.name &&
+        ref.producer.version === observation.producer.version &&
+        ref.observationSchemaVersion === observation.schemaVersion;
+    if (!matchesObservation) {
+        return invalidRequest('baseline contract sourceObservation does not match the supplied observation artifact; refusing to approve an unrelated observation');
+    }
+    const normalized = normalizeOutputLocation(options.outputLocation);
+    if (!normalized.ok)
+        return { ok: false, diagnostics: [normalized.diagnostic] };
+    const persisted = await writePersistentBaselineContract(contract, normalized.value, options.cwd === undefined ? {} : { cwd: options.cwd });
+    if (!persisted.ok)
+        return { ok: false, diagnostics: persisted.diagnostics };
+    return {
+        ok: true,
+        baselineId: contract.baselineId,
+        ...(contract.supersedesBaselineId === undefined ? {} : { supersedesBaselineId: contract.supersedesBaselineId }),
+        artifactRoot: persisted.artifactRoot,
+        manifestPath: persisted.manifestPath,
+        clauseCount: contract.clauses.length,
+    };
+}
+/**
+ * The one canonical application-level per-change-contract persistence use
+ * case (`save-change-contract`) - persistence only, never approval
+ * terminology or semantics. Validates the raw contract through the existing
+ * frozen `isValidPerChangeContract` gate (which already rejects a
+ * `PersistentBaselineContract` passed here, an authored `category:
+ * "unexpected"`, and every other structural rule - never duplicated here),
+ * then persists exactly once. `supersedesBaselineClauseIds` is preserved
+ * exactly as authored; this function performs no baseline-reference
+ * resolution (that remains the evaluator's responsibility).
+ */
+export async function persistPerChangeContract(rawContract, options) {
+    const validation = isValidPerChangeContract(rawContract);
+    if (!validation.valid)
+        return invalidRequest(`per-change contract is invalid: ${validation.reason}`);
+    const contract = rawContract;
+    const normalized = normalizeOutputLocation(options.outputLocation);
+    if (!normalized.ok)
+        return { ok: false, diagnostics: [normalized.diagnostic] };
+    const persisted = await writePerChangeContract(contract, normalized.value, options.cwd === undefined ? {} : { cwd: options.cwd });
+    if (!persisted.ok)
+        return { ok: false, diagnostics: persisted.diagnostics };
+    const supersedesBaselineClauseCount = contract.clauses.reduce((count, clause) => count + (clause.supersedesBaselineClauseIds?.length ?? 0), 0);
+    return {
+        ok: true,
+        contractId: contract.contractId,
+        artifactRoot: persisted.artifactRoot,
+        manifestPath: persisted.manifestPath,
+        clauseCount: contract.clauses.length,
+        supersedesBaselineClauseCount,
+    };
+}
+//# sourceMappingURL=frontendContractPersistenceService.js.map

package/dist/application/frontendContractPersistenceService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontendContractPersistenceService.js","sourceRoot":"","sources":["../../src/application/frontendContractPersistenceService.ts"],"names":[],"mappings":"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"}

package/dist/application/observationPersistence.d.ts

@@ -0,0 +1,59 @@
+import type { NormalizedObservationRequest } from '../request/request.js';
+import type { BrowserCaptureResult } from '../browser/types.js';
+import type { ObservationArtifact } from '../domain/schema.js';
+import type { CompletionState } from '../domain/completion.js';
+import type { Diagnostic } from '../domain/diagnostics.js';
+import type { PersistedObservationResult } from '../artifacts/types.js';
+import type { WriteObservationArtifactOptions } from '../artifacts/artifactWriter.js';
+export type { PersistedObservationResult } from '../artifacts/types.js';
+/**
+ * Assembles the frozen ObservationArtifact shape from one already-successful
+ * Batch 2/3 browser capture. Pure - no filesystem access, no Playwright
+ * dependency - so it is testable independently of both Chromium and disk
+ * I/O. `requestId`/`observationId` reuse the existing Batch 1 identity
+ * functions verbatim; `completion` reuses the existing Batch 1
+ * post-capture completion rule over the capture's own diagnostics.
+ */
+export declare function buildObservationArtifact(capture: Extract<BrowserCaptureResult, {
+    ok: true;
+}>, request: NormalizedObservationRequest): ObservationArtifact;
+/**
+ * Minimum application-facing persistence seam for Batch 5: combines an
+ * existing successful browser capture with the artifact writer. Not wired to
+ * the CLI in this batch.
+ */
+export declare function persistBrowserCapture(capture: Extract<BrowserCaptureResult, {
+    ok: true;
+}>, request: NormalizedObservationRequest, options?: WriteObservationArtifactOptions): Promise<PersistedObservationResult>;
+/**
+ * Observer-owned summary of one full observation attempt, with just enough
+ * information for a presentation layer (the Batch 5 CLI) to report a result
+ * without ever seeing a Playwright object, a raw Node filesystem exception,
+ * or persistence implementation detail.
+ */
+export type ApplicationObservationResult = {
+    ok: true;
+    observationId: string;
+    requestId: string;
+    completion: CompletionState;
+    artifactRoot: string;
+    manifestPath: string;
+    screenshotPath: string;
+    targetCount: number;
+    diagnostics: Diagnostic[];
+} | {
+    ok: false;
+    diagnostics: Diagnostic[];
+};
+/**
+ * The one canonical application-level observation use case: takes an
+ * already-normalized request, runs the existing browser capture exactly
+ * once, and - only for a successful capture - persists it exactly once
+ * through the existing artifact writer. Reuses `runBrowserCapture`,
+ * `buildObservationArtifact`, and `writeObservationArtifact` verbatim; it
+ * does not go through `persistBrowserCapture` because that helper re-derives
+ * a fresh `ObservationArtifact` (and therefore a fresh, different
+ * `observationId`) internally, which would desync the identity a caller
+ * inspects here from the identity actually written to disk.
+ */
+export declare function observe(request: NormalizedObservationRequest, options?: WriteObservationArtifactOptions): Promise<ApplicationObservationResult>;

package/dist/application/observationPersistence.js

@@ -0,0 +1,79 @@
+import { runBrowserCapture } from './browserCaptureService.js';
+import { ARTIFACT_KIND, SCHEMA_VERSION, getProducerInfo } from '../domain/schema.js';
+import { buildRequestIdentity, buildObservationIdentity } from '../domain/identity.js';
+import { deriveCompletion } from '../domain/completion.js';
+import { writeObservationArtifact, SCREENSHOT_FILENAME } from '../artifacts/artifactWriter.js';
+/**
+ * Assembles the frozen ObservationArtifact shape from one already-successful
+ * Batch 2/3 browser capture. Pure - no filesystem access, no Playwright
+ * dependency - so it is testable independently of both Chromium and disk
+ * I/O. `requestId`/`observationId` reuse the existing Batch 1 identity
+ * functions verbatim; `completion` reuses the existing Batch 1
+ * post-capture completion rule over the capture's own diagnostics.
+ */
+export function buildObservationArtifact(capture, request) {
+    const requestId = buildRequestIdentity(request);
+    const observationId = buildObservationIdentity(requestId);
+    const completion = deriveCompletion(capture.diagnostics, 'post-capture');
+    return {
+        artifactKind: ARTIFACT_KIND,
+        schemaVersion: SCHEMA_VERSION,
+        observationId,
+        requestId,
+        producer: getProducerInfo(),
+        browser: { state: 'available', source: 'browser', value: capture.provenance },
+        requestConfig: request,
+        provenance: { capturedAt: new Date().toISOString(), observationMethod: 'chromium-navigate-and-capture' },
+        pageEvidence: capture.pageEvidence,
+        targetEvidence: capture.targetEvidence,
+        ...(capture.scrollScenarioEvidence ? { scrollScenarioEvidence: capture.scrollScenarioEvidence } : {}),
+        screenshot: { state: 'available', source: 'browser', value: { path: SCREENSHOT_FILENAME } },
+        completion,
+        diagnostics: capture.diagnostics,
+        limits: { truncated: false, omittedFields: [], omittedTargets: [] },
+        artifactReferences: [{ path: SCREENSHOT_FILENAME, kind: 'screenshot' }],
+    };
+}
+/**
+ * Minimum application-facing persistence seam for Batch 5: combines an
+ * existing successful browser capture with the artifact writer. Not wired to
+ * the CLI in this batch.
+ */
+export async function persistBrowserCapture(capture, request, options = {}) {
+    const artifact = buildObservationArtifact(capture, request);
+    return writeObservationArtifact(artifact, capture.screenshot, options);
+}
+/**
+ * The one canonical application-level observation use case: takes an
+ * already-normalized request, runs the existing browser capture exactly
+ * once, and - only for a successful capture - persists it exactly once
+ * through the existing artifact writer. Reuses `runBrowserCapture`,
+ * `buildObservationArtifact`, and `writeObservationArtifact` verbatim; it
+ * does not go through `persistBrowserCapture` because that helper re-derives
+ * a fresh `ObservationArtifact` (and therefore a fresh, different
+ * `observationId`) internally, which would desync the identity a caller
+ * inspects here from the identity actually written to disk.
+ */
+export async function observe(request, options = {}) {
+    const capture = await runBrowserCapture(request);
+    if (!capture.ok) {
+        return { ok: false, diagnostics: capture.diagnostics };
+    }
+    const artifact = buildObservationArtifact(capture, request);
+    const persisted = await writeObservationArtifact(artifact, capture.screenshot, options);
+    if (!persisted.ok) {
+        return { ok: false, diagnostics: persisted.diagnostics };
+    }
+    return {
+        ok: true,
+        observationId: artifact.observationId,
+        requestId: artifact.requestId,
+        completion: artifact.completion,
+        artifactRoot: persisted.artifactRoot,
+        manifestPath: persisted.manifestPath,
+        screenshotPath: persisted.screenshotPath,
+        targetCount: Object.keys(artifact.targetEvidence).length,
+        diagnostics: artifact.diagnostics,
+    };
+}
+//# sourceMappingURL=observationPersistence.js.map

package/dist/application/observationPersistence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observationPersistence.js","sourceRoot":"","sources":["../../src/application/observationPersistence.ts"],"names":[],"mappings":"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"}

package/dist/application/projectCheckService.d.ts

@@ -0,0 +1,3 @@
+import { type CheckWorkflowResult } from '../projectWorkflow/checkResult.js';
+/** Compose existing canonical capture/comparison/contract/reference owners into one project workflow. */
+export declare function checkProject(projectRoot: string, requestedBaseline?: string): Promise<CheckWorkflowResult>;

package/dist/application/projectCheckService.js

@@ -0,0 +1,169 @@
+import path from 'node:path';
+import { readProjectConfig } from '../projectWorkflow/projectConfig.js';
+import { aliasCatalogPath, projectConfigPath, projectEvidenceRoot } from '../projectWorkflow/projectPaths.js';
+import { readAliasCatalog } from '../projectWorkflow/aliasCatalog.js';
+import { loadBindingsFile, loadComparisonConfigFile, resolveContainedAcceptancePath } from '../projectWorkflow/checkAcceptance.js';
+import { readObservationArtifact } from '../artifacts/artifactReader.js';
+import { readFrontendContractEvaluationArtifact } from '../artifacts/frontendContractEvaluationArtifactReader.js';
+import { readPersistentBaselineContract, readPerChangeContract } from '../artifacts/frontendContractArtifactReader.js';
+import { readExternalReferenceArtifact } from '../artifacts/externalReferenceArtifactReader.js';
+import { compareAndPersistFromArtifactRoots } from './comparisonService.js';
+import { evaluateAndPersistFromArtifactRoots } from './frontendContractEvaluationService.js';
+import { evaluateReferenceCandidateFidelityFromArtifactRoots } from './referenceFidelityEvaluationService.js';
+import { captureCurrentObservation } from './projectWorkflowService.js';
+import { emptyCheckResult, finalizeCheckStatus, projectContractResult, projectReferenceResult, } from '../projectWorkflow/checkResult.js';
+function projectRelative(projectRoot, absolutePath) {
+    return path.relative(projectRoot, absolutePath).split(path.sep).join('/');
+}
+function addBlocker(result, code, message) {
+    result.blockers.push({ code, message });
+}
+async function prepareAcceptance(projectRoot, config) {
+    const prepared = {};
+    if (config.comparisonConfigFile !== undefined) {
+        const resolved = resolveContainedAcceptancePath(projectRoot, config.comparisonConfigFile);
+        if (!resolved.ok)
+            return { ok: false, code: 'acceptance-config-invalid', message: resolved.error };
+        const loaded = loadComparisonConfigFile(resolved.path);
+        if (!loaded.ok)
+            return { ok: false, code: 'acceptance-config-invalid', message: loaded.error };
+        prepared.comparisonConfig = loaded.config;
+    }
+    if (config.contract !== undefined) {
+        const baselineRoot = resolveContainedAcceptancePath(projectRoot, config.contract.baselineArtifact);
+        const changeRoot = resolveContainedAcceptancePath(projectRoot, config.contract.changeArtifact);
+        if (!baselineRoot.ok || !changeRoot.ok)
+            return { ok: false, code: 'acceptance-config-invalid', message: 'configured contract artifact path is invalid or outside the project' };
+        const baseline = await readPersistentBaselineContract(path.join(baselineRoot.path, 'manifest.json'));
+        const change = await readPerChangeContract(path.join(changeRoot.path, 'manifest.json'));
+        if (!baseline.ok || !change.ok)
+            return { ok: false, code: 'acceptance-config-invalid', message: 'configured contract artifact is invalid' };
+        prepared.contract = { baselineRoot: baselineRoot.path, changeRoot: changeRoot.path, baseline: baseline.contract, change: change.contract };
+    }
+    if (config.reference !== undefined) {
+        const referenceRoot = resolveContainedAcceptancePath(projectRoot, config.reference.approvedArtifact);
+        if (!referenceRoot.ok)
+            return { ok: false, code: 'acceptance-config-invalid', message: referenceRoot.error };
+        const reference = await readExternalReferenceArtifact(path.join(referenceRoot.path, 'manifest.json'));
+        if (!reference.ok)
+            return { ok: false, code: 'acceptance-config-invalid', message: 'configured reference artifact is invalid' };
+        if (reference.artifact.lifecycle.state !== 'approved')
+            return { ok: false, code: 'reference-not-approved', message: 'configured reference is not approved' };
+        let bindings = [];
+        if (config.reference.bindingsFile !== undefined) {
+            const bindingsPath = resolveContainedAcceptancePath(projectRoot, config.reference.bindingsFile);
+            if (!bindingsPath.ok)
+                return { ok: false, code: 'acceptance-config-invalid', message: bindingsPath.error };
+            const loaded = loadBindingsFile(bindingsPath.path);
+            if (!loaded.ok)
+                return { ok: false, code: 'acceptance-config-invalid', message: loaded.error };
+            bindings = loaded.bindings;
+        }
+        prepared.reference = { root: referenceRoot.path, bindings: bindings };
+    }
+    return { ok: true, value: prepared };
+}
+/** Compose existing canonical capture/comparison/contract/reference owners into one project workflow. */
+export async function checkProject(projectRoot, requestedBaseline) {
+    const result = emptyCheckResult();
+    const configRead = await readProjectConfig(projectConfigPath(projectRoot));
+    if (!configRead.ok) {
+        addBlocker(result, 'acceptance-config-invalid', 'project configuration is invalid');
+        return finalizeCheckStatus(result);
+    }
+    const config = configRead.config;
+    result.contract.configured = config.acceptance?.contract !== undefined;
+    result.contract.state = result.contract.configured ? 'NOT_RUN' : 'NOT_CONFIGURED';
+    result.reference.configured = config.acceptance?.reference !== undefined;
+    result.reference.state = result.reference.configured ? 'NOT_RUN' : 'NOT_CONFIGURED';
+    const catalogRead = await readAliasCatalog(aliasCatalogPath(projectRoot));
+    if (!catalogRead.ok) {
+        addBlocker(result, 'baseline-artifact-invalid', 'project alias catalog is invalid');
+        return finalizeCheckStatus(result);
+    }
+    const baselineAlias = requestedBaseline ?? config.defaultBaseline;
+    const baselineRecord = catalogRead.catalog.observations[baselineAlias];
+    if (baselineRecord === undefined) {
+        addBlocker(result, 'baseline-alias-not-found', `baseline alias "${baselineAlias}" was not found`);
+        return finalizeCheckStatus(result);
+    }
+    const evidenceRoot = projectEvidenceRoot(projectRoot);
+    const baselineRoot = path.join(evidenceRoot, ...baselineRecord.relativeArtifactDir.split('/'));
+    const baselineRead = await readObservationArtifact(path.join(baselineRoot, 'manifest.json'));
+    if (!baselineRead.ok || baselineRead.artifact.observationId !== baselineRecord.observationId || baselineRead.artifact.requestId !== baselineRecord.requestId) {
+        addBlocker(result, 'baseline-artifact-invalid', 'baseline alias does not resolve to the declared canonical observation identity');
+        return finalizeCheckStatus(result);
+    }
+    result.baseline = { alias: baselineAlias, observationId: baselineRecord.observationId, requestId: baselineRecord.requestId, artifactPath: projectRelative(projectRoot, baselineRoot) };
+    const acceptance = config.acceptance === undefined ? { ok: true, value: {} } : await prepareAcceptance(projectRoot, config.acceptance);
+    if (!acceptance.ok) {
+        addBlocker(result, acceptance.code, acceptance.message);
+        if (acceptance.code === 'reference-not-approved')
+            result.reference.state = 'BLOCKED';
+        return finalizeCheckStatus(result);
+    }
+    const captured = await captureCurrentObservation(projectRoot);
+    if (!captured.ok) {
+        addBlocker(result, 'candidate-capture-failed', 'current candidate capture failed; the previous current alias was preserved');
+        return finalizeCheckStatus(result);
+    }
+    result.candidate = { alias: 'current', observationId: captured.observationId, requestId: captured.requestId, artifactPath: projectRelative(projectRoot, captured.artifactRoot) };
+    const compared = await compareAndPersistFromArtifactRoots(baselineRoot, captured.artifactRoot, {
+        ...(acceptance.value.comparisonConfig === undefined ? {} : { config: acceptance.value.comparisonConfig }),
+        outputLocation: `.frontend-observer/evidence/comparisons/${baselineAlias}-vs-current`,
+        cwd: projectRoot,
+    });
+    if (!compared.ok) {
+        result.comparison = { state: 'BLOCKED' };
+        addBlocker(result, 'comparison-failed', 'canonical comparison could not be constructed');
+    }
+    else {
+        result.comparison = {
+            state: compared.comparability,
+            comparisonId: compared.comparisonId,
+            artifactPath: projectRelative(projectRoot, compared.artifactRoot),
+            differenceCount: compared.differenceCount,
+            relationshipChangeCount: compared.relationshipChangeCount,
+            diagnosticsCount: compared.diagnosticsCount,
+        };
+        if (compared.comparability === 'incomparable')
+            addBlocker(result, 'comparison-incomparable', 'canonical comparison is incomparable');
+        if (acceptance.value.contract !== undefined && compared.comparability !== 'incomparable') {
+            const contract = acceptance.value.contract;
+            const evaluated = await evaluateAndPersistFromArtifactRoots(baselineRoot, captured.artifactRoot, compared.artifactRoot, contract.baselineRoot, contract.changeRoot, { outputLocation: `.frontend-observer/evidence/evaluations/${baselineAlias}-vs-current`, cwd: projectRoot });
+            if (!evaluated.ok) {
+                result.contract.state = 'BLOCKED';
+                addBlocker(result, 'contract-evaluation-failed', 'canonical frontend-contract evaluation could not be constructed');
+            }
+            else {
+                const persisted = await readFrontendContractEvaluationArtifact(evaluated.manifestPath);
+                if (!persisted.ok) {
+                    result.contract.state = 'BLOCKED';
+                    addBlocker(result, 'contract-evaluation-failed', 'persisted frontend-contract evaluation is invalid');
+                }
+                else {
+                    result.contract = projectContractResult(persisted.artifact, contract.baseline.clauses, contract.change.clauses, projectRelative(projectRoot, evaluated.artifactRoot));
+                    if (result.contract.state === 'BLOCKED')
+                        addBlocker(result, 'contract-evidence-unavailable', 'contract evidence is unavailable or conflicting');
+                }
+            }
+        }
+    }
+    if (acceptance.value.reference !== undefined) {
+        const reference = acceptance.value.reference;
+        const evaluated = await evaluateReferenceCandidateFidelityFromArtifactRoots(reference.root, captured.artifactRoot, reference.bindings);
+        if (!evaluated.ok) {
+            result.reference.state = 'BLOCKED';
+            addBlocker(result, 'reference-evaluation-failed', 'canonical reference-fidelity evaluation could not be constructed');
+        }
+        else {
+            result.reference = projectReferenceResult(evaluated.evaluation);
+            if (evaluated.evaluation.state === 'not-evaluated')
+                addBlocker(result, 'reference-not-evaluated', 'reference fidelity was not evaluated');
+            else if (result.reference.unavailableRequirements.length > 0)
+                addBlocker(result, 'reference-evidence-unavailable', 'required reference evidence is unavailable');
+        }
+    }
+    return finalizeCheckStatus(result);
+}
+//# sourceMappingURL=projectCheckService.js.map

package/dist/application/projectCheckService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"projectCheckService.js","sourceRoot":"","sources":["../../src/application/projectCheckService.ts"],"names":[],"mappings":"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"}

package/dist/application/projectWorkflowService.d.ts

@@ -0,0 +1,46 @@
+import type { Diagnostic } from '../domain/diagnostics.js';
+import type { RawNamedTarget } from '../request/request.js';
+export type ProjectWorkflowErrorCode = 'project-not-initialized' | 'project-config-exists' | 'project-config-invalid' | 'project-catalog-invalid' | 'alias-invalid' | 'alias-reserved' | 'alias-exists' | 'project-state-write-failure' | 'observation-failure';
+type WorkflowFailure = {
+    ok: false;
+    code: ProjectWorkflowErrorCode;
+    message: string;
+    diagnostics?: readonly Diagnostic[];
+};
+export interface InitializeProjectInput {
+    projectRoot: string;
+    url: string;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    targets: RawNamedTarget[];
+    defaultBaseline?: string;
+    replace: boolean;
+}
+export declare function initializeFrontendObserverProject(input: InitializeProjectInput): Promise<{
+    ok: true;
+    configPath: string;
+} | WorkflowFailure>;
+export interface CaptureNamedObservationInput {
+    projectRoot: string;
+    alias: string;
+    replace: boolean;
+}
+export type CaptureNamedObservationResult = {
+    ok: true;
+    alias: string;
+    observationId: string;
+    requestId: string;
+    artifactRoot: string;
+    completionState: string;
+    diagnostics: readonly Diagnostic[];
+} | WorkflowFailure;
+export declare function captureNamedObservation(input: CaptureNamedObservationInput): Promise<CaptureNamedObservationResult>;
+export declare function captureCurrentObservation(projectRoot: string): Promise<CaptureNamedObservationResult>;
+export declare function loadProjectViewerState(projectRoot: string): Promise<{
+    ok: true;
+    root: string;
+    aliases: Readonly<Record<string, string>>;
+} | WorkflowFailure>;
+export {};

package/dist/application/projectWorkflowService.js

@@ -0,0 +1,92 @@
+import { access, mkdir, readFile, writeFile, rename, rm } from 'node:fs/promises';
+import path from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { normalizeRequest } from '../request/request.js';
+import { observe } from './observationPersistence.js';
+import { PROJECT_CONFIG_SCHEMA_VERSION, readProjectConfig, validateObservationAlias, validateProjectConfig } from '../projectWorkflow/projectConfig.js';
+import { ALIAS_CATALOG_SCHEMA_VERSION, readAliasCatalog, writeAliasCatalog } from '../projectWorkflow/aliasCatalog.js';
+import { aliasCatalogPath, observationOutputLocation, projectConfigPath, projectEvidenceRoot } from '../projectWorkflow/projectPaths.js';
+async function exists(file) { return access(file).then(() => true, () => false); }
+async function atomicTextWrite(file, text) {
+    const temp = `${file}.tmp-${process.pid}-${randomBytes(6).toString('hex')}`;
+    try {
+        await writeFile(temp, text, 'utf8');
+        await rename(temp, file);
+    }
+    catch (error) {
+        await rm(temp, { force: true }).catch(() => undefined);
+        throw error;
+    }
+}
+export async function initializeFrontendObserverProject(input) {
+    const root = path.resolve(input.projectRoot);
+    const configPath = projectConfigPath(root);
+    if ((await exists(configPath)) && !input.replace)
+        return { ok: false, code: 'project-config-exists', message: 'frontend-observer.json already exists; pass --replace to replace configuration only' };
+    const candidate = { schemaVersion: PROJECT_CONFIG_SCHEMA_VERSION, url: input.url, viewport: input.viewport, targets: input.targets, defaultBaseline: input.defaultBaseline ?? 'baseline' };
+    const validated = validateProjectConfig(candidate);
+    if (!validated.ok)
+        return { ok: false, code: 'project-config-invalid', message: validated.reason };
+    try {
+        await mkdir(projectEvidenceRoot(root), { recursive: true });
+        await atomicTextWrite(configPath, `${JSON.stringify(validated.config, null, 2)}\n`);
+        const catalogPath = aliasCatalogPath(root);
+        if (!(await exists(catalogPath)))
+            await writeAliasCatalog(catalogPath, { schemaVersion: ALIAS_CATALOG_SCHEMA_VERSION, observations: {} });
+        const ignorePath = path.join(root, '.gitignore');
+        const existing = await readFile(ignorePath, 'utf8').catch(() => '');
+        if (!existing.split(/\r?\n/).some((line) => line.trim() === '.frontend-observer/')) {
+            const prefix = existing.length === 0 || existing.endsWith('\n') ? existing : `${existing}\n`;
+            await writeFile(ignorePath, `${prefix}.frontend-observer/\n`, 'utf8');
+        }
+        return { ok: true, configPath };
+    }
+    catch (error) {
+        return { ok: false, code: 'project-state-write-failure', message: error instanceof Error ? error.message : String(error) };
+    }
+}
+async function captureObservation(input, allowReserved) {
+    const aliasValidation = validateObservationAlias(input.alias, allowReserved);
+    if (!aliasValidation.ok)
+        return { ok: false, code: aliasValidation.reason === 'reserved' ? 'alias-reserved' : 'alias-invalid', message: aliasValidation.reason === 'reserved' ? 'alias "current" is reserved for a later workflow command' : 'alias must match ^[a-z0-9][a-z0-9._-]{0,63}$ and must not be a traversal expression' };
+    const config = await readProjectConfig(projectConfigPath(input.projectRoot));
+    if (!config.ok)
+        return { ok: false, code: 'project-config-invalid', message: config.reason };
+    const catalogResult = await readAliasCatalog(aliasCatalogPath(input.projectRoot));
+    if (!catalogResult.ok)
+        return { ok: false, code: 'project-catalog-invalid', message: catalogResult.reason };
+    if (catalogResult.catalog.observations[input.alias] !== undefined && !input.replace)
+        return { ok: false, code: 'alias-exists', message: `alias "${input.alias}" already exists; pass --replace to point it at a new observation` };
+    const normalized = normalizeRequest({ targetUrl: config.config.url, viewport: config.config.viewport, targets: config.config.targets, outputLocation: observationOutputLocation(input.alias) });
+    if (!normalized.ok)
+        return { ok: false, code: 'project-config-invalid', message: normalized.diagnostics.map((entry) => entry.message).join('; ') };
+    const result = await observe(normalized.request, { cwd: input.projectRoot });
+    if (!result.ok)
+        return { ok: false, code: 'observation-failure', message: 'observation failed', diagnostics: result.diagnostics };
+    const relative = path.relative(projectEvidenceRoot(input.projectRoot), result.artifactRoot).split(path.sep).join('/');
+    if (relative.startsWith('../') || path.isAbsolute(relative))
+        return { ok: false, code: 'project-state-write-failure', message: 'persisted observation path escaped the managed evidence root' };
+    const updated = { ...catalogResult.catalog, observations: { ...catalogResult.catalog.observations, [input.alias]: { observationId: result.observationId, requestId: result.requestId, relativeArtifactDir: relative } } };
+    try {
+        await writeAliasCatalog(aliasCatalogPath(input.projectRoot), updated);
+    }
+    catch (error) {
+        return { ok: false, code: 'project-state-write-failure', message: `observation persisted, but alias catalog update failed: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    return { ok: true, alias: input.alias, observationId: result.observationId, requestId: result.requestId, artifactRoot: result.artifactRoot, completionState: result.completion.state, diagnostics: result.diagnostics };
+}
+export async function captureNamedObservation(input) { return captureObservation(input, false); }
+export async function captureCurrentObservation(projectRoot) { return captureObservation({ projectRoot, alias: 'current', replace: true }, true); }
+export async function loadProjectViewerState(projectRoot) {
+    const config = await readProjectConfig(projectConfigPath(projectRoot));
+    if (!config.ok)
+        return { ok: false, code: 'project-config-invalid', message: config.reason };
+    const catalog = await readAliasCatalog(aliasCatalogPath(projectRoot));
+    if (!catalog.ok)
+        return { ok: false, code: 'project-catalog-invalid', message: catalog.reason };
+    const aliases = {};
+    for (const [alias, record] of Object.entries(catalog.catalog.observations))
+        aliases[record.relativeArtifactDir] = alias;
+    return { ok: true, root: projectEvidenceRoot(projectRoot), aliases };
+}
+//# sourceMappingURL=projectWorkflowService.js.map