@valon-technologies/gestalt 0.0.1-alpha.1

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@valon-technologies/gestalt",
+  "version": "0.0.1-alpha.1",
+  "description": "TypeScript SDK for Gestalt executable providers",
+  "license": "Apache-2.0",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/valon-technologies/gestalt",
+    "directory": "sdk/typescript"
+  },
+  "bugs": {
+    "url": "https://github.com/valon-technologies/gestalt/issues"
+  },
+  "homepage": "https://github.com/valon-technologies/gestalt/tree/main/sdk/typescript#readme",
+  "exports": {
+    ".": "./src/index.ts",
+    "./build": "./src/build.ts",
+    "./runtime": "./src/runtime.ts",
+    "./schema": "./src/schema.ts",
+    "./target": "./src/target.ts"
+  },
+  "bin": {
+    "gestalt-ts-build": "./src/build.ts",
+    "gestalt-ts-runtime": "./src/runtime.ts"
+  },
+  "files": [
+    "src",
+    "gen",
+    "README.md",
+    "tsconfig.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build:proto": "buf generate --template ../proto/buf.typescript.gen.yaml ../proto",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "check": "bun test && tsc --noEmit"
+  },
+  "dependencies": {
+    "@bufbuild/protobuf": "2.11.0",
+    "@connectrpc/connect": "2.1.0",
+    "@connectrpc/connect-node": "2.1.0",
+    "yaml": "2.8.1"
+  },
+  "devDependencies": {
+    "@types/bun": "1.3.2",
+    "typescript": "5.9.3"
+  },
+  "peerDependencies": {
+    "typescript": "^5.9.0"
+  }
+}

package/src/api.ts

@@ -0,0 +1,98 @@
+export interface Subject {
+  id: string;
+  kind: string;
+  displayName: string;
+  authSource: string;
+}
+
+export interface Credential {
+  mode: string;
+  subjectId: string;
+  connection: string;
+  instance: string;
+}
+
+export interface Access {
+  policy: string;
+  role: string;
+}
+
+export interface Request {
+  token: string;
+  connectionParams: Record<string, string>;
+  subject: Subject;
+  credential: Credential;
+  access: Access;
+}
+
+export const responseBrand: unique symbol = Symbol("gestalt.response");
+
+export interface Response<T> {
+  readonly [responseBrand]: true;
+  status?: number;
+  body: T;
+}
+
+export interface OperationResult {
+  status: number;
+  body: string;
+}
+
+export type MaybePromise<T> = T | Promise<T>;
+
+export function response<T>(status: number, body: T): Response<T> {
+  return {
+    [responseBrand]: true,
+    status,
+    body,
+  };
+}
+
+export function ok<T>(body: T): Response<T> {
+  return response(200, body);
+}
+
+export function request(
+  token = "",
+  connectionParams: Record<string, string> = {},
+  subject: Partial<Subject> = {},
+  credential: Partial<Credential> = {},
+  access: Partial<Access> = {},
+): Request {
+  return {
+    token,
+    connectionParams: {
+      ...connectionParams,
+    },
+    subject: {
+      id: subject.id ?? "",
+      kind: subject.kind ?? "",
+      displayName: subject.displayName ?? "",
+      authSource: subject.authSource ?? "",
+    },
+    credential: {
+      mode: credential.mode ?? "",
+      subjectId: credential.subjectId ?? "",
+      connection: credential.connection ?? "",
+      instance: credential.instance ?? "",
+    },
+    access: {
+      policy: access.policy ?? "",
+      role: access.role ?? "",
+    },
+  };
+}
+
+export function connectionParam(
+  input: Request | undefined,
+  name: string,
+): string | undefined {
+  return input?.connectionParams[name];
+}
+
+export function errorMessage(error: unknown): string {
+  if (error instanceof Error && error.message) {
+    return error.message;
+  }
+  return String(error);
+}

package/src/auth.ts

@@ -0,0 +1,103 @@
+import { RuntimeProvider, type RuntimeProviderOptions } from "./provider.ts";
+import type { MaybePromise } from "./api.ts";
+
+export interface AuthenticatedUser {
+  subject: string;
+  email?: string;
+  emailVerified?: boolean;
+  displayName?: string;
+  avatarUrl?: string;
+  claims?: Record<string, string>;
+}
+
+export interface BeginLoginRequest {
+  callbackUrl: string;
+  hostState: string;
+  scopes: string[];
+  options: Record<string, string>;
+}
+
+export interface BeginLoginResponse {
+  authorizationUrl: string;
+  providerState?: Uint8Array;
+}
+
+export interface CompleteLoginRequest {
+  query: Record<string, string>;
+  providerState: Uint8Array;
+  callbackUrl: string;
+}
+
+export interface AuthSessionSettings {
+  sessionTtlSeconds: number | bigint;
+}
+
+export interface AuthProviderOptions extends RuntimeProviderOptions {
+  beginLogin: (
+    request: BeginLoginRequest,
+  ) => MaybePromise<BeginLoginResponse>;
+  completeLogin: (
+    request: CompleteLoginRequest,
+  ) => MaybePromise<AuthenticatedUser>;
+  validateExternalToken?: (
+    token: string,
+  ) => MaybePromise<AuthenticatedUser | null | undefined>;
+  sessionSettings?: () => MaybePromise<AuthSessionSettings>;
+}
+
+export class AuthProvider extends RuntimeProvider {
+  readonly kind = "auth" as const;
+
+  private readonly beginLoginHandler: AuthProviderOptions["beginLogin"];
+  private readonly completeLoginHandler: AuthProviderOptions["completeLogin"];
+  private readonly validateExternalTokenHandler: AuthProviderOptions["validateExternalToken"];
+  private readonly sessionSettingsHandler: AuthProviderOptions["sessionSettings"];
+
+  constructor(options: AuthProviderOptions) {
+    super(options);
+    this.beginLoginHandler = options.beginLogin;
+    this.completeLoginHandler = options.completeLogin;
+    this.validateExternalTokenHandler = options.validateExternalToken;
+    this.sessionSettingsHandler = options.sessionSettings;
+  }
+
+  async beginLogin(request: BeginLoginRequest): Promise<BeginLoginResponse> {
+    return await this.beginLoginHandler(request);
+  }
+
+  async completeLogin(request: CompleteLoginRequest): Promise<AuthenticatedUser> {
+    return await this.completeLoginHandler(request);
+  }
+
+  supportsExternalTokenValidation(): boolean {
+    return this.validateExternalTokenHandler !== undefined;
+  }
+
+  async validateExternalToken(token: string): Promise<AuthenticatedUser | null | undefined> {
+    return await this.validateExternalTokenHandler?.(token);
+  }
+
+  supportsSessionSettings(): boolean {
+    return this.sessionSettingsHandler !== undefined;
+  }
+
+  async sessionSettings(): Promise<AuthSessionSettings | undefined> {
+    return await this.sessionSettingsHandler?.();
+  }
+}
+
+export function defineAuthProvider(options: AuthProviderOptions): AuthProvider {
+  return new AuthProvider(options);
+}
+
+export function isAuthProvider(value: unknown): value is AuthProvider {
+  return (
+    value instanceof AuthProvider ||
+    (typeof value === "object" &&
+      value !== null &&
+      "kind" in value &&
+      (value as { kind?: unknown }).kind === "auth" &&
+      "beginLogin" in value &&
+      "completeLogin" in value)
+  );
+}

package/src/build.ts

@@ -0,0 +1,181 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+
+import { parseProviderTarget, resolveProviderModulePath, type ProviderTarget } from "./target.ts";
+
+export const USAGE =
+  "usage: bun run build.ts ROOT PROVIDER_TARGET OUTPUT PROVIDER_NAME GOOS GOARCH";
+
+export type BuildArgs = {
+  root: string;
+  target: string;
+  outputPath: string;
+  providerName: string;
+  goos: string;
+  goarch: string;
+};
+
+export async function main(argv: string[] = process.argv.slice(2)): Promise<number> {
+  const args = parseBuildArgs(argv);
+  if (!args) {
+    console.error(USAGE);
+    return 2;
+  }
+  buildProviderBinary(args);
+  return 0;
+}
+
+export function parseBuildArgs(argv: string[]): BuildArgs | undefined {
+  if (argv.length !== 6) {
+    return undefined;
+  }
+  return {
+    root: argv[0]!,
+    target: argv[1]!,
+    outputPath: argv[2]!,
+    providerName: argv[3]!,
+    goos: argv[4]!,
+    goarch: argv[5]!,
+  };
+}
+
+export function buildProviderBinary(args: BuildArgs): void {
+  const root = resolve(args.root);
+  const outputPath = resolve(args.outputPath);
+  const target = parseProviderTarget(args.target);
+  const workDir = mkdtempSync(join(tmpdir(), "gestalt-typescript-build-"));
+
+  try {
+    const wrapperPath = writeBundledWrapper(workDir, root, target, args.providerName);
+    const bunCommand = bunBuildCommand(wrapperPath, outputPath, args.goos, args.goarch);
+    const result = spawnSync(bunCommand.command, bunCommand.args, {
+      cwd: root,
+      stdio: "inherit",
+    });
+    if (result.status !== 0) {
+      throw new Error(`bun build failed with status ${result.status ?? "unknown"}`);
+    }
+  } finally {
+    rmSync(workDir, {
+      recursive: true,
+      force: true,
+    });
+  }
+}
+
+export const buildPluginBinary = buildProviderBinary;
+
+export function bunBuildCommand(
+  wrapperPath: string,
+  outputPath: string,
+  goos: string,
+  goarch: string,
+): { command: string; args: string[] } {
+  return {
+    command: resolveBunExecutable(),
+    args: [
+      "build",
+      "--compile",
+      "--target",
+      bunTarget(goos, goarch),
+      "--outfile",
+      outputPath,
+      wrapperPath,
+    ],
+  };
+}
+
+export function bunTarget(goos: string, goarch: string): string {
+  const key = `${goos}/${goarch}`;
+  switch (key) {
+    case "darwin/amd64":
+      return "bun-darwin-x64";
+    case "darwin/arm64":
+      return "bun-darwin-arm64";
+    case "linux/amd64":
+      return "bun-linux-x64";
+    case "linux/arm64":
+      return "bun-linux-arm64";
+    case "windows/amd64":
+      return "bun-windows-x64";
+    case "windows/arm64":
+      return "bun-windows-arm64";
+    default:
+      throw new Error(`unsupported Bun target for ${key}`);
+  }
+}
+
+function writeBundledWrapper(
+  workDir: string,
+  root: string,
+  target: ProviderTarget,
+  providerName: string,
+): string {
+  const wrapperPath = join(workDir, "bundled-runtime.ts");
+  const modulePath = JSON.stringify(resolveProviderModulePath(root, target));
+  const runtimePath = JSON.stringify(resolve(import.meta.dir, "runtime.ts"));
+  const exportName = target.exportName ? JSON.stringify(target.exportName) : "undefined";
+  const source = `
+import * as bundledModule from ${modulePath};
+import { runBundledProvider } from ${runtimePath};
+
+const candidate = ${
+    target.exportName
+      ? `bundledModule[${exportName}]`
+      : defaultBundledCandidateExpression(target.kind)
+  };
+await runBundledProvider(candidate, ${JSON.stringify(target.kind)}, ${JSON.stringify(providerName)});
+`;
+  writeFileSync(wrapperPath, source, "utf8");
+  return wrapperPath;
+}
+
+function defaultBundledCandidateExpression(kind: ProviderTarget["kind"]): string {
+  switch (kind) {
+    case "integration":
+      return "bundledModule.provider ?? bundledModule.plugin ?? bundledModule.default";
+    case "auth":
+      return "bundledModule.auth ?? bundledModule.provider ?? bundledModule.default";
+    case "cache":
+      return "bundledModule.cache ?? bundledModule.provider ?? bundledModule.default";
+    case "secrets":
+      return "bundledModule.secrets ?? bundledModule.provider ?? bundledModule.default";
+    case "s3":
+      return "bundledModule.s3 ?? bundledModule.provider ?? bundledModule.default";
+    case "telemetry":
+      return "bundledModule.telemetry ?? bundledModule.provider ?? bundledModule.default";
+  }
+  throw new Error(`unsupported provider kind: ${kind satisfies never}`);
+}
+
+function resolveBunExecutable(): string {
+  const candidates = [
+    process.env.GESTALT_BUN,
+    join(homedir(), ".bun", "bin", "bun"),
+    "bun",
+  ].filter((value): value is string => Boolean(value));
+
+  for (const candidate of candidates) {
+    if (candidate === "bun") {
+      return candidate;
+    }
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  return "bun";
+}
+
+if (import.meta.main) {
+  void main().then(
+    (code) => {
+      process.exitCode = code;
+    },
+    (error: unknown) => {
+      console.error(error instanceof Error ? error.stack ?? error.message : String(error));
+      process.exitCode = 1;
+    },
+  );
+}