@aiworkbench/vibe-publish 0.0.1

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@aiworkbench/vibe-publish",
+  "version": "0.0.1",
+  "publishConfig": { "access": "public" },
+  "type": "module",
+  "bin": {
+    "vibe-publish": "./dist/index.js"
+  },
+  "main": "dist/index.js",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "bun build ./src/index.ts --outfile ./dist/index.js --target=node --external @azure/storage-blob",
+    "dev": "bun --watch src/index.ts",
+    "test": "bun test",
+    "type-check": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@aiworkbench/vibe-types": "workspace:*",
+    "@azure/storage-blob": "^12.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  },
+  "files": ["dist", "src"]
+}

package/src/__tests__/config.test.ts

@@ -0,0 +1,87 @@
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { loadConfig } from "../config.js";
+
+describe("loadConfig — GitHub URL resolution", () => {
+  const envBackup: Record<string, string | undefined> = {};
+  const envKeys = [
+    "VIBE_GITHUB_API_URL",
+    "VIBE_GITHUB_SERVER_URL",
+    "GITHUB_API_URL",
+    "GITHUB_SERVER_URL",
+  ];
+
+  beforeEach(() => {
+    for (const key of envKeys) {
+      envBackup[key] = process.env[key];
+      delete process.env[key];
+    }
+  });
+
+  afterEach(() => {
+    for (const key of envKeys) {
+      if (envBackup[key] === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = envBackup[key];
+      }
+    }
+  });
+
+  test("defaults to public GitHub URLs when no env vars set", () => {
+    const config = loadConfig();
+    expect(config.githubApiUrl).toBe("https://api.github.com");
+    expect(config.githubServerUrl).toBe("https://github.com");
+  });
+
+  test("VIBE_GITHUB_* env vars override defaults", () => {
+    process.env.VIBE_GITHUB_API_URL = "https://ghe.corp.com/api/v3";
+    process.env.VIBE_GITHUB_SERVER_URL = "https://ghe.corp.com";
+
+    const config = loadConfig();
+    expect(config.githubApiUrl).toBe("https://ghe.corp.com/api/v3");
+    expect(config.githubServerUrl).toBe("https://ghe.corp.com");
+  });
+
+  test("GITHUB_* env vars (CI-provided) override defaults", () => {
+    process.env.GITHUB_API_URL = "https://ghe.corp.com/api/v3";
+    process.env.GITHUB_SERVER_URL = "https://ghe.corp.com";
+
+    const config = loadConfig();
+    expect(config.githubApiUrl).toBe("https://ghe.corp.com/api/v3");
+    expect(config.githubServerUrl).toBe("https://ghe.corp.com");
+  });
+
+  test("VIBE_GITHUB_* takes precedence over GITHUB_*", () => {
+    process.env.VIBE_GITHUB_API_URL = "https://vibe-override/api/v3";
+    process.env.GITHUB_API_URL = "https://ci-provided/api/v3";
+
+    const config = loadConfig();
+    expect(config.githubApiUrl).toBe("https://vibe-override/api/v3");
+  });
+
+  test("explicit overrides take precedence over all env vars", () => {
+    process.env.VIBE_GITHUB_API_URL = "https://env-value/api/v3";
+
+    const config = loadConfig({
+      githubApiUrl: "https://explicit-override/api/v3",
+    });
+    expect(config.githubApiUrl).toBe("https://explicit-override/api/v3");
+  });
+
+  test("empty string env vars are treated as unset", () => {
+    process.env.VIBE_GITHUB_API_URL = "";
+    process.env.VIBE_GITHUB_SERVER_URL = "";
+
+    const config = loadConfig();
+    expect(config.githubApiUrl).toBe("https://api.github.com");
+    expect(config.githubServerUrl).toBe("https://github.com");
+  });
+
+  test("empty VIBE_GITHUB_* falls through to GITHUB_*", () => {
+    process.env.VIBE_GITHUB_API_URL = "";
+    process.env.GITHUB_API_URL = "https://ghe.corp.com/api/v3";
+
+    const config = loadConfig();
+    expect(config.githubApiUrl).toBe("https://ghe.corp.com/api/v3");
+  });
+});

package/src/__tests__/github-adapter.test.ts

@@ -0,0 +1,57 @@
+import { describe, test, expect } from "bun:test";
+import { GitHubAdapter, type GitHubConfig } from "../git-platform/github.js";
+
+function createAdapter(overrides: Partial<GitHubConfig> = {}): GitHubAdapter {
+  return new GitHubAdapter({
+    registryRepo: "my-org/vibe-registry",
+    token: "ghp_test123",
+    apiUrl: "https://api.github.com",
+    serverUrl: "https://github.com",
+    ...overrides,
+  });
+}
+
+describe("GitHubAdapter — public GitHub", () => {
+  const adapter = createAdapter();
+
+  test("cloneUrl uses github.com", () => {
+    // Access private method via prototype for testing
+    const url = (adapter as any).cloneUrl();
+    expect(url).toBe(
+      "https://x-access-token:ghp_test123@github.com/my-org/vibe-registry.git",
+    );
+  });
+
+  test("hostname is derived from serverUrl", () => {
+    expect((adapter as any).hostname).toBe("github.com");
+  });
+});
+
+describe("GitHubAdapter — GitHub Enterprise Server", () => {
+  const adapter = createAdapter({
+    apiUrl: "https://ghe.corp.com/api/v3",
+    serverUrl: "https://ghe.corp.com",
+  });
+
+  test("cloneUrl uses GHE hostname", () => {
+    const url = (adapter as any).cloneUrl();
+    expect(url).toBe(
+      "https://x-access-token:ghp_test123@ghe.corp.com/my-org/vibe-registry.git",
+    );
+  });
+
+  test("hostname is derived from GHE serverUrl", () => {
+    expect((adapter as any).hostname).toBe("ghe.corp.com");
+  });
+});
+
+describe("GitHubAdapter — GHE with custom port", () => {
+  const adapter = createAdapter({
+    apiUrl: "https://ghe.corp.com:8443/api/v3",
+    serverUrl: "https://ghe.corp.com:8443",
+  });
+
+  test("hostname does not include port", () => {
+    expect((adapter as any).hostname).toBe("ghe.corp.com");
+  });
+});

package/src/config.ts

@@ -0,0 +1,72 @@
+export type Environment = "dev" | "staging" | "prod";
+export type StorageProviderType = "azure-blob" | "s3" | "gcs";
+export type GitPlatformType = "github" | "azure-devops" | "gitlab";
+
+export interface PublishConfig {
+  environment: Environment;
+  directPush: boolean;
+
+  // Storage
+  storageProvider: StorageProviderType;
+  azureAccountName?: string;
+  azureAccountKey?: string;
+  azureContainerName?: string;
+
+  // Git platform
+  gitPlatform: GitPlatformType;
+  registryRepo?: string;
+  registryToken?: string;
+
+  // GitHub host URLs (for GitHub Enterprise Server support)
+  githubApiUrl: string;
+  githubServerUrl: string;
+
+  // Publisher identity
+  publishedBy: string;
+}
+
+export function loadConfig(overrides: Partial<PublishConfig> = {}): PublishConfig {
+  const env = (overrides.environment ??
+    process.env.VIBE_ENVIRONMENT ??
+    "dev") as Environment;
+
+  return {
+    environment: env,
+    directPush:
+      overrides.directPush ?? process.env.VIBE_DIRECT_PUSH === "true",
+
+    storageProvider: (overrides.storageProvider ??
+      process.env.VIBE_STORAGE_PROVIDER ??
+      "azure-blob") as StorageProviderType,
+    azureAccountName:
+      overrides.azureAccountName ?? process.env.VIBE_STORAGE_ACCOUNT_NAME,
+    azureAccountKey:
+      overrides.azureAccountKey ?? process.env.VIBE_STORAGE_ACCOUNT_KEY,
+    azureContainerName:
+      overrides.azureContainerName ?? process.env.VIBE_STORAGE_CONTAINER_NAME,
+
+    gitPlatform: (overrides.gitPlatform ??
+      process.env.VIBE_GIT_PLATFORM ??
+      "github") as GitPlatformType,
+    registryRepo: overrides.registryRepo ?? process.env.VIBE_REGISTRY_REPO,
+    registryToken: overrides.registryToken ?? process.env.VIBE_REGISTRY_TOKEN,
+
+    githubApiUrl:
+      overrides.githubApiUrl ??
+      (process.env.VIBE_GITHUB_API_URL || undefined) ??
+      (process.env.GITHUB_API_URL || undefined) ??
+      "https://api.github.com",
+
+    githubServerUrl:
+      overrides.githubServerUrl ??
+      (process.env.VIBE_GITHUB_SERVER_URL || undefined) ??
+      (process.env.GITHUB_SERVER_URL || undefined) ??
+      "https://github.com",
+
+    publishedBy:
+      overrides.publishedBy ??
+      process.env.GITHUB_ACTOR ??
+      process.env.USER ??
+      "unknown",
+  };
+}

package/src/git-platform/azure-devops.ts

@@ -0,0 +1,39 @@
+import type { GitPlatformAdapter } from "./interface.js";
+
+/**
+ * Azure DevOps Git adapter — stub.
+ *
+ * To implement: use the Azure DevOps REST API or `az repos` CLI
+ * for clone, push, and PR creation.
+ */
+export class AzureDevOpsAdapter implements GitPlatformAdapter {
+  constructor(_config: { organization: string; project: string; repo: string; token: string }) {
+    throw new Error(
+      "AzureDevOpsAdapter is not yet implemented. See azure-devops.ts for notes.",
+    );
+  }
+
+  cloneRegistry(_targetDir: string): Promise<string> {
+    throw new Error("Not implemented");
+  }
+
+  createPullRequest(_opts: {
+    repoDir: string;
+    branchName: string;
+    title: string;
+    body: string;
+    baseBranch: string;
+    filesToAdd: string[];
+  }): Promise<{ url: string; number: number }> {
+    throw new Error("Not implemented");
+  }
+
+  pushDirectly(_opts: {
+    repoDir: string;
+    branchName: string;
+    commitMessage: string;
+    filesToAdd: string[];
+  }): Promise<void> {
+    throw new Error("Not implemented");
+  }
+}

package/src/git-platform/github.ts

@@ -0,0 +1,129 @@
+import { execFileSync } from "node:child_process";
+import type { GitPlatformAdapter } from "./interface.js";
+
+export interface GitHubConfig {
+  registryRepo: string; // "org/vibe-registry"
+  token: string;
+  apiUrl: string; // e.g. "https://api.github.com" or "https://ghe.corp.com/api/v3"
+  serverUrl: string; // e.g. "https://github.com" or "https://ghe.corp.com"
+}
+
+export class GitHubAdapter implements GitPlatformAdapter {
+  private repo: string;
+  private token: string;
+  private apiUrl: string;
+  private serverUrl: string;
+  private hostname: string;
+
+  constructor(config: GitHubConfig) {
+    this.repo = config.registryRepo;
+    this.token = config.token;
+    this.apiUrl = config.apiUrl;
+    this.serverUrl = config.serverUrl;
+    this.hostname = new URL(config.serverUrl).hostname;
+  }
+
+  private cloneUrl(): string {
+    return `https://x-access-token:${this.token}@${this.hostname}/${this.repo}.git`;
+  }
+
+  private redact(text: string): string {
+    return this.token ? text.replaceAll(this.token, "***") : text;
+  }
+
+  private git(args: string[], cwd: string): string {
+    try {
+      return execFileSync("git", args, {
+        cwd,
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"],
+      }).trim();
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      throw new Error(this.redact(msg));
+    }
+  }
+
+  async cloneRegistry(targetDir: string): Promise<string> {
+    try {
+      execFileSync(
+        "git",
+        ["clone", "--depth", "1", this.cloneUrl(), targetDir],
+        { stdio: ["pipe", "pipe", "pipe"] },
+      );
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      throw new Error(this.redact(msg));
+    }
+    this.git(["config", "user.name", "vibe-publish[bot]"], targetDir);
+    this.git(
+      ["config", "user.email", `vibe-publish[bot]@users.noreply.${this.hostname}`],
+      targetDir,
+    );
+    return targetDir;
+  }
+
+  async createPullRequest(opts: {
+    repoDir: string;
+    branchName: string;
+    title: string;
+    body: string;
+    baseBranch: string;
+    filesToAdd: string[];
+  }): Promise<{ url: string; number: number }> {
+    const { repoDir, branchName, title, body, baseBranch, filesToAdd } = opts;
+
+    this.git(["checkout", "-b", branchName], repoDir);
+
+    for (const file of filesToAdd) {
+      this.git(["add", file], repoDir);
+    }
+
+    this.git(["commit", "-m", title], repoDir);
+    this.git(["push", "origin", branchName], repoDir);
+
+    // Create PR via GitHub API
+    const apiUrl = `${this.apiUrl}/repos/${this.repo}/pulls`;
+    const response = await fetch(apiUrl, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${this.token}`,
+        Accept: "application/vnd.github+json",
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        title,
+        body,
+        head: branchName,
+        base: baseBranch,
+      }),
+    });
+
+    if (!response.ok) {
+      const text = await response.text();
+      throw new Error(`Failed to create PR: ${response.status} ${text}`);
+    }
+
+    const pr = (await response.json()) as {
+      html_url: string;
+      number: number;
+    };
+    return { url: pr.html_url, number: pr.number };
+  }
+
+  async pushDirectly(opts: {
+    repoDir: string;
+    branchName: string;
+    commitMessage: string;
+    filesToAdd: string[];
+  }): Promise<void> {
+    const { repoDir, branchName, commitMessage, filesToAdd } = opts;
+
+    for (const file of filesToAdd) {
+      this.git(["add", file], repoDir);
+    }
+
+    this.git(["commit", "-m", commitMessage], repoDir);
+    this.git(["push", "origin", branchName], repoDir);
+  }
+}

package/src/git-platform/gitlab.ts

@@ -0,0 +1,38 @@
+import type { GitPlatformAdapter } from "./interface.js";
+
+/**
+ * GitLab adapter — stub.
+ *
+ * To implement: use the GitLab REST API for clone, push, and MR creation.
+ */
+export class GitLabAdapter implements GitPlatformAdapter {
+  constructor(_config: { host: string; project: string; token: string }) {
+    throw new Error(
+      "GitLabAdapter is not yet implemented. See gitlab.ts for notes.",
+    );
+  }
+
+  cloneRegistry(_targetDir: string): Promise<string> {
+    throw new Error("Not implemented");
+  }
+
+  createPullRequest(_opts: {
+    repoDir: string;
+    branchName: string;
+    title: string;
+    body: string;
+    baseBranch: string;
+    filesToAdd: string[];
+  }): Promise<{ url: string; number: number }> {
+    throw new Error("Not implemented");
+  }
+
+  pushDirectly(_opts: {
+    repoDir: string;
+    branchName: string;
+    commitMessage: string;
+    filesToAdd: string[];
+  }): Promise<void> {
+    throw new Error("Not implemented");
+  }
+}

package/src/git-platform/index.ts

@@ -0,0 +1,37 @@
+import type { GitPlatformAdapter } from "./interface.js";
+import { GitHubAdapter } from "./github.js";
+import type { PublishConfig } from "../config.js";
+
+export type { GitPlatformAdapter } from "./interface.js";
+
+export function resolveGitPlatform(config: PublishConfig): GitPlatformAdapter {
+  switch (config.gitPlatform) {
+    case "github":
+      if (!config.registryRepo || !config.registryToken) {
+        throw new Error(
+          "GitHub requires VIBE_REGISTRY_REPO and VIBE_REGISTRY_TOKEN",
+        );
+      }
+      return new GitHubAdapter({
+        registryRepo: config.registryRepo,
+        token: config.registryToken,
+        apiUrl: config.githubApiUrl,
+        serverUrl: config.githubServerUrl,
+      });
+
+    case "azure-devops":
+      throw new Error(
+        'Azure DevOps adapter is not yet implemented. Set VIBE_GIT_PLATFORM="github" or implement AzureDevOpsAdapter.',
+      );
+
+    case "gitlab":
+      throw new Error(
+        'GitLab adapter is not yet implemented. Set VIBE_GIT_PLATFORM="github" or implement GitLabAdapter.',
+      );
+
+    default:
+      throw new Error(
+        `Unknown git platform: "${config.gitPlatform}". Supported: github, azure-devops, gitlab`,
+      );
+  }
+}

package/src/git-platform/interface.ts

@@ -0,0 +1,23 @@
+/** Adapter for interacting with a Git hosting platform. */
+export interface GitPlatformAdapter {
+  /** Clone the registry repo into a local directory. Returns the path. */
+  cloneRegistry(targetDir: string): Promise<string>;
+
+  /** Create a pull request with the given changes. */
+  createPullRequest(opts: {
+    repoDir: string;
+    branchName: string;
+    title: string;
+    body: string;
+    baseBranch: string;
+    filesToAdd: string[];
+  }): Promise<{ url: string; number: number }>;
+
+  /** Push changes directly (no PR). Used for dev environment. */
+  pushDirectly(opts: {
+    repoDir: string;
+    branchName: string;
+    commitMessage: string;
+    filesToAdd: string[];
+  }): Promise<void>;
+}

package/src/index.ts

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+/**
+ * @aiworkbench/vibe-publish
+ *
+ * CLI to publish a mini-app bundle to blob storage and update the registry.
+ *
+ * Usage:
+ *   vibe-publish --environment dev [--direct-push]
+ *
+ * Configuration is loaded from VIBE_* environment variables.
+ * See config.ts for the full list.
+ */
+import { parseArgs } from "node:util";
+import { loadConfig, type Environment } from "./config.js";
+import { publish } from "./publish.js";
+
+async function main() {
+  const { values } = parseArgs({
+    options: {
+      environment: { type: "string", short: "e" },
+      "direct-push": { type: "boolean", default: false },
+      "app-dir": { type: "string", default: "." },
+      help: { type: "boolean", short: "h" },
+    },
+  });
+
+  if (values.help) {
+    console.log(`
+Usage: vibe-publish [options]
+
+Options:
+  -e, --environment <env>  Target environment: dev, staging, prod (default: dev)
+  --direct-push            Push directly to main instead of opening a PR
+  --app-dir <path>         Path to the mini-app directory (default: .)
+  -h, --help               Show this help
+    `.trim());
+    process.exit(0);
+  }
+
+  const config = loadConfig({
+    environment: values.environment as Environment | undefined,
+    directPush: values["direct-push"] || undefined,
+  });
+
+  const appDir = values["app-dir"] ?? process.cwd();
+
+  try {
+    const result = await publish(appDir, config);
+    console.log(`\nDone. ${result.entry.id} v${result.entry.version} published.`);
+  } catch (err) {
+    console.error(`\nPublish failed: ${(err as Error).message}`);
+    process.exit(1);
+  }
+}
+
+main();

package/src/integrity.ts

@@ -0,0 +1,10 @@
+import { createHash } from "node:crypto";
+
+/**
+ * Compute an SRI integrity hash (sha384) for a buffer.
+ * Returns a string like "sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K…"
+ */
+export function computeIntegrity(content: Buffer): string {
+  const hash = createHash("sha384").update(content).digest("base64");
+  return `sha384-${hash}`;
+}

package/src/publish.ts

@@ -0,0 +1,108 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import type { VibeManifest, RegistryEntry } from "@aiworkbench/vibe-types";
+import type { PublishConfig } from "./config.js";
+import { computeIntegrity } from "./integrity.js";
+import { resolveStorageProvider } from "./storage/index.js";
+import { resolveGitPlatform } from "./git-platform/index.js";
+import { updateRegistry } from "./registry.js";
+
+export interface PublishResult {
+  entry: RegistryEntry;
+  registryMethod: "push" | "pr";
+  prUrl?: string;
+}
+
+/**
+ * Main publish orchestrator.
+ *
+ * 1. Read manifest.json + dist/index.js from the mini-app directory
+ * 2. Compute SRI integrity hash
+ * 3. Check immutability — reject if version already in storage
+ * 4. Upload bundle to blob storage
+ * 5. Build RegistryEntry
+ * 6. Update registry (push or PR)
+ */
+export async function publish(
+  appDir: string,
+  config: PublishConfig,
+): Promise<PublishResult> {
+  // 1. Read manifest and bundle
+  const manifestPath = resolve(appDir, "manifest.json");
+  const bundlePath = resolve(appDir, "dist/index.js");
+
+  let manifest: VibeManifest;
+  try {
+    manifest = JSON.parse(readFileSync(manifestPath, "utf-8")) as VibeManifest;
+  } catch {
+    throw new Error(`Cannot read manifest.json at ${manifestPath}`);
+  }
+
+  let bundleContent: Buffer;
+  try {
+    bundleContent = readFileSync(bundlePath) as unknown as Buffer;
+  } catch {
+    throw new Error(
+      `Cannot read dist/index.js at ${bundlePath}. Did you run "bun run build"?`,
+    );
+  }
+
+  const { id, version } = manifest;
+  console.log(`Publishing ${id} v${version} → ${config.environment}`);
+
+  // 2. Compute integrity
+  const integrity = computeIntegrity(bundleContent);
+
+  // 3. Resolve storage + check immutability
+  const storage = resolveStorageProvider(config);
+  const alreadyExists = await storage.exists(id, version, "index.js");
+  if (alreadyExists) {
+    throw new Error(
+      `Immutability violation: ${id}/${version}/index.js already exists in storage. ` +
+        `Bump the version in manifest.json to publish a new release.`,
+    );
+  }
+
+  // 4. Upload bundle
+  console.log(`Uploading ${id}/${version}/index.js…`);
+  const { url: bundleUrl, sizeBytes } = await storage.upload(
+    id,
+    version,
+    "index.js",
+    bundleContent,
+    "application/javascript",
+  );
+  console.log(`Uploaded: ${bundleUrl} (${sizeBytes} bytes)`);
+
+  // 5. Build registry entry
+  const entry: RegistryEntry = {
+    ...manifest,
+    bundleUrl,
+    integrity,
+    bundleSizeBytes: sizeBytes,
+    publishedAt: new Date().toISOString(),
+    publishedBy: config.publishedBy,
+  };
+
+  // 6. Update registry
+  console.log(`Updating registry (${config.environment})…`);
+  const git = resolveGitPlatform(config);
+  const result = await updateRegistry({
+    entry,
+    environment: config.environment,
+    directPush: config.directPush,
+    git,
+  });
+
+  if (result.method === "pr") {
+    console.log(`PR created: ${result.url}`);
+  } else {
+    console.log(`Pushed directly to main`);
+  }
+
+  return {
+    entry,
+    registryMethod: result.method,
+    prUrl: result.url,
+  };
+}

package/src/registry.ts

@@ -0,0 +1,83 @@
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { randomBytes } from "node:crypto";
+import type { RegistryEntry } from "@aiworkbench/vibe-types";
+import type { GitPlatformAdapter } from "./git-platform/interface.js";
+import type { Environment } from "./config.js";
+
+/**
+ * Upsert a registry entry into the target environment's apps.json.
+ *
+ * - If `directPush` is true, pushes directly to main (used for dev).
+ * - Otherwise, creates a PR (used for staging/prod).
+ */
+export async function updateRegistry(opts: {
+  entry: RegistryEntry;
+  environment: Environment;
+  directPush: boolean;
+  git: GitPlatformAdapter;
+}): Promise<{ method: "push" | "pr"; url?: string }> {
+  const { entry, environment, directPush, git } = opts;
+
+  // Clone registry to temp dir
+  const tmpBase = join(tmpdir(), `vibe-registry-${randomBytes(4).toString("hex")}`);
+  mkdirSync(tmpBase, { recursive: true });
+  const repoDir = await git.cloneRegistry(tmpBase);
+
+  // Read existing apps.json
+  const appsFile = join(repoDir, environment, "apps.json");
+  let apps: RegistryEntry[];
+  try {
+    apps = JSON.parse(readFileSync(appsFile, "utf-8")) as RegistryEntry[];
+  } catch {
+    apps = [];
+  }
+
+  // Upsert: replace same app id, or append
+  const existingIdx = apps.findIndex((a) => a.id === entry.id);
+  if (existingIdx !== -1) {
+    apps[existingIdx] = entry;
+  } else {
+    apps.push(entry);
+  }
+
+  // Sort by id for deterministic output
+  apps.sort((a, b) => a.id.localeCompare(b.id));
+
+  // Write back
+  writeFileSync(appsFile, JSON.stringify(apps, null, 2) + "\n");
+
+  const relPath = `${environment}/apps.json`;
+
+  if (directPush) {
+    await git.pushDirectly({
+      repoDir,
+      branchName: "main",
+      commitMessage: `publish: ${entry.id} v${entry.version} → ${environment}`,
+      filesToAdd: [relPath],
+    });
+    return { method: "push" };
+  }
+
+  const branchName = `publish/${environment}/${entry.id}-${entry.version}`;
+  const pr = await git.createPullRequest({
+    repoDir,
+    branchName,
+    title: `publish: ${entry.id} v${entry.version} → ${environment}`,
+    body: [
+      `## Publish ${entry.id} v${entry.version}`,
+      "",
+      `| Field | Value |`,
+      `|---|---|`,
+      `| **Environment** | ${environment} |`,
+      `| **Bundle URL** | ${entry.bundleUrl} |`,
+      `| **Integrity** | \`${entry.integrity.slice(0, 20)}…\` |`,
+      `| **Published by** | ${entry.publishedBy} |`,
+    ].join("\n"),
+    baseBranch: "main",
+    filesToAdd: [relPath],
+  });
+
+  return { method: "pr", url: pr.url };
+}

package/src/storage/azure-blob.ts

@@ -0,0 +1,72 @@
+import {
+  BlobServiceClient,
+  StorageSharedKeyCredential,
+} from "@azure/storage-blob";
+import type { StorageProvider } from "./interface.js";
+
+export interface AzureBlobConfig {
+  accountName: string;
+  accountKey: string;
+  containerName: string;
+}
+
+export class AzureBlobProvider implements StorageProvider {
+  private client: BlobServiceClient;
+  private containerName: string;
+  private accountName: string;
+
+  constructor(config: AzureBlobConfig) {
+    this.accountName = config.accountName;
+    this.containerName = config.containerName;
+
+    const credential = new StorageSharedKeyCredential(
+      config.accountName,
+      config.accountKey,
+    );
+    this.client = new BlobServiceClient(
+      `https://${config.accountName}.blob.core.windows.net`,
+      credential,
+    );
+  }
+
+  getUrl(appId: string, version: string, filename: string): string {
+    return `https://${this.accountName}.blob.core.windows.net/${this.containerName}/${appId}/${version}/${filename}`;
+  }
+
+  async exists(
+    appId: string,
+    version: string,
+    filename: string,
+  ): Promise<boolean> {
+    const container = this.client.getContainerClient(this.containerName);
+    const blob = container.getBlockBlobClient(
+      `${appId}/${version}/${filename}`,
+    );
+    return blob.exists();
+  }
+
+  async upload(
+    appId: string,
+    version: string,
+    filename: string,
+    content: Buffer,
+    contentType: string,
+  ): Promise<{ url: string; sizeBytes: number }> {
+    const container = this.client.getContainerClient(this.containerName);
+    const blob = container.getBlockBlobClient(
+      `${appId}/${version}/${filename}`,
+    );
+
+    await blob.upload(content, content.length, {
+      blobHTTPHeaders: {
+        blobContentType: contentType,
+        blobCacheControl: "public, max-age=31536000, immutable",
+      },
+    });
+
+    return {
+      url: this.getUrl(appId, version, filename),
+      sizeBytes: content.length,
+    };
+  }
+}

package/src/storage/gcs.ts

@@ -0,0 +1,37 @@
+import type { StorageProvider } from "./interface.js";
+
+/**
+ * Google Cloud Storage provider — stub.
+ *
+ * To implement: install `@google-cloud/storage` and fill in
+ * upload / exists / getUrl using the GCS SDK.
+ */
+export class GCSProvider implements StorageProvider {
+  constructor(_config: { bucket: string; projectId: string }) {
+    throw new Error(
+      "GCSProvider is not yet implemented. See gcs.ts for notes.",
+    );
+  }
+
+  getUrl(_appId: string, _version: string, _filename: string): string {
+    throw new Error("Not implemented");
+  }
+
+  exists(
+    _appId: string,
+    _version: string,
+    _filename: string,
+  ): Promise<boolean> {
+    throw new Error("Not implemented");
+  }
+
+  upload(
+    _appId: string,
+    _version: string,
+    _filename: string,
+    _content: Buffer,
+    _contentType: string,
+  ): Promise<{ url: string; sizeBytes: number }> {
+    throw new Error("Not implemented");
+  }
+}

package/src/storage/index.ts

@@ -0,0 +1,40 @@
+import type { StorageProvider } from "./interface.js";
+import { AzureBlobProvider } from "./azure-blob.js";
+import type { PublishConfig } from "../config.js";
+
+export type { StorageProvider } from "./interface.js";
+
+export function resolveStorageProvider(config: PublishConfig): StorageProvider {
+  switch (config.storageProvider) {
+    case "azure-blob":
+      if (
+        !config.azureAccountName ||
+        !config.azureAccountKey ||
+        !config.azureContainerName
+      ) {
+        throw new Error(
+          "Azure Blob requires VIBE_STORAGE_ACCOUNT_NAME, VIBE_STORAGE_ACCOUNT_KEY, and VIBE_STORAGE_CONTAINER_NAME",
+        );
+      }
+      return new AzureBlobProvider({
+        accountName: config.azureAccountName,
+        accountKey: config.azureAccountKey,
+        containerName: config.azureContainerName,
+      });
+
+    case "s3":
+      throw new Error(
+        'S3 provider is not yet implemented. Set VIBE_STORAGE_PROVIDER="azure-blob" or implement S3Provider.',
+      );
+
+    case "gcs":
+      throw new Error(
+        'GCS provider is not yet implemented. Set VIBE_STORAGE_PROVIDER="azure-blob" or implement GCSProvider.',
+      );
+
+    default:
+      throw new Error(
+        `Unknown storage provider: "${config.storageProvider}". Supported: azure-blob, s3, gcs`,
+      );
+  }
+}

package/src/storage/interface.ts

@@ -0,0 +1,17 @@
+/** Storage provider for uploading mini-app bundles. */
+export interface StorageProvider {
+  /** Upload a file to storage. Returns the public URL and size. */
+  upload(
+    appId: string,
+    version: string,
+    filename: string,
+    content: Buffer,
+    contentType: string,
+  ): Promise<{ url: string; sizeBytes: number }>;
+
+  /** Check whether a file already exists in storage. */
+  exists(appId: string, version: string, filename: string): Promise<boolean>;
+
+  /** Get the public URL for a file (does not check existence). */
+  getUrl(appId: string, version: string, filename: string): string;
+}

package/src/storage/s3.ts

@@ -0,0 +1,35 @@
+import type { StorageProvider } from "./interface.js";
+
+/**
+ * AWS S3 storage provider — stub.
+ *
+ * To implement: install `@aws-sdk/client-s3` and fill in
+ * upload / exists / getUrl using the S3 SDK.
+ */
+export class S3Provider implements StorageProvider {
+  constructor(_config: { bucket: string; region: string }) {
+    throw new Error("S3Provider is not yet implemented. See s3.ts for notes.");
+  }
+
+  getUrl(_appId: string, _version: string, _filename: string): string {
+    throw new Error("Not implemented");
+  }
+
+  exists(
+    _appId: string,
+    _version: string,
+    _filename: string,
+  ): Promise<boolean> {
+    throw new Error("Not implemented");
+  }
+
+  upload(
+    _appId: string,
+    _version: string,
+    _filename: string,
+    _content: Buffer,
+    _contentType: string,
+  ): Promise<{ url: string; sizeBytes: number }> {
+    throw new Error("Not implemented");
+  }
+}