@forgedevv/shared 0.0.0-stage → 0.1.0

package/dist/constants.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Business constants shared by every FORGE app (docs/INTERFACES.md §1).
+ * Percentages are expressed in basis points (bps) unless the name says `Pct`.
+ */
+export declare const PRICING: {
+    readonly creationUsd: 33;
+    readonly modificationUsd: 5.5;
+    readonly includedModifications: 2;
+    readonly maxAttemptsBeforeRefund: 2;
+    readonly quoteValiditySeconds: 120;
+};
+export declare const FEES: {
+    /** Our fee on our own buy button (before graduation). */
+    readonly platformFeeBps: 30;
+    /** After graduation; Jupiter keeps 20 % of it. */
+    readonly jupiterIntegratorFeeBps: 30;
+    /** FORGE creator share on the coin of every launchpad. */
+    readonly forgeCreatorSharePct: 25;
+};
+export declare const CLIENT_BOUNDS: {
+    /** Trading fee range offered to clients. */
+    readonly tradingFeeBps: {
+        readonly min: 50;
+        readonly max: 200;
+    };
+    readonly coinCreatorSharePct: {
+        readonly min: 0;
+        readonly max: 50;
+        readonly default: 25;
+    };
+    /**
+     * Coin creation fee set by the client: 0 (no fee) or between 0.001 and 1 SOL
+     * (0.001 SOL = MIN_POOL_CREATION_FEE of the SDK). Whether the SDK accepts 0 must be
+     * confirmed by devnet test 1; otherwise the minimum becomes 0.001.
+     */
+    readonly poolCreationFeeSol: {
+        readonly min: 0.001;
+        readonly max: 1;
+        readonly allowZero: true;
+    };
+    /** Imposed (Meteora migration bots). */
+    readonly migrationThresholdSol: 10;
+};
+export declare const OPS: {
+    readonly dormantDaysBeforeSleep: 30;
+    readonly claimIntervalHours: 24;
+    readonly agentBudgetUsdPerJob: 15;
+    readonly agentTimeoutMinutes: 30;
+    /** Past this delay, an active job with no news is considered crashed. */
+    readonly jobLockStaleMinutes: 45;
+};
+/** 1 SOL = 1_000_000_000 lamports. */
+export declare const LAMPORTS_PER_SOL = 1000000000;

package/dist/constants.js

@@ -0,0 +1,42 @@
+/**
+ * Business constants shared by every FORGE app (docs/INTERFACES.md §1).
+ * Percentages are expressed in basis points (bps) unless the name says `Pct`.
+ */
+export const PRICING = {
+    creationUsd: 33,
+    modificationUsd: 5.5,
+    includedModifications: 2,
+    maxAttemptsBeforeRefund: 2,
+    quoteValiditySeconds: 120,
+};
+export const FEES = {
+    /** Our fee on our own buy button (before graduation). */
+    platformFeeBps: 30,
+    /** After graduation; Jupiter keeps 20 % of it. */
+    jupiterIntegratorFeeBps: 30,
+    /** FORGE creator share on the coin of every launchpad. */
+    forgeCreatorSharePct: 25,
+};
+export const CLIENT_BOUNDS = {
+    /** Trading fee range offered to clients. */
+    tradingFeeBps: { min: 50, max: 200 },
+    coinCreatorSharePct: { min: 0, max: 50, default: 25 },
+    /**
+     * Coin creation fee set by the client: 0 (no fee) or between 0.001 and 1 SOL
+     * (0.001 SOL = MIN_POOL_CREATION_FEE of the SDK). Whether the SDK accepts 0 must be
+     * confirmed by devnet test 1; otherwise the minimum becomes 0.001.
+     */
+    poolCreationFeeSol: { min: 0.001, max: 1, allowZero: true },
+    /** Imposed (Meteora migration bots). */
+    migrationThresholdSol: 10,
+};
+export const OPS = {
+    dormantDaysBeforeSleep: 30,
+    claimIntervalHours: 24,
+    agentBudgetUsdPerJob: 15,
+    agentTimeoutMinutes: 30,
+    /** Past this delay, an active job with no news is considered crashed. */
+    jobLockStaleMinutes: 45,
+};
+/** 1 SOL = 1_000_000_000 lamports. */
+export const LAMPORTS_PER_SOL = 1_000_000_000;

package/dist/db.d.ts

@@ -0,0 +1,164 @@
+import { z } from 'zod';
+import type { FailedStage, JobStatus, JobType } from './jobs.js';
+import { type LaunchpadSpec } from './spec.js';
+/**
+ * Row types of the Supabase tables (docs/INTERFACES.md §5). Column names are kept in snake_case.
+ * Nullability mirrors the SQL exactly: a column without `not null` is typed `| null`, even when
+ * it has a default.
+ */
+export declare const LaunchpadStatus: z.ZodEnum<{
+    live: "live";
+    draft: "draft";
+    sleeping: "sleeping";
+    disabled: "disabled";
+}>;
+export type LaunchpadStatus = z.infer<typeof LaunchpadStatus>;
+export declare const PaymentStatus: z.ZodEnum<{
+    refunded: "refunded";
+    quoted: "quoted";
+    confirmed: "confirmed";
+    expired: "expired";
+}>;
+export type PaymentStatus = z.infer<typeof PaymentStatus>;
+export declare const PaymentKind: z.ZodEnum<{
+    creation: "creation";
+    modification: "modification";
+}>;
+export type PaymentKind = z.infer<typeof PaymentKind>;
+export declare const ChatRole: z.ZodEnum<{
+    user: "user";
+    assistant: "assistant";
+    system: "system";
+}>;
+export type ChatRole = z.infer<typeof ChatRole>;
+/** Kill switches. */
+export declare const FlagKey: z.ZodEnum<{
+    deploys_paused: "deploys_paused";
+    buyback_paused: "buyback_paused";
+    signups_paused: "signups_paused";
+    claims_paused: "claims_paused";
+    cashbox_sweep_paused: "cashbox_sweep_paused";
+    refunds_paused: "refunds_paused";
+}>;
+export type FlagKey = z.infer<typeof FlagKey>;
+/** ISO 8601 timestamp as returned by PostgREST for `timestamptz`. */
+export type Timestamptz = string;
+/**
+ * Postgres `bigint` / `numeric`: PostgREST may return a JSON number or a string. Convert with
+ * `BigInt(String(value))` for lamports, never with floating point math.
+ */
+export type DbBigint = number | string;
+export type DbNumeric = number | string;
+export interface UserRow {
+    wallet: string;
+    created_at: Timestamptz | null;
+}
+export interface LaunchpadRow {
+    id: string;
+    owner_wallet: string;
+    slug: string;
+    spec: LaunchpadSpec;
+    github_repo: string | null;
+    vercel_project_id: string | null;
+    /** Meteora config address. */
+    launchpad_config: string | null;
+    launchpad_coin_config: string | null;
+    launchpad_coin_mint: string | null;
+    /** Identifier of the creator wallet inside the signer (never the key). */
+    creator_wallet_ref: string | null;
+    included_modifications_left: number | null;
+    status: LaunchpadStatus;
+    last_trade_at: Timestamptz | null;
+    created_at: Timestamptz | null;
+}
+/**
+ * `jobs.owner_tx_details` (jsonb): the public accounts of the launch transaction stored in
+ * `jobs.owner_tx`, as the signer reported them (`details` of `POST /v1/launch-coin/prepare`). The
+ * builder writes it in the same update as `owner_tx`; apps/web pins these accounts when it checks
+ * the stored transaction (`verifyLaunchCoinTransaction` of @forge/core) and hands them to the
+ * browser (`OwnerTransactionLaunch`), instead of reading them back from the transaction.
+ * `config` is the launchpad coin config. Null on rows written before migration 0009.
+ */
+export declare const JobOwnerTxDetails: z.ZodObject<{
+    config: z.ZodString;
+    pool: z.ZodString;
+    creator: z.ZodString;
+    nonceAccount: z.ZodString;
+    metadataUri: z.ZodURL;
+}, z.core.$strip>;
+export type JobOwnerTxDetails = z.infer<typeof JobOwnerTxDetails>;
+export interface JobRow {
+    id: string;
+    launchpad_id: string;
+    type: JobType;
+    status: JobStatus;
+    /** Build attempts only. */
+    attempts: number;
+    /** Set when status = 'failed'. */
+    failed_stage: FailedStage | null;
+    /** Client request (modifications). */
+    request: string | null;
+    preview_url: string | null;
+    /** Partially signed launch transaction (base64) with a durable nonce. */
+    owner_tx: string | null;
+    /** Launch accounts of `owner_tx` (jsonb, validate with `JobOwnerTxDetails` when reading). */
+    owner_tx_details: JobOwnerTxDetails | null;
+    error: string | null;
+    api_cost_usd: DbNumeric | null;
+    /** Id of the worker holding the job. */
+    locked_by: string | null;
+    locked_at: Timestamptz | null;
+    created_at: Timestamptz | null;
+    updated_at: Timestamptz | null;
+}
+export interface PaymentRow {
+    id: string;
+    job_id: string;
+    /** = launchpads.owner_wallet */
+    payer_wallet: string;
+    kind: PaymentKind;
+    usd_amount: DbNumeric;
+    lamports: DbBigint;
+    quote_expires_at: Timestamptz;
+    tx_signature: string | null;
+    status: PaymentStatus;
+    refund_signature: string | null;
+    created_at: Timestamptz | null;
+}
+export interface ConversationRow {
+    id: string;
+    owner_wallet: string;
+    /** Null while designing, set when the spec is confirmed. */
+    launchpad_id: string | null;
+    created_at: Timestamptz | null;
+}
+export interface ChatMessageRow {
+    id: number;
+    conversation_id: string;
+    role: ChatRole;
+    content: string;
+    created_at: Timestamptz | null;
+}
+export interface JobEventRow {
+    id: number;
+    job_id: string;
+    /** Shown in the chat in real time. */
+    message: string;
+    created_at: Timestamptz | null;
+}
+export interface FlagRow {
+    key: FlagKey;
+    value: boolean;
+}
+/** Table name -> row type. */
+export interface Tables {
+    users: UserRow;
+    launchpads: LaunchpadRow;
+    jobs: JobRow;
+    payments: PaymentRow;
+    conversations: ConversationRow;
+    chat_messages: ChatMessageRow;
+    job_events: JobEventRow;
+    flags: FlagRow;
+}
+export type TableName = keyof Tables;

package/dist/db.js

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+import { SolanaAddress } from './spec.js';
+/**
+ * Row types of the Supabase tables (docs/INTERFACES.md §5). Column names are kept in snake_case.
+ * Nullability mirrors the SQL exactly: a column without `not null` is typed `| null`, even when
+ * it has a default.
+ */
+export const LaunchpadStatus = z.enum(['draft', 'live', 'sleeping', 'disabled']);
+export const PaymentStatus = z.enum(['quoted', 'confirmed', 'expired', 'refunded']);
+export const PaymentKind = z.enum(['creation', 'modification']);
+export const ChatRole = z.enum(['user', 'assistant', 'system']);
+/** Kill switches. */
+export const FlagKey = z.enum([
+    'deploys_paused',
+    'buyback_paused',
+    'signups_paused',
+    'claims_paused',
+    'cashbox_sweep_paused',
+    'refunds_paused',
+]);
+/**
+ * `jobs.owner_tx_details` (jsonb): the public accounts of the launch transaction stored in
+ * `jobs.owner_tx`, as the signer reported them (`details` of `POST /v1/launch-coin/prepare`). The
+ * builder writes it in the same update as `owner_tx`; apps/web pins these accounts when it checks
+ * the stored transaction (`verifyLaunchCoinTransaction` of @forge/core) and hands them to the
+ * browser (`OwnerTransactionLaunch`), instead of reading them back from the transaction.
+ * `config` is the launchpad coin config. Null on rows written before migration 0009.
+ */
+export const JobOwnerTxDetails = z.object({
+    config: SolanaAddress,
+    pool: SolanaAddress,
+    /** FORGE creator wallet of the launchpad: pool creator and durable nonce authority. */
+    creator: SolanaAddress,
+    /** Durable nonce account of the launch transaction. */
+    nonceAccount: SolanaAddress,
+    /** Coin metadata URI written by the pool creation (https, kept exactly as sent). */
+    metadataUri: z.url({ protocol: /^https$/, error: 'Must be an https URL' }),
+});

package/dist/env.d.ts

@@ -0,0 +1,21 @@
+export declare const R2_ENV: readonly ["R2_ACCESS_KEY_ID", "R2_SECRET_ACCESS_KEY", "R2_ACCOUNT_ID", "R2_BUCKET"];
+/** Variables that may be absent. FORGE_MINT is absent before the $FORGE launch. */
+export declare const OPTIONAL_ENV: readonly ["FORGE_MINT"];
+/**
+ * apps/web. RPC_URL and SUPABASE_SERVICE_ROLE_KEY are server-only.
+ * FORGE_GATING_AMOUNT is required only when FORGE_MINT is set.
+ */
+export declare const WEB_ENV: readonly ["SOLANA_CLUSTER", "RPC_URL", "SUPABASE_URL", "SUPABASE_ANON_KEY", "SUPABASE_SERVICE_ROLE_KEY", "ANTHROPIC_API_KEY", "FORGE_MINT", "FORGE_GATING_AMOUNT", "FORGE_CASHBOX_WALLET", "JUPITER_API_KEY", "SESSION_SECRET", "SUPABASE_JWT_SECRET", "NEXT_PUBLIC_APP_URL", "NEXT_PUBLIC_SUPABASE_URL", "NEXT_PUBLIC_SUPABASE_ANON_KEY", "NEXT_PUBLIC_SOLANA_CLUSTER", "R2_ACCESS_KEY_ID", "R2_SECRET_ACCESS_KEY", "R2_ACCOUNT_ID", "R2_BUCKET"];
+/** apps/launchpad-template. RPC_URL is server-only; FORGE_* addresses are read through @forge/core. */
+export declare const TEMPLATE_ENV: readonly ["SOLANA_CLUSTER", "RPC_URL", "FORGE_MULTISIG_VAULT", "FORGE_METEORA_REFERRAL_ACCOUNT", "FORGE_PLATFORM_FEE_WALLET", "FORGE_JUPITER_REFERRAL_ACCOUNT", "JUPITER_API_KEY", "R2_ACCESS_KEY_ID", "R2_SECRET_ACCESS_KEY", "R2_ACCOUNT_ID", "R2_BUCKET"];
+/** Variables the builder does not use itself but copies into each client Vercel project. */
+export declare const BUILDER_VERCEL_INJECTED_ENV: readonly ["FORGE_MULTISIG_VAULT", "FORGE_METEORA_REFERRAL_ACCOUNT", "FORGE_PLATFORM_FEE_WALLET", "FORGE_JUPITER_REFERRAL_ACCOUNT", "JUPITER_API_KEY", "R2_ACCESS_KEY_ID", "R2_SECRET_ACCESS_KEY", "R2_ACCOUNT_ID", "R2_BUCKET"];
+/** apps/builder. ANTHROPIC_API_KEY is used by the gateway only. */
+export declare const BUILDER_ENV: readonly ["SOLANA_CLUSTER", "SUPABASE_URL", "SUPABASE_SERVICE_ROLE_KEY", "ANTHROPIC_API_KEY", "FORGE_MULTISIG_VAULT", "FORGE_METEORA_REFERRAL_ACCOUNT", "FORGE_PLATFORM_FEE_WALLET", "FORGE_JUPITER_REFERRAL_ACCOUNT", "JUPITER_API_KEY", "R2_ACCESS_KEY_ID", "R2_SECRET_ACCESS_KEY", "R2_ACCOUNT_ID", "R2_BUCKET", "GITHUB_APP_ID", "GITHUB_APP_PRIVATE_KEY", "GITHUB_ORG", "VERCEL_TOKEN", "VERCEL_TEAM_ID", "SIGNER_URL", "SIGNER_HMAC_SECRET", "TELEGRAM_BOT_TOKEN", "TELEGRAM_CHAT_ID"];
+/** apps/signer. FORGE_MINT is used for the buyback (simulation mode when absent). */
+export declare const SIGNER_ENV: readonly ["SOLANA_CLUSTER", "RPC_URL", "SUPABASE_URL", "SUPABASE_SERVICE_ROLE_KEY", "FORGE_MINT", "FORGE_CASHBOX_WALLET", "FORGE_MULTISIG_VAULT", "FORGE_JUPITER_REFERRAL_ACCOUNT", "JUPITER_API_KEY", "SIGNER_URL", "SIGNER_HMAC_SECRET", "SIGNER_KEYSTORE_PASSPHRASE", "SIGNER_KEYSTORE_DIR", "SIGNER_ALLOWED_IPS", "SIGNER_PORT", "TELEGRAM_BOT_TOKEN", "TELEGRAM_CHAT_ID"];
+export type WebEnvName = (typeof WEB_ENV)[number];
+export type TemplateEnvName = (typeof TEMPLATE_ENV)[number];
+export type BuilderEnvName = (typeof BUILDER_ENV)[number];
+export type SignerEnvName = (typeof SIGNER_ENV)[number];
+export type EnvName = WebEnvName | TemplateEnvName | BuilderEnvName | SignerEnvName;

package/dist/env.js

@@ -0,0 +1,92 @@
+/*
+ * Environment variable names per app (docs/INTERFACES.md §8). Names only, never values.
+ * `R2_*` is expanded to the variables of the fun-launch scaffold (docs/METEORA.md).
+ */
+export const R2_ENV = [
+    'R2_ACCESS_KEY_ID',
+    'R2_SECRET_ACCESS_KEY',
+    'R2_ACCOUNT_ID',
+    'R2_BUCKET',
+];
+/** Variables that may be absent. FORGE_MINT is absent before the $FORGE launch. */
+export const OPTIONAL_ENV = ['FORGE_MINT'];
+/**
+ * apps/web. RPC_URL and SUPABASE_SERVICE_ROLE_KEY are server-only.
+ * FORGE_GATING_AMOUNT is required only when FORGE_MINT is set.
+ */
+export const WEB_ENV = [
+    'SOLANA_CLUSTER',
+    'RPC_URL',
+    'SUPABASE_URL',
+    'SUPABASE_ANON_KEY',
+    'SUPABASE_SERVICE_ROLE_KEY',
+    'ANTHROPIC_API_KEY',
+    'FORGE_MINT',
+    'FORGE_GATING_AMOUNT',
+    'FORGE_CASHBOX_WALLET',
+    'JUPITER_API_KEY',
+    'SESSION_SECRET',
+    'SUPABASE_JWT_SECRET',
+    'NEXT_PUBLIC_APP_URL',
+    'NEXT_PUBLIC_SUPABASE_URL',
+    'NEXT_PUBLIC_SUPABASE_ANON_KEY',
+    'NEXT_PUBLIC_SOLANA_CLUSTER',
+    ...R2_ENV,
+];
+/** apps/launchpad-template. RPC_URL is server-only; FORGE_* addresses are read through @forge/core. */
+export const TEMPLATE_ENV = [
+    'SOLANA_CLUSTER',
+    'RPC_URL',
+    'FORGE_MULTISIG_VAULT',
+    'FORGE_METEORA_REFERRAL_ACCOUNT',
+    'FORGE_PLATFORM_FEE_WALLET',
+    'FORGE_JUPITER_REFERRAL_ACCOUNT',
+    'JUPITER_API_KEY',
+    ...R2_ENV,
+];
+/** Variables the builder does not use itself but copies into each client Vercel project. */
+export const BUILDER_VERCEL_INJECTED_ENV = [
+    'FORGE_MULTISIG_VAULT',
+    'FORGE_METEORA_REFERRAL_ACCOUNT',
+    'FORGE_PLATFORM_FEE_WALLET',
+    'FORGE_JUPITER_REFERRAL_ACCOUNT',
+    'JUPITER_API_KEY',
+    ...R2_ENV,
+];
+/** apps/builder. ANTHROPIC_API_KEY is used by the gateway only. */
+export const BUILDER_ENV = [
+    'SOLANA_CLUSTER',
+    'SUPABASE_URL',
+    'SUPABASE_SERVICE_ROLE_KEY',
+    'ANTHROPIC_API_KEY',
+    ...BUILDER_VERCEL_INJECTED_ENV,
+    'GITHUB_APP_ID',
+    'GITHUB_APP_PRIVATE_KEY',
+    'GITHUB_ORG',
+    'VERCEL_TOKEN',
+    'VERCEL_TEAM_ID',
+    'SIGNER_URL',
+    'SIGNER_HMAC_SECRET',
+    'TELEGRAM_BOT_TOKEN',
+    'TELEGRAM_CHAT_ID',
+];
+/** apps/signer. FORGE_MINT is used for the buyback (simulation mode when absent). */
+export const SIGNER_ENV = [
+    'SOLANA_CLUSTER',
+    'RPC_URL',
+    'SUPABASE_URL',
+    'SUPABASE_SERVICE_ROLE_KEY',
+    'FORGE_MINT',
+    'FORGE_CASHBOX_WALLET',
+    'FORGE_MULTISIG_VAULT',
+    'FORGE_JUPITER_REFERRAL_ACCOUNT',
+    'JUPITER_API_KEY',
+    'SIGNER_URL',
+    'SIGNER_HMAC_SECRET',
+    'SIGNER_KEYSTORE_PASSPHRASE',
+    'SIGNER_KEYSTORE_DIR',
+    'SIGNER_ALLOWED_IPS',
+    'SIGNER_PORT',
+    'TELEGRAM_BOT_TOKEN',
+    'TELEGRAM_CHAT_ID',
+];

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from './constants.js';
+export * from './spec.js';
+export * from './site-config.js';
+export * from './jobs.js';
+export * from './db.js';
+export * from './api.js';
+export * from './web-client.js';
+export * from './env.js';

package/dist/index.js

@@ -0,0 +1,8 @@
+export * from './constants.js';
+export * from './spec.js';
+export * from './site-config.js';
+export * from './jobs.js';
+export * from './db.js';
+export * from './api.js';
+export * from './web-client.js';
+export * from './env.js';

package/dist/jobs.d.ts

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+/** Job statuses (docs/INTERFACES.md §4). */
+export declare const JobStatus: z.ZodEnum<{
+    spec_ready: "spec_ready";
+    paid: "paid";
+    building: "building";
+    preview_ready: "preview_ready";
+    approved: "approved";
+    onchain_setup: "onchain_setup";
+    awaiting_owner_signature: "awaiting_owner_signature";
+    owner_signed: "owner_signed";
+    deploying: "deploying";
+    live: "live";
+    failed: "failed";
+    refunded: "refunded";
+}>;
+export type JobStatus = z.infer<typeof JobStatus>;
+export declare const JobType: z.ZodEnum<{
+    create_launchpad: "create_launchpad";
+    modify_launchpad: "modify_launchpad";
+}>;
+export type JobType = z.infer<typeof JobType>;
+export declare const FailedStage: z.ZodEnum<{
+    build: "build";
+    onchain: "onchain";
+    deploy: "deploy";
+}>;
+export type FailedStage = z.infer<typeof FailedStage>;
+/** Statuses during which the builder holds the job lock (locked_by / locked_at). */
+export declare const ACTIVE_JOB_STATUSES: readonly ["building", "onchain_setup", "deploying"];
+export type ActiveJobStatus = (typeof ACTIVE_JOB_STATUSES)[number];
+/** Happy path of a `create_launchpad` job, in order. */
+export declare const CREATE_FLOW: readonly ["spec_ready", "paid", "building", "preview_ready", "approved", "onchain_setup", "awaiting_owner_signature", "owner_signed", "deploying", "live"];
+/** Happy path of a `modify_launchpad` job, in order. */
+export declare const MODIFY_FLOW: readonly ["spec_ready", "paid", "building", "preview_ready", "approved", "deploying", "live"];
+export declare function isActiveJobStatus(status: JobStatus): status is ActiveJobStatus;
+/** Ordered happy path for a job type. */
+export declare function flowForJobType(type: JobType): readonly JobStatus[];
+/**
+ * Stage recorded in failed_stage when a job fails (or is found stale) in the given status:
+ * building -> build, onchain_setup -> onchain, deploying -> deploy. Null for non-active statuses.
+ */
+export declare function failedStageForStatus(status: ActiveJobStatus): FailedStage;
+export declare function failedStageForStatus(status: JobStatus): FailedStage | null;

package/dist/jobs.js

@@ -0,0 +1,76 @@
+import { z } from 'zod';
+/** Job statuses (docs/INTERFACES.md §4). */
+export const JobStatus = z.enum([
+    /** Created by apps/web: spec confirmed (creation) or modification request recorded. */
+    'spec_ready',
+    /** Payment confirmed on-chain. */
+    'paid',
+    /** Builder: container running. */
+    'building',
+    /** Preview URL available. */
+    'preview_ready',
+    /** The client approved the preview. */
+    'approved',
+    /** Builder + signer: configs creation and launch transaction preparation. */
+    'onchain_setup',
+    /** Launch transaction ready in jobs.owner_tx; the client must sign the first buy. */
+    'awaiting_owner_signature',
+    /** apps/web: client transaction confirmed on-chain. */
+    'owner_signed',
+    /** Builder: merge to main, Vercel production deploy. */
+    'deploying',
+    'live',
+    /** A stage failed (see failed_stage and attempts). */
+    'failed',
+    'refunded',
+]);
+export const JobType = z.enum(['create_launchpad', 'modify_launchpad']);
+export const FailedStage = z.enum(['build', 'onchain', 'deploy']);
+/** Statuses during which the builder holds the job lock (locked_by / locked_at). */
+export const ACTIVE_JOB_STATUSES = [
+    'building',
+    'onchain_setup',
+    'deploying',
+];
+/** Happy path of a `create_launchpad` job, in order. */
+export const CREATE_FLOW = [
+    'spec_ready',
+    'paid',
+    'building',
+    'preview_ready',
+    'approved',
+    'onchain_setup',
+    'awaiting_owner_signature',
+    'owner_signed',
+    'deploying',
+    'live',
+];
+/** Happy path of a `modify_launchpad` job, in order. */
+export const MODIFY_FLOW = [
+    'spec_ready',
+    'paid',
+    'building',
+    'preview_ready',
+    'approved',
+    'deploying',
+    'live',
+];
+export function isActiveJobStatus(status) {
+    return ACTIVE_JOB_STATUSES.includes(status);
+}
+/** Ordered happy path for a job type. */
+export function flowForJobType(type) {
+    return type === 'create_launchpad' ? CREATE_FLOW : MODIFY_FLOW;
+}
+export function failedStageForStatus(status) {
+    switch (status) {
+        case 'building':
+            return 'build';
+        case 'onchain_setup':
+            return 'onchain';
+        case 'deploying':
+            return 'deploy';
+        default:
+            return null;
+    }
+}

package/dist/site-config.d.ts

@@ -0,0 +1,66 @@
+import { z } from 'zod';
+export declare const SolanaCluster: z.ZodEnum<{
+    devnet: "devnet";
+    "mainnet-beta": "mainnet-beta";
+}>;
+export type SolanaCluster = z.infer<typeof SolanaCluster>;
+/** `live`, `sleeping` (dormant) or `disabled` (cut by FORGE). Written by the builder only. */
+export declare const SiteMode: z.ZodEnum<{
+    live: "live";
+    sleeping: "sleeping";
+    disabled: "disabled";
+}>;
+export type SiteMode = z.infer<typeof SiteMode>;
+/**
+ * `forge.config.json`, generated by the builder in each client repo and read by the client site
+ * (docs/INTERFACES.md §3). The builder agent may change `theme` and `content`, never `onchain`
+ * nor `mode`. FORGE addresses (multisig, referrals, platform fee wallet) are NOT in this file.
+ */
+export declare const ForgeSiteConfig: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    name: z.ZodString;
+    slug: z.ZodString;
+    mode: z.ZodEnum<{
+        live: "live";
+        sleeping: "sleeping";
+        disabled: "disabled";
+    }>;
+    onchain: z.ZodOptional<z.ZodObject<{
+        cluster: z.ZodEnum<{
+            devnet: "devnet";
+            "mainnet-beta": "mainnet-beta";
+        }>;
+        launchpadConfig: z.ZodString;
+        launchpadCoinConfig: z.ZodString;
+        launchpadCoinMint: z.ZodString;
+        ownerWallet: z.ZodString;
+        poolCreationFeeSol: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    theme: z.ZodObject<{
+        primaryColor: z.ZodString;
+        accentColor: z.ZodString;
+        darkMode: z.ZodBoolean;
+    }, z.core.$strip>;
+    content: z.ZodObject<{
+        tagline: z.ZodString;
+        about: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type ForgeSiteConfig = z.infer<typeof ForgeSiteConfig>;
+/** Read-only view of forge.config.json exposed to the template UI (docs/frontend/CONTRACT.md). */
+export interface SiteConfig {
+    name: string;
+    slug: string;
+    theme: {
+        primaryColor: string;
+        accentColor: string;
+        darkMode: boolean;
+    };
+    content: {
+        tagline: string;
+        about: string;
+    };
+    mode: SiteMode;
+}
+/** Pure projection of a parsed forge.config.json to the UI-facing SiteConfig. */
+export declare function toSiteConfig(config: ForgeSiteConfig): SiteConfig;

package/dist/site-config.js

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+import { Slug, SolanaAddress, isValidPoolCreationFeeSol } from './spec.js';
+export const SolanaCluster = z.enum(['devnet', 'mainnet-beta']);
+/** `live`, `sleeping` (dormant) or `disabled` (cut by FORGE). Written by the builder only. */
+export const SiteMode = z.enum(['live', 'sleeping', 'disabled']);
+const HexColor = z.string().regex(/^#[0-9a-fA-F]{6}$/);
+/**
+ * `forge.config.json`, generated by the builder in each client repo and read by the client site
+ * (docs/INTERFACES.md §3). The builder agent may change `theme` and `content`, never `onchain`
+ * nor `mode`. FORGE addresses (multisig, referrals, platform fee wallet) are NOT in this file.
+ */
+export const ForgeSiteConfig = z.object({
+    version: z.literal(1),
+    name: z.string().min(2).max(32),
+    slug: Slug,
+    mode: SiteMode,
+    /** Absent until the on-chain setup is done. */
+    onchain: z
+        .object({
+        cluster: SolanaCluster,
+        launchpadConfig: SolanaAddress,
+        launchpadCoinConfig: SolanaAddress,
+        launchpadCoinMint: SolanaAddress,
+        ownerWallet: SolanaAddress,
+        /** Coin creation fee charged by this launchpad, shown to coin creators before signing. */
+        poolCreationFeeSol: z.number().refine(isValidPoolCreationFeeSol).optional(),
+    })
+        .optional(),
+    theme: z.object({
+        primaryColor: HexColor,
+        accentColor: HexColor,
+        darkMode: z.boolean(),
+    }),
+    content: z.object({
+        tagline: z.string().max(120),
+        about: z.string(),
+    }),
+});
+/** Pure projection of a parsed forge.config.json to the UI-facing SiteConfig. */
+export function toSiteConfig(config) {
+    return {
+        name: config.name,
+        slug: config.slug,
+        theme: { ...config.theme },
+        content: { ...config.content },
+        mode: config.mode,
+    };
+}