@tryvitris/website-harness 0.0.0-stage → 0.1.0-beta.5

package/bin/types/src/agent/trace.d.ts

@@ -0,0 +1,337 @@
+import { type StagePreparation, type ToolExecutionReceipt } from "./preparation.ts";
+import type { AgentState, SkillGraph } from "./graph.ts";
+import { type CursorHookSummary } from "./cursor-hook.ts";
+export declare const TRACE_SCHEMA_VERSION: 1;
+export declare const TRACE_EVENT_SCHEMA_VERSION: 1;
+export declare const TRACE_DIR_REL = "agent/runs/traces";
+export declare const TRACE_ACTIVE_REL = "agent/runs/traces/active.json";
+export declare const TRACE_LAST_REL = "agent/runs/traces/last.json";
+export type TraceStatus = "recording" | "stopped" | "superseded";
+export type EvidencePresence = "present" | "absent" | "ambiguous";
+export type AgentActionVisibility = "unobserved" | "partial" | "unknown";
+export type FactVisibility = "observed_by_kernel" | "reported_by_cursor_export" | "inferred_from_file_changes" | "observed_by_cursor_hook";
+export type PromptFidelity = "verified" | "unverified" | "missing";
+export type TraceEventType = "stage_prepared" | "stage_completed" | "tool_completed" | "stage_invalidated" | "run_finished" | "cursor_attached";
+export interface CursorExportInspection {
+    format: "unverified-markdown";
+    userPrompt: EvidencePresence;
+    toolNames: EvidencePresence;
+    toolArguments: EvidencePresence;
+    toolResults: EvidencePresence;
+    timestamps: EvidencePresence;
+    chatIdentity: EvidencePresence;
+    agentActions: AgentActionVisibility;
+    notes: string[];
+}
+export interface CursorExportRecord {
+    sourceFilename: string;
+    storedPath: string;
+    hash: string;
+    importedAt: string;
+    bytes: number;
+    preparationIds?: string[];
+    inspection: CursorExportInspection;
+}
+export interface TraceManifest {
+    schemaVersion: 1;
+    traceId: string;
+    site: string;
+    sitePath: string;
+    startedAt: string;
+    endedAt?: string;
+    kernelRevision: string;
+    graphVersion: number;
+    label?: string;
+    status: TraceStatus;
+    cursorExports: CursorExportRecord[];
+    ownedPreparationIds: string[];
+    promptSnapshots: Record<string, {
+        path: string;
+        hash: string;
+        bytes: number;
+        publishedHash?: string;
+        fidelity: PromptFidelity;
+    }>;
+    warnings: Array<{
+        timestamp: string;
+        message: string;
+        kind?: string;
+        preparationId?: string;
+        expectedHash?: string;
+        actualHash?: string;
+        snapshotPath?: string;
+    }>;
+}
+export interface TraceActiveMarker {
+    schemaVersion: 1;
+    traceId: string;
+    startedAt: string;
+}
+export interface TraceLastMarker {
+    schemaVersion: 1;
+    traceId: string;
+    stoppedAt: string;
+    status: "stopped" | "superseded";
+}
+export interface TraceEvent {
+    schemaVersion: 1;
+    type: TraceEventType;
+    timestamp: string;
+    traceId: string;
+    nodeId?: string;
+    preparationId?: string;
+    attempt?: number;
+    reused?: boolean;
+    result?: string;
+    failures?: string[];
+    failureSummary?: string;
+    promptHash?: string;
+    promptPath?: string;
+    promptBytes?: number;
+    estimatedPromptTokens?: number;
+    hashMismatch?: boolean;
+    promptFidelity?: PromptFidelity;
+    publishedPromptHash?: string;
+    snapshotPromptHash?: string;
+    receiptPath?: string;
+    logPath?: string;
+    usagePath?: string;
+    durationMs?: number;
+    exitCode?: number;
+    command?: string[];
+    stateStatus?: string;
+    repairTarget?: string;
+    changedFiles?: {
+        created: string[];
+        modified: string[];
+        deleted: string[];
+    };
+    agentTokens: "unknown" | {
+        input?: number;
+        output?: number;
+        measured: boolean;
+        source: string;
+    };
+    visibility: FactVisibility;
+    sourceFilename?: string;
+    storedPath?: string;
+    notes?: string[];
+}
+export interface TraceStageSummary {
+    nodeId: string;
+    preparationId?: string;
+    attempt: number;
+    kind?: string;
+    result?: string;
+    preparedAt?: string;
+    completedAt?: string;
+    elapsedMs?: number;
+    promptBytes?: number;
+    estimatedPromptTokens?: number;
+    toolDurationMs?: number;
+    failures: string[];
+    repairTarget?: string;
+    changedFiles?: {
+        created: string[];
+        modified: string[];
+        deleted: string[];
+    };
+    evidence: Array<{
+        fact: string;
+        visibility: FactVisibility;
+        path?: string;
+    }>;
+    agentTokens: "unknown" | {
+        input?: number;
+        output?: number;
+        measured: boolean;
+        source: string;
+    };
+    promptFidelity?: PromptFidelity;
+    publishedPromptHash?: string;
+    snapshotPromptHash?: string;
+    missing?: string[];
+    cursorActions?: {
+        reads: {
+            count: number;
+            durationMs: number;
+        };
+        searches: {
+            count: number;
+            durationMs: number;
+        };
+        writes: {
+            count: number;
+            durationMs: number;
+        };
+        shell: {
+            count: number;
+            durationMs: number;
+        };
+        mcp: {
+            count: number;
+            durationMs: number;
+        };
+        retries: number;
+        eventIds: string[];
+        outsideExpectedWrites: string[];
+    };
+}
+export interface TraceSummary {
+    schemaVersion: 1;
+    traceId: string;
+    status: TraceStatus;
+    site: string;
+    startedAt: string;
+    endedAt?: string;
+    kernelRevision: string;
+    graphVersion: number;
+    label?: string;
+    agentActions: AgentActionVisibility;
+    agentTokens: "unknown";
+    visibilityGaps: string[];
+    stages: TraceStageSummary[];
+    repeatedFailures: Array<{
+        text: string;
+        count: number;
+    }>;
+    longStages: Array<{
+        nodeId: string;
+        preparationId?: string;
+        elapsedMs: number;
+    }>;
+    promptNotes: string[];
+    promptIntegrityWarnings: Array<{
+        preparationId: string;
+        expectedHash: string;
+        actualHash: string;
+        snapshotPath: string;
+        message: string;
+    }>;
+    cursorExports: CursorExportRecord[];
+    cursorHooks: CursorHookSummary;
+    evidencePaths: string[];
+}
+export interface TraceCliResult {
+    handled: boolean;
+    exitCode: number;
+    message?: string;
+}
+export declare function siteRel(root: string, absPath: string): string;
+export declare function tracesRoot(root: string): string;
+export declare function activeMarkerPath(root: string): string;
+export declare function lastMarkerPath(root: string): string;
+export declare function traceDir(root: string, traceId: string): string;
+export declare function readKernelRevision(kernel: string): string;
+/** Append one JSONL line. Sequential process reopen is safe on Windows. */
+export declare function appendJsonl(path: string, value: unknown): void;
+export declare function loadActiveMarker(root: string): TraceActiveMarker | undefined;
+export declare function loadLastMarker(root: string): TraceLastMarker | undefined;
+export declare function loadManifest(root: string, traceId: string): TraceManifest | undefined;
+/**
+ * Active recording session wins. Otherwise the most recently stopped/superseded
+ * trace. Ambiguous or missing state requires `--trace <id>`.
+ */
+export declare function resolveDefaultTraceId(root: string): {
+    traceId: string;
+    source: "active" | "last";
+} | {
+    error: string;
+};
+export declare function loadRecordingSession(root: string): {
+    marker: TraceActiveMarker;
+    manifest: TraceManifest;
+} | undefined;
+export declare function withTraceSafe(root: string, fn: () => void): void;
+export declare function startTraceSession(opts: {
+    root: string;
+    kernel: string;
+    graph: SkillGraph;
+    label?: string;
+    kernelRevision?: string;
+}): {
+    traceId: string;
+    resumed: false;
+    superseded?: string;
+};
+export declare function stopTraceSession(root: string): {
+    traceId: string;
+    alreadyStopped?: boolean;
+} | undefined;
+export declare function readEvents(root: string, traceId: string): TraceEvent[];
+export declare function snapshotPreparedPrompt(root: string, preparation: Pick<StagePreparation, "id" | "promptHash">): {
+    path: string;
+    hash: string;
+    bytes: number;
+    hashMismatch: boolean;
+    alreadyPresent: boolean;
+    publishedHash?: string;
+    fidelity: PromptFidelity;
+} | undefined;
+export declare function recordStagePrepared(opts: {
+    root: string;
+    preparation: StagePreparation;
+    reused?: boolean;
+}): void;
+export declare function recordStageCompleted(opts: {
+    root: string;
+    preparation: StagePreparation;
+    ok: boolean;
+    failures: string[];
+    idempotentReplay?: boolean;
+    priorNodeStatuses?: Record<string, string>;
+    state?: AgentState;
+    durationMs?: number;
+    agentUsage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+        measured: boolean;
+    };
+}): void;
+export declare function recordToolCompleted(opts: {
+    root: string;
+    nodeId: string;
+    receipt: ToolExecutionReceipt;
+    iteration?: number;
+    priorNodeStatuses?: Record<string, string>;
+    state?: AgentState;
+}): void;
+export declare function recordStageInvalidated(opts: {
+    root: string;
+    preparation: Pick<StagePreparation, "id" | "nodeId" | "attempt" | "status" | "invalidationReason">;
+    result?: "invalidated" | "canceled";
+}): void;
+/** Conservative inspection. Never treats prose as proof that a tool ran. */
+export declare function inspectCursorExport(text: string): CursorExportInspection;
+export declare function attachCursorExport(opts: {
+    root: string;
+    file: string;
+    preparationIds?: string[];
+    traceId?: string;
+}): CursorExportRecord;
+export declare function buildTraceSummary(root: string, traceId: string): TraceSummary;
+export declare function renderTraceSummaryMarkdown(summary: TraceSummary): string;
+export declare function writeSummaryFiles(root: string, traceId: string): TraceSummary;
+export declare function cleanupTrace(root: string, traceId: string): {
+    traceId: string;
+    removed: string;
+};
+export declare function formatTraceStatus(root: string): string;
+/**
+ * Handle exclusive go/trace commands before the workflow lock and state save.
+ * `--trace-start` with a workflow action is not exclusive: the caller starts then continues.
+ */
+export declare function dispatchTraceCli(opts: {
+    root: string;
+    kernel: string;
+    graph: SkillGraph;
+    argv: string[];
+    log?: (message: string) => void;
+}): TraceCliResult;
+export declare function maybeStartTraceFromArgv(opts: {
+    root: string;
+    kernel: string;
+    graph: SkillGraph;
+    argv: string[];
+    log?: (message: string) => void;
+}): string | undefined;

package/bin/types/src/agent/workflow-config.d.ts

@@ -0,0 +1,25 @@
+export interface WorkflowConfig {
+    schemaVersion: 1;
+    executionMode: "active-agent" | "external-worker";
+}
+export declare const DEFAULT_WORKFLOW_CONFIG: WorkflowConfig;
+/** Load existing agent/workflow.json or return default active-agent configuration. */
+export declare function loadWorkflowConfig(root: string): WorkflowConfig;
+/** Save agent/workflow.json configuration with mutation lock. */
+export declare function saveWorkflowConfig(root: string, config: WorkflowConfig): void;
+/**
+ * Ensures agent/workflow.json exists with valid defaults.
+ */
+export declare function ensureWorkflowConfig(root: string): {
+    config: WorkflowConfig;
+    quarantinedAdapters: string[];
+};
+/**
+ * Quarantines legacy adapter files to dated backups, ensuring active runners/leases are never disrupted.
+ */
+export declare function quarantineLegacyAdapters(root: string): string[];
+/**
+ * Validates that the execution mode is active-agent.
+ * Unconditionally rejects external-worker dispatch without fallback.
+ */
+export declare function enforceActiveAgentMode(config: WorkflowConfig): void;

package/bin/types/src/agent/workflow.d.ts

@@ -0,0 +1,104 @@
+import { type AgentState, type GraphNode, type SkillGraph } from "./graph.ts";
+import { JevClient } from "./jev/client.ts";
+import type { JevConfig, JevMode, JevTransport } from "./jev/types.ts";
+import { type StagePreparation } from "./preparation.ts";
+export declare const SHARED_TRUNK_NODES: readonly ["harvest", "business", "business-review", "media"];
+export declare const CAPTURE_PATHS: string[];
+export declare const PROTECTED_SOURCE_PATHS: string[];
+export type AdapterConfig = {
+    command: string;
+    args: string[];
+    prompt: "stdin" | "argument";
+    model?: string;
+    maxTokensPerCall?: number;
+    author?: {
+        command: string;
+        args: string[];
+        prompt: "stdin" | "argument";
+        model?: string;
+    };
+    reviewer?: {
+        command: string;
+        args: string[];
+        prompt: "stdin" | "argument";
+        model?: string;
+    };
+};
+export type WorkflowOptions = {
+    root: string;
+    kernel: string;
+    argv?: string[];
+    max?: number;
+    maxCumulative?: number;
+    maxCumulativeTokens?: number;
+    maxCumulativeDurationMs?: number;
+    timeout?: number;
+    stopWhen?: (state: AgentState, graph: SkillGraph) => boolean;
+    skipLock?: boolean;
+    includeOptional?: boolean;
+    noPreviewServer?: boolean;
+    /** Keep every author and critic objective in the current session, even with a reviewer adapter installed. */
+    activeAgentOnly?: boolean;
+    log?: (message: string) => void;
+    onLog?: (message: string) => void;
+    signal?: AbortSignal;
+    jevMode?: JevMode;
+    jevConfig?: JevConfig;
+    compactPackets?: boolean;
+    jevClient?: JevClient;
+    jevFetch?: JevTransport;
+    testStageExecutor?: (opts: {
+        stage: GraphNode;
+        prep: StagePreparation;
+        prompt: string;
+        root?: string;
+        outputPath?: string;
+    }) => Promise<void>;
+};
+export type WorkflowResult = {
+    state: AgentState;
+    graph: SkillGraph;
+    exitCode: number;
+};
+export declare function argFrom(argv: string[], key: string): string | undefined;
+export declare function hasFlag(argv: string[], key: string): boolean;
+/** Strip coordinator flags so a child site cannot mint a new theme/restart budget. */
+export declare function childWorkflowArgv(argv: string[]): string[];
+export declare function loadAdapter(root: string, role?: "author" | "reviewer"): AdapterConfig;
+export declare function sharedTrunkComplete(state: AgentState): boolean;
+export declare function loadSiteGraph(root: string): SkillGraph;
+export declare function killProcessTree(pid: number): void;
+export declare function spawnAdapterProcess(opts: {
+    maxTokens?: number;
+    command: string;
+    args: string[];
+    cwd: string;
+    input?: string;
+    env: NodeJS.ProcessEnv;
+    timeout: number;
+    outputPath: string;
+    signal?: AbortSignal;
+}): Promise<{
+    status: number | null;
+    error?: string;
+    signal?: string | null;
+    timedOut?: boolean;
+    aborted?: boolean;
+}>;
+export declare function invokeAdapter(opts: {
+    maxTokens?: number;
+    cwd: string;
+    adapter: AdapterConfig;
+    nodeId: string;
+    prompt: string;
+    timeout: number;
+    runnerPid: number;
+    outputPath: string;
+    signal?: AbortSignal;
+}): Promise<{
+    status: number | null;
+    error?: string;
+    signal?: string | null;
+    durationMs: number;
+}>;
+export declare function runWorkflow(opts: WorkflowOptions): Promise<WorkflowResult>;

package/bin/types/src/blocks/library-profile.d.ts

@@ -0,0 +1,9 @@
+import { type BlockLibrary } from "../agent/jev/block-catalog.ts";
+export type LibraryProfile = "legacy-v0" | "slice-v1";
+/** The profile is site-owned. A refresh must not rewrite launch.json. */
+export declare function readLibraryProfile(siteRoot: string): LibraryProfile;
+export declare function loadProfiledBlockLibrary(kernel: string, siteRoot: string): {
+    profile: LibraryProfile;
+    releaseIdentity: string;
+    library: BlockLibrary;
+};

package/bin/types/src/blocks/metadata.d.ts

@@ -0,0 +1,65 @@
+export interface BlockMeta {
+    schemaVersion: 1;
+    id: string;
+    revision: number;
+    status: "draft" | "inspected" | "pilot" | "stable" | "deprecated";
+    owner: string;
+    sourceHash: string;
+    fit: {
+        visitorJobs: string[];
+        pageRoles: string[];
+        useWhen: string[];
+        avoidWhen: string[];
+    };
+    content: {
+        requiredSlots: string[];
+        optionalSlots: string[];
+        testedItemCounts: number[];
+    };
+    media: {
+        min: number;
+        max: number;
+        optionalBehavior: string;
+        aspect: string[];
+    };
+    composition: {
+        hierarchy: string;
+        alignment: string;
+        density: string;
+        mediaProminence: string;
+        geometry: string[];
+        boundary: string;
+    };
+    adaptation: {
+        flexible: string[];
+        invariants: string[];
+        customWhen: string[];
+    };
+    responsive: {
+        readingOrder: string;
+        reflow: string;
+        crop: string;
+    };
+    interaction: {
+        behavior: string;
+        islands: string[];
+    };
+    evidence: {
+        provenance: string[];
+        testedContexts: string[];
+        accessibility: string[];
+        previewManifest?: string;
+    };
+}
+export declare function blockSourceHash(dir: string): string;
+export declare function blockPreviewRendererHash(root: string): string;
+export declare function readBlockMeta(dir: string, id: string, slots: {
+    name: string;
+    required: boolean;
+}[]): BlockMeta | undefined;
+export declare function blockPreviewEvidence(dir: string, meta?: BlockMeta): {
+    status: "current" | "stale" | "unavailable";
+    mobile?: string;
+    desktop?: string;
+    hashes?: Record<string, string>;
+};

package/bin/types/src/build/index.d.ts

@@ -0,0 +1,29 @@
+import type { Catalog, PageSource, SiteConfig, ThemeTokens } from "../types.ts";
+import type { PublicForm } from '../forms/config.ts';
+export type BuildSiteInput = {
+    site: SiteConfig;
+    pages: PageSource[];
+    theme: Partial<ThemeTokens>;
+    catalog: Catalog;
+    backendOrigin?: string;
+    /** @deprecated Use backendOrigin. */
+    kernelOrigin?: string;
+    outDir: string;
+    themeHref?: string;
+    publicOrigin?: string;
+    forms?: PublicForm[];
+    webAnalyticsToken?: string;
+};
+export declare function loadSiteCatalog(siteDir: string): Promise<Catalog>;
+export declare function loadSitePages(siteDir: string): Promise<PageSource[]>;
+export declare function loadSiteDir(dir: string): Promise<{
+    site: SiteConfig;
+    theme: Partial<ThemeTokens>;
+    pages: PageSource[];
+    catalog: Catalog;
+}>;
+export declare function buildSite(input: BuildSiteInput): Promise<string[]>;
+export declare function fetchLiveContent(kernelOrigin: string, slug: string, token: string): Promise<{
+    site: SiteConfig;
+    theme: Partial<ThemeTokens>;
+} | null>;

package/bin/types/src/build/responsive-media.d.ts

@@ -0,0 +1,19 @@
+export type MediaDerivative = {
+    url: string;
+    width: number;
+    height: number;
+    bytes: number;
+    sha256: string;
+};
+export type MediaBuildReport = {
+    version: 1;
+    images: {
+        source: string;
+        sha256: string;
+        bytes: number;
+        variants: MediaDerivative[];
+    }[];
+    warnings: string[];
+};
+/** Build-time only: no remote downloads, origin changes, source mutation, or paid image API. */
+export declare function responsiveMedia(dist: string, cacheDir: string): Promise<MediaBuildReport>;

package/bin/types/src/build/serve.d.ts

@@ -0,0 +1,4 @@
+export declare const previewIdentity: (dist: string) => string;
+export declare function previewServer(dist: string, options?: {
+    compress?: boolean;
+}): import("http").Server<typeof import("http").IncomingMessage, typeof import("http").ServerResponse>;

package/bin/types/src/build/static-output.d.ts

@@ -0,0 +1,2 @@
+/** Apply delivery rules after public assets have been copied, without changing authored source. */
+export declare function finalizeStaticOutput(dist: string, publicOrigin?: string): void;

package/bin/types/src/build/verified.d.ts

@@ -0,0 +1 @@
+export declare function buildVerified(siteRoot: string, output?: string, origin?: string, slug?: string): Promise<void>;

package/bin/types/src/cli/api.d.ts

@@ -0,0 +1,17 @@
+export { createSite, type CreateSiteOptions } from "./site-create.ts";
+export { runDoctor, type DoctorOptions, type DoctorDiagnostic } from "./doctor.ts";
+export { runSite, buildAdapterConfig, type RunOptions } from "./run.ts";
+export { refineSite, type RefineOptions } from "./refine.ts";
+export { statusSite, type StatusOptions } from "./status.ts";
+export { resumeSite, cancelSite, type LifecycleOptions } from "./lifecycle.ts";
+export { importFeedback, synthesizeSite, type FeedbackImportOptions, type SynthesizeOptions } from "./feedback.ts";
+export { verifySite, type VerifyOptions, type VerifyResultData } from "./verify.ts";
+export { previewSite, type PreviewOptions } from "./preview.ts";
+export { deploySite, type DeployOptions, type DeployResultData } from "./deploy.ts";
+export { shareSite, type ShareOptions } from "./share.ts";
+export { EXIT_CODES, type ExitCode, type CommandResult, type OutputMode, type VitrisEvent } from "./types.ts";
+export { migrateSite } from "./site-migrate.ts";
+export { inspectSite, prepareChange, applyOperations, buildSiteDraft, verifyChange, discardChange } from "../engine/index.ts";
+export { upgradeSite, type UpgradeOptions } from "./upgrade.ts";
+export { prepareVerifiedRelease, deployVerifiedArtifact } from "../integrations/hosting.ts";
+export { runPreserve } from "./preserve.ts";

package/bin/types/src/cli/deploy.d.ts

@@ -0,0 +1,21 @@
+import { type CommandResult } from "./types.ts";
+export type DeployOptions = {
+    site?: string;
+    provider?: "cloudflare";
+    environment?: "preview" | "production";
+    branch?: string;
+    dryRun?: boolean;
+    signal?: AbortSignal;
+    onLog?: (line: string) => void;
+};
+export type DeployResultData = {
+    url?: string;
+    environment: string;
+    project: string;
+    smokeCheck?: {
+        ok: boolean;
+        status: number;
+        message: string;
+    };
+};
+export declare function deploySite(opts?: DeployOptions): Promise<CommandResult<DeployResultData>>;

package/bin/types/src/cli/doctor.d.ts

@@ -0,0 +1,16 @@
+import { type CommandResult } from "./types.ts";
+export type DoctorOptions = {
+    site?: string;
+    provider?: string;
+    operation?: string;
+    dryRun?: boolean;
+};
+export type DoctorDiagnostic = {
+    name: string;
+    ok: boolean;
+    message: string;
+    severity: "error" | "warning" | "info";
+};
+export declare function runDoctor(opts?: DoctorOptions): Promise<CommandResult<{
+    diagnostics: DoctorDiagnostic[];
+}>>;

package/bin/types/src/cli/events.d.ts

@@ -0,0 +1,16 @@
+import type { CommandResult, OutputMode, VitrisEvent } from "./types.ts";
+export declare class EventStream {
+    private mode;
+    private events;
+    constructor(mode?: OutputMode);
+    getMode(): OutputMode;
+    emit(event: Omit<VitrisEvent, "timestamp">): void;
+    log(message: string): void;
+    error(message: string): void;
+    status(status: unknown): void;
+    finish<T>(result: CommandResult<T>): void;
+}
+export declare function determineOutputMode(flags: {
+    json?: boolean;
+    events?: boolean;
+}): OutputMode;