@mondaydotcomorg/z2h-cli 0.10.1 → 0.11.0

package/src/index.ts

@@ -1,19 +1,22 @@
 import { createRequire } from 'node:module';
-import { readFileSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { Command } from 'commander';
 import { execa } from 'execa';
+import { getWorkspaceHome } from './util/workspace';
 import { devCommand } from './commands/dev';
 import { buildCommand } from './commands/build';
 import { cleanCommand } from './commands/clean';
 import { deployCommand } from './commands/deploy';
+import { grantCommand, revokeCommand, transferOwnerCommand } from './commands/grant';
 import { createWorkspaceCommand } from './commands/create-workspace';
 import { createCommand, CreateOptions } from './commands/create';
 import { generateZ2HTokenCommand } from './commands/generate-z2h-token';
 import { migrateCommand } from './commands/migrate';
+import { editCommand } from './commands/edit';
 import { errorLog, fail, getOutputMode } from './util/logger';
 import { trackDuration } from './util/tracker';
+import { getCwdAppName } from './util/app-name';
 
 const { version } = createRequire(import.meta.url)('../package.json') as { version: string };
 
@@ -30,15 +33,17 @@ function selfUpdate(): void {
   }
 }
 
-function getCwdAppName(): string | undefined {
-  try {
-    return (JSON.parse(readFileSync('package.json', 'utf8')) as { name?: string }).name;
-  } catch {
-    return undefined;
+const CONFLICTING_ENV_VARS = ['AWS_PROFILE'];
+
+function stripConflictingEnvVars(): void {
+  for (const name of CONFLICTING_ENV_VARS) {
+    delete process.env[name];
   }
 }
 
 async function main(): Promise<void> {
+  stripConflictingEnvVars();
+
   const program = new Command();
   program
     .name('z2h-cli')
@@ -96,14 +101,26 @@ async function main(): Promise<void> {
 
   program
     .command('deploy')
-    .description('Build, upload artifacts to S3, and update the Z2H manifest')
+    .description('Build, upload to S3, and register the app with the Z2H backend')
     .option('--dry-run', 'print what would happen without uploading anything')
     .option('--json', 'emit structured JSON on stdout')
-    .action(async (opts: { dryRun?: boolean; json?: boolean }) => {
+    .option(
+      '--remote <type>',
+      'First deploy only: source control remote to initialise — s3 (shared storage) or github (your repo). Error if the app already has a git remote.'
+    )
+    .option(
+      '--repo-url <url>',
+      'First deploy only: GitHub repo URL — required when --remote=github. Error if the app already has a git remote.'
+    )
+    .action(async (opts: { dryRun?: boolean; json?: boolean; remote?: string; repoUrl?: string }) => {
       try {
-        await trackDuration('z2h_app_deploy_success', () => deployCommand(opts), {
-          app_name: getCwdAppName(),
-        });
+        await trackDuration(
+          'z2h_app_deploy_success',
+          () => deployCommand(opts as Parameters<typeof deployCommand>[0]),
+          {
+            app_name: getCwdAppName(),
+          }
+        );
       } catch (err) {
         await fail(`deploy failed: ${(err as Error).message}`, { command: 'deploy' }, 2);
       }
@@ -111,7 +128,7 @@ async function main(): Promise<void> {
 
   program
     .command('create-workspace')
-    .description('Bootstrap the ~/zth-projects/ yarn workspace (one-time setup)')
+    .description(`Bootstrap the ${getWorkspaceHome()}/ yarn workspace (one-time setup)`)
     .option('--json', 'emit structured JSON on stdout')
     .action(async (opts: { json?: boolean }) => {
       try {
@@ -139,7 +156,7 @@ async function main(): Promise<void> {
 
   program
     .command('create <app-name>')
-    .description('Scaffold a new Z2H consumer app inside ~/zth-projects/')
+    .description(`Scaffold a new Z2H consumer app inside ${getWorkspaceHome()}/`)
     .option('--template <name>', 'Template name (default | html-embed)')
     .option('--html-file <path>', 'Path to an HTML file to embed (implies --template html-embed)')
     .option('--remote <type>', 'Source control remote: s3 (shared storage) or github (your repo)')
@@ -162,6 +179,59 @@ async function main(): Promise<void> {
       }
     );
 
+  program
+    .command('edit <app-name>')
+    .description(`Pull the latest version of an app into ${getWorkspaceHome()}/<app-name>, cloning it first if needed`)
+    .option('--json', 'emit structured JSON on stdout')
+    .action(async (appName: string, opts: { json?: boolean }) => {
+      try {
+        await trackDuration('z2h_app_edit_pulled', () => editCommand(appName, opts), {
+          app_name: appName,
+        });
+      } catch (err) {
+        await fail(`edit failed: ${(err as Error).message}`, { command: 'edit' }, 1);
+      }
+    });
+
+  program
+    .command('grant [email]')
+    .description('Grant access to the current app (email, --public, or both)')
+    .option('--public', 'make the app visible to all monday.com employees')
+    .option('--level <level>', 'access level for user grants: owner, editor, or viewer (default: viewer)')
+    .option('--json', 'emit structured JSON on stdout')
+    .action(async (email: string | undefined, opts: { public?: boolean; level?: string; json?: boolean }) => {
+      try {
+        await grantCommand(email, opts as Parameters<typeof grantCommand>[1]);
+      } catch (err) {
+        await fail(`grant failed: ${(err as Error).message}`, { command: 'grant' }, 1);
+      }
+    });
+
+  program
+    .command('revoke [email]')
+    .description('Revoke access to the current app (email or --public; owners/admins only)')
+    .option('--public', 'remove the public grant, making the app visible to owners/admins only')
+    .option('--json', 'emit structured JSON on stdout')
+    .action(async (email: string | undefined, opts: { public?: boolean; json?: boolean }) => {
+      try {
+        await revokeCommand(email, opts as Parameters<typeof revokeCommand>[1]);
+      } catch (err) {
+        await fail(`revoke failed: ${(err as Error).message}`, { command: 'revoke' }, 1);
+      }
+    });
+
+  program
+    .command('transfer-owner [email]')
+    .description('Transfer ownership of the current app to another monday.com user')
+    .option('--json', 'emit structured JSON on stdout')
+    .action(async (email: string | undefined, opts: { json?: boolean }) => {
+      try {
+        await transferOwnerCommand(email, opts);
+      } catch (err) {
+        await fail(`transfer-owner failed: ${(err as Error).message}`, { command: 'transfer-owner' }, 1);
+      }
+    });
+
   program
     .command('migrate')
     .description('Run pending workspace migrations')

package/src/shadow/prepare.ts

@@ -10,8 +10,8 @@ import { isPortFree, pickPort } from './port';
 import { syncShadow } from './sync';
 import type { ConsumerPaths, ConsumerPkg, PreparedShadow, ShadowMetadata } from '../types';
 
-export async function prepareShadow(): Promise<PreparedShadow> {
-  const paths = resolveConsumerPaths(process.cwd());
+export async function prepareShadow(consumerDir: string = process.cwd()): Promise<PreparedShadow> {
+  const paths = resolveConsumerPaths(consumerDir);
 
   if (!(await pathExists(paths.consumerPkg))) {
     throw new Error(`No package.json found in ${paths.consumerDir}`);

package/src/templates/app/CLAUDE.md

@@ -45,6 +45,21 @@ When a request needs data, follow `z2h:coding-standards-mf` §0: write a `runQue
 
 ---
 
+## App Visibility
+
+Apps are **private by default** — only you can view them. After the first deploy the `z2h:feature-development` skill automatically asks whether to open it up:
+
+> "Should this app be visible to everyone at monday.com, or just you for now?"
+
+To change visibility at any time:
+
+```
+npx z2h-cli grant --public   # open to all monday.com employees
+npx z2h-cli revoke --public  # back to private
+```
+
+---
+
 ## ⛔ No Agent Visual Testing
 
 When you make a change, **do not screenshot, do not run `axcli chrome`, do not run `playwright-cli`, do not open browser tabs**. The user is sitting in front of the live preview and verifies with their own eyes — HMR updates instantly. Edit → tell the user → wait for their approval. Agent-side visual checks have proven slow and unreliable in this flow.

package/src/util/app-name.ts

@@ -1,3 +1,5 @@
+import { readFileSync } from 'node:fs';
+
 /**
  * Strip any npm scope (`@scope/`) from a package name.
  * e.g. `@trident/customer-viewer` → `customer-viewer`, `foo` → `foo`.
@@ -6,6 +8,14 @@ export function cleanAppName(name: string): string {
   return name.replace(/^@[^/]+\//, '');
 }
 
+export function getCwdAppName(): string | undefined {
+  try {
+    return (JSON.parse(readFileSync('package.json', 'utf8')) as { name?: string }).name;
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * Canonical MF bundle name: the de-scoped app name with an `mf-` prefix.
  * This matches the trident convention (shadow pkg is `@trident/mf-<app>`,

package/src/util/auth/__tests__/broker-credential-provider.test.ts

@@ -1,5 +1,10 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { brokerCredentialProvider, STS_BROKER_PATH } from '../broker-credential-provider';
+import {
+  brokerCredentialProvider,
+  fetchDeployVersion,
+  DEPLOY_VERSION_PATH,
+  STS_BROKER_PATH,
+} from '../broker-credential-provider';
 import { DEFAULT_BROKER_BASE_URL } from '../../../constants';
 import * as authStore from '../auth-store';
 
@@ -32,8 +37,35 @@ function mockFetchOnce(body: unknown, init: { status?: number; text?: string } =
   return fetchMock;
 }
 
+describe('fetchDeployVersion', () => {
+  it('POSTs the appName to the version endpoint and returns the version', async () => {
+    const fetchMock = mockFetchOnce({ version: 4 });
+
+    const version = await fetchDeployVersion('my-app');
+
+    expect(version).toBe(4);
+    expect(fetchMock).toHaveBeenCalledWith(
+      `${DEFAULT_BROKER_BASE_URL}${DEPLOY_VERSION_PATH}`,
+      expect.objectContaining({
+        method: 'POST',
+        body: JSON.stringify({ appName: 'my-app' }),
+      })
+    );
+  });
+
+  it('returns 0 when the broker returns no version field (new app)', async () => {
+    mockFetchOnce({});
+    await expect(fetchDeployVersion('my-app')).resolves.toBe(0);
+  });
+
+  it('surfaces a remediation hint on 401', async () => {
+    mockFetchOnce({}, { status: 401, text: 'Unauthorized' });
+    await expect(fetchDeployVersion('my-app')).rejects.toThrow(/token rejected by the broker/);
+  });
+});
+
 describe('brokerCredentialProvider', () => {
-  it('POSTs the appName to the broker with a Bearer token + parses the response', async () => {
+  it('POSTs the appName + version to the broker with a Bearer token + parses the response', async () => {
     const fetchMock = mockFetchOnce({ ...STUB_CREDS, expiration: FAR_FUTURE_EXPIRY });
     const provider = brokerCredentialProvider({ appName: 'my-app' });
     const creds = await provider();

package/src/util/auth/broker-credential-provider.ts

@@ -1,51 +1,78 @@
-import { brokerBaseUrl } from '../../constants';
+import { brokerBaseUrl, routingHeaders } from '../../constants';
 import { readZthAuth } from './auth-store';
 import type { AwsCredentialIdentity, AwsCredentialIdentityProvider } from '@aws-sdk/types';
 
 export const STS_BROKER_PATH = '/z2h-cli/sts/credentials';
+export const DEPLOY_VERSION_PATH = '/z2h-cli/apps/version';
 
 // Refresh the cached credentials this many ms before they expire so the next
 // AWS API call doesn't race the broker round-trip against a hard expiry.
 const REFRESH_BUFFER_MS = 5 * 60 * 1000;
 
-interface BrokerResponse {
+interface CredentialsResponse {
   accessKeyId?: string;
   secretAccessKey?: string;
   sessionToken?: string;
   expiration?: string;
 }
 
-async function fetchCredentialsOnce(appName: string): Promise<AwsCredentialIdentity> {
-  const { token } = await readZthAuth();
-  const url = `${brokerBaseUrl()}${STS_BROKER_PATH}`;
+interface VersionResponse {
+  version?: number;
+}
 
-  let res: Response;
+async function postToBroker(path: string, body: unknown): Promise<Response> {
+  const { token } = await readZthAuth();
   try {
-    res = await fetch(url, {
+    return await fetch(`${brokerBaseUrl()}${path}`, {
       method: 'POST',
       headers: {
         Authorization: `Bearer ${token}`,
         'Content-Type': 'application/json',
         Accept: 'application/json',
+        ...routingHeaders(),
       },
-      body: JSON.stringify({ appName }),
+      body: JSON.stringify(body),
     });
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     throw new Error(`Z2H deploy broker request failed: ${message}`);
   }
+}
 
+function assertBrokerOk(res: Response): void {
   if (res.status === 401 || res.status === 403) {
     throw new Error(
       `Z2H deploy token rejected by the broker (${res.status}). Refresh user token by running 'z2h-cli generate-z2h-token'.`
     );
   }
+}
+
+/**
+ * Reserve the version this deploy will write to. Split out of the STS
+ * credentials call so version derivation lives on its own endpoint — the CLI
+ * asks for the version first, then requests credentials scoped to it.
+ */
+export async function fetchDeployVersion(appName: string): Promise<number> {
+  const res = await postToBroker(DEPLOY_VERSION_PATH, { appName });
+  assertBrokerOk(res);
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`Z2H deploy broker returned ${res.status}: ${text.slice(0, 1024)}`);
+  }
+  const body = (await res.json()) as VersionResponse;
+
+  return body.version ?? 0;
+}
+
+async function fetchStsOnce(appName: string): Promise<AwsCredentialIdentity> {
+  const res = await postToBroker(STS_BROKER_PATH, { appName });
+  assertBrokerOk(res);
   if (!res.ok) {
     const text = await res.text();
     throw new Error(`Z2H deploy broker returned ${res.status}: ${text.slice(0, 1024)}`);
   }
 
-  const body = (await res.json()) as BrokerResponse;
+  const body = (await res.json()) as CredentialsResponse;
   if (!body.accessKeyId || !body.secretAccessKey || !body.sessionToken || !body.expiration) {
     throw new Error('Z2H deploy broker response missing required credential fields');
   }
@@ -60,8 +87,9 @@ async function fetchCredentialsOnce(appName: string): Promise<AwsCredentialIdent
 
 /**
  * AWS SDK credential provider that fetches short-lived deploy credentials
- * from the bigbrain-zth STS broker. Credentials are cached in memory until
- * 5 minutes before expiry; concurrent calls share a single in-flight fetch.
+ * from the bigbrain-zth STS broker for a specific version. Credentials are
+ * cached in memory until 5 minutes before expiry; concurrent calls share a
+ * single in-flight fetch.
  */
 export function brokerCredentialProvider({ appName }: { appName: string }): AwsCredentialIdentityProvider {
   let cached: AwsCredentialIdentity | undefined;
@@ -76,10 +104,10 @@ export function brokerCredentialProvider({ appName }: { appName: string }): AwsC
       return inflight;
     }
 
-    inflight = fetchCredentialsOnce(appName)
-      .then(creds => {
-        cached = creds;
-        return creds;
+    inflight = fetchStsOnce(appName)
+      .then(credentials => {
+        cached = credentials;
+        return credentials;
       })
       .finally(() => {
         inflight = undefined;

package/src/util/broker/app.ts

@@ -0,0 +1,34 @@
+import { brokerBaseUrl, routingHeaders } from '../../constants';
+import { readZthAuth } from '../auth/auth-store';
+
+export interface AppInfo {
+  appName: string;
+  version: number;
+  entry: Record<string, unknown>;
+  deployedBy: string;
+  gitRemote: string;
+  createdBy: string;
+}
+
+/**
+ * Fetches a single app's current state from the broker.
+ * Returns null if the app has never been deployed (404).
+ */
+export async function fetchApp(appName: string): Promise<AppInfo | null> {
+  const { token } = await readZthAuth();
+  const res = await fetch(`${brokerBaseUrl()}/z2h-cli/apps/${encodeURIComponent(appName)}`, {
+    headers: {
+      Authorization: `Bearer ${token}`,
+      Accept: 'application/json',
+      ...routingHeaders(),
+    },
+  });
+  if (res.status === 404) {
+    return null;
+  }
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`Z2H app lookup failed (${res.status}): ${text.slice(0, 512)}`);
+  }
+  return res.json() as Promise<AppInfo>;
+}

package/src/util/git/__tests__/repo.test.ts

@@ -8,11 +8,12 @@ import {
   defaultS3Remote,
   initRepo,
   cloneRepo,
+  guardCleanTree,
   safeBackupIfDirty,
   pullAndResolve,
+  pushToRemote,
   remoteHead,
   localHead,
-  commitDetailedAndPush,
 } from '../repo';
 
 vi.mock('execa', () => ({ execa: vi.fn() }));
@@ -22,6 +23,7 @@ vi.mock('fs-extra', () => ({
     readFile: vi.fn(),
     outputFile: vi.fn(),
     pathExists: vi.fn(),
+    ensureDir: vi.fn().mockResolvedValue(undefined),
   },
 }));
 
@@ -50,9 +52,53 @@ describe('defaultS3Remote', () => {
 
 describe('cloneRepo', () => {
   it('calls git clone with correct args', async () => {
-    mockExeca.mockResolvedValueOnce(execaOk());
+    mockExeca.mockResolvedValueOnce(execaOk()); // git clone
+    mockExeca.mockRejectedValueOnce(new Error('no global hooksPath')); // git config --global (no override needed)
+    await cloneRepo('s3://bucket/my-app/git', DIR);
+    expect(mockExeca).toHaveBeenCalledWith(
+      'git',
+      ['clone', 's3://bucket/my-app/git', DIR],
+      expect.objectContaining({})
+    );
+  });
+
+  it('merges supplied env into process.env for git subprocess', async () => {
+    mockExeca.mockResolvedValueOnce(execaOk()); // git clone
+    mockExeca.mockRejectedValueOnce(new Error('no global hooksPath')); // git config --global
+    await cloneRepo('s3://bucket/my-app/git', DIR, { AWS_ACCESS_KEY_ID: 'KEY' });
+    const opts = (mockExeca.mock.calls[0] as unknown as unknown[])[2] as { env: Record<string, string> };
+    expect(opts.env['AWS_ACCESS_KEY_ID']).toBe('KEY');
+  });
+
+  it('overrides global hooks locally when core.hooksPath is set', async () => {
+    mockExeca.mockResolvedValueOnce(execaOk()); // git clone
+    mockExeca.mockResolvedValueOnce(execaOk('/Users/dev/.global-git-hooks')); // git config --global core.hooksPath
+    mockExeca.mockResolvedValueOnce(execaOk()); // git config --local core.hooksPath
     await cloneRepo('s3://bucket/my-app/git', DIR);
-    expect(mockExeca).toHaveBeenCalledWith('git', ['clone', 's3://bucket/my-app/git', DIR]);
+    expect(mockExeca).toHaveBeenCalledWith(
+      'git',
+      ['config', '--local', 'core.hooksPath', '.zth/hooks'],
+      expect.objectContaining({})
+    );
+  });
+});
+
+// ── guardCleanTree ───────────────────────────────────────────────────────────
+
+describe('guardCleanTree', () => {
+  it('resolves when working tree is clean', async () => {
+    mockExeca.mockResolvedValueOnce(execaOk(''));
+    await expect(guardCleanTree(DIR)).resolves.toBeUndefined();
+  });
+
+  it('throws when working tree has uncommitted changes', async () => {
+    mockExeca.mockResolvedValueOnce(execaOk('M src/index.ts'));
+    await expect(guardCleanTree(DIR)).rejects.toThrow('uncommitted changes');
+  });
+
+  it('propagates the error when git status fails (e.g. not a git repo)', async () => {
+    mockExeca.mockRejectedValueOnce(new Error('fatal: not a git repository (or any of the parent directories): .git'));
+    await expect(guardCleanTree(DIR)).rejects.toThrow(/not a git repository/);
   });
 });
 
@@ -132,10 +178,66 @@ describe('pullAndResolve', () => {
     await expect(pullAndResolve(DIR)).resolves.toBeUndefined();
   });
 
-  it('throws GitConflictError on non-fast-forward', async () => {
-    mockExeca.mockRejectedValueOnce(new Error('fatal: Not possible to fast-forward')); // git pull
+  it('throws GitConflictError with structured JSON on non-fast-forward', async () => {
+    mockExeca
+      .mockRejectedValueOnce(new Error('fatal: Not possible to fast-forward')) // git pull
+      .mockResolvedValueOnce(execaOk('')) // safeBackupIfDirty: git status --porcelain (clean)
+      .mockResolvedValueOnce(execaOk()) // gatherConflictInfo: git fetch origin
+      .mockResolvedValueOnce(execaOk('abc local commit')) // git log origin/master..HEAD
+      .mockResolvedValueOnce(execaOk('def remote commit')) // git log HEAD..origin/master
+      .mockResolvedValueOnce(execaOk('src/index.ts')); // git diff --name-only
+
+    const err = await pullAndResolve(DIR).catch(e => e);
+
+    expect(err).toBeInstanceOf(GitConflictError);
+    const info = JSON.parse(err.message);
+    expect(info.localCommits).toEqual(['abc local commit']);
+    expect(info.remoteCommits).toEqual(['def remote commit']);
+    expect(info.conflictingFiles).toEqual(['src/index.ts']);
+  });
+});
+
+// ── pushToRemote ─────────────────────────────────────────────────────────────
+
+describe('pushToRemote', () => {
+  it('pushes to origin master', async () => {
+    mockExeca.mockResolvedValueOnce(execaOk()); // git push -u origin master
+
+    await expect(pushToRemote(DIR)).resolves.toBeUndefined();
+
+    expect(mockExeca).toHaveBeenCalledWith('git', ['push', '-u', 'origin', 'master'], expect.objectContaining({}));
+  });
+
+  it('throws GitConflictError with structured JSON when push is rejected', async () => {
+    mockExeca
+      .mockRejectedValueOnce(new Error('![rejected] master -> master (non-fast-forward)')) // git push
+      .mockResolvedValueOnce(execaOk()) // gatherConflictInfo: git fetch origin
+      .mockResolvedValueOnce(execaOk('abc local')) // git log origin/master..HEAD
+      .mockResolvedValueOnce(execaOk('def remote')) // git log HEAD..origin/master
+      .mockResolvedValueOnce(execaOk('file.ts')); // git diff --name-only
+
+    const err = await pushToRemote(DIR).catch(e => e);
+
+    expect(err).toBeInstanceOf(GitConflictError);
+    const info = JSON.parse(err.message);
+    expect(info.localCommits).toEqual(['abc local']);
+    expect(info.remoteCommits).toEqual(['def remote']);
+    expect(info.conflictingFiles).toEqual(['file.ts']);
+  });
+
+  it('re-throws non-rejection push errors as-is', async () => {
+    mockExeca.mockRejectedValueOnce(new Error('Connection refused'));
 
-    await expect(pullAndResolve(DIR)).rejects.toThrow(GitConflictError);
+    const err = await pushToRemote(DIR).catch(e => e);
+    expect(err).not.toBeInstanceOf(GitConflictError);
+    expect(err.message).toMatch(/Connection refused/);
+  });
+
+  it('passes env to git subprocess', async () => {
+    mockExeca.mockResolvedValueOnce(execaOk());
+    await pushToRemote(DIR, { AWS_ACCESS_KEY_ID: 'KEY' });
+    const opts = (mockExeca.mock.calls[0] as unknown as unknown[])[2] as { env: Record<string, string> };
+    expect(opts.env['AWS_ACCESS_KEY_ID']).toBe('KEY');
   });
 });
 
@@ -161,87 +263,3 @@ describe('localHead', () => {
     expect(await localHead(DIR)).toBe('abc123');
   });
 });
-
-// ── commitDetailedAndPush ────────────────────────────────────────────────────
-
-describe('commitDetailedAndPush', () => {
-  it('throws when not on master branch', async () => {
-    mockExeca.mockResolvedValueOnce(execaOk('feature/oops\n')); // git rev-parse --abbrev-ref HEAD
-
-    await expect(commitDetailedAndPush(DIR, 1)).rejects.toThrow(/expected branch "master"/);
-  });
-
-  it('commits with a version-prefixed message and pushes', async () => {
-    mockExeca
-      .mockResolvedValueOnce(execaOk('master\n')) // git rev-parse --abbrev-ref HEAD
-      .mockResolvedValueOnce(execaOk()) // git add .
-      .mockResolvedValueOnce(execaOk('src/index.ts\nnew-file.ts')) // git diff --cached --name-only
-      .mockResolvedValueOnce(execaOk('M  src/index.ts\nA  new-file.ts')) // git status --short
-      .mockResolvedValueOnce(execaOk()) // git commit
-      .mockResolvedValueOnce(execaOk()); // git push -u origin master
-
-    await commitDetailedAndPush(DIR, 3);
-
-    const commitCall = mockExeca.mock.calls.find(c => c[0] === 'git' && (c[1] as string[])[0] === 'commit');
-    expect(commitCall).toBeDefined();
-    const msg = (commitCall![1] as string[])[2];
-    expect(msg).toMatch(/^v3:/);
-    expect(msg).toContain('src/index.ts');
-
-    const pushCall = mockExeca.mock.calls.find(c => c[0] === 'git' && (c[1] as string[])[0] === 'push');
-    expect(pushCall![1]).toEqual(['push', '-u', 'origin', 'master']);
-  });
-
-  it('throws when there is nothing to commit', async () => {
-    mockExeca
-      .mockResolvedValueOnce(execaOk('master\n')) // git rev-parse --abbrev-ref HEAD
-      .mockResolvedValueOnce(execaOk()) // git add .
-      .mockResolvedValueOnce(execaOk('')); // git diff --cached --name-only (empty)
-
-    await expect(commitDetailedAndPush(DIR, 4)).rejects.toThrow(/Nothing new to deploy/);
-  });
-
-  it('throws GitConflictError when push is rejected', async () => {
-    mockExeca
-      .mockResolvedValueOnce(execaOk('master\n')) // git rev-parse --abbrev-ref HEAD
-      .mockResolvedValueOnce(execaOk()) // git add .
-      .mockResolvedValueOnce(execaOk('src/index.ts')) // git diff --cached --name-only
-      .mockResolvedValueOnce(execaOk(' M src/index.ts')) // git status --short
-      .mockResolvedValueOnce(execaOk()) // git commit
-      .mockRejectedValueOnce(new Error('[rejected]')); // git push -u origin master
-
-    await expect(commitDetailedAndPush(DIR, 4)).rejects.toThrow(GitConflictError);
-  });
-
-  it('re-throws non-rejection push errors as-is', async () => {
-    mockExeca
-      .mockResolvedValueOnce(execaOk('master\n')) // git rev-parse --abbrev-ref HEAD
-      .mockResolvedValueOnce(execaOk()) // git add .
-      .mockResolvedValueOnce(execaOk('src/index.ts')) // git diff --cached --name-only
-      .mockResolvedValueOnce(execaOk(' M src/index.ts')) // git status --short
-      .mockResolvedValueOnce(execaOk()) // git commit
-      .mockRejectedValueOnce(new Error('Connection refused')); // git push — auth/network error
-
-    const err = await commitDetailedAndPush(DIR, 4).catch(e => e);
-    expect(err).not.toBeInstanceOf(GitConflictError);
-    expect(err.message).toMatch(/Connection refused/);
-  });
-
-  it('truncates long file lists to 5 entries', async () => {
-    const manyFiles = Array.from({ length: 8 }, (_, i) => `M  file${i}.ts`).join('\n');
-    const manyNames = Array.from({ length: 8 }, (_, i) => `file${i}.ts`).join('\n');
-    mockExeca
-      .mockResolvedValueOnce(execaOk('master\n')) // git rev-parse --abbrev-ref HEAD
-      .mockResolvedValueOnce(execaOk()) // git add .
-      .mockResolvedValueOnce(execaOk(manyNames)) // git diff --cached --name-only
-      .mockResolvedValueOnce(execaOk(manyFiles)) // git status --short
-      .mockResolvedValueOnce(execaOk()) // git commit
-      .mockResolvedValueOnce(execaOk()); // git push
-
-    await commitDetailedAndPush(DIR, 1);
-
-    const commitCall = mockExeca.mock.calls.find(c => c[0] === 'git' && (c[1] as string[])[0] === 'commit');
-    const msg = (commitCall![1] as string[])[2];
-    expect(msg).toContain('+3 more');
-  });
-});

package/src/util/git/git-env.ts

@@ -0,0 +1,23 @@
+import { brokerCredentialProvider } from '../auth/broker-credential-provider';
+
+/**
+ * Builds the AWS_* environment that `git-remote-s3` needs to talk to an S3-backed
+ * git remote, by minting short-lived broker credentials scoped to the app.
+ *
+ * Returns `undefined` for non-S3 remotes (GitHub apps ride the user's own git
+ * credential helper) and when there is no remote at all.
+ */
+export async function resolveGitEnv(
+  appName: string,
+  gitRemote: string | undefined
+): Promise<Record<string, string> | undefined> {
+  if (!gitRemote?.startsWith('s3://')) {
+    return undefined;
+  }
+  const creds = await brokerCredentialProvider({ appName })();
+  return {
+    AWS_ACCESS_KEY_ID: creds.accessKeyId,
+    AWS_SECRET_ACCESS_KEY: creds.secretAccessKey,
+    AWS_SESSION_TOKEN: creds.sessionToken ?? '',
+  };
+}