@coreframe/config 0.1.5 → 0.1.7

package/dist/index.d.ts

@@ -2,115 +2,200 @@ import { JsonObject, JsonValue, PrimaryWorkerContributions, PrimaryWorkerEnviron
 
 //#region src/index.d.ts
 type CoreframeConfig = {
-  assets?: AssetsConfig;
-  database?: DatabaseConfig;
-  deploy?: DeployConfig;
-  dev?: DevConfig;
-  i18n?: I18nConfig;
-  flutter?: FlutterConfig;
-  preview?: PreviewConfig;
+  /** Object storage and public asset delivery settings. */assets?: AssetsConfig; /** Database settings used by local and deployment workflows. */
+  database?: DatabaseConfig; /** Deployment hooks, environments, checks, and release settings. */
+  deploy?: DeployConfig; /** Local development settings. */
+  dev?: DevConfig; /** Translation catalog and locale settings. */
+  i18n?: I18nConfig; /** Flutter host integration settings. */
+  flutter?: FlutterConfig; /** Local preview server and tunnel settings. */
+  preview?: PreviewConfig; /** Worker build and runtime settings. */
   worker?: WorkerConfig;
 };
 type FlutterConfig = {
-  deepLink: FlutterDeepLinkConfig;
+  /** Custom URL origin accepted for navigation into the Flutter app. */deepLink: FlutterDeepLinkConfig;
 };
 type FlutterDeepLinkConfig = {
-  host: string;
+  /** Lowercase URL host accepted for Flutter navigation links, without a port. */host: string; /** Lowercase URI scheme used by Flutter navigation links. */
   scheme: string;
 };
 type AssetsConfig = {
-  credentialProfile: string;
-  endpoint: string;
-  projectId: string;
-  publicBaseUrl: string;
-  publicBucket: string;
-  region: string;
+  /** Credential profile used to access the asset storage service. */credentialProfile: string; /** S3-compatible API endpoint for the asset storage service. */
+  endpoint: string; /** Project identifier used to namespace generated asset keys. */
+  projectId: string; /** Base URL from which browsers load published assets. */
+  publicBaseUrl: string; /** Bucket containing assets published for browser access. */
+  publicBucket: string; /** Storage region passed to the S3-compatible client. */
+  region: string; /** Bucket containing original source assets. */
   sourceBucket: string;
 };
 type DatabaseDialect = "postgres" | "sqlite";
 type DatabaseConfig = {
-  dialect: DatabaseDialect;
+  /** Database engine used by project workflows. */dialect: DatabaseDialect; /** Project-relative module that seeds the database. */
   seed?: string;
 };
 type DevPlatform = "android" | "desktop" | "ios" | "macos" | "web" | "webext";
 type DevConfig = {
-  platforms?: DevPlatform[];
+  /** Platforms started by the development command. */platforms?: DevPlatform[];
 };
 type PreviewTunnelConfig = {
-  dns: "external" | "managed";
-  hostname: string;
-  name: string;
+  /** Whether Coreframe or an external provider manages the tunnel hostname's DNS. */dns: "external" | "managed"; /** Public hostname assigned to the preview tunnel. */
+  hostname: string; /** Cloudflare tunnel name. */
+  name: string; /** Credential profile used to manage the tunnel. */
   profile: string;
 };
 type PreviewConfig = {
-  appOrigin?: string;
-  host?: string;
-  port?: number;
+  /** Exact HTTPS origin used by browser-facing application URLs. */appOrigin?: string; /** Network interface on which the local preview server listens. */
+  host?: string; /** TCP port on which the local preview server listens. */
+  port?: number; /** Whether startup fails when the configured port is unavailable. */
   strictPort?: boolean;
-  tunnel?: PreviewTunnelConfig;
+  /**
+   * Public tunnel settings for the local preview server.
+   *
+   * @example
+   *   defineConfig({
+   *     preview: {
+   *       appOrigin: "https://preview.example.com",
+   *       tunnel: {
+   *         dns: "managed",
+   *         hostname: "preview.example.com",
+   *         name: "coreframe-preview",
+   *         profile: "company",
+   *       },
+   *     },
+   *   })
+   */
+  tunnel?: PreviewTunnelConfig; /** Worker bindings supplied during preview. */
+  worker?: PreviewWorkerConfig;
+};
+type PreviewWorkerConfig = {
+  /** JSON-serializable values exposed as worker bindings during preview. */bindings: Record<string, JsonObject>;
 };
 type I18nConfig = {
-  catalogs: string[];
+  /** Catalog names generated for each configured locale. */catalogs: string[]; /** Project-relative directory containing translation catalogs. */
   directory?: string;
+  /**
+   * External command used to generate translated messages.
+   *
+   * @example
+   *   defineConfig({
+   *     i18n: {
+   *       catalogs: ["web"],
+   *       generator: {
+   *         command: "node",
+   *         args: ["scripts/i18n/generate.ts"],
+   *         id: "vercel-ai-sdk-openai",
+   *       },
+   *       locales: ["en", "es"],
+   *       sourceLocale: "en",
+   *     },
+   *   })
+   */
   generator?: {
-    args?: string[];
-    command: string;
+    /** Arguments appended to the translation generator command. */args?: string[]; /** Executable invoked to generate translations. */
+    command: string; /** Stable identifier recorded for the translation generator. */
     id: string;
-  };
-  locales: string[];
+  }; /** Locale identifiers included in translation workflows. */
+  locales: string[]; /** Locale in which source messages are written. */
   sourceLocale: string;
 };
 type DeployEnvironment = "staging" | "production";
 type DeployContext = {
-  environment: DeployEnvironment;
-  releaseName: string;
-  url: string;
+  /** Deployment environment being released. */environment: DeployEnvironment; /** Human-readable name assigned to the release. */
+  releaseName: string; /** Public URL of the deployed application. */
+  url: string; /** Version assigned to the release. */
   version: string;
 };
 type TauriReleasePlatform = "macos" | "windows" | "linux" | "ios" | "android";
 type TauriReleasePlatformConfig = {
-  artifactGlobs?: string[];
-  buildArgs?: string[];
-  targetTriple?: string;
+  /** Glob patterns used to find build artifacts for the platform. */artifactGlobs?: string[]; /** Arguments passed to the Tauri build command for the platform. */
+  buildArgs?: string[]; /** Rust target triple used to build the platform. */
+  targetTriple?: string; /** Platform key written to the Tauri updater manifest. */
   updatePlatform?: string;
 };
 type TauriReleaseConfig = {
-  artifactDownloadDir?: string;
-  b2Bucket?: string;
-  latestManifestPath?: string;
+  /** Local directory into which remote workflow artifacts are downloaded. */artifactDownloadDir?: string; /** Backblaze B2 bucket that receives release files. */
+  b2Bucket?: string; /** Local path where the latest updater manifest is written. */
+  latestManifestPath?: string; /** Platforms built on the machine running the deploy command. */
   localPlatforms?: TauriReleasePlatform[];
-  platform?: Partial<Record<TauriReleasePlatform, TauriReleasePlatformConfig>>;
-  publicBaseUrl?: string;
-  publicPathPrefix?: string;
-  releaseNotesPath?: string;
-  releasePath?: string;
-  releaseUploadDir?: string;
-  workflowPlatforms?: TauriReleasePlatform[];
-  workflowName?: string;
-  workflowPollIntervalMs?: number;
-  workflowRef?: string;
+  /**
+   * Per-platform artifact discovery and build overrides.
+   *
+   * @example
+   *   defineConfig({
+   *     deploy: {
+   *       tauriRelease: {
+   *         platform: {
+   *           macos: {
+   *             artifactGlobs: ["src-tauri/target/release/bundle/macos/*.sig"],
+   *             targetTriple: "aarch64-apple-darwin",
+   *           },
+   *         },
+   *       },
+   *     },
+   *   })
+   */
+  platform?: Partial<Record<TauriReleasePlatform, TauriReleasePlatformConfig>>; /** Public base URL used to construct release download URLs. */
+  publicBaseUrl?: string; /** Path prefix added to public release download URLs. */
+  publicPathPrefix?: string; /** Project-relative path to the release notes file. */
+  releaseNotesPath?: string; /** Remote path under which versioned release files are stored. */
+  releasePath?: string; /** Local directory containing release files ready for upload. */
+  releaseUploadDir?: string; /** Platforms built by the remote release workflow. */
+  workflowPlatforms?: TauriReleasePlatform[]; /** GitHub Actions workflow used to build remote release artifacts. */
+  workflowName?: string; /** Delay in milliseconds between remote workflow status checks. */
+  workflowPollIntervalMs?: number; /** Git ref on which the remote release workflow runs. */
+  workflowRef?: string; /** Maximum time in milliseconds to wait for the remote workflow. */
   workflowTimeoutMs?: number;
 };
 type DeploySmokeCheck = {
-  name: string;
-  path?: string;
-  url?: string;
+  /** Label used to identify the check in deployment output. */name: string; /** Application-relative path checked after deployment. */
+  path?: string; /** Absolute URL checked after deployment instead of an application path. */
+  url?: string; /** HTTP status code or codes that count as a successful check. */
   expectedStatus?: "2xx" | number | number[];
 };
 type DeployEnvironmentConfig = {
-  url?: string;
+  /** Public application URL for the deployment environment. */url?: string;
 };
 type StagingHostnameConfig = {
-  managedLabelPrefix: string;
-  parentHostname: string;
+  /** Prefix added to generated staging DNS labels. */managedLabelPrefix: string; /** Parent hostname under which staging hostnames are generated. */
+  parentHostname: string; /** Worker service whose application-origin secret is updated for staging. */
   workerService: string;
 };
 type DeployConfig = {
-  afterDeploy?: (context: DeployContext) => Promise<void> | void;
-  afterWorkerDeploy?: (context: DeployContext) => Promise<void> | void;
+  /** Hook called after all deployment work completes. */afterDeploy?: (context: DeployContext) => Promise<void> | void; /** Hook called immediately after the worker deployment completes. */
+  afterWorkerDeploy?: (context: DeployContext) => Promise<void> | void; /** Per-environment deployment overrides. */
   environments?: Partial<Record<DeployEnvironment, DeployEnvironmentConfig>>;
+  /**
+   * HTTP checks run against the application after deployment.
+   *
+   * @example
+   *   defineConfig({
+   *     deploy: {
+   *       smokeChecks: [
+   *         { name: "home", path: "/" },
+   *         {
+   *           name: "status page",
+   *           url: "https://status.example.com/health",
+   *           expectedStatus: [200, 204],
+   *         },
+   *       ],
+   *     },
+   *   })
+   */
   smokeChecks?: DeploySmokeCheck[];
-  stagingHostname?: StagingHostnameConfig;
+  /**
+   * Settings for generating and assigning staging hostnames.
+   *
+   * @example
+   *   defineConfig({
+   *     deploy: {
+   *       stagingHostname: {
+   *         managedLabelPrefix: "review-",
+   *         parentHostname: "staging.example.com",
+   *         workerService: "example-api-staging",
+   *       },
+   *     },
+   *   })
+   */
+  stagingHostname?: StagingHostnameConfig; /** Tauri desktop and mobile release settings. */
   tauriRelease?: TauriReleaseConfig;
 };
 declare function defineConfig(config: CoreframeConfig): CoreframeConfig;
@@ -122,4 +207,4 @@ declare function readProjectConfig({
 declare function importProjectModule<T>(path: string, cwd?: string): Promise<T>;
 declare function importProjectDependency<T>(specifier: string, cwd?: string): Promise<T>;
 //#endregion
-export { AssetsConfig, CoreframeConfig, DatabaseConfig, DatabaseDialect, DeployConfig, DeployContext, DeployEnvironment, DeployEnvironmentConfig, DeploySmokeCheck, DevConfig, DevPlatform, FlutterConfig, FlutterDeepLinkConfig, I18nConfig, JsonObject, JsonValue, PreviewConfig, PreviewTunnelConfig, PrimaryWorkerContributions, PrimaryWorkerEnvironment, StagingHostnameConfig, TauriReleaseConfig, TauriReleasePlatform, TauriReleasePlatformConfig, WorkerConfig, WorkerDeployEnvironment, WorkerEnvironmentDeclaration, WorkerEnvironmentKind, WorkerEnvironmentVariableConfig, WranglerConfig, coreframeGeneratedWorkerVariables, coreframeLocalWorkerVariables, coreframeManagedWorkerSecrets, defineConfig, derivePrimaryWorkerConfig, importProjectDependency, importProjectModule, normalizeWorkerEnvironment, primaryWorkerConfigPath, primaryWorkerEnvironments, readProjectConfig, validateWorkerInventoryOwnership, workerBindingNames, wranglerEnvironmentNames };
+export { AssetsConfig, CoreframeConfig, DatabaseConfig, DatabaseDialect, DeployConfig, DeployContext, DeployEnvironment, DeployEnvironmentConfig, DeploySmokeCheck, DevConfig, DevPlatform, FlutterConfig, FlutterDeepLinkConfig, I18nConfig, JsonObject, JsonValue, PreviewConfig, PreviewTunnelConfig, PreviewWorkerConfig, PrimaryWorkerContributions, PrimaryWorkerEnvironment, StagingHostnameConfig, TauriReleaseConfig, TauriReleasePlatform, TauriReleasePlatformConfig, WorkerConfig, WorkerDeployEnvironment, WorkerEnvironmentDeclaration, WorkerEnvironmentKind, WorkerEnvironmentVariableConfig, WranglerConfig, coreframeGeneratedWorkerVariables, coreframeLocalWorkerVariables, coreframeManagedWorkerSecrets, defineConfig, derivePrimaryWorkerConfig, importProjectDependency, importProjectModule, normalizeWorkerEnvironment, primaryWorkerConfigPath, primaryWorkerEnvironments, readProjectConfig, validateWorkerInventoryOwnership, workerBindingNames, wranglerEnvironmentNames };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coreframe/config",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Environment and project configuration utilities for Coreframe apps",
   "repository": {
     "type": "git",