@evref-bl/dev-nexus 0.1.0-alpha.0

package/dist/workTrackingTypes.d.ts

@@ -0,0 +1,202 @@
+export type WorkTrackingProviderName = "local" | "vibe-kanban" | "github" | "gitlab" | "jira";
+export type WorkStatus = "todo" | "ready" | "in_progress" | "blocked" | "done" | "wont_do";
+export interface WorkTrackingRepositoryConfig {
+    owner?: string;
+    name?: string;
+    id?: string;
+    path?: string;
+}
+export interface WorkTrackingBoardConfig {
+    kind: string;
+    id?: string | null;
+    number?: number | null;
+    owner?: string | null;
+    ownerKind?: string | null;
+    projectId?: string | null;
+    statusFieldId?: string | null;
+    statusOptions?: Record<string, string>;
+}
+export interface BaseWorkTrackingConfig {
+    provider: WorkTrackingProviderName;
+    host?: string | null;
+    repository?: WorkTrackingRepositoryConfig;
+    board?: WorkTrackingBoardConfig | null;
+}
+export interface LocalWorkTrackingConfig extends BaseWorkTrackingConfig {
+    provider: "local";
+    storePath?: string | null;
+}
+export interface VibeKanbanWorkTrackingConfig extends BaseWorkTrackingConfig {
+    provider: "vibe-kanban";
+    projectId?: string | null;
+    repoId?: string | null;
+}
+export interface GitHubWorkTrackingConfig extends BaseWorkTrackingConfig {
+    provider: "github";
+    repository: WorkTrackingRepositoryConfig & {
+        owner: string;
+        name: string;
+    };
+}
+export interface GitLabWorkTrackingConfig extends BaseWorkTrackingConfig {
+    provider: "gitlab";
+    repository: WorkTrackingRepositoryConfig & {
+        id: string;
+    };
+}
+export interface JiraWorkTrackingConfig extends BaseWorkTrackingConfig {
+    provider: "jira";
+    projectKey: string;
+    issueType?: string | null;
+}
+export type WorkTrackingConfig = LocalWorkTrackingConfig | VibeKanbanWorkTrackingConfig | GitHubWorkTrackingConfig | GitLabWorkTrackingConfig | JiraWorkTrackingConfig;
+export interface ExternalRef {
+    provider: WorkTrackingProviderName | string;
+    host?: string | null;
+    repositoryId?: string | null;
+    repositoryOwner?: string | null;
+    repositoryName?: string | null;
+    projectId?: string | null;
+    boardId?: string | null;
+    itemId: string;
+    itemNumber?: number | null;
+    itemKey?: string | null;
+    nodeId?: string | null;
+    webUrl?: string | null;
+}
+export interface WorkBoard {
+    id: string;
+    name: string;
+    provider: WorkTrackingProviderName | string;
+    externalRef?: ExternalRef;
+    webUrl?: string | null;
+}
+export interface WorkComment {
+    id: string;
+    body: string;
+    author?: string | null;
+    createdAt?: string | null;
+    updatedAt?: string | null;
+    externalRef?: ExternalRef;
+}
+export interface WorkItem {
+    id: string;
+    title: string;
+    description?: string | null;
+    status: WorkStatus;
+    provider: WorkTrackingProviderName | string;
+    labels?: string[];
+    assignees?: string[];
+    milestone?: string | null;
+    createdAt?: string | null;
+    updatedAt?: string | null;
+    closedAt?: string | null;
+    webUrl?: string | null;
+    externalRef?: ExternalRef;
+}
+export interface WorkItemRef {
+    provider?: WorkTrackingProviderName | string;
+    id?: string;
+    externalRef?: ExternalRef;
+}
+export interface WorkItemQuery {
+    projectRoot?: string;
+    status?: WorkStatus | WorkStatus[];
+    labels?: string[];
+    assignees?: string[];
+    search?: string;
+    limit?: number;
+}
+export interface CreateWorkItemInput {
+    projectRoot?: string;
+    title: string;
+    description?: string | null;
+    status?: WorkStatus;
+    labels?: string[];
+    assignees?: string[];
+    milestone?: string | null;
+}
+export interface WorkItemPatch {
+    title?: string;
+    description?: string | null;
+    status?: WorkStatus;
+    labels?: string[];
+    assignees?: string[];
+    milestone?: string | null;
+}
+export interface TrackerCapabilities {
+    createItem: boolean;
+    listItems: boolean;
+    getItem: boolean;
+    updateItem: boolean;
+    comment: boolean;
+    labels: boolean;
+    assignees: boolean;
+    milestones: boolean;
+    board: boolean;
+    boardStatus: boolean;
+    draftItems: boolean;
+    webhooks: boolean;
+}
+export type WorkTrackerCapabilityName = "create" | "list" | "get" | "update" | "comment" | "labels" | "assignees" | "milestones" | "board" | "boardStatus";
+export interface WorkTrackerActionCapabilities {
+    create: boolean;
+    list: boolean;
+    get: boolean;
+    update: boolean;
+    comment: boolean;
+    labels: boolean;
+    assignees: boolean;
+    milestones: boolean;
+    board: boolean;
+    boardStatus: boolean;
+}
+export interface WorkTrackerCapabilityReport {
+    provider: WorkTrackingProviderName | string;
+    capabilities: WorkTrackerActionCapabilities;
+    unsupported: WorkTrackerCapabilityName[];
+}
+export interface TrackerProjectRef {
+    provider: WorkTrackingProviderName | string;
+    id: string;
+    name?: string;
+    externalRef?: ExternalRef;
+}
+export interface TrackerBoardRef {
+    provider: WorkTrackingProviderName | string;
+    id: string;
+    name?: string;
+    externalRef?: ExternalRef;
+}
+export interface DetectedTracker {
+    confidence: "low" | "medium" | "high";
+    config: WorkTrackingConfig;
+    reason?: string;
+}
+export interface DetectTrackerInput {
+    projectRoot: string;
+    remoteUrl?: string | null;
+}
+export interface NexusProjectContext {
+    homePath: string;
+    projectRoot: string;
+    projectId: string;
+    projectName: string;
+    componentId?: string;
+    componentName?: string;
+    sourceRoot?: string;
+    workTracking?: WorkTrackingConfig;
+}
+export interface WorkTrackerProvider {
+    provider: WorkTrackingProviderName | string;
+    capabilities: TrackerCapabilities;
+    detect?(input: DetectTrackerInput): Promise<DetectedTracker | undefined>;
+    ensureProject?(context: NexusProjectContext): Promise<TrackerProjectRef>;
+    ensureBoard?(context: NexusProjectContext): Promise<TrackerBoardRef>;
+    createWorkItem(input: CreateWorkItemInput): Promise<WorkItem>;
+    listWorkItems(query: WorkItemQuery): Promise<WorkItem[]>;
+    getWorkItem(ref: WorkItemRef): Promise<WorkItem>;
+    updateWorkItem(ref: WorkItemRef, patch: WorkItemPatch): Promise<WorkItem>;
+    addComment(ref: WorkItemRef, body: string): Promise<WorkComment>;
+    setStatus?(ref: WorkItemRef, status: WorkStatus): Promise<WorkItem>;
+}

package/dist/workTrackingTypes.js

@@ -0,0 +1 @@
+export {};

package/dist/workTrackingVibeProvider.d.ts

@@ -0,0 +1,35 @@
+import { type EnsureVibeKanbanBoardResult } from "./vibeKanbanBoardAdapter.js";
+import { type RegisterVibeKanbanProjectResult } from "./vibeKanbanProjectAdapter.js";
+import type { VibeKanbanApiOptions } from "./vibeKanbanApi.js";
+import type { CreateWorkItemInput, NexusProjectContext, TrackerBoardRef, TrackerCapabilities, TrackerProjectRef, VibeKanbanWorkTrackingConfig, WorkComment, WorkItem, WorkItemPatch, WorkItemQuery, WorkItemRef, WorkStatus, WorkTrackerProvider } from "./workTrackingTypes.js";
+export interface VibeWorkTrackerProviderOptions extends VibeKanbanApiOptions {
+    config?: VibeKanbanWorkTrackingConfig;
+    color?: string;
+}
+export interface VibeTrackerProjectRef extends TrackerProjectRef {
+    vibeKanbanRepo: RegisterVibeKanbanProjectResult;
+}
+export interface VibeTrackerBoardRef extends TrackerBoardRef {
+    vibeKanbanBoard: EnsureVibeKanbanBoardResult;
+}
+export declare class VibeWorkTrackerProviderError extends Error {
+    constructor(message: string);
+}
+export declare const vibeWorkTrackerCapabilities: TrackerCapabilities;
+export declare function createVibeWorkTrackerProvider(options: VibeWorkTrackerProviderOptions): VibeWorkTrackerProvider;
+export declare class VibeWorkTrackerProvider implements WorkTrackerProvider {
+    readonly provider = "vibe-kanban";
+    readonly capabilities: TrackerCapabilities;
+    private readonly options;
+    constructor(options: VibeWorkTrackerProviderOptions);
+    ensureProject(context: NexusProjectContext): Promise<VibeTrackerProjectRef>;
+    ensureBoard(context: NexusProjectContext): Promise<VibeTrackerBoardRef>;
+    createWorkItem(_input: CreateWorkItemInput): Promise<WorkItem>;
+    listWorkItems(_query: WorkItemQuery): Promise<WorkItem[]>;
+    getWorkItem(_ref: WorkItemRef): Promise<WorkItem>;
+    updateWorkItem(_ref: WorkItemRef, _patch: WorkItemPatch): Promise<WorkItem>;
+    addComment(_ref: WorkItemRef, _body: string): Promise<WorkComment>;
+    setStatus(_ref: WorkItemRef, _status: WorkStatus): Promise<WorkItem>;
+    private vibeProjectOptions;
+    private vibeBoardOptions;
+}

package/dist/workTrackingVibeProvider.js

@@ -0,0 +1,119 @@
+import { ensureVibeKanbanBoard, } from "./vibeKanbanBoardAdapter.js";
+import { registerVibeKanbanProject, } from "./vibeKanbanProjectAdapter.js";
+export class VibeWorkTrackerProviderError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "VibeWorkTrackerProviderError";
+    }
+}
+export const vibeWorkTrackerCapabilities = {
+    createItem: false,
+    listItems: false,
+    getItem: false,
+    updateItem: false,
+    comment: false,
+    labels: false,
+    assignees: false,
+    milestones: false,
+    board: true,
+    boardStatus: false,
+    draftItems: false,
+    webhooks: false,
+};
+export function createVibeWorkTrackerProvider(options) {
+    return new VibeWorkTrackerProvider(options);
+}
+export class VibeWorkTrackerProvider {
+    provider = "vibe-kanban";
+    capabilities = vibeWorkTrackerCapabilities;
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async ensureProject(context) {
+        const projectRoot = sourceRootFor(context);
+        const result = await registerVibeKanbanProject({
+            ...this.vibeProjectOptions(),
+            projectRoot,
+            name: context.projectName,
+        });
+        const name = result.project.display_name ?? result.project.name ?? context.projectName;
+        return {
+            provider: "vibe-kanban",
+            id: result.projectId,
+            name,
+            vibeKanbanRepo: result,
+            externalRef: {
+                provider: "vibe-kanban",
+                host: this.options.host ?? null,
+                itemId: result.projectId,
+                projectId: result.projectId,
+                repositoryId: result.projectId,
+            },
+        };
+    }
+    async ensureBoard(context) {
+        const result = await ensureVibeKanbanBoard({
+            ...this.vibeBoardOptions(),
+            name: context.projectName,
+            color: this.options.color,
+        });
+        return {
+            provider: "vibe-kanban",
+            id: result.boardId,
+            name: result.board.name,
+            vibeKanbanBoard: result,
+            externalRef: {
+                provider: "vibe-kanban",
+                host: this.options.host ?? null,
+                itemId: result.boardId,
+                projectId: result.boardId,
+                boardId: result.boardId,
+            },
+        };
+    }
+    async createWorkItem(_input) {
+        throw unsupportedVibeWorkItemsError("createWorkItem");
+    }
+    async listWorkItems(_query) {
+        throw unsupportedVibeWorkItemsError("listWorkItems");
+    }
+    async getWorkItem(_ref) {
+        throw unsupportedVibeWorkItemsError("getWorkItem");
+    }
+    async updateWorkItem(_ref, _patch) {
+        throw unsupportedVibeWorkItemsError("updateWorkItem");
+    }
+    async addComment(_ref, _body) {
+        throw unsupportedVibeWorkItemsError("addComment");
+    }
+    async setStatus(_ref, _status) {
+        throw unsupportedVibeWorkItemsError("setStatus");
+    }
+    vibeProjectOptions() {
+        return {
+            host: this.options.host,
+            port: this.options.port,
+            fetch: this.options.fetch,
+        };
+    }
+    vibeBoardOptions() {
+        return {
+            host: this.options.host,
+            port: this.options.port,
+            fetch: this.options.fetch,
+            organizationId: this.options.config?.board?.owner ?? undefined,
+            name: "",
+        };
+    }
+}
+function sourceRootFor(context) {
+    const projectRoot = context.sourceRoot ?? context.projectRoot;
+    if (projectRoot.trim().length === 0) {
+        throw new VibeWorkTrackerProviderError("projectRoot is required");
+    }
+    return projectRoot;
+}
+function unsupportedVibeWorkItemsError(operation) {
+    return new VibeWorkTrackerProviderError(`Vibe Kanban provider does not support neutral work item operation: ${operation}`);
+}

package/dist/worktreeExecutionMetadata.d.ts

@@ -0,0 +1,76 @@
+export type WorktreeVerificationStatus = "passed" | "failed" | "not_run";
+export type WorktreePublicationDecisionType = "not_decided" | "local_only" | "direct_integration" | "review_handoff" | "blocked";
+export interface WorktreeVerificationInput {
+    command: string;
+    status?: WorktreeVerificationStatus;
+    summary?: string | null;
+}
+export interface WorktreeVerificationRecord {
+    command: string;
+    status: WorktreeVerificationStatus;
+    summary: string | null;
+    recordedAt: string;
+}
+export interface WorktreePublicationDecisionInput {
+    type: WorktreePublicationDecisionType;
+    targetBranch?: string | null;
+    remote?: string | null;
+    prUrl?: string | null;
+    reason?: string | null;
+}
+export interface WorktreePublicationDecision {
+    type: WorktreePublicationDecisionType;
+    targetBranch: string | null;
+    remote: string | null;
+    prUrl: string | null;
+    reason: string | null;
+    decidedAt: string;
+}
+export interface WorktreeOwnerWorkItem {
+    id: string;
+    title: string | null;
+}
+export interface WorktreeOwnershipMetadata {
+    componentId: string;
+    sourceRoot: string;
+    worktreesRoot: string;
+    worktreePath: string;
+    branchName: string;
+    baseRef: string | null;
+    workItem: WorktreeOwnerWorkItem | null;
+}
+export interface WorktreeExecutionMetadata {
+    worktree: WorktreeOwnershipMetadata | null;
+    commitIds: string[];
+    verification: WorktreeVerificationRecord[];
+    publicationDecision: WorktreePublicationDecision | null;
+    updatedAt: string | null;
+}
+export interface WorktreeExecutionUpdate {
+    worktree?: WorktreeOwnershipMetadata | null;
+    commitIds?: string[];
+    verification?: WorktreeVerificationInput;
+    publicationDecision?: WorktreePublicationDecisionInput;
+}
+export declare const worktreeExecutionMetadataDirectoryName = ".dev-nexus";
+export declare const worktreeExecutionMetadataFileName = "execution.json";
+export declare class WorktreeExecutionMetadataError extends Error {
+    constructor(message: string);
+}
+export declare function emptyWorktreeExecutionMetadata(): WorktreeExecutionMetadata;
+export declare function worktreeExecutionMetadataPath(worktreePath: string): string;
+export declare function readWorktreeExecutionMetadata(worktreePath: string): WorktreeExecutionMetadata;
+export declare function writeWorktreeExecutionMetadata(worktreePath: string, metadata: WorktreeExecutionMetadata): string;
+export declare function updateWorktreeExecutionMetadata(worktreePath: string, update: WorktreeExecutionUpdate, now?: Date | string): WorktreeExecutionMetadata;
+export declare function hasWorktreeExecutionUpdate(update: WorktreeExecutionUpdate): boolean;
+export declare function applyWorktreeExecutionUpdate(existing: unknown, update: WorktreeExecutionUpdate, updatedAt: string): WorktreeExecutionMetadata;
+export declare function normalizeWorktreeExecutionMetadata(value: unknown): WorktreeExecutionMetadata;
+export declare function worktreeOwnershipMetadataFromPreparedWorktree(value: {
+    componentId: string;
+    sourceRoot: string;
+    worktreesRoot: string;
+    worktreePath: string;
+    branchName: string;
+    baseRef: string | null;
+    workItem: WorktreeOwnerWorkItem | null;
+}): WorktreeOwnershipMetadata;

package/dist/worktreeExecutionMetadata.js

@@ -0,0 +1,239 @@
+import fs from "node:fs";
+import path from "node:path";
+export const worktreeExecutionMetadataDirectoryName = ".dev-nexus";
+export const worktreeExecutionMetadataFileName = "execution.json";
+export class WorktreeExecutionMetadataError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "WorktreeExecutionMetadataError";
+    }
+}
+export function emptyWorktreeExecutionMetadata() {
+    return {
+        worktree: null,
+        commitIds: [],
+        verification: [],
+        publicationDecision: null,
+        updatedAt: null,
+    };
+}
+export function worktreeExecutionMetadataPath(worktreePath) {
+    return path.join(path.resolve(requiredNonEmptyString(worktreePath, "worktreePath")), worktreeExecutionMetadataDirectoryName, worktreeExecutionMetadataFileName);
+}
+export function readWorktreeExecutionMetadata(worktreePath) {
+    const metadataPath = worktreeExecutionMetadataPath(worktreePath);
+    if (!fs.existsSync(metadataPath)) {
+        return emptyWorktreeExecutionMetadata();
+    }
+    return normalizeWorktreeExecutionMetadata(JSON.parse(fs.readFileSync(metadataPath, "utf8").replace(/^\uFEFF/, "")));
+}
+export function writeWorktreeExecutionMetadata(worktreePath, metadata) {
+    const metadataPath = worktreeExecutionMetadataPath(worktreePath);
+    const normalized = normalizeWorktreeExecutionMetadata(metadata);
+    fs.mkdirSync(path.dirname(metadataPath), { recursive: true });
+    fs.writeFileSync(metadataPath, `${JSON.stringify(normalized, null, 2)}\n`, "utf8");
+    return metadataPath;
+}
+export function updateWorktreeExecutionMetadata(worktreePath, update, now = new Date()) {
+    const updated = applyWorktreeExecutionUpdate(readWorktreeExecutionMetadata(worktreePath), update, isoString(now));
+    writeWorktreeExecutionMetadata(worktreePath, updated);
+    return updated;
+}
+export function hasWorktreeExecutionUpdate(update) {
+    return Boolean(Object.prototype.hasOwnProperty.call(update, "worktree") ||
+        update.commitIds?.length ||
+        update.verification ||
+        update.publicationDecision);
+}
+export function applyWorktreeExecutionUpdate(existing, update, updatedAt) {
+    if (!hasWorktreeExecutionUpdate(update)) {
+        throw new WorktreeExecutionMetadataError("At least one execution field is required");
+    }
+    const execution = normalizeWorktreeExecutionMetadata(existing);
+    const worktree = Object.prototype.hasOwnProperty.call(update, "worktree")
+        ? normalizeWorktreeOwnership(update.worktree)
+        : execution.worktree;
+    const commitIds = [...execution.commitIds];
+    for (const commitId of update.commitIds ?? []) {
+        const normalized = requiredNonEmptyString(commitId, "commitId");
+        if (!commitIds.includes(normalized)) {
+            commitIds.push(normalized);
+        }
+    }
+    const verification = [...execution.verification];
+    if (update.verification) {
+        verification.push({
+            command: requiredNonEmptyString(update.verification.command, "verification.command"),
+            status: update.verification.status ?? "passed",
+            summary: optionalNullableString(update.verification.summary) ?? null,
+            recordedAt: requiredNonEmptyString(updatedAt, "updatedAt"),
+        });
+    }
+    const publicationDecision = update.publicationDecision
+        ? {
+            type: normalizePublicationDecisionType(update.publicationDecision.type, "publicationDecision.type"),
+            targetBranch: optionalNullableString(update.publicationDecision.targetBranch) ?? null,
+            remote: optionalNullableString(update.publicationDecision.remote) ?? null,
+            prUrl: optionalNullableString(update.publicationDecision.prUrl) ?? null,
+            reason: optionalNullableString(update.publicationDecision.reason) ?? null,
+            decidedAt: requiredNonEmptyString(updatedAt, "updatedAt"),
+        }
+        : execution.publicationDecision;
+    return {
+        worktree,
+        commitIds,
+        verification,
+        publicationDecision,
+        updatedAt: requiredNonEmptyString(updatedAt, "updatedAt"),
+    };
+}
+export function normalizeWorktreeExecutionMetadata(value) {
+    if (value === undefined || value === null) {
+        return emptyWorktreeExecutionMetadata();
+    }
+    if (typeof value !== "object" || Array.isArray(value)) {
+        throw new WorktreeExecutionMetadataError("worktree execution metadata must be an object");
+    }
+    const record = value;
+    return {
+        worktree: normalizeWorktreeOwnership(record.worktree),
+        commitIds: normalizeStringArray(record.commitIds, "execution.commitIds"),
+        verification: normalizeVerificationRecords(record.verification),
+        publicationDecision: normalizePublicationDecision(record.publicationDecision),
+        updatedAt: typeof record.updatedAt === "string" && record.updatedAt.trim()
+            ? record.updatedAt
+            : null,
+    };
+}
+export function worktreeOwnershipMetadataFromPreparedWorktree(value) {
+    const normalized = normalizeWorktreeOwnership(value);
+    if (!normalized) {
+        throw new WorktreeExecutionMetadataError("prepared worktree ownership metadata is required");
+    }
+    return normalized;
+}
+function normalizeWorktreeOwnership(value) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    if (typeof value !== "object" || Array.isArray(value)) {
+        throw new WorktreeExecutionMetadataError("execution.worktree must be an object or null");
+    }
+    const record = value;
+    const sourceRoot = path.resolve(requiredNonEmptyString(record.sourceRoot, "execution.worktree.sourceRoot"));
+    const worktreesRoot = path.resolve(requiredNonEmptyString(record.worktreesRoot, "execution.worktree.worktreesRoot"));
+    const worktreePath = path.resolve(requiredNonEmptyString(record.worktreePath, "execution.worktree.worktreePath"));
+    assertWorktreePathInsideRoot(worktreesRoot, worktreePath);
+    return {
+        componentId: requiredNonEmptyString(record.componentId, "execution.worktree.componentId"),
+        sourceRoot,
+        worktreesRoot,
+        worktreePath,
+        branchName: requiredNonEmptyString(record.branchName, "execution.worktree.branchName"),
+        baseRef: optionalNullableString(record.baseRef) ?? null,
+        workItem: normalizeWorktreeOwnerWorkItem(record.workItem),
+    };
+}
+function normalizeWorktreeOwnerWorkItem(value) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    if (typeof value !== "object" || Array.isArray(value)) {
+        throw new WorktreeExecutionMetadataError("execution.worktree.workItem must be an object or null");
+    }
+    const record = value;
+    return {
+        id: requiredNonEmptyString(record.id, "execution.worktree.workItem.id"),
+        title: optionalNullableString(record.title) ?? null,
+    };
+}
+function assertWorktreePathInsideRoot(worktreesRoot, worktreePath) {
+    const relative = path.relative(worktreesRoot, worktreePath);
+    if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+        throw new WorktreeExecutionMetadataError(`execution.worktree.worktreePath must resolve inside worktreesRoot: ${worktreePath}`);
+    }
+}
+function normalizeVerificationRecords(value) {
+    if (value === undefined || value === null) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        throw new WorktreeExecutionMetadataError("execution.verification must be an array");
+    }
+    return value.map((item, index) => {
+        if (!item || typeof item !== "object" || Array.isArray(item)) {
+            throw new WorktreeExecutionMetadataError(`execution.verification[${index}] must be an object`);
+        }
+        const record = item;
+        return {
+            command: requiredNonEmptyString(record.command, `execution.verification[${index}].command`),
+            status: normalizeVerificationStatus(record.status, `execution.verification[${index}].status`),
+            summary: optionalNullableString(record.summary) ?? null,
+            recordedAt: requiredNonEmptyString(record.recordedAt, `execution.verification[${index}].recordedAt`),
+        };
+    });
+}
+function normalizePublicationDecision(value) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    if (typeof value !== "object" || Array.isArray(value)) {
+        throw new WorktreeExecutionMetadataError("execution.publicationDecision must be an object or null");
+    }
+    const record = value;
+    return {
+        type: normalizePublicationDecisionType(record.type, "execution.publicationDecision.type"),
+        targetBranch: optionalNullableString(record.targetBranch) ?? null,
+        remote: optionalNullableString(record.remote) ?? null,
+        prUrl: optionalNullableString(record.prUrl) ?? null,
+        reason: optionalNullableString(record.reason) ?? null,
+        decidedAt: requiredNonEmptyString(record.decidedAt, "execution.publicationDecision.decidedAt"),
+    };
+}
+function normalizeStringArray(value, name) {
+    if (value === undefined || value === null) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        throw new WorktreeExecutionMetadataError(`${name} must be an array`);
+    }
+    return value.map((item, index) => requiredNonEmptyString(item, `${name}[${index}]`));
+}
+function normalizeVerificationStatus(value, name) {
+    if (value === "passed" || value === "failed" || value === "not_run") {
+        return value;
+    }
+    throw new WorktreeExecutionMetadataError(`${name} must be passed, failed, or not_run`);
+}
+function normalizePublicationDecisionType(value, name) {
+    if (value === "not_decided" ||
+        value === "local_only" ||
+        value === "direct_integration" ||
+        value === "review_handoff" ||
+        value === "blocked") {
+        return value;
+    }
+    throw new WorktreeExecutionMetadataError(`${name} must be not_decided, local_only, direct_integration, review_handoff, or blocked`);
+}
+function optionalNullableString(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (value === null) {
+        return null;
+    }
+    return requiredNonEmptyString(value, "value");
+}
+function isoString(value) {
+    const date = value instanceof Date ? value : new Date(value);
+    if (Number.isNaN(date.getTime())) {
+        throw new WorktreeExecutionMetadataError("now must be a valid date");
+    }
+    return date.toISOString();
+}
+function requiredNonEmptyString(value, name) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new WorktreeExecutionMetadataError(`${name} must be a non-empty string`);
+    }
+    return value.trim();
+}