@alienplatform/bindings 1.0.0

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@alienplatform/bindings",
+  "version": "1.0.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "keywords": [
+    "alien",
+    "bindings",
+    "grpc",
+    "sdk"
+  ],
+  "author": "",
+  "license": "ISC",
+  "description": "TypeScript SDK for Alien bindings - gRPC client for Storage, KV, Queue, Vault, and more",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/alienplatform/alien.git",
+    "directory": "packages/bindings"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "@types/node": "^24.0.15",
+    "ts-proto": "^2.7.0",
+    "tsdown": "^0.13.0",
+    "typescript": "^5.8.3",
+    "vitest": "^3.1.4",
+    "@alienplatform/typescript-config": "^1.0.0"
+  },
+  "dependencies": {
+    "@bufbuild/protobuf": "^2.5.3",
+    "@grpc/grpc-js": "^1.13.4",
+    "long": "^5.3.2",
+    "nice-grpc": "^2.1.11",
+    "nice-grpc-common": "^2.0.2",
+    "protobufjs": "^7.5.3",
+    "ts-pattern": "^5.7.1",
+    "zod": "4.3.2",
+    "@alienplatform/core": "^1.0.1"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run --passWithNoTests",
+    "test:ts": "tsc --noEmit",
+    "generate": "./scripts/generate-proto.sh",
+    "format-and-lint": "biome check .",
+    "format-and-lint:fix": "biome check . --write"
+  }
+}

package/scripts/generate-proto.sh

@@ -0,0 +1,46 @@
+#!/bin/bash
+
+# Generate TypeScript types from proto files using ts-proto + nice-grpc
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PACKAGE_DIR="$(dirname "$SCRIPT_DIR")"
+PROTO_DIR="$PACKAGE_DIR/../../crates/alien-bindings/proto"
+OUT_DIR="$PACKAGE_DIR/src/generated"
+
+# Clean and create output directory
+rm -rf "$OUT_DIR"
+mkdir -p "$OUT_DIR"
+
+# Find protoc - prefer system installation
+if command -v protoc &> /dev/null; then
+  PROTOC="protoc"
+else
+  echo "Error: protoc not found. Install via 'brew install protobuf' on macOS."
+  exit 1
+fi
+
+# Find ts-proto plugin
+TS_PROTO_PLUGIN="$PACKAGE_DIR/node_modules/.bin/protoc-gen-ts_proto"
+
+if [ ! -f "$TS_PROTO_PLUGIN" ]; then
+  echo "Error: protoc-gen-ts_proto not found. Run 'pnpm install' first."
+  exit 1
+fi
+
+echo "Using protoc: $PROTOC"
+echo "Using ts-proto plugin: $TS_PROTO_PLUGIN"
+echo "Generating TypeScript types from proto files..."
+
+# Generate types for all proto files
+# Using nice-grpc options as per the playbook
+"$PROTOC" \
+  --plugin="protoc-gen-ts_proto=$TS_PROTO_PLUGIN" \
+  --ts_proto_out="$OUT_DIR" \
+  --ts_proto_opt=outputServices=nice-grpc,outputServices=generic-definitions,useExactTypes=false,esModuleInterop=true,importSuffix=.js \
+  --proto_path="$PROTO_DIR" \
+  "$PROTO_DIR"/*.proto
+
+echo "Generated TypeScript types in $OUT_DIR"
+echo "Done!"

package/src/bindings/AGENTS.md

@@ -0,0 +1,105 @@
+# Binding Implementations
+
+Each TypeScript binding must match its Rust counterpart in `alien-bindings/src/providers/<name>/grpc.rs`.
+
+**Examples:**
+- `kv.ts` → `providers/kv/grpc.rs`
+- `storage.ts` → `providers/storage/grpc.rs`
+- `build.ts` → `providers/build/grpc.rs`
+
+## Core Pattern: Public API → gRPC → Public API
+
+```
+┌─────────────────┐       ┌─────────────────┐       ┌─────────────────┐
+│   Public API    │  →    │   gRPC Proto    │  →    │   Public API    │
+│   (SDK types)   │       │   (wire format) │       │   (SDK types)   │
+└─────────────────┘       └─────────────────┘       └─────────────────┘
+     User calls              Internal only            User receives
+```
+
+**Public API types** come from `@alienplatform/core` or `../types.ts`. Proto types are **internal only** - never exposed to users.
+
+```typescript
+// ❌ Bad - exposing proto types
+async getStatus(buildId: string): Promise<BuildExecutionProto>
+
+// ✅ Good - convert proto to public types
+async getStatus(buildId: string): Promise<BuildExecution> {
+  const response = await this.client.getBuildStatus({ ... })
+  return this.fromProtoExecution(response.execution!)  // Transform here
+}
+```
+
+## Guidelines
+
+### 1. Match All Rust Trait Methods
+Every method in the Rust trait must have a TypeScript equivalent. Check for missing methods when adding bindings.
+
+### 2. Match Rust Enum Fallbacks Exactly
+Rust often maps unknown/unspecified enum values to a specific fallback. TypeScript must match:
+
+```rust
+// Rust: maps Unspecified → Failed
+BuildStatus::Unspecified => BuildStatus::Failed,
+```
+```typescript
+// TypeScript: must match
+[BuildStatusProto.BUILD_STATUS_UNSPECIFIED]: "FAILED",  // NOT "QUEUED"
+```
+
+### 3. Transform Types in Private Helpers
+Keep transformations consistent and testable:
+
+```typescript
+private fromProtoExecution(proto: BuildExecutionProto): BuildExecution {
+  return {
+    id: proto.id,
+    status: statusMap[proto.status] ?? "FAILED",
+    startTime: proto.startTime ? new Date(proto.startTime) : undefined,
+  }
+}
+
+private toProtoConfig(config: BuildStartConfig): BuildConfigProto {
+  return {
+    script: config.script,
+    computeType: computeTypeMap[config.computeType] ?? ComputeType.UNSPECIFIED,
+  }
+}
+```
+
+### 4. Convert Units Consistently
+Rust uses `Duration`, TypeScript uses milliseconds:
+
+```typescript
+ttlSeconds: options.ttlMs ? Math.floor(options.ttlMs / 1000) : undefined
+timeoutSeconds: request.timeoutMs ? Math.floor(request.timeoutMs / 1000) : undefined
+```
+
+### 5. Use wrapGrpcCall for Error Handling
+Always wrap gRPC calls with context for proper error mapping:
+
+```typescript
+return await wrapGrpcCall(
+  "BuildService",
+  "GetBuildStatus",
+  async () => { ... },
+  { bindingName: this.bindingName },  // Context for error mapping
+)
+```
+
+### 6. Handle Optional Proto Fields
+Rust `Option<T>` becomes `T | undefined`. Use nullish coalescing:
+
+```typescript
+uri: proto.uri ?? "",
+createdAt: proto.createdAt ? new Date(proto.createdAt) : undefined,
+```
+
+## Convenience Methods
+
+TypeScript may add convenience methods not in Rust (e.g., `getJson()`, `exists()`, `waitForCompletion()`). These are fine if they build on core methods.
+
+## See Also
+
+- Parent: `packages/bindings/AGENTS.md` - Package overview and type architecture
+- Proto definitions: `crates/alien-bindings/proto/`

package/src/bindings/artifact-registry.ts

@@ -0,0 +1,314 @@
+/**
+ * ArtifactRegistry binding implementation.
+ *
+ * Provides container image repository management.
+ */
+
+import { type Channel, createClient } from "nice-grpc"
+import {
+  ArtifactRegistryServiceDefinition,
+  ComputeServiceType as ComputeServiceTypeProto,
+  type Credentials,
+  type CrossAccountAccess as CrossAccountAccessProto,
+  type CrossAccountPermissions as CrossAccountPermissionsProto,
+  type ArtifactRegistryServiceClient as GeneratedClient,
+  ArtifactRegistryPermissions as PermissionsProto,
+  type RepositoryResult,
+} from "../generated/artifact_registry.js"
+import { wrapGrpcCall } from "../grpc-utils.js"
+import type {
+  ArtifactRegistryCredentials,
+  ArtifactRegistryPermissions,
+  ComputeServiceType,
+  CrossAccountAccess,
+  CrossAccountPermissions,
+  RepositoryInfo,
+} from "../types.js"
+
+// Permission map
+const permissionMap: Record<ArtifactRegistryPermissions, PermissionsProto> = {
+  pull: PermissionsProto.PULL,
+  "push-pull": PermissionsProto.PUSH_PULL,
+}
+
+/**
+ * ArtifactRegistry binding for container repository management.
+ *
+ * @example
+ * ```typescript
+ * import { artifactRegistry } from "@alienplatform/bindings"
+ *
+ * const registry = artifactRegistry("my-registry")
+ *
+ * // Create a repository
+ * const repo = await registry.createRepository("my-app")
+ * console.log("Repository URI:", repo.uri)
+ *
+ * // Generate push credentials
+ * const creds = await registry.generateCredentials("my-app", "push-pull")
+ * console.log("Username:", creds.username)
+ * ```
+ */
+export class ArtifactRegistry {
+  private readonly client: GeneratedClient
+  private readonly bindingName: string
+
+  constructor(channel: Channel, bindingName: string) {
+    this.client = createClient(ArtifactRegistryServiceDefinition, channel)
+    this.bindingName = bindingName
+  }
+
+  /**
+   * Create a repository.
+   *
+   * @param repoName - Name of the repository
+   * @returns Repository information
+   */
+  async createRepository(repoName: string): Promise<RepositoryInfo> {
+    return await wrapGrpcCall(
+      "ArtifactRegistryService",
+      "CreateRepository",
+      async () => {
+        const response = await this.client.createRepository({
+          bindingName: this.bindingName,
+          repoName,
+        })
+        return this.fromProtoResult(response.result!)
+      },
+      { bindingName: this.bindingName },
+    )
+  }
+
+  /**
+   * Get repository details.
+   *
+   * @param repoId - Repository ID
+   * @returns Repository information
+   */
+  async getRepository(repoId: string): Promise<RepositoryInfo> {
+    return await wrapGrpcCall(
+      "ArtifactRegistryService",
+      "GetRepository",
+      async () => {
+        const response = await this.client.getRepository({
+          bindingName: this.bindingName,
+          repoId,
+        })
+        return this.fromProtoResult(response.result!)
+      },
+      { bindingName: this.bindingName },
+    )
+  }
+
+  /**
+   * Add cross-account access to a repository.
+   *
+   * @param repoId - Repository ID
+   * @param access - Cross-account access configuration
+   */
+  async addCrossAccountAccess(repoId: string, access: CrossAccountAccess): Promise<void> {
+    await wrapGrpcCall(
+      "ArtifactRegistryService",
+      "AddCrossAccountAccess",
+      async () => {
+        await this.client.addCrossAccountAccess({
+          bindingName: this.bindingName,
+          repoId,
+          access: this.toProtoCrossAccountAccess(access),
+        })
+      },
+      { bindingName: this.bindingName },
+    )
+  }
+
+  /**
+   * Remove cross-account access from a repository.
+   *
+   * @param repoId - Repository ID
+   * @param access - Cross-account access configuration to remove
+   */
+  async removeCrossAccountAccess(repoId: string, access: CrossAccountAccess): Promise<void> {
+    await wrapGrpcCall(
+      "ArtifactRegistryService",
+      "RemoveCrossAccountAccess",
+      async () => {
+        await this.client.removeCrossAccountAccess({
+          bindingName: this.bindingName,
+          repoId,
+          access: this.toProtoCrossAccountAccess(access),
+        })
+      },
+      { bindingName: this.bindingName },
+    )
+  }
+
+  /**
+   * Get current cross-account access permissions for a repository.
+   *
+   * @param repoId - Repository ID
+   * @returns Current cross-account permissions
+   */
+  async getCrossAccountAccess(repoId: string): Promise<CrossAccountPermissions> {
+    return await wrapGrpcCall(
+      "ArtifactRegistryService",
+      "GetCrossAccountAccess",
+      async () => {
+        const response = await this.client.getCrossAccountAccess({
+          bindingName: this.bindingName,
+          repoId,
+        })
+        return this.fromProtoCrossAccountPermissions(response.permissions!)
+      },
+      { bindingName: this.bindingName },
+    )
+  }
+
+  /**
+   * Generate credentials for repository access.
+   *
+   * @param repoId - Repository ID
+   * @param permissions - Permission level (pull or push-pull)
+   * @param ttlSeconds - Optional TTL in seconds
+   * @returns Repository credentials
+   */
+  async generateCredentials(
+    repoId: string,
+    permissions: ArtifactRegistryPermissions,
+    ttlSeconds?: number,
+  ): Promise<ArtifactRegistryCredentials> {
+    return await wrapGrpcCall(
+      "ArtifactRegistryService",
+      "GenerateCredentials",
+      async () => {
+        const response = await this.client.generateCredentials({
+          bindingName: this.bindingName,
+          repoId,
+          permissions: permissionMap[permissions],
+          ttlSeconds,
+        })
+        return this.fromProtoCredentials(response.credentials!)
+      },
+      { bindingName: this.bindingName },
+    )
+  }
+
+  /**
+   * Delete a repository.
+   *
+   * @param repoId - Repository ID
+   */
+  async deleteRepository(repoId: string): Promise<void> {
+    await wrapGrpcCall(
+      "ArtifactRegistryService",
+      "DeleteRepository",
+      async () => {
+        await this.client.deleteRepository({
+          bindingName: this.bindingName,
+          repoId,
+        })
+      },
+      { bindingName: this.bindingName },
+    )
+  }
+
+  // Private helpers
+
+  private fromProtoResult(proto: RepositoryResult): RepositoryInfo {
+    return {
+      name: proto.name,
+      uri: proto.uri ?? "",
+      createdAt: proto.createdAt ? new Date(proto.createdAt) : undefined,
+    }
+  }
+
+  private fromProtoCredentials(proto: Credentials): ArtifactRegistryCredentials {
+    return {
+      username: proto.username,
+      password: proto.password,
+      expiresAt: proto.expiresAt ? new Date(proto.expiresAt) : undefined,
+    }
+  }
+
+  private toProtoCrossAccountAccess(access: CrossAccountAccess): CrossAccountAccessProto {
+    if (access.type === "aws") {
+      return {
+        aws: {
+          accountIds: access.aws.accountIds,
+          allowedServiceTypes: access.aws.allowedServiceTypes.map(st =>
+            this.computeServiceTypeToProto(st),
+          ),
+          roleArns: access.aws.roleArns,
+        },
+        gcp: undefined,
+      }
+    }
+    return {
+      aws: undefined,
+      gcp: {
+        projectNumbers: access.gcp.projectNumbers,
+        allowedServiceTypes: access.gcp.allowedServiceTypes.map(st =>
+          this.computeServiceTypeToProto(st),
+        ),
+        serviceAccountEmails: access.gcp.serviceAccountEmails,
+      },
+    }
+  }
+
+  private fromProtoCrossAccountAccess(proto: CrossAccountAccessProto): CrossAccountAccess {
+    if (proto.aws) {
+      return {
+        type: "aws",
+        aws: {
+          accountIds: proto.aws.accountIds,
+          allowedServiceTypes: proto.aws.allowedServiceTypes
+            .map(st => this.protoToComputeServiceType(st))
+            .filter((st): st is ComputeServiceType => st !== undefined),
+          roleArns: proto.aws.roleArns,
+        },
+      }
+    }
+    if (proto.gcp) {
+      return {
+        type: "gcp",
+        gcp: {
+          projectNumbers: proto.gcp.projectNumbers,
+          allowedServiceTypes: proto.gcp.allowedServiceTypes
+            .map(st => this.protoToComputeServiceType(st))
+            .filter((st): st is ComputeServiceType => st !== undefined),
+          serviceAccountEmails: proto.gcp.serviceAccountEmails,
+        },
+      }
+    }
+    throw new Error("Invalid CrossAccountAccess: neither aws nor gcp set")
+  }
+
+  private fromProtoCrossAccountPermissions(
+    proto: CrossAccountPermissionsProto,
+  ): CrossAccountPermissions {
+    if (!proto.access) {
+      throw new Error("Invalid CrossAccountPermissions: access is missing")
+    }
+    return {
+      access: this.fromProtoCrossAccountAccess(proto.access),
+      lastUpdated: proto.lastUpdated,
+    }
+  }
+
+  private computeServiceTypeToProto(st: ComputeServiceType): ComputeServiceTypeProto {
+    switch (st) {
+      case "function":
+        return ComputeServiceTypeProto.FUNCTION
+      default:
+        return ComputeServiceTypeProto.UNRECOGNIZED
+    }
+  }
+
+  private protoToComputeServiceType(st: ComputeServiceTypeProto): ComputeServiceType | undefined {
+    switch (st) {
+      case ComputeServiceTypeProto.FUNCTION:
+        return "function"
+      default:
+        return undefined
+    }
+  }
+}