@mondaydotcomorg/z2h-cli 0.10.0 → 0.11.0

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 ?? '',
+  };
+}

package/src/util/git/remote-options.ts

@@ -0,0 +1,37 @@
+import { defaultS3Remote } from './repo';
+
+export const REMOTE_TYPES = ['s3', 'github'] as const;
+
+export type RemoteType = (typeof REMOTE_TYPES)[number];
+
+export interface RemoteOptions {
+  remote?: RemoteType;
+  repoUrl?: string;
+}
+
+/**
+ * Validates --remote and --repo-url option values.
+ * Pass `requireRemote: true` when the flag is mandatory (e.g. create).
+ */
+export function validateRemoteOptions(opts: RemoteOptions, requireRemote = false): void {
+  if (!opts.remote) {
+    if (requireRemote) {
+      throw new Error(`--remote is required. Use --remote=s3 (shared storage) or --remote=github (your GitHub repo).`);
+    }
+    return;
+  }
+  if (!(REMOTE_TYPES as readonly string[]).includes(opts.remote)) {
+    throw new Error(`Unknown remote "${opts.remote}". Use ${REMOTE_TYPES.join(' or ')}.`);
+  }
+  if (opts.remote === 'github' && !opts.repoUrl) {
+    throw new Error('--repo-url is required when using --remote=github.');
+  }
+}
+
+/**
+ * Resolves the git remote URL from --remote / --repo-url options.
+ * Call after validateRemoteOptions.
+ */
+export function resolveRemoteUrl(remote: RemoteType, appName: string, repoUrl?: string): string {
+  return remote === 's3' ? defaultS3Remote(appName) : (repoUrl as string);
+}

package/src/util/git/repo.ts

@@ -4,6 +4,18 @@ import { execa } from 'execa';
 import { BUCKET_WRITE_NAME } from '../../constants';
 import { mfAppName } from '../app-name';
 
+type GitEnv = Record<string, string | undefined>;
+
+function execGit(args: string[], dir: string, env?: GitEnv) {
+  return execa('git', args, { cwd: dir, env });
+}
+
+async function execGitLines(args: string[], dir: string, env?: GitEnv): Promise<string[]> {
+  return execGit(args, dir, env)
+    .then(r => r.stdout.split('\n').filter(Boolean))
+    .catch(() => []);
+}
+
 export class GitConflictError extends Error {
   constructor(message: string) {
     super(message);
@@ -11,7 +23,14 @@ export class GitConflictError extends Error {
   }
 }
 
+export interface ConflictInfo {
+  localCommits: string[];
+  remoteCommits: string[];
+  conflictingFiles: string[];
+}
+
 const REQUIRED_GITIGNORE_ENTRIES = ['node_modules/', '.zth/', 'build/'];
+const LOCAL_HOOKS_DIR = '.zth/hooks';
 
 export function defaultS3Remote(app: string): string {
   return `s3://${BUCKET_WRITE_NAME}/${mfAppName(app)}/git`;
@@ -19,26 +38,40 @@ export function defaultS3Remote(app: string): string {
 
 export async function initRepo(dir: string, remote: string): Promise<void> {
   await ensureGitignore(dir);
-  await execa('git', ['init', '-b', 'master'], { cwd: dir });
-  await execa('git', ['add', '.'], { cwd: dir });
-  await execa('git', ['commit', '-m', 'Initial commit'], { cwd: dir });
-  await execa('git', ['remote', 'add', 'origin', remote], { cwd: dir });
+  await execGit(['init', '-b', 'master'], dir);
+  await overrideGlobalHooks(dir);
+  await execGit(['add', '.'], dir);
+  await execGit(['commit', '-m', 'Initial commit'], dir);
+  await execGit(['remote', 'add', 'origin', remote], dir);
 }
 
 export async function getRemoteUrl(dir: string): Promise<string | undefined> {
-  return execa('git', ['remote', 'get-url', 'origin'], { cwd: dir })
+  return execGit(['remote', 'get-url', 'origin'], dir)
     .then(r => r.stdout.trim() || undefined)
     .catch(() => undefined);
 }
 
-export async function cloneRepo(remote: string, dir: string): Promise<void> {
-  await execa('git', ['clone', remote, dir]);
+/**
+ * Throws if the working tree has uncommitted changes. Call only on a known git
+ * repo (e.g. guarded by a resolved remote) — a failing `git status` propagates
+ * rather than being silently treated as "clean".
+ */
+export async function guardCleanTree(dir: string): Promise<void> {
+  const { stdout } = await execGit(['status', '--porcelain'], dir);
+  if (stdout.trim()) {
+    throw new Error('You have uncommitted changes — commit your changes before deploying.');
+  }
+}
+
+export async function cloneRepo(remote: string, dir: string, env: Record<string, string> = {}): Promise<void> {
+  await execa('git', ['clone', remote, dir], { env: { ...process.env, ...env } });
+  await overrideGlobalHooks(dir);
 }
 
 export async function safeBackupIfDirty(dir: string): Promise<void> {
   let status: string;
   try {
-    ({ stdout: status } = await execa('git', ['status', '--porcelain'], { cwd: dir }));
+    ({ stdout: status } = await execGit(['status', '--porcelain'], dir));
   } catch {
     return;
   }
@@ -51,19 +84,55 @@ export async function safeBackupIfDirty(dir: string): Promise<void> {
   await fs.copy(dir, backupDir, { overwrite: false });
 }
 
-export async function pullAndResolve(dir: string): Promise<void> {
+export async function pullAndResolve(dir: string, env?: Record<string, string>): Promise<void> {
+  const gitEnv = env ? { ...process.env, ...env } : undefined;
   try {
-    await execa('git', ['pull', '--ff-only'], { cwd: dir });
-  } catch {
-    // TODO(Phase 7): safeBackupIfDirty(dir) → resolveDivergence(dir) instead of throwing
-    throw new GitConflictError(
-      'This app changed while you were working — please re-open it to get the latest version.'
-    );
+    await execGit(['pull', '--ff-only'], dir, gitEnv);
+  } catch (err) {
+    // First deploy: remote exists but has no commits yet — not a conflict.
+    const e = err as Error & { stderr?: string };
+    const msg = `${e.message ?? ''} ${e.stderr ?? ''}`;
+    if (/couldn't find remote ref|no tracking information|does not appear to be a git repository/i.test(msg)) {
+      return;
+    }
+    await safeBackupIfDirty(dir);
+    const info = await gatherConflictInfo(dir, gitEnv);
+    throw new GitConflictError(JSON.stringify(info));
+  }
+}
+
+/**
+ * Pushes the local master branch to origin. On a rejected (non-fast-forward) push —
+ * i.e. a deploy landed while we were building — gathers structured conflict info and
+ * throws GitConflictError so the deploy stops before anything goes live (spec: push
+ * must stop the deploy before the bundle upload). The skill re-resolves and re-runs,
+ * which rebuilds against the latest. Non-conflict push errors re-throw as-is.
+ */
+export async function pushToRemote(dir: string, env?: Record<string, string>): Promise<void> {
+  const gitEnv = env ? { ...process.env, ...env } : undefined;
+  try {
+    await execGit(['push', '-u', 'origin', 'master'], dir, gitEnv);
+  } catch (err) {
+    // execa puts the command in message but stderr in a separate field.
+    const e = err as Error & { stderr?: string };
+    const msg = `${e.message ?? ''} ${e.stderr ?? ''}`;
+    const isRejected = /\[rejected\]|non-fast-forward/.test(msg);
+    // git-remote-s3 emits EPIPE when git closes its stdin after a completed
+    // push (new commits or already-up-to-date). Treat EPIPE without a
+    // rejection marker as success — the push went through.
+    if (/EPIPE/.test(msg) && !isRejected) {
+      return;
+    }
+    if (isRejected) {
+      const info = await gatherConflictInfo(dir, gitEnv);
+      throw new GitConflictError(JSON.stringify(info));
+    }
+    throw err;
   }
 }
 
 export async function remoteHead(dir: string): Promise<string> {
-  const { stdout } = await execa('git', ['ls-remote', 'origin', 'refs/heads/master'], { cwd: dir });
+  const { stdout } = await execGit(['ls-remote', 'origin', 'refs/heads/master'], dir);
   const sha = stdout.split('\t')[0]?.trim();
   if (!sha) {
     throw new Error('could not read remote head — is the remote reachable?');
@@ -72,43 +141,48 @@ export async function remoteHead(dir: string): Promise<string> {
 }
 
 export async function localHead(dir: string): Promise<string> {
-  const { stdout } = await execa('git', ['rev-parse', 'HEAD'], { cwd: dir });
+  const { stdout } = await execGit(['rev-parse', 'HEAD'], dir);
   return stdout.trim();
 }
 
-export async function commitDetailedAndPush(dir: string, version: number): Promise<void> {
-  const { stdout: branch } = await execa('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd: dir });
-  if (branch.trim() !== 'master') {
-    throw new Error(`expected branch "master" but you are on "${branch.trim()}" — switch back before deploying.`);
-  }
-  await execa('git', ['add', '.'], { cwd: dir });
-  const { stdout: staged } = await execa('git', ['diff', '--cached', '--name-only'], { cwd: dir });
-  if (!staged.trim()) {
-    throw new Error('Nothing new to deploy — no files have changed since the last deploy.');
+async function gatherConflictInfo(dir: string, gitEnv?: GitEnv): Promise<ConflictInfo> {
+  await execGit(['fetch', 'origin'], dir, gitEnv).catch(() => {});
+
+  const [localCommits, remoteCommits, conflictingFiles] = await Promise.all([
+    execGitLines(['log', 'origin/master..HEAD', '--oneline'], dir, gitEnv),
+    execGitLines(['log', 'HEAD..origin/master', '--oneline'], dir, gitEnv),
+    execGitLines(['diff', '--name-only', 'HEAD', 'origin/master'], dir, gitEnv),
+  ]);
+
+  return { localCommits, remoteCommits, conflictingFiles };
+}
+
+/**
+ * If the user has a global core.hooksPath (e.g. ~/.global-git-hooks with a
+ * prevent-push-to-master script), override it locally so Z2H's non-interactive
+ * pushes aren't blocked. Other repos on the machine stay protected.
+ */
+async function overrideGlobalHooks(dir: string): Promise<void> {
+  if (await fs.pathExists(path.join(dir, LOCAL_HOOKS_DIR))) {
+    return;
   }
-  const message = await buildCommitMessage(dir, version);
-  await execa('git', ['commit', '-m', message], { cwd: dir });
-  try {
-    await execa('git', ['push', '-u', 'origin', 'master'], { cwd: dir });
-  } catch (err) {
-    if (/\[rejected\]|non-fast-forward/.test((err as Error).message)) {
-      throw new GitConflictError('push rejected — remote has new commits');
-    }
-    throw err;
+
+  const globalHooksPath = await execGit(['config', '--global', 'core.hooksPath'], dir)
+    .then(r => r.stdout.trim())
+    .catch(() => '');
+
+  if (!globalHooksPath) {
+    return;
   }
-}
 
-async function buildCommitMessage(dir: string, version: number): Promise<string> {
-  // TODO(Phase 7): replace with LLM-generated summary using git diff + commit messages
-  const { stdout } = await execa('git', ['status', '--short'], { cwd: dir });
-  const files = stdout
-    .split('\n')
-    .map(line => line.slice(3).trim())
-    .filter(Boolean);
-  const fileList = files.length
-    ? files.slice(0, 5).join(', ') + (files.length > 5 ? ` (+${files.length - 5} more)` : '')
-    : 'no changes';
-  return `v${version}: deploy — ${fileList}`;
+  await fs.ensureDir(path.join(dir, LOCAL_HOOKS_DIR));
+  await execGit(['config', '--local', 'core.hooksPath', LOCAL_HOOKS_DIR], dir);
+
+  // eslint-disable-next-line no-console
+  console.warn(
+    `⚠️  Detected global git hooks at ${globalHooksPath}\n` +
+      `   Overriding locally for this Z2H project (your other repos are unaffected).`
+  );
 }
 
 async function ensureGitignore(dir: string): Promise<void> {

package/src/util/machine-identity.ts

@@ -0,0 +1,10 @@
+/**
+ * Returns the machine app name when running as a service (e.g. agent-runner).
+ * Available when the process is a monday.com microservice with `APP_NAME` set
+ * by the platform runtime.
+ *
+ * Returns `undefined` for interactive human users (fallback to os.userInfo).
+ */
+export function getMachineAppName(): string | undefined {
+  return process.env.APP_NAME || undefined;
+}

package/src/util/s3/client.ts

@@ -1,23 +1,16 @@
 import { S3Client } from '@aws-sdk/client-s3';
-import { brokerCredentialProvider } from '../auth/broker-credential-provider';
 import { REGION } from '../../constants';
+import type { AwsCredentialIdentity } from '@aws-sdk/types';
 
 let client: S3Client | null = null;
 
-/**
- * Initialize the per-process S3 client with broker-issued credentials scoped
- * to the given app's S3 prefix. Must be called once before any `getS3Client`.
- */
-export function setupS3Client({ appName }: { appName: string }): void {
-  client = new S3Client({
-    region: REGION,
-    credentials: brokerCredentialProvider({ appName }),
-  });
+export function setupS3Client(credentials: AwsCredentialIdentity): void {
+  client = new S3Client({ region: REGION, credentials });
 }
 
 export function getS3Client(): S3Client {
   if (!client) {
-    throw new Error('S3 client not initialized — call setupS3Client({ appName }) first.');
+    throw new Error('S3 client not initialized — call setupS3Client(credentials) first.');
   }
   return client;
 }