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

package/bin/types/src/agent/reference-studies.d.ts

@@ -0,0 +1,110 @@
+import { type FitProfile, type FitSignals } from "./reference-fit.ts";
+type FilePin = {
+    path: string;
+    sha256: string;
+};
+export type ReferenceStudy = {
+    motionTags?: string[];
+    temporalEvidence?: import("./reference-library.ts").ReferenceRecord["temporalEvidence"];
+    id: string;
+    revision: number;
+    title: string;
+    primaryFamily: string;
+    assetMinimum: string;
+    fitSignals: string[];
+    organizingIdea: string;
+    lessonIds: string[];
+    referenceIds: string[];
+    selectionProfile?: FitProfile;
+    exampleScope?: string;
+    releaseNotes?: string;
+    comparisonStatus?: string;
+    sourcePath: string;
+    status: string;
+    humanPreference: null;
+    brief: {
+        fictional: true;
+        facts: unknown;
+        factsHash: string;
+        mediaHash: string;
+    };
+    provenance: {
+        content: string;
+        media: string;
+        rights: string;
+    };
+    renderEvidence: {
+        route: string;
+        viewport: {
+            width: number;
+            height: number;
+        };
+        preview: FilePin;
+        fullPreview?: FilePin;
+        visualReview: {
+            assessor: string;
+            reviewedAt: string;
+            assessment: string;
+        };
+    }[];
+};
+/** Original teaching material is independently pinned; external curation never supplies assets. */
+export declare function loadReferenceStudies(kernel: string, release?: string): {
+    base: string;
+    manifest: {
+        schemaVersion: number;
+        release: string;
+        labeledPreferenceData: boolean;
+        catalog: FilePin;
+        files: FilePin[];
+    };
+    manifestHash: string;
+    catalog: {
+        schemaVersion: number;
+        release: string;
+        studies: ReferenceStudy[];
+    };
+    pins: Map<string, FilePin>;
+};
+export declare function referenceStudyExpansions(kernel: string, signals: FitSignals, references: string[], accepted?: {
+    id: string;
+    revision: number;
+}[], release?: string): {
+    pack: {
+        base: string;
+        manifest: {
+            schemaVersion: number;
+            release: string;
+            labeledPreferenceData: boolean;
+            catalog: FilePin;
+            files: FilePin[];
+        };
+        manifestHash: string;
+        catalog: {
+            schemaVersion: number;
+            release: string;
+            studies: ReferenceStudy[];
+        };
+        pins: Map<string, FilePin>;
+    };
+    excluded: {
+        id: string;
+        reason: string;
+    }[];
+    gaps: string[];
+    selected: {
+        id: string;
+        revision: number;
+        score: number;
+        reasons: string[];
+        handle: string;
+        idea: string;
+    }[];
+    expansions: {
+        id: string;
+        hash: string;
+        chars: number;
+        text: string;
+    }[];
+};
+export {};

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

@@ -0,0 +1,348 @@
+import { type AgentState, type SkillGraph } from "./graph.ts";
+import { type ChangeOrigin, type ChangePlanRecord, type ChangeRequestRecord } from "../engine/contracts.ts";
+export declare const CHANGE_SCOPES: readonly ["business", "copy", "pages", "direction", "media"];
+export type ChangeScope = (typeof CHANGE_SCOPES)[number];
+export type FeedbackGrain = "website" | "page" | "section" | "element";
+export type FeedbackKind = "nav_behavior" | "nav_styling" | "content" | "media" | "general";
+export type FeedbackItem = {
+    grain: FeedbackGrain;
+    text: string;
+    path?: string;
+    sectionId?: string;
+    hook?: string;
+    kind?: FeedbackKind;
+    target?: string;
+};
+export type MemoryDecision = {
+    id: string;
+    status: "current" | "superseded";
+    kind: "fact" | "media" | "direction" | "copy" | "preference" | "issue";
+    acceptance?: "proposal" | "provisional" | "accepted";
+    summary: string;
+    evidence?: string;
+    grain?: FeedbackGrain;
+    path?: string;
+    sectionId?: string;
+    hook?: string;
+    intent?: "positive" | "negative" | "preserve" | "observation";
+    origin?: "operator" | "agent" | "editor" | "hosted" | "machine" | "human";
+    target?: string;
+    supersededBy?: string;
+};
+export type SiteMemory = {
+    schemaVersion: 1;
+    seededAt: string;
+    updatedAt: string;
+    businessHash: string;
+    mediaHash: string;
+    directionHash: string;
+    copyHash: string;
+    factIds: string[];
+    mediaIds: string[];
+    decisions: MemoryDecision[];
+    unresolved: string[];
+    preferences: FeedbackItem[];
+    pendingRequest?: {
+        requestId: string;
+        scope: string;
+        startedAt: string;
+    };
+    acceptedRequests?: Array<{
+        requestId: string;
+        scope: string;
+        acceptedAt: string;
+    }>;
+};
+export type ChangeRequest = {
+    instruction: string;
+    originalRequest: string;
+    scope: ChangeScope;
+    scopes?: ChangeScope[];
+    affectedNodes?: string[];
+    isMixed?: boolean;
+    classifiedScope: ChangeScope;
+    overrideScope?: ChangeScope;
+    evidencePath: string;
+    rationale: string;
+    affectedPages: string[];
+    proposedChanges: string[];
+    likes: FeedbackItem[];
+    dislikes: FeedbackItem[];
+    preserve: FeedbackItem[];
+    implementationReason?: string;
+    scopeAmendments?: Array<{
+        at: string;
+        reason: string;
+        before: ChangeScope[];
+        after: ChangeScope[];
+        priorRequest: string;
+    }>;
+    shadowProposal?: {
+        scope: ChangeScope;
+        scopes?: ChangeScope[];
+        affectedNodes?: string[];
+        isMixed?: boolean;
+        isAmbiguous?: boolean;
+        rationale?: string;
+        confidence?: number;
+    };
+    plan?: ChangePlanRecord;
+    origin?: ChangeOrigin;
+};
+export type NavLink = {
+    href: string;
+    label: string;
+};
+export type RefineBaseline = {
+    capturedAt: string;
+    layoutHash: string;
+    structuralLayoutHash?: string;
+    themeHash?: string;
+    businessHash: string;
+    mediaHash: string;
+    copyHash: string;
+    directionHash: string;
+    distHash: string;
+    screenshotHash: string;
+    nodes: AgentState["nodes"];
+    mediaIds: string[];
+    factIds: string[];
+    preserve: FeedbackItem[];
+    navLinks?: NavLink[];
+    structuredPreserve?: Array<{
+        text: string;
+        target?: string;
+        baselineText?: string;
+        error?: string;
+    }>;
+};
+export type RefineReport = {
+    schemaVersion: 1;
+    instruction: string;
+    scope: ChangeScope;
+    classifiedScope: ChangeScope;
+    rationale: string;
+    proposedChanges: string[];
+    changed: string[];
+    preserved: string[];
+    before: {
+        layoutHash: string;
+        distHash: string;
+        screenshotHash: string;
+    };
+    after: {
+        layoutHash: string;
+        distHash: string;
+        screenshotHash: string;
+    };
+    memoryKeys: string[];
+    failures: string[];
+    skippedLayoutRewrite: boolean;
+};
+export declare const START_NODE: Record<ChangeScope, string>;
+export declare function classifyChange(instruction: string): {
+    scope: ChangeScope;
+    scopes: ChangeScope[];
+    affectedNodes: string[];
+    isMixed: boolean;
+    isAmbiguous?: boolean;
+    rationale: string;
+    affectedPages: string[];
+    proposedChanges: string[];
+};
+export declare function classifyChangeAsync(instruction: string, opts?: {
+    root?: string;
+    client?: import("./jev/client.ts").JevClient;
+    mode?: import("./jev/types.ts").JevMode;
+    overrideScope?: ChangeScope;
+    threshold?: number;
+    signal?: AbortSignal;
+}): Promise<{
+    scope: ChangeScope;
+    scopes?: ChangeScope[];
+    affectedNodes?: string[];
+    classifiedScope: ChangeScope;
+    rationale: string;
+    affectedPages: string[];
+    proposedChanges: string[];
+    isMixed?: boolean;
+    isAmbiguous?: boolean;
+    confidence?: number;
+    jevEvaluated: boolean;
+    shadowProposal?: {
+        scope: ChangeScope;
+        scopes?: ChangeScope[];
+        affectedNodes?: string[];
+        isMixed?: boolean;
+        isAmbiguous?: boolean;
+        rationale?: string;
+        confidence?: number;
+    };
+}>;
+export declare function parseFeedback(instruction: string): {
+    likes: FeedbackItem[];
+    dislikes: FeedbackItem[];
+    preserve: FeedbackItem[];
+};
+export declare function affectedNodeIds(graph: SkillGraph, startId: string): Set<string>;
+export declare function requestNodesFor(scope: ChangeScope): string[];
+export declare function seedSiteMemory(root: string): SiteMemory;
+export declare function loadSiteMemory(root: string): SiteMemory;
+export declare function updateSiteMemory(root: string, request: ChangeRequest, extras?: {
+    implementationReason?: string;
+    unresolved?: string[];
+}): SiteMemory;
+export declare function extractNavLinks(root: string): NavLink[];
+export declare function structuralLayoutHash(root: string): string;
+export declare function pageTextHash(root: string): string;
+export type CopyPlanSection = {
+    id: string;
+    heading?: string;
+    body?: string;
+    factIds?: string[];
+    note?: string;
+    caption?: string;
+    cta?: string;
+    slots?: Record<string, string>;
+};
+export type CopyPlanPage = {
+    path: string;
+    sections: CopyPlanSection[];
+};
+export type CopyPlan = {
+    version: 2;
+    storyboardHash?: string;
+    pages: CopyPlanPage[];
+};
+export declare function escapeHtml(text: string): string;
+export declare function isSafeUrl(url: string): boolean;
+export declare function renderInlineMarkdown(text: string): string;
+export declare function isProtectedParagraph(html: string): boolean;
+export declare function findBalancedSlot(html: string, slotName: string): {
+    matchStart: number;
+    matchEnd: number;
+    openTag: string;
+    tagName: string;
+    contentStart: number;
+    contentEnd: number;
+    closeTag: string;
+} | null;
+export declare function findBalancedElement(html: string, sectionId: string): {
+    matchStart: number;
+    matchEnd: number;
+    openTag: string;
+    tagName: string;
+    contentStart: number;
+    contentEnd: number;
+    closeTag: string;
+} | null;
+export declare function applyCopyPlanToPages(root: string): {
+    applied: boolean;
+    modifiedPages: string[];
+    changes: Array<{
+        page: string;
+        sectionId: string;
+        heading?: string;
+        body?: string;
+        note?: string;
+        caption?: string;
+        cta?: string;
+    }>;
+    error?: string;
+};
+export declare function captureRefineBaseline(root: string, state: AgentState, preserve: FeedbackItem[]): RefineBaseline;
+export declare function loadRefineBaseline(root: string, requestId?: string): RefineBaseline | undefined;
+export declare function beginChange(opts: {
+    root: string;
+    graph: SkillGraph;
+    state: AgentState;
+    instruction: string;
+    scopeFlag?: string;
+    requestId?: string;
+    classified?: {
+        scope: ChangeScope;
+        scopes?: ChangeScope[];
+        affectedNodes?: string[];
+        isMixed?: boolean;
+        rationale: string;
+        affectedPages: string[];
+        proposedChanges: string[];
+        shadowProposal?: {
+            scope: ChangeScope;
+            scopes?: ChangeScope[];
+            affectedNodes?: string[];
+            isMixed?: boolean;
+            isAmbiguous?: boolean;
+            rationale?: string;
+            confidence?: number;
+        };
+    };
+}): ChangeRequest;
+export declare function restoreUnchangedLayout(root: string, state: AgentState): boolean;
+export declare function regressionFailures(root: string, requestId?: string): string[];
+export declare function writeRefineReport(root: string, opts?: {
+    skippedLayoutRewrite?: boolean;
+    failures?: string[];
+    requestId?: string;
+}): RefineReport;
+export declare function summarizeRefine(root: string): string | undefined;
+export declare function consumeRefinePending(root: string): boolean;
+export declare function loadChangeRequest(root: string, requestId?: string): ChangeRequest | undefined;
+export declare function mergeImplementationReason(root: string, nodeId: string): void;
+export declare function detectMemoryDrift(root: string): {
+    drifted: boolean;
+    driftedFiles: string[];
+    details: string[];
+};
+export type PrepareRefineResult = {
+    requestId: string;
+    scope: ChangeScope;
+    scopes: ChangeScope[];
+    classifiedScope: ChangeScope;
+    rationale: string;
+    affectedPages: string[];
+    proposedChanges: string[];
+    impactedNodes: string[];
+    baselinePath: string;
+    drift: {
+        drifted: boolean;
+        driftedFiles: string[];
+        details: string[];
+    };
+    checklist: string[];
+};
+/** Expand operator classification while retaining the original instruction,
+ * immutable baseline and prior request versions. */
+export declare function amendRefineScopes(root: string, requestId: string, scopes: ChangeScope[], reason: string): ChangeRequest;
+export declare function prepareRefine(opts: {
+    root: string;
+    instruction: string;
+    scope?: string;
+    requestId?: string;
+    plan?: ChangePlanRecord;
+    explicitPreferences?: ChangeRequestRecord["explicitPreferences"];
+    origin?: ChangeOrigin;
+}): PrepareRefineResult;
+export type VerifyRefineResult = {
+    ok: boolean;
+    failures: string[];
+    summary: string;
+    report?: RefineReport;
+    technical?: "pass" | "fail";
+    fulfillment?: "pass" | "fail" | "unevaluated";
+    design?: "pass" | "fail" | "unevaluated";
+    verifiedSourceRevision?: string;
+    verifiedBuildDigest?: string;
+    completedChecks?: Record<string, "pass" | "fail" | "unevaluated">;
+};
+export declare function verifyRefine(opts: {
+    root: string;
+    requestId?: string;
+    browser?: boolean;
+    accept?: boolean;
+}): Promise<VerifyRefineResult>;
+/** Called by the engine only after its final locked source/artifact comparison. */
+export declare function acceptVerifiedRefine(root: string, requestId: string): void;
+export declare const REFRESH_PRESERVE_FILES: Set<string>;
+export declare const REFRESH_PRESERVE_DIRS: RegExp;
+export declare const REFRESH_PRESERVE_DIR_NAMES: Set<string>;

package/bin/types/src/agent/result-manifest.d.ts

@@ -0,0 +1,38 @@
+import type { AgentState, CumulativeSpend, SkillGraph } from "./graph.ts";
+export type ResultManifestStatus = "verified_preview" | "provisional_preview" | "refinement_blocked" | "needs_repair" | "failed" | "canceled";
+export type ResultManifest = {
+    schemaVersion: 1;
+    runId?: string;
+    siteRoot: string;
+    status: ResultManifestStatus;
+    localUrl?: string;
+    provisionalUrl?: string;
+    revision: string;
+    coveredRoutes: string[];
+    gateStatus: Record<string, "pending" | "done" | "failed" | "in_progress">;
+    durationMs: number;
+    cumulativeSpend: CumulativeSpend;
+    usageSummary: {
+        inputTokens: number | null;
+        outputTokens: number | null;
+        observedInputTokens: number;
+        observedOutputTokens: number;
+        meteringCoverage: "complete" | "incomplete" | "no-agent-work";
+        jevTransportCalls: number;
+    };
+    unresolvedLimitations: string[];
+    completedAt: string;
+};
+export declare function discoverCoveredRoutes(root: string): string[];
+export declare function extractUnresolvedLimitations(root: string): string[];
+export declare function generateResultManifest(opts: {
+    root: string;
+    state: AgentState;
+    graph: SkillGraph;
+    runId?: string;
+    localUrl?: string;
+    provisionalUrl?: string;
+    durationMs?: number;
+}): ResultManifest;
+export declare function writeResultManifest(root: string, manifest: ResultManifest): void;
+export declare function loadResultManifest(root: string): ResultManifest | undefined;

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

@@ -0,0 +1,10 @@
+import { nextNode, validateGraph, type AgentState, type GraphNode, type SkillGraph } from "./graph.ts";
+export declare function loadState(root: string, graph: SkillGraph): AgentState;
+export declare function reconcile(root: string, graph: SkillGraph, state: AgentState): void;
+export declare function inputHash(root: string, node: GraphNode): string;
+export declare function instructionContractHash(root: string, node: GraphNode): string;
+export declare function begin(root: string, graph: SkillGraph, state: AgentState, node: GraphNode): void;
+export declare function finish(root: string, graph: SkillGraph, state: AgentState, node: GraphNode, failures: string[]): void;
+export declare function contextPacket(root: string, graph: SkillGraph, state: AgentState, node: GraphNode): string;
+export declare function acquire(root: string): () => void;
+export { nextNode, validateGraph };

package/bin/types/src/agent/site-inputs.d.ts

@@ -0,0 +1,26 @@
+export declare const ADDITIONAL_CONTENT_PATH = "onboarding/additional-content.md";
+export declare const TEMPLATE_INPUT_PATH = "agent/template-input.json";
+export type SiteInputOptions = {
+    template?: string;
+    templateRelease?: string;
+    content?: string;
+    contentFile?: string;
+};
+export type TemplateInput = {
+    version: 1;
+    id: string;
+    release: string;
+    instruction: string;
+};
+export type ResolvedSiteInputs = {
+    template?: TemplateInput;
+    content?: string;
+};
+export declare function additionalContentGuidance(root: string): string;
+/** Resolve and validate everything before scaffolding or mutating a site. */
+export declare function resolveSiteInputs(opts: SiteInputOptions): ResolvedSiteInputs;
+export declare function persistSiteInputs(root: string, inputs: ResolvedSiteInputs): void;
+/** Materialize only after harvest and media, so branding uses real captured evidence. */
+export declare function acceptTemplateInput(root: string): void;
+export declare function siteInputsFromArgv(argv: string[]): SiteInputOptions;
+export declare function siteInputsFromFlags(flags: Record<string, string | boolean>): SiteInputOptions;

package/bin/types/src/agent/source-manifest.d.ts

@@ -0,0 +1,9 @@
+export declare const SOURCE_ROOTS: string[];
+export declare function sourceManifest(root: string): {
+    hash: string;
+    files: {
+        path: string;
+        sha256: string;
+        bytes: number;
+    }[];
+};

package/bin/types/src/agent/state-transition.d.ts

@@ -0,0 +1,16 @@
+import { type AgentState, type GraphNode, type SkillGraph } from "./graph.ts";
+export declare function computeNextState(opts: {
+    root: string;
+    graph: SkillGraph;
+    currentState: AgentState;
+    node: GraphNode;
+    failures: string[];
+    agentUsage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+        measured: boolean;
+    };
+    durationMs?: number;
+    countAttempt?: boolean;
+    externallyMetered?: boolean;
+}): AgentState;

package/bin/types/src/agent/storyboard-media.d.ts

@@ -0,0 +1,11 @@
+import type { MediaInventory, Storyboard } from "./artifacts.ts";
+import type { MediaSelection } from "../stock/selection.ts";
+export type MediaPlanningIssueCode = "MEDIA_UNPLACED" | "MEDIA_ROUTE_INVALID" | "MEDIA_SELECTION_CONFLICT" | "MEDIA_REFERENCE_INVALID" | "MEDIA_ASSET_INVALID";
+export type MediaPlanningIssue = {
+    code: MediaPlanningIssueCode;
+    artifact: "onboarding/storyboard.json" | "onboarding/media-selection.json";
+    message: string;
+};
+export declare const mediaIssueFailure: (issue: MediaPlanningIssue) => string;
+/** V2 section plans remain readable. V3 requires an explicit selection and placement contract. */
+export declare function validateStoryboardMedia(story: Storyboard, inventory: MediaInventory, selection?: MediaSelection): MediaPlanningIssue[];

package/bin/types/src/agent/study-render.d.ts

@@ -0,0 +1,27 @@
+export type StudySpec = {
+    candidate: string;
+    path: string;
+};
+export type StudyRenderCheck = {
+    candidate: string;
+    path: string;
+    width: number;
+    screenshot: string;
+    screenshotHash: string;
+    failures: string[];
+};
+/** Unique screenshot stem from a confined study HTML path (onboarding/studies/…). */
+export declare function studyScreenshotId(path: string): string;
+/** Readable stems; colliding sanitized names get a short hash of the exact normalized relative path. */
+export declare function studyScreenshotIds(paths: string[]): Map<string, string>;
+export declare function renderStudySources(opts: {
+    root: string;
+    outputRoot?: string;
+    studies: StudySpec[];
+    copyPaths?: string[];
+    screenshotDir?: string;
+    reportPath?: string;
+    subjectHash: string;
+}): Promise<{
+    checks: StudyRenderCheck[];
+}>;

package/bin/types/src/agent/template-adaptation.d.ts

@@ -0,0 +1,69 @@
+import type { SkillGraph } from './graph.ts';
+export declare const ADAPTATION_PATH = "onboarding/template-adaptation.json";
+export declare const TEMPLATE_DECISIONS_PATH = "agent/template-decisions.json";
+export type AdaptationPreferences = {
+    version: 1;
+    sections: 'preserve-ask' | 'agent-decides';
+    aiImages: 'ask-each' | 'no-ai' | 'agent-decides';
+    priorities: string;
+    /** Explicit direct-input continuation; absent retains interactive checkpoints. */
+    checkpoints?: 'automatic' | 'ask';
+};
+export type TemplateAdaptation = {
+    version: 1;
+    selectionHash: string;
+    reference: {
+        url: string;
+        evidence: string[];
+    };
+    qualities: Array<{
+        id: string;
+        relationship: string;
+        implementation: string;
+    }>;
+    sections: Array<{
+        id: string;
+        referenceSection: string;
+        referenceIds?: string[];
+        owner?: string;
+        disposition: 'retain' | 'adapt' | 'remove';
+        route: string;
+        targetId: string;
+        content: 'ready' | 'draft' | 'placeholder';
+        nextStep?: string;
+    }>;
+    images: Array<{
+        id: string;
+        purpose: string;
+        treatment: string;
+        identity: string;
+        status: 'proposed' | 'approved' | 'declined';
+        output?: string;
+        commissionHash?: string;
+        references?: Array<{
+            assetId: string;
+            path: string;
+            sha256: string;
+        }>;
+    }>;
+};
+export type TemplateDecision = {
+    kind: 'remove-section' | 'generate-image';
+    id: string;
+    proposalHash: string;
+    source: 'user-chat' | 'user-ui';
+    instruction: string;
+};
+export declare function validateAdaptationPreferences(value: unknown): asserts value is AdaptationPreferences;
+export declare function adaptationPreferences(root: string): AdaptationPreferences | undefined;
+/** Apply before reconciliation as well as preparation/completion: output and
+ * dependency identities must use the same effective graph on every load. */
+export declare function applyTemplateAdaptationGraph(root: string, graph: SkillGraph): SkillGraph;
+/** Excludes workflow status/output so an approved proposal survives production. */
+export declare function templateProposalHash(proposal: TemplateAdaptation['images'][number] | TemplateAdaptation['sections'][number]): string;
+export declare function submitTemplateDecision(root: string, decision: TemplateDecision): void;
+export declare function assertTemplateImageAuthorization(root: string, requestId: string, commission?: {
+    sourceAssetIds: string[];
+}): void;
+export declare function templateAdaptationFailures(root: string, node: string): string[];
+export declare function templateAdaptationGuidance(root: string): string;