@treeseed/sdk 0.1.1 → 0.3.0

package/dist/platform/env.yaml

@@ -0,0 +1,394 @@
+entries:
+  GH_TOKEN:
+    label: GitHub access token
+    group: auth
+    description: Personal access token used by Treeseed for GitHub CLI automation, repository setup, CI secret sync, and GitHub Copilot SDK-backed workflows.
+    howToGet: "Create a GitHub fine-grained personal access token scoped to the TreeSeed repository. Required repository permissions: Contents read/write, Environments read/write, Secrets and variables read/write, Actions and workflows read/write, Pull requests read/write, Issues read/write. Then paste it here as GH_TOKEN."
+    sensitivity: secret
+    targets:
+      - local-file
+      - railway-secret
+    scopes:
+      - local
+      - staging
+      - prod
+    requirement: required
+    purposes:
+      - save
+      - config
+    validation:
+      kind: nonempty
+    sourcePriority:
+      - machine-config
+      - process-env
+  CLOUDFLARE_API_TOKEN:
+    label: Cloudflare API token
+    group: auth
+    description: Account-level Cloudflare API token used by Wrangler and CI to manage Pages, Workers, Workers KV, D1, Queues, DNS, secrets, and deploys.
+    howToGet: "Create a Cloudflare account-level API token scoped to the target domain and account. Required permissions: Account Cloudflare Pages edit, Account Workers Scripts edit, Account Workers KV Storage edit, Account D1 edit, Account Queues edit, Zone DNS edit. Then paste it here as CLOUDFLARE_API_TOKEN."
+    sensitivity: secret
+    targets:
+      - local-file
+      - github-secret
+    scopes:
+      - local
+      - staging
+      - prod
+    requirement: required
+    purposes:
+      - save
+      - deploy
+      - destroy
+      - config
+    validation:
+      kind: nonempty
+    sourcePriority:
+      - machine-config
+      - process-env
+  RAILWAY_API_TOKEN:
+    label: Railway API token
+    group: auth
+    description: Primary Railway token for user or workspace scoped access, including project creation and most Treeseed-managed Railway flows.
+    howToGet: In Railway, create a user or workspace API token that can create and manage the target project, then paste it here as RAILWAY_API_TOKEN.
+    sensitivity: secret
+    targets:
+      - local-file
+      - railway-secret
+    scopes:
+      - local
+      - staging
+      - prod
+    requirement: conditional
+    purposes:
+      - deploy
+      - destroy
+      - config
+    validation:
+      kind: nonempty
+    sourcePriority:
+      - machine-config
+      - process-env
+    relevanceRef: railwayManagedEnabled
+    requiredWhenRef: railwayManagedEnabled
+  RAILWAY_TOKEN:
+    label: Railway project token
+    group: auth
+    description: Optional Railway token for project-scoped resource management after a project already exists.
+    howToGet: In Railway, generate a project-scoped token only if you need project resource management separate from the primary API token, then paste it here as RAILWAY_TOKEN.
+    sensitivity: secret
+    targets:
+      - local-file
+      - railway-secret
+    scopes:
+      - local
+      - staging
+      - prod
+    requirement: optional
+    purposes:
+      - deploy
+      - destroy
+      - config
+    validation:
+      kind: nonempty
+    sourcePriority:
+      - machine-config
+      - process-env
+    relevanceRef: railwayManagedEnabled
+  CLOUDFLARE_ACCOUNT_ID:
+    label: Cloudflare account ID
+    group: cloudflare
+    description: Identifies the Cloudflare account Treeseed should provision and deploy into.
+    howToGet: In the Cloudflare dashboard, open Workers & Pages or Account Home and copy the account ID.
+    sensitivity: plain
+    targets:
+      - local-file
+      - github-variable
+      - config-file
+    scopes:
+      - staging
+      - prod
+    requirement: required
+    purposes:
+      - save
+      - deploy
+      - destroy
+      - config
+    validation:
+      kind: nonempty
+    sourcePriority:
+      - machine-config
+      - process-env
+      - treeseed.site.yaml
+  TREESEED_FORM_TOKEN_SECRET:
+    label: Forms token secret
+    group: forms
+    description: Signs form-related tokens and protects Treeseed forms workflows in local and hosted runtimes.
+    howToGet: Treeseed can generate a strong random secret for you. Reuse it across environments only if that matches your security model.
+    sensitivity: secret
+    targets:
+      - local-file
+      - wrangler-dev-vars
+      - github-secret
+      - cloudflare-secret
+    scopes:
+      - local
+      - staging
+      - prod
+    requirement: required
+    purposes:
+      - dev
+      - save
+      - deploy
+      - config
+    validation:
+      kind: nonempty
+    sourcePriority:
+      - machine-config
+      - process-env
+    defaultValueRef: generatedSecret
+    localDefaultValueRef: generatedSecret
+  TREESEED_PUBLIC_TURNSTILE_SITE_KEY:
+    label: Turnstile site key
+    group: forms
+    description: Public site key used by the browser to render the Turnstile challenge when forms protection is enabled.
+    howToGet: Create a Turnstile widget in Cloudflare Turnstile and copy the site key.
+    sensitivity: plain
+    targets:
+      - local-file
+      - wrangler-dev-vars
+      - github-variable
+      - cloudflare-var
+    scopes:
+      - local
+      - staging
+      - prod
+    requirement: conditional
+    purposes:
+      - dev
+      - save
+      - deploy
+      - config
+    validation:
+      kind: nonempty
+    sourcePriority:
+      - machine-config
+      - process-env
+    relevanceRef: turnstileEnabled
+    requiredWhenRef: turnstileNonLocal
+  TREESEED_TURNSTILE_SECRET_KEY:
+    label: Turnstile secret key
+    group: forms
+    description: Server-side Turnstile secret used to verify challenge responses.
+    howToGet: Create a Turnstile widget in Cloudflare Turnstile and copy the secret key.
+    sensitivity: secret
+    targets:
+      - local-file
+      - wrangler-dev-vars
+      - github-secret
+      - cloudflare-secret
+    scopes:
+      - local
+      - staging
+      - prod
+    requirement: conditional
+    purposes:
+      - dev
+      - save
+      - deploy
+      - config
+    validation:
+      kind: nonempty
+    sourcePriority:
+      - machine-config
+      - process-env
+    relevanceRef: turnstileEnabled
+    requiredWhenRef: turnstileNonLocal
+  TREESEED_PUBLIC_FORMS_LOCAL_BYPASS_TURNSTILE:
+    label: Local Turnstile bypass
+    group: local-development
+    description: Lets contributors edit content and exercise forms locally without a live Turnstile widget.
+    howToGet: Treeseed defaults this to true for local development. You can switch it off if you want to test with real Turnstile keys locally.
+    sensitivity: plain
+    targets:
+      - local-file
+      - wrangler-dev-vars
+    scopes:
+      - local
+    requirement: optional
+    purposes:
+      - dev
+      - config
+    validation:
+      kind: boolean
+    sourcePriority:
+      - machine-config
+      - process-env
+    localDefaultValueRef: localFormsBypassDefault
+  TREESEED_SMTP_HOST:
+    label: SMTP host
+    group: smtp
+    description: SMTP host for Treeseed email delivery when SMTP-backed forms behavior is enabled.
+    howToGet: Use the SMTP hostname from your email provider or local Mailpit instance.
+    sensitivity: plain
+    targets:
+      - local-file
+      - wrangler-dev-vars
+      - github-variable
+      - cloudflare-var
+    scopes:
+      - local
+      - staging
+      - prod
+    requirement: conditional
+    purposes:
+      - dev
+      - save
+      - deploy
+      - config
+    validation:
+      kind: nonempty
+    sourcePriority:
+      - machine-config
+      - process-env
+    relevanceRef: smtpEnabled
+    requiredWhenRef: smtpNonLocal
+  TREESEED_SMTP_PORT:
+    label: SMTP port
+    group: smtp
+    description: Port used to connect to the SMTP server.
+    howToGet: Use the port provided by your email service, commonly 587, 465, or the Mailpit local port.
+    sensitivity: plain
+    targets:
+      - local-file
+      - wrangler-dev-vars
+      - github-variable
+      - cloudflare-var
+    scopes:
+      - local
+      - staging
+      - prod
+    requirement: conditional
+    purposes:
+      - dev
+      - save
+      - deploy
+      - config
+    validation:
+      kind: number
+    sourcePriority:
+      - machine-config
+      - process-env
+    relevanceRef: smtpEnabled
+    requiredWhenRef: smtpNonLocal
+  TREESEED_SMTP_USERNAME:
+    label: SMTP username
+    group: smtp
+    description: SMTP identity used when authenticating to the mail provider.
+    howToGet: Use the SMTP username or mailbox identity from your email provider.
+    sensitivity: plain
+    targets:
+      - local-file
+      - wrangler-dev-vars
+      - github-variable
+      - cloudflare-var
+    scopes:
+      - local
+      - staging
+      - prod
+    requirement: conditional
+    purposes:
+      - dev
+      - save
+      - deploy
+      - config
+    validation:
+      kind: nonempty
+    sourcePriority:
+      - machine-config
+      - process-env
+    relevanceRef: smtpEnabled
+    requiredWhenRef: smtpNonLocal
+  TREESEED_SMTP_PASSWORD:
+    label: SMTP password
+    group: smtp
+    description: SMTP password or app password used for authenticated email sending.
+    howToGet: Use the SMTP password or app-specific password from your email provider.
+    sensitivity: secret
+    targets:
+      - local-file
+      - wrangler-dev-vars
+      - github-secret
+      - cloudflare-secret
+    scopes:
+      - local
+      - staging
+      - prod
+    requirement: conditional
+    purposes:
+      - dev
+      - save
+      - deploy
+      - config
+    validation:
+      kind: nonempty
+    sourcePriority:
+      - machine-config
+      - process-env
+    relevanceRef: smtpEnabled
+    requiredWhenRef: smtpNonLocal
+  TREESEED_SMTP_FROM:
+    label: SMTP from address
+    group: smtp
+    description: Email address Treeseed uses as the sender for mail notifications.
+    howToGet: Use a verified sender address from your SMTP provider.
+    sensitivity: plain
+    targets:
+      - local-file
+      - wrangler-dev-vars
+      - github-variable
+      - cloudflare-var
+    scopes:
+      - local
+      - staging
+      - prod
+    requirement: conditional
+    purposes:
+      - dev
+      - save
+      - deploy
+      - config
+    validation:
+      kind: email
+    sourcePriority:
+      - machine-config
+      - process-env
+    relevanceRef: smtpEnabled
+    requiredWhenRef: smtpNonLocal
+  TREESEED_SMTP_REPLY_TO:
+    label: SMTP reply-to address
+    group: smtp
+    description: Reply-to address attached to Treeseed-generated emails.
+    howToGet: Use a monitored mailbox that should receive replies from end users.
+    sensitivity: plain
+    targets:
+      - local-file
+      - wrangler-dev-vars
+      - github-variable
+      - cloudflare-var
+    scopes:
+      - local
+      - staging
+      - prod
+    requirement: conditional
+    purposes:
+      - dev
+      - save
+      - deploy
+      - config
+    validation:
+      kind: email
+    sourcePriority:
+      - machine-config
+      - process-env
+    relevanceRef: smtpEnabled
+    requiredWhenRef: smtpNonLocal

package/dist/platform/environment.d.ts

@@ -0,0 +1,130 @@
+import type { TreeseedDeployConfig, TreeseedTenantConfig } from './contracts.ts';
+import { type LoadedTreeseedPluginEntry } from './plugins/runtime.ts';
+export declare const TREESEED_ENVIRONMENT_SCOPES: readonly ["local", "staging", "prod"];
+export declare const TREESEED_ENVIRONMENT_REQUIREMENTS: readonly ["required", "conditional", "optional"];
+export declare const TREESEED_ENVIRONMENT_TARGETS: readonly ["local-file", "wrangler-dev-vars", "github-secret", "github-variable", "cloudflare-secret", "cloudflare-var", "railway-secret", "config-file"];
+export declare const TREESEED_ENVIRONMENT_PURPOSES: readonly ["dev", "save", "deploy", "destroy", "config"];
+export declare const TREESEED_ENVIRONMENT_SENSITIVITY: readonly ["secret", "plain", "derived"];
+export type TreeseedEnvironmentScope = (typeof TREESEED_ENVIRONMENT_SCOPES)[number];
+export type TreeseedEnvironmentRequirement = (typeof TREESEED_ENVIRONMENT_REQUIREMENTS)[number];
+export type TreeseedEnvironmentTarget = (typeof TREESEED_ENVIRONMENT_TARGETS)[number];
+export type TreeseedEnvironmentPurpose = (typeof TREESEED_ENVIRONMENT_PURPOSES)[number];
+export type TreeseedEnvironmentSensitivity = (typeof TREESEED_ENVIRONMENT_SENSITIVITY)[number];
+export type TreeseedEnvironmentValidation = {
+    kind: 'string' | 'nonempty' | 'boolean' | 'number' | 'url' | 'email';
+} | {
+    kind: 'enum';
+    values: string[];
+};
+export type TreeseedEnvironmentValueResolver = string | ((context: TreeseedEnvironmentContext, scope: TreeseedEnvironmentScope) => string);
+export type TreeseedMachineSecretPayload = {
+    algorithm: 'aes-256-gcm';
+    iv: string;
+    tag: string;
+    ciphertext: string;
+};
+export type TreeseedMachineConfig = {
+    version: number;
+    project: {
+        tenantRoot: string;
+        tenantId: string;
+        slug: string;
+        name: string;
+        siteUrl: string;
+        overlayPath?: string;
+    };
+    settings: {
+        sync: {
+            github: boolean;
+            cloudflare: boolean;
+        };
+    };
+    environments: Record<TreeseedEnvironmentScope, {
+        values: Record<string, string>;
+        secrets: Record<string, TreeseedMachineSecretPayload>;
+    }>;
+};
+export type TreeseedEnvironmentContext = {
+    deployConfig: TreeseedDeployConfig;
+    tenantConfig?: TreeseedTenantConfig;
+    plugins: LoadedTreeseedPluginEntry[];
+    tenantRoot: string;
+};
+export type TreeseedEnvironmentEntry = {
+    id: string;
+    label: string;
+    group: string;
+    description: string;
+    howToGet: string;
+    sensitivity: TreeseedEnvironmentSensitivity;
+    targets: TreeseedEnvironmentTarget[];
+    scopes: TreeseedEnvironmentScope[];
+    requirement: TreeseedEnvironmentRequirement;
+    purposes: TreeseedEnvironmentPurpose[];
+    validation?: TreeseedEnvironmentValidation;
+    sourcePriority?: string[];
+    defaultValue?: TreeseedEnvironmentValueResolver;
+    localDefaultValue?: TreeseedEnvironmentValueResolver;
+    isRelevant?: (context: TreeseedEnvironmentContext, scope: TreeseedEnvironmentScope, purpose?: TreeseedEnvironmentPurpose) => boolean;
+    requiredWhen?: (context: TreeseedEnvironmentContext, scope: TreeseedEnvironmentScope, purpose?: TreeseedEnvironmentPurpose) => boolean;
+};
+export type TreeseedEnvironmentEntryYaml = Omit<TreeseedEnvironmentEntry, 'id' | 'defaultValue' | 'localDefaultValue' | 'isRelevant' | 'requiredWhen'> & {
+    defaultValueRef?: string;
+    localDefaultValueRef?: string;
+    relevanceRef?: string;
+    requiredWhenRef?: string;
+};
+export type TreeseedEnvironmentEntryOverride = Partial<Omit<TreeseedEnvironmentEntryYaml, 'id'>> & {
+    id?: string;
+};
+export type TreeseedEnvironmentRegistryOverlay = {
+    entries?: Record<string, TreeseedEnvironmentEntryOverride>;
+};
+export type TreeseedResolvedEnvironmentRegistry = {
+    context: TreeseedEnvironmentContext;
+    entries: TreeseedEnvironmentEntry[];
+};
+export type TreeseedEnvironmentValidationProblem = {
+    id: string;
+    label: string;
+    reason: 'missing' | 'invalid';
+    message: string;
+    entry: TreeseedEnvironmentEntry;
+};
+export type TreeseedEnvironmentValidationResult = {
+    ok: boolean;
+    entries: TreeseedEnvironmentEntry[];
+    required: TreeseedEnvironmentEntry[];
+    missing: TreeseedEnvironmentValidationProblem[];
+    invalid: TreeseedEnvironmentValidationProblem[];
+};
+export declare function loadTreeseedEnvironmentOverlay(tenantRoot: string): {
+    path: string;
+    overlay: TreeseedEnvironmentRegistryOverlay;
+};
+export declare function resolveTreeseedEnvironmentContext(options?: {
+    deployConfig?: TreeseedDeployConfig;
+    tenantConfig?: TreeseedTenantConfig;
+    plugins?: LoadedTreeseedPluginEntry[];
+}): TreeseedEnvironmentContext;
+export declare function resolveTreeseedEnvironmentRegistry(options?: {
+    deployConfig?: TreeseedDeployConfig;
+    tenantConfig?: TreeseedTenantConfig;
+    plugins?: LoadedTreeseedPluginEntry[];
+}): TreeseedResolvedEnvironmentRegistry;
+export declare function isTreeseedEnvironmentEntryRelevant(entry: TreeseedEnvironmentEntry, context: TreeseedEnvironmentContext, scope: TreeseedEnvironmentScope, purpose?: TreeseedEnvironmentPurpose): boolean;
+export declare function getTreeseedEnvironmentSuggestedValues(options: {
+    scope: TreeseedEnvironmentScope;
+    purpose?: TreeseedEnvironmentPurpose;
+    deployConfig?: TreeseedDeployConfig;
+    tenantConfig?: TreeseedTenantConfig;
+    plugins?: LoadedTreeseedPluginEntry[];
+}): Record<string, string>;
+export declare function validateTreeseedEnvironmentValues(options: {
+    values: Record<string, string | undefined>;
+    scope: TreeseedEnvironmentScope;
+    purpose: TreeseedEnvironmentPurpose;
+    deployConfig?: TreeseedDeployConfig;
+    tenantConfig?: TreeseedTenantConfig;
+    plugins?: LoadedTreeseedPluginEntry[];
+}): TreeseedEnvironmentValidationResult;