@tailor-platform/sdk 2.0.0-next.1 → 2.0.0-next.11

package/dist/cli/shared/config-loader.d.mts

@@ -0,0 +1,32 @@
+import { Plugin } from "../../plugin/types.mjs";
+import { AppConfig, EnvValue } from "../../configure/config/types.mjs";
+//#region src/cli/shared/config-loader.d.ts
+/**
+ * App config whose `env` entries have been resolved to the values that get
+ * deployed: the `{ value, allowSecretReason }` form accepted in `defineConfig`
+ * is unwrapped during loading, so nothing downstream can deploy a wrapper
+ * object or the reason string alongside the value.
+ */
+type ResolvedEnvAppConfig = Omit<AppConfig, "env"> & {
+  env?: Record<string, EnvValue>;
+};
+/** Loaded configuration with resolved path. */
+type LoadedConfig = ResolvedEnvAppConfig & {
+  path: string;
+};
+interface LoadConfigOptions {
+  /** Import cache-busting value for callers that reload the config module after a rebuild. */
+  importNonce?: string;
+}
+/**
+ * Load Tailor configuration file and associated plugins.
+ * @param configPath - Optional explicit config path
+ * @param options - Optional module import behavior.
+ * @returns Loaded config, plugins, and config path
+ */
+declare function loadConfig(configPath?: string, options?: LoadConfigOptions): Promise<{
+  config: LoadedConfig;
+  plugins: Plugin[];
+}>;
+//#endregion
+export { LoadConfigOptions, LoadedConfig, ResolvedEnvAppConfig, loadConfig };

package/dist/cli/shared/context.d.mts

@@ -0,0 +1,29 @@
+import "./client.mjs";
+import "./args.mjs";
+import { z } from "zod";
+//#region src/cli/shared/context.d.ts
+type LoadWorkspaceIdOptions = {
+  workspaceId?: string;
+  profile?: string;
+};
+type LoadAccessTokenOptions = {
+  profile?: string;
+};
+/**
+ * Load workspace ID from command options, environment variables, or platform config.
+ * In CLI context, env fallback is also handled by politty's arg env option.
+ * Priority: opts/workspaceId > env/workspaceId > opts/profile > error
+ * @param opts - Workspace and profile options
+ * @returns Resolved workspace ID
+ */
+declare function loadWorkspaceId(opts?: LoadWorkspaceIdOptions): Promise<string>;
+/**
+ * Load access token from environment variables, command options, or platform config.
+ * In CLI context, profile env fallback is also handled by politty's arg env option.
+ * Priority: env/TAILOR_PLATFORM_TOKEN > env/TAILOR_TOKEN (deprecated) > opts/profile > env/profile > config/currentUser > error
+ * @param opts - Profile options
+ * @returns Resolved access token
+ */
+declare function loadAccessToken(opts?: LoadAccessTokenOptions): Promise<string>;
+//#endregion
+export { loadAccessToken, loadWorkspaceId };

package/dist/cli/shared/error-json.d.mts

@@ -0,0 +1,23 @@
+//#region src/cli/shared/error-json.d.ts
+interface ErrorToJsonOptions {
+  /** Include the original stack trace in the error envelope. */
+  includeStack?: boolean;
+}
+/**
+ * Convert a CLI failure into the stable JSON error envelope.
+ * @param error - Failure to serialize
+ * @param options - JSON serialization options
+ * @returns JSON-compatible error envelope
+ */
+declare function errorToJson(error: unknown, options?: ErrorToJsonOptions): {
+  error: Readonly<Record<string, unknown>>;
+};
+/**
+ * Serialize a CLI failure into the stable JSON error envelope.
+ * @param error - Failure to serialize
+ * @param options - JSON serialization options
+ * @returns Serialized JSON error envelope
+ */
+declare function serializeError(error: unknown, options?: ErrorToJsonOptions): string;
+//#endregion
+export { ErrorToJsonOptions, errorToJson, serializeError };

package/dist/cli/shared/readonly-guard.d.mts

@@ -0,0 +1,25 @@
+//#region src/cli/shared/readonly-guard.d.ts
+interface AssertWritableOptions {
+  /** Explicit profile name from command args. Falls back to TAILOR_PLATFORM_PROFILE. */
+  profile?: string;
+}
+/**
+ * Throw a CLIError if the active profile has `readonly: true`.
+ *
+ * Resolves the active profile in this order:
+ * 1. `opts.profile` (CLI flag)
+ * 2. `process.env.TAILOR_PLATFORM_PROFILE`
+ *
+ * If neither is set, no profile is in scope so the call is allowed. This is
+ * intentional: `TAILOR_PLATFORM_TOKEN` direct access (CI / machine user) and
+ * `--workspace-id` without a profile are out-of-band paths whose authorization
+ * is governed by the bearer token itself, not by the local profile flag.
+ *
+ * If the resolved profile cannot be found in the config, this function returns
+ * silently and lets downstream loaders surface the not-found error.
+ * @param opts - Options
+ * @param opts.profile - Optional explicit profile name from command args
+ */
+declare function assertWritable(opts?: AssertWritableOptions): Promise<void>;
+//#endregion
+export { assertWritable };

package/dist/cli/shared/script-executor.d.mts

@@ -0,0 +1,77 @@
+import { AuthInvokerSchema } from "../../tailor-proto/src/tailor/v1/auth_resource_pb.mjs";
+import { FunctionExecution_Status } from "../../tailor-proto/src/tailor/v1/function_resource_pb.mjs";
+import { OperatorClient } from "./client.mjs";
+import { Jsonifiable } from "type-fest";
+import { MessageInitShape } from "@bufbuild/protobuf";
+//#region src/cli/shared/script-executor.d.ts
+/** Authentication context for script execution, provided as a plain object. */
+type ScriptInvoker = MessageInitShape<typeof AuthInvokerSchema>;
+/**
+ * Options for script execution
+ */
+interface ScriptExecutionOptions<T extends Jsonifiable = Jsonifiable> {
+  /** Operator client instance */
+  client: OperatorClient;
+  /** Workspace ID */
+  workspaceId: string;
+  /** Script name (for identification) */
+  name: string;
+  /** Bundled script code to execute */
+  code: string;
+  /** Optional JSON-serializable argument to pass to the script */
+  arg?: T;
+  /** Auth invoker for script execution */
+  invoker: ScriptInvoker;
+  /** Polling interval in milliseconds (default: 1000ms) */
+  pollInterval?: number;
+}
+/**
+ * Result of script execution
+ */
+interface ScriptExecutionResult {
+  /** Whether the script executed successfully */
+  success: boolean;
+  /** Logs output from the script execution */
+  logs: string;
+  /** Result value from the script execution */
+  result: string;
+  /** Error message if execution failed */
+  error?: string;
+}
+/**
+ * Result from waiting for execution completion
+ */
+interface ExecutionWaitResult {
+  /** Execution status */
+  status: FunctionExecution_Status;
+  /** Logs output from the execution */
+  logs: string;
+  /** Result value from the execution */
+  result: string;
+}
+/**
+ * Wait for a function execution to complete
+ *
+ * Polls the getFunctionExecution API until the execution reaches a terminal state
+ * (SUCCESS or FAILED).
+ * @param {OperatorClient} client - Operator client instance
+ * @param {string} workspaceId - Workspace ID
+ * @param {string} executionId - Execution ID to wait for
+ * @param {number} [pollInterval] - Polling interval in milliseconds (default: 1000ms)
+ * @returns {Promise<ExecutionWaitResult>} Execution result
+ * @throws {Error} If execution is not found
+ */
+declare function waitForExecution(client: OperatorClient, workspaceId: string, executionId: string, pollInterval?: number): Promise<ExecutionWaitResult>;
+/**
+ * Execute a script via TestExecScript API and wait for completion
+ *
+ * This function:
+ * 1. Calls testExecScript API to start execution
+ * 2. Polls getFunctionExecution until completion
+ * 3. Returns structured result with success/failure status
+ * @param {ScriptExecutionOptions} options - Execution options
+ * @returns {Promise<ScriptExecutionResult>} Execution result
+ */
+declare function executeScript<T extends Jsonifiable = Jsonifiable>(options: ScriptExecutionOptions<T>): Promise<ScriptExecutionResult>;
+//#endregion
+export { ExecutionWaitResult, ScriptExecutionOptions, ScriptExecutionResult, ScriptInvoker, executeScript, waitForExecution };

package/dist/cli/shared/seed-chunker.d.mts

@@ -0,0 +1,45 @@
+import { JsonObject } from "type-fest";
+//#region src/cli/shared/seed-chunker.d.ts
+/**
+ * Seed data keyed by type name, with an array of records per type.
+ */
+type SeedData = Record<string, JsonObject[]>;
+/**
+ * A single chunk of seed data with metadata for ordered execution.
+ */
+type SeedChunk = {
+  data: SeedData;
+  order: string[];
+  index: number;
+  total: number;
+};
+/**
+ * Options for chunking seed data.
+ */
+type ChunkSeedDataOptions = {
+  /** Seed data keyed by type name */
+  data: SeedData;
+  /** Ordered list of type names (dependency order) */
+  order: string[];
+  /** Byte size of the bundled seed script code */
+  codeByteSize: number;
+  /** Maximum gRPC message size in bytes (default: 3.5MB) */
+  maxMessageSize?: number;
+};
+/**
+ * Split seed data into chunks that fit within the gRPC message size limit.
+ *
+ * Algorithm:
+ * 1. Calculate the available budget for the arg field (maxMessageSize - codeByteSize - overhead)
+ * 2. If all data fits in one message, return a single chunk
+ * 3. Otherwise, iterate through types in dependency order:
+ *    - If a type fits in the current chunk, add it
+ *    - If adding a type would exceed the budget, finalize the current chunk and start a new one
+ *    - If a single type exceeds the budget, split its records across multiple chunks
+ *    - If a single record exceeds the budget, throw an error
+ * @param options - Chunking options
+ * @returns Array of seed chunks
+ */
+declare function chunkSeedData(options: ChunkSeedDataOptions): SeedChunk[];
+//#endregion
+export { ChunkSeedDataOptions, SeedChunk, SeedData, chunkSeedData };

package/dist/cli/shared/seed-context.d.mts

@@ -0,0 +1,49 @@
+import { LoadedConfig } from "./config-loader.mjs";
+import { SeedNamespaceConfig } from "../../plugin/builtin/seed/seed-type-processor.mjs";
+//#region src/cli/shared/seed-context.d.ts
+/**
+ * IdP `_User` seeding context, present when the config uses the built-in IdP
+ * with a user profile type.
+ */
+interface SeedIdpUserContext {
+  /** IdP namespace the `_User` records belong to. */
+  idpNamespace: string;
+  /** Server-side script that creates `_User` records from seed rows. */
+  seedScriptCode: string;
+  /** Server-side script that deletes all `_User` records. */
+  truncateScriptCode: string;
+}
+/**
+ * Everything a seed run needs from the local config: the seed data location,
+ * per-namespace seeding order, and IdP user context.
+ */
+interface SeedContext {
+  /** The loaded Tailor config. */
+  config: LoadedConfig;
+  /** Absolute path to the seedPlugin output directory. */
+  distPath: string;
+  /** Default machine user name from seedPlugin options, if configured. */
+  machineUserName?: string | undefined;
+  /** Seed ordering information per TailorDB namespace. */
+  namespaces: SeedNamespaceConfig[];
+  /** IdP `_User` seeding context, or null when not applicable. */
+  idpUser: SeedIdpUserContext | null;
+}
+/**
+ * Options for {@link loadSeedContext}.
+ */
+interface LoadSeedContextOptions {
+  /** Path to tailor.config.ts. Defaults to searching from the current directory. */
+  configPath?: string;
+}
+/**
+ * Load the seed context from the local config. Requires `seedPlugin` to be
+ * configured in the config's plugins. A relative `distPath` in the seedPlugin
+ * options is resolved against the current working directory — the same base
+ * `tailor generate` writes it to.
+ * @param options - Seed context loading options.
+ * @returns The seed context computed from the local config.
+ */
+declare function loadSeedContext(options?: LoadSeedContextOptions): Promise<SeedContext>;
+//#endregion
+export { LoadSeedContextOptions, SeedContext, SeedIdpUserContext, type SeedNamespaceConfig, loadSeedContext };

package/dist/cli/shared/tailordb-namespaces.d.mts

@@ -0,0 +1,40 @@
+import { Plugin, TailorDBNamespaceData } from "../../plugin/types.mjs";
+import { LoadedConfig } from "./config-loader.mjs";
+import "../services/application.mjs";
+//#region src/cli/shared/tailordb-namespaces.d.ts
+/**
+ * Namespace selection for {@link loadTailorDBNamespaces}: explicit namespace
+ * names, or a selector deriving them from the loaded config and its plugins.
+ * Returning `undefined` (or omitting the option) loads all owned namespaces.
+ */
+type TailorDBNamespaceSelector = string[] | ((config: LoadedConfig, plugins: Plugin[]) => string[] | undefined);
+/**
+ * Options for {@link loadTailorDBNamespaces}.
+ */
+interface LoadTailorDBNamespacesOptions {
+  /** Path to tailor.config.ts. Defaults to searching from the current directory. */
+  configPath?: string;
+  /** Namespaces to load. Omit to load all owned namespaces. */
+  namespaces?: TailorDBNamespaceSelector;
+}
+/**
+ * Result of {@link loadTailorDBNamespaces}.
+ */
+interface LoadedTailorDBNamespaces {
+  /** The loaded Tailor config. */
+  config: LoadedConfig;
+  /** Plugins collected from the config module's plugin-array exports (typically `definePlugins()`). */
+  plugins: Plugin[];
+  /** Loaded TailorDB namespace data, in config order. */
+  namespaces: TailorDBNamespaceData[];
+}
+/**
+ * Load local TailorDB namespaces exactly as SDK generation/deploy sees them:
+ * the config is loaded, user types are generated, and each selected
+ * namespace's types are loaded with namespace plugins applied.
+ * @param options - Namespace loading options.
+ * @returns The loaded config and TailorDB namespace data.
+ */
+declare function loadTailorDBNamespaces(options?: LoadTailorDBNamespacesOptions): Promise<LoadedTailorDBNamespaces>;
+//#endregion
+export { LoadTailorDBNamespacesOptions, LoadedTailorDBNamespaces, TailorDBNamespaceSelector, loadTailorDBNamespaces };

package/dist/cli/shared/tsconfig-paths-plugin.d.mts

@@ -0,0 +1,2 @@
+import "rolldown";
+import "get-tsconfig";

package/dist/cli/shared/type-generator.d.mts

@@ -0,0 +1,20 @@
+import "../../configure/config/types.mjs";
+import { ResolvedEnvAppConfig } from "./config-loader.mjs";
+//#region src/cli/shared/type-generator.d.ts
+/**
+ * Options for generating user type definitions
+ */
+interface GenerateUserTypesOptions {
+  /** Application config with resolved `env` values */
+  config: ResolvedEnvAppConfig;
+  /** Path to Tailor config file */
+  configPath: string;
+}
+/**
+ * Generate user type definitions from the app config and write them to disk.
+ * @param options - Generation options
+ * @returns Promise that resolves when types are generated
+ */
+declare function generateUserTypes(options: GenerateUserTypesOptions): Promise<void>;
+//#endregion
+export { generateUserTypes };

package/dist/cli/shared/workspace-name.d.mts

@@ -0,0 +1 @@
+import { z } from "zod";

package/dist/cli/ts-hook.d.mts

@@ -0,0 +1,4 @@
+export declare function resolve(...args: unknown[]): Promise<unknown>;
+export declare function load(...args: unknown[]): Promise<unknown>;
+export declare function resolveSync(...args: unknown[]): unknown;
+export declare function loadSync(...args: unknown[]): unknown;