create-vireo

export type CreateVireoOptions = {
    directory: string;
    profile?: VireoProfile;
    projectName?: string;
    displayName?: string;
    ownerName?: string;
    repositoryUrl?: string;
    supportUrl?: string;
    securityContact?: string;
    javaPackage?: string;
    database?: VireoDatabase;
    packageManager?: VireoPackageManager;
    git?: boolean;
    dryRun?: boolean;
    templateDirectory?: string;
};

export type CreateVireoResult = {
    directory: string;
    projectName: string;
    displayName: string;
    profile: VireoProfile;
    javaPackage?: string;
    database?: VireoDatabase;
    packageManager: VireoPackageManager;
    gitInitialized: boolean;
    templateCommit: string;
    dryRun: boolean;
};

export type EntityFieldSchema = {
    name: string;
    type: EntityFieldType;
    required?: boolean;
    unique?: boolean;
    default?: boolean | number | string;
    example?: boolean | number | string;
    enumValues?: string[];
    constraints?: {
        max?: number;
        min?: number;
        pattern?: string;
    };
    query?: {
        filterable?: boolean;
        searchable?: boolean;
        sortable?: boolean;
    };
    ui?: {
        control?: "checkbox" | "date" | "number" | "select" | "text" | "textarea";
        list?: boolean;
        label?: string;
    };
};

export type EntityFieldType = "boolean" | "date" | "decimal" | "enum" | "integer" | "long" | "string" | "text" | "timestamp" | "uuid";

export type EntityGenerationFileResult = {
    path: string;
    role: GeneratedFile["role"] | "manifest";
    status: "create" | "customized" | "delete" | "unchanged" | "update";
};

export type EntityGenerationManifest = {
    schemaVersion: 1;
    generatorVersion: string;
    target?: VireoGenerationTarget;
    entity: string;
    plural: string;
    fileStem: string;
    schemaDigest: string;
    contractDigest: string;
    schemaPath: string;
    files: ManifestFile[];
};

export type EntityNames = {
    className: string;
    constant: string;
    fileStem: string;
    packageName: string;
    packagePath: string;
    pageClass: string;
    plural: string;
    routeId: string;
};

export type EntityRelationshipSchema = {
    name: string;
    kind: "many-to-one";
    target: string;
    required?: boolean;
    displayField: string;
};

export declare class EntitySchemaError extends Error {
    readonly problems: string[];
    readonly code = "VIR-GEN-001";
    constructor(problems: string[]);
}

export type GenerateEntityOptions = {
    projectDirectory: string;
    schemaPath: string;
    outputDirectory?: string;
    dryRun?: boolean;
    force?: boolean;
    acceptOverwrite?: boolean;
    target?: VireoGenerationTarget;
};

export type GenerateEntityResult = {
    entity: string;
    plural: string;
    projectDirectory: string;
    outputDirectory: string;
    schemaDigest: string;
    contractDigest: string;
    target: VireoGenerationTarget;
    dryRun: boolean;
    files: EntityGenerationFileResult[];
};

export type GeneratedContractCheck = {
    entity: string;
    ok: boolean;
    problems: string[];
};

export type RemoveExampleFile = {
    path: string;
    status: "delete" | "update" | "create";
};

export type RemoveExampleResult = {
    projectDirectory: string;
    state: "present" | "removed";
    dryRun: boolean;
    files: RemoveExampleFile[];
};

export declare const TEMPLATE_ARCHIVE_URL = "https://codeload.github.com/vireocodedev/vireo-template/tar.gz/0557990f024a8736b6e661f8fc264861deb99b65";

export declare const TEMPLATE_COMMIT = "0557990f024a8736b6e661f8fc264861deb99b65";

export declare const VIREO_ENTITY_SCHEMA_VERSION: 1;

export declare const VIREO_GENERATOR_VERSION = "0.4.0";

export type VireoDatabase = "postgresql" | "h2";

export type VireoEntitySchema = {
    schemaVersion: typeof VIREO_ENTITY_SCHEMA_VERSION;
    kind: "entity";
    entity: {
        name: string;
        plural: string;
        description?: string;
    };
    database: {
        table: string;
        migrationVersion: number;
    };
    api: {
        path: string;
    };
    permissions: {
        read: string;
        manage: string;
    };
    capabilities: {
        history: boolean;
        offline: boolean;
        query: boolean;
    };
    fields: EntityFieldSchema[];
    relationships?: EntityRelationshipSchema[];
    localization: {
        en: {
            singular: string;
            plural: string;
        };
        hr?: {
            singular: string;
            plural: string;
        };
    };
};

export type VireoGenerationTarget = "frontend" | "full-stack";

export declare class VireoGeneratorError extends Error {
    readonly code: "VIR-GEN-002" | "VIR-GEN-003" | "VIR-GEN-004" | "VIR-GEN-005" | "VIR-GEN-006";
    constructor(code: "VIR-GEN-002" | "VIR-GEN-003" | "VIR-GEN-004" | "VIR-GEN-005" | "VIR-GEN-006", message: string);
}

export type VireoPackageManager = "npm";

export type VireoProfile = "full-stack" | "frontend";

export type VireoProjectStatus = {
    recordedRelease: string | null;
    templateCommit: string | null;
    currentRelease: string;
    targetRelease: string | null;
    targetTemplateCommit: string | null;
    nextHop: string | null;
    interruptedUpgrade: boolean;
    managedFiles: Array<{
        path: string;
        state: "clean" | "customized" | "missing" | "add" | "update" | "delete" | "unchanged" | "conflict" | "untracked";
    }>;
    applicationOwnedActions: VireoUpgradeManualAction[];
    capabilities: Array<{
        name: string;
        state: "managed" | "ejected";
    }>;
};

export type VireoUpgradeCheck = {
    id: "source" | "dependencies" | "lockfile" | "migrations" | "generated-contracts" | "application-owned";
    status: "pass" | "manual";
    detail: string;
};

export declare class VireoUpgradeError extends Error {
    readonly code: string;
    constructor(code: string, message: string);
}

export type VireoUpgradeFile = {
    path: string;
    status: "create" | "update" | "delete" | "unchanged";
};

export type VireoUpgradeOptions = {
    projectDirectory: string;
    targetRelease: string;
    dryRun?: boolean;
    acceptApplicationOwned?: boolean;
};

export type VireoUpgradeResult = {
    sourceRelease: string;
    targetRelease: string;
    targetTemplateCommit: string;
    dryRun: boolean;
    checks: VireoUpgradeCheck[];
    files: VireoUpgradeFile[];
    manualActions: VireoUpgradeManualAction[];
};

export type WireContract = {
    schemaVersion: 2;
    entity: string;
    id: {
        name: "id";
        type: "long";
        wireType: "integer";
    };
    fields: Array<{
        name: string;
        type: EntityFieldType;
        wireType: "boolean" | "integer" | "number" | "string";
        nullable: boolean;
        enumValues?: string[];
        constraints?: EntityFieldSchema["constraints"];
    }>;
    relationships: Array<{
        name: string;
        target: string;
        required: boolean;
        input: {
            name: string;
            wireType: "integer";
        };
        responseDisplay: {
            name: string;
            source: string;
            wireType: "string";
            nullable: boolean;
        };
    }>;
    createRequest: {
        fields: Array<{
            name: string;
            nullable: boolean;
            required: boolean;
            writable: true;
        }>;
    };
    patchRequest: {
        fields: Array<{
            name: string;
            omittedRetains: true;
            explicitNull: "clears" | "invalid";
            writable: true;
        }>;
    };
    response: {
        fields: Array<{
            name: string;
            nullable: boolean;
            responseOnly?: true;
        }>;
    };
    endpoints: {
        search: {
            method: "POST";
            path: string;
            response: "page";
        };
        create: {
            method: "POST";
            path: string;
            request: "create";
            response: "response";
        };
        update: {
            method: "PATCH";
            path: string;
            request: "patch";
            response: "response";
        };
        delete: {
            method: "DELETE";
            path: string;
        };
    };
    semantics: {
        date: "ISO-8601 calendar date";
        decimal: "JSON number; BigDecimal is canonical on the server" | "JSON number by default; the application adapter owns precision-sensitive transport mapping";
        errors: "Vireo ApiError { status, code, message, errors: field-message map or null, timestamp }; validation failures use code VALIDATION_FAILED" | "The application adapter normalizes backend-specific failures into frontend errors";
        nullability: "optional fields are explicit JSON null; unknown response fields are stripped by Zod";
        timestamp: "ISO-8601 UTC or offset timestamp";
    };
};

export declare function checkGeneratedEntities(projectDirectory: string): Promise<GeneratedContractCheck[]>;

export declare function createVireo(options: CreateVireoOptions): Promise<CreateVireoResult>;

export declare function createWireContract(schema: VireoEntitySchema, target?: VireoGenerationTarget, relationships?: ResolvedEntityRelationship[]): WireContract;

export declare function ejectEntity(projectDirectory: string, plural: string, dryRun?: boolean): Promise<{
    entity: string;
    plural: string;
    dryRun: boolean;
    retainedFiles: string[];
}>;

export declare function entityNames(schema: VireoEntitySchema, project: VireoProjectMetadata): EntityNames;

export declare function findExampleReferences(projectDirectory: string, profile?: ProjectMetadata["profile"]): Promise<string[]>;

export declare function generateEntity(options: GenerateEntityOptions): Promise<GenerateEntityResult>;

export declare function parseEntitySchema(value: unknown): VireoEntitySchema;

export declare function readEntitySchema(path: string): Promise<VireoEntitySchema>;

export declare function readProjectMetadata(projectDirectory: string): Promise<VireoProjectMetadata>;

export declare function removeExample(projectDirectory: string, apply?: boolean): Promise<RemoveExampleResult>;

The frontend projection owns this script rather than the Template. Keep its renderer public so release evidence can independently reproduce the frozen managed baseline without reading the upgrade policy itself.

/**
 * The frontend projection owns this script rather than the Template. Keep its
 * renderer public so release evidence can independently reproduce the frozen
 * managed baseline without reading the upgrade policy itself.
 */
export declare function renderFrontendDoctorScript(path: string): Promise<string>;

export declare function sha256(value: string | Uint8Array): string;

export declare function stableJson(value: unknown): string;

export declare function upgradeVireoProject(options: VireoUpgradeOptions): Promise<VireoUpgradeResult>;

export declare function vireoProjectStatus(projectDirectory: string): Promise<VireoProjectStatus>;