@barekey/sdk 0.4.3 → 0.5.0

package/src/internal/standalone.ts

@@ -0,0 +1,309 @@
+import {
+  FsNotAvailableError,
+  InvalidConfigurationProvidedError,
+  parseBigIntOrThrow,
+  parseBooleanOrThrow,
+  parseDateOrThrow,
+  parseFloatOrThrow,
+} from "../errors.js";
+import type {
+  BarekeyDeclaredType,
+  BarekeyVariableDefinition,
+} from "../types.js";
+import { loadNodeRuntime } from "./node-runtime.js";
+import type { TypegenManifest, TypegenManifestVariable } from "./typegen.js";
+
+type StandaloneVariable = {
+  name: string;
+  value: string;
+};
+
+type StandaloneSnapshot = {
+  variables: Array<StandaloneVariable>;
+  manifestVersion: string;
+};
+
+function isStandaloneEnvFile(fileName: string): boolean {
+  if (fileName === ".env") {
+    return true;
+  }
+
+  if (!fileName.startsWith(".env.")) {
+    return false;
+  }
+
+  const suffix = fileName.slice(".env.".length);
+  if (suffix.length === 0) {
+    return false;
+  }
+
+  return suffix.split(".")[0] !== "example";
+}
+
+function normalizeStandaloneKey(fileName: string, key: string): string {
+  const normalizedKey = key.trim().toUpperCase();
+  if (fileName === ".env") {
+    return normalizedKey;
+  }
+
+  const suffix = fileName.slice(".env.".length);
+  const prefix = suffix
+    .split(".")
+    .filter((token) => token.length > 0)
+    .map((token) => token.toUpperCase())
+    .join("_");
+
+  return prefix.length === 0 ? normalizedKey : `${prefix}_${normalizedKey}`;
+}
+
+function parseQuotedValue(value: string, quote: '"' | "'"): string {
+  let result = "";
+  let escaped = false;
+
+  for (let index = 1; index < value.length; index += 1) {
+    const character = value[index];
+    if (character === undefined) {
+      break;
+    }
+
+    if (quote === '"' && escaped) {
+      if (character === "n") {
+        result += "\n";
+      } else if (character === "r") {
+        result += "\r";
+      } else if (character === "t") {
+        result += "\t";
+      } else {
+        result += character;
+      }
+      escaped = false;
+      continue;
+    }
+
+    if (quote === '"' && character === "\\") {
+      escaped = true;
+      continue;
+    }
+
+    if (character === quote) {
+      return result;
+    }
+
+    result += character;
+  }
+
+  return result;
+}
+
+function parseEnvValue(rawValue: string): string {
+  const trimmed = rawValue.trim();
+  if (trimmed.length === 0) {
+    return "";
+  }
+
+  const firstCharacter = trimmed[0];
+  if (firstCharacter === '"' || firstCharacter === "'") {
+    return parseQuotedValue(trimmed, firstCharacter);
+  }
+
+  const commentStart = trimmed.search(/\s#/);
+  return (commentStart >= 0 ? trimmed.slice(0, commentStart) : trimmed).trim();
+}
+
+function parseStandaloneEnvContents(fileName: string, contents: string): Array<StandaloneVariable> {
+  const variables: Array<StandaloneVariable> = [];
+
+  for (const rawLine of contents.split(/\r?\n/)) {
+    const trimmedLine = rawLine.trimStart();
+    if (trimmedLine.length === 0 || trimmedLine.startsWith("#")) {
+      continue;
+    }
+
+    const line = trimmedLine.startsWith("export ")
+      ? trimmedLine.slice("export ".length).trimStart()
+      : trimmedLine;
+    const delimiterIndex = line.indexOf("=");
+    if (delimiterIndex <= 0) {
+      continue;
+    }
+
+    const rawKey = line.slice(0, delimiterIndex).trim();
+    if (rawKey.length === 0) {
+      continue;
+    }
+
+    variables.push({
+      name: normalizeStandaloneKey(fileName, rawKey),
+      value: parseEnvValue(line.slice(delimiterIndex + 1)),
+    });
+  }
+
+  return variables;
+}
+
+async function hashString(value: string): Promise<string> {
+  if (globalThis.crypto?.subtle !== undefined) {
+    const digest = await globalThis.crypto.subtle.digest(
+      "SHA-256",
+      new TextEncoder().encode(value),
+    );
+    return [...new Uint8Array(digest)]
+      .map((part) => part.toString(16).padStart(2, "0"))
+      .join("");
+  }
+
+  let hash = 0;
+  for (let index = 0; index < value.length; index += 1) {
+    hash = (hash * 31 + value.charCodeAt(index)) >>> 0;
+  }
+  return hash.toString(16).padStart(8, "0");
+}
+
+function inferStandaloneDeclaredType(value: string): BarekeyDeclaredType {
+  try {
+    parseBooleanOrThrow(value);
+    return "boolean";
+  } catch {}
+
+  try {
+    parseBigIntOrThrow(value);
+    return "int64";
+  } catch {}
+
+  try {
+    parseFloatOrThrow(value);
+    return "float";
+  } catch {}
+
+  try {
+    parseDateOrThrow(value);
+    return "date";
+  } catch {}
+
+  return "string";
+}
+
+function typeScriptTypeForDeclaredType(value: BarekeyDeclaredType): string {
+  if (value === "boolean") {
+    return "boolean";
+  }
+  if (value === "int64") {
+    return "bigint";
+  }
+  if (value === "float") {
+    return "number";
+  }
+  if (value === "date") {
+    return "Date";
+  }
+  return "string";
+}
+
+async function loadStandaloneSnapshot(rootDirectory: string): Promise<StandaloneSnapshot> {
+  const runtime = await loadNodeRuntime();
+  if (runtime === null) {
+    throw new FsNotAvailableError({
+      message: "Barekey standalone mode requires a local filesystem to read .env files.",
+    });
+  }
+
+  let fileNames: Array<string>;
+  try {
+    const entries = await runtime.fs.readdir(rootDirectory, {
+      withFileTypes: true,
+    });
+    fileNames = entries
+      .filter((entry) => entry.isFile() && isStandaloneEnvFile(entry.name))
+      .map((entry) => entry.name)
+      .sort((left, right) => {
+        if (left === ".env") {
+          return right === ".env" ? 0 : -1;
+        }
+        if (right === ".env") {
+          return 1;
+        }
+        return left.localeCompare(right);
+      });
+  } catch (error: unknown) {
+    throw new InvalidConfigurationProvidedError({
+      message: `Barekey standalone mode could not read env files from ${rootDirectory}.`,
+      cause: error,
+    });
+  }
+
+  const mergedVariables = new Map<string, string>();
+  const fingerprintParts: Array<string> = [];
+
+  for (const fileName of fileNames) {
+    const filePath = runtime.path.join(rootDirectory, fileName);
+    let contents: string;
+    try {
+      contents = await runtime.fs.readFile(filePath, "utf8");
+    } catch (error: unknown) {
+      throw new InvalidConfigurationProvidedError({
+        message: `Barekey standalone mode could not read ${filePath}.`,
+        cause: error,
+      });
+    }
+
+    fingerprintParts.push(`${fileName}\n${contents}`);
+    for (const variable of parseStandaloneEnvContents(fileName, contents)) {
+      mergedVariables.set(variable.name, variable.value);
+    }
+  }
+
+  return {
+    variables: [...mergedVariables.entries()]
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([name, value]) => ({ name, value })),
+    manifestVersion: `standalone-${await hashString(fingerprintParts.join("\n---\n"))}`,
+  };
+}
+
+export async function loadStandaloneDefinitions(
+  rootDirectory: string,
+): Promise<Array<BarekeyVariableDefinition>> {
+  const snapshot = await loadStandaloneSnapshot(rootDirectory);
+  return snapshot.variables.map((variable) => ({
+    name: variable.name,
+    kind: "secret",
+    declaredType: inferStandaloneDeclaredType(variable.value),
+    visibility: "private",
+    value: variable.value,
+  }));
+}
+
+export async function buildStandaloneTypegenManifest(input: {
+  rootDirectory: string;
+  organization: string;
+  project: string;
+  environment: string;
+}): Promise<TypegenManifest> {
+  const snapshot = await loadStandaloneSnapshot(input.rootDirectory);
+  const variables: Array<TypegenManifestVariable> = snapshot.variables.map((variable) => {
+    const declaredType = inferStandaloneDeclaredType(variable.value);
+    return {
+      name: variable.name,
+      visibility: "private",
+      kind: "secret",
+      declaredType,
+      required: true,
+      updatedAtMs: Date.now(),
+      typeScriptType: typeScriptTypeForDeclaredType(declaredType),
+      valueATypeScriptType: null,
+      valueBTypeScriptType: null,
+      rolloutFunction: null,
+      rolloutMilestones: null,
+    };
+  });
+
+  return {
+    orgId: `standalone:${input.organization}`,
+    orgSlug: input.organization,
+    projectSlug: input.project,
+    stageSlug: input.environment,
+    generatedAtMs: Date.now(),
+    manifestVersion: snapshot.manifestVersion,
+    variables,
+  };
+}

package/src/internal/typegen.ts

@@ -4,8 +4,10 @@ import {
   writeTextFileAtomic,
 } from "./node-runtime.js";
 import type {
+  BarekeyMode,
   BarekeyRolloutFunction,
   BarekeyRolloutMilestone,
+  BarekeyTypegenMode,
   BarekeyTypegenResult,
 } from "../types.js";
 
@@ -43,13 +45,19 @@ type TypegenMetadata = {
   orgSlug: string | null;
   projectSlug: string | null;
   stageSlug: string | null;
+  typegenMode: BarekeyTypegenMode | null;
+  runtimeMode: BarekeyMode | null;
+  localEnvRoot: string | null;
 };
 
 type TypegenMetadataIdentity = {
-  baseUrl: string;
+  baseUrl: string | null;
   orgSlug: string;
   projectSlug: string;
   stageSlug: string;
+  typegenMode: BarekeyTypegenMode;
+  runtimeMode: BarekeyMode;
+  localEnvRoot: string | null;
 };
 
 function renderLinearMilestones(milestones: Array<BarekeyRolloutMilestone>): string {
@@ -76,7 +84,14 @@ function renderRolloutMetadataType(row: TypegenManifestVariable): string {
   return `Linear<${renderedMilestones}>`;
 }
 
-function renderVariableType(row: TypegenManifestVariable): string {
+function renderVariableType(
+  row: TypegenManifestVariable,
+  mode: BarekeyTypegenMode,
+): string {
+  if (mode === "minimal") {
+    return row.typeScriptType;
+  }
+
   const renderEnvDescriptor = (input: {
     mode: "Secret" | "AB";
     rollout: string;
@@ -100,6 +115,7 @@ function renderVariableType(row: TypegenManifestVariable): string {
 function buildGeneratedTypesContents(
   manifest: TypegenManifest,
   input: {
+    mode: BarekeyTypegenMode;
     typeModulePath: "./dist/types.js" | "./dist/public-types.js";
     declaredModulePath: "./dist/types.js" | "./dist/public-types.js";
     interfaceName: "BarekeyGeneratedTypeMap" | "BarekeyPublicGeneratedTypeMap";
@@ -110,16 +126,19 @@ function buildGeneratedTypesContents(
     .slice()
     .filter(input.include)
     .sort((left, right) => left.name.localeCompare(right.name))
-    .map((row) => `    ${JSON.stringify(row.name)}: ${renderVariableType(row)};`)
+    .map((row) => `    ${JSON.stringify(row.name)}: ${renderVariableType(row, input.mode)};`)
     .join("\n");
 
+  const importLine =
+    input.mode === "semantic"
+      ? `import type { AB, EaseInOut, Env, Linear, Secret, Step } from "${input.typeModulePath}";\n\n`
+      : "";
+
   return `/* eslint-disable */
 /* This file is generated by barekey typegen. */
 /* barekey-manifest-version: ${manifest.manifestVersion} */
 
-import type { AB, EaseInOut, Env, Linear, Secret, Step } from "${input.typeModulePath}";
-
-declare module "${input.declaredModulePath}" {
+${importLine}declare module "${input.declaredModulePath}" {
   interface ${input.interfaceName} {
 ${mapLines.length > 0 ? mapLines : ""}
   }
@@ -156,6 +175,10 @@ function parseTypegenMetadata(contents: string | null): TypegenMetadata | null {
       orgSlug?: unknown;
       projectSlug?: unknown;
       stageSlug?: unknown;
+      typegenMode?: unknown;
+      runtimeMode?: unknown;
+      localEnvRoot?: unknown;
+      mode?: unknown;
     };
     if (
       candidate.version !== TYPEGEN_METADATA_VERSION ||
@@ -172,6 +195,21 @@ function parseTypegenMetadata(contents: string | null): TypegenMetadata | null {
       (candidate.stageSlug !== undefined &&
         candidate.stageSlug !== null &&
         typeof candidate.stageSlug !== "string") ||
+      (candidate.typegenMode !== undefined &&
+        candidate.typegenMode !== null &&
+        candidate.typegenMode !== "semantic" &&
+        candidate.typegenMode !== "minimal") ||
+      (candidate.mode !== undefined &&
+        candidate.mode !== null &&
+        candidate.mode !== "semantic" &&
+        candidate.mode !== "minimal") ||
+      (candidate.runtimeMode !== undefined &&
+        candidate.runtimeMode !== null &&
+        candidate.runtimeMode !== "centralized" &&
+        candidate.runtimeMode !== "standalone") ||
+      (candidate.localEnvRoot !== undefined &&
+        candidate.localEnvRoot !== null &&
+        typeof candidate.localEnvRoot !== "string") ||
       !Number.isFinite(Date.parse(candidate.last))
     ) {
       return null;
@@ -184,6 +222,9 @@ function parseTypegenMetadata(contents: string | null): TypegenMetadata | null {
       orgSlug: candidate.orgSlug ?? null,
       projectSlug: candidate.projectSlug ?? null,
       stageSlug: candidate.stageSlug ?? null,
+      typegenMode: candidate.typegenMode ?? candidate.mode ?? null,
+      runtimeMode: candidate.runtimeMode ?? "centralized",
+      localEnvRoot: candidate.localEnvRoot ?? null,
     };
   } catch {
     return null;
@@ -202,6 +243,9 @@ function buildTypegenMetadataContents(
       orgSlug: identity.orgSlug,
       projectSlug: identity.projectSlug,
       stageSlug: identity.stageSlug,
+      typegenMode: identity.typegenMode,
+      runtimeMode: identity.runtimeMode,
+      localEnvRoot: identity.localEnvRoot,
     },
     null,
     2,
@@ -213,18 +257,23 @@ export async function resolveInstalledSdkGeneratedTypesPath(): Promise<string |
   return target?.serverGeneratedTypesPath ?? null;
 }
 
-export function renderGeneratedTypesForManifest(manifest: TypegenManifest): {
+export function renderGeneratedTypesForManifest(
+  manifest: TypegenManifest,
+  mode: BarekeyTypegenMode = "semantic",
+): {
   serverContents: string;
   publicContents: string;
 } {
   return {
     serverContents: buildGeneratedTypesContents(manifest, {
+      mode,
       typeModulePath: "./dist/types.js",
       declaredModulePath: "./dist/types.js",
       interfaceName: "BarekeyGeneratedTypeMap",
       include: () => true,
     }),
     publicContents: buildGeneratedTypesContents(manifest, {
+      mode,
       typeModulePath: "./dist/public-types.js",
       declaredModulePath: "./dist/public-types.js",
       interfaceName: "BarekeyPublicGeneratedTypeMap",
@@ -251,7 +300,10 @@ export async function hasFreshInstalledSdkTypegen(
     metadata.baseUrl !== identity.baseUrl ||
     metadata.orgSlug !== identity.orgSlug ||
     metadata.projectSlug !== identity.projectSlug ||
-    metadata.stageSlug !== identity.stageSlug
+    metadata.stageSlug !== identity.stageSlug ||
+    metadata.typegenMode !== identity.typegenMode ||
+    metadata.runtimeMode !== identity.runtimeMode ||
+    metadata.localEnvRoot !== identity.localEnvRoot
   ) {
     return false;
   }
@@ -278,7 +330,10 @@ export async function writeInstalledSdkGeneratedTypes(
     readTextFile(target.serverGeneratedTypesPath),
     readTextFile(target.publicGeneratedTypesPath),
   ]);
+  const rendered = renderGeneratedTypesForManifest(manifest, identity.typegenMode);
   if (
+    existingServerContents === rendered.serverContents &&
+    existingPublicContents === rendered.publicContents &&
     readManifestVersion(existingServerContents) === manifest.manifestVersion &&
     readManifestVersion(existingPublicContents) === manifest.manifestVersion
   ) {
@@ -295,8 +350,6 @@ export async function writeInstalledSdkGeneratedTypes(
     };
   }
 
-  const rendered = renderGeneratedTypesForManifest(manifest);
-
   await Promise.all([
     writeTextFileAtomic(
       target.serverGeneratedTypesPath,

package/src/public-client.ts

@@ -70,6 +70,10 @@ export class PublicBarekeyClient {
   private requirementsPromise: Promise<void> | null = null;
 
   constructor();
+  constructor(options: {
+    requirements?: PublicBarekeyClientOptions["requirements"];
+    baseUrl?: string;
+  });
   constructor(options: {
     organization: string;
     project: string;

package/src/public-types.ts

@@ -17,6 +17,7 @@ export type {
   BarekeyStandardSchemaV1,
   BarekeyTemporalInstant,
   BarekeyTemporalInstantLike,
+  BarekeyTypegenMode,
   BarekeyTtlInput,
   BarekeyTypegenResult,
   BarekeyVariableDefinition,

package/src/public.ts

@@ -48,6 +48,7 @@ export type {
   BarekeyGetOptions,
   BarekeyJsonConfig,
   BarekeyLiteralString,
+  BarekeyMode,
   BarekeyResolvedRecord,
   BarekeyResolvedRecords,
   BarekeyResolvedKind,
@@ -57,6 +58,7 @@ export type {
   BarekeyStandardSchemaV1,
   BarekeyTemporalInstant,
   BarekeyTemporalInstantLike,
+  BarekeyTypegenMode,
   BarekeyTtlInput,
   BarekeyValueForGeneratedMap,
   BarekeyValuesForGeneratedMap,

package/src/server.ts

@@ -51,6 +51,7 @@ export type {
   BarekeyJsonConfig,
   BarekeyKey,
   BarekeyLiteralString,
+  BarekeyMode,
   BarekeyKnownKey,
   BarekeyResolvedRecord,
   BarekeyResolvedRecords,
@@ -59,6 +60,7 @@ export type {
   BarekeyStandardSchemaV1,
   BarekeyTemporalInstant,
   BarekeyTemporalInstantLike,
+  BarekeyTypegenMode,
   BarekeyTtlInput,
   BarekeyTypegenResult,
   BarekeyValueForGeneratedMap,

package/src/types.ts

@@ -3,6 +3,9 @@ export type BarekeyVisibility = "private" | "public";
 
 export type BarekeyDeclaredType = "string" | "boolean" | "int64" | "float" | "date" | "json";
 
+export type BarekeyTypegenMode = "semantic" | "minimal";
+export type BarekeyMode = "centralized" | "standalone";
+
 export type BarekeyTemporalInstant = {
   readonly epochMilliseconds: number;
   toJSON(): string;
@@ -68,12 +71,6 @@ type BarekeyEnvMarker<TMode, TVisibility, TRollout> = {
   };
 };
 
-type BarekeyEnvFromDescriptor<TDescriptor extends BarekeyAnyEnvDescriptor> = TDescriptor["Type"] &
-  BarekeyEnvMarker<TDescriptor["Mode"], TDescriptor["Visibility"], TDescriptor["Rollout"]>;
-
-type BarekeyLegacyEnv<TMode, TValue, TRollout, TVisibility> = TValue &
-  BarekeyEnvMarker<TMode, TVisibility, TRollout>;
-
 export type Env<
   TDescriptorOrMode,
   TValue = never,
@@ -81,9 +78,14 @@ export type Env<
   TVisibility = never,
 > = [TValue] extends [never]
   ? TDescriptorOrMode extends BarekeyAnyEnvDescriptor
-    ? BarekeyEnvFromDescriptor<TDescriptorOrMode>
+    ? TDescriptorOrMode["Type"] &
+        BarekeyEnvMarker<
+          TDescriptorOrMode["Mode"],
+          TDescriptorOrMode["Visibility"],
+          TDescriptorOrMode["Rollout"]
+        >
     : never
-  : BarekeyLegacyEnv<TDescriptorOrMode, TValue, TRollout, TVisibility>;
+  : TValue & BarekeyEnvMarker<TDescriptorOrMode, TVisibility, TRollout>;
 
 export type BarekeyCoerceTarget = "string" | "boolean" | "int64" | "float" | "date" | "json";
 
@@ -196,6 +198,10 @@ export type BarekeyJsonConfig = {
   environment?: string;
   org?: string;
   stage?: string;
+  config?: {
+    typegen?: BarekeyTypegenMode;
+    mode?: BarekeyMode;
+  };
 };
 
 export type BarekeyStandardSchemaResult =