@mondaydotcomorg/z2h-cli 0.10.0 → 0.11.0

package/dist/esm/index.mjs

@@ -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.mjs';
 import { devCommand } from './commands/dev.mjs';
 import { buildCommand } from './commands/build.mjs';
 import { cleanCommand } from './commands/clean.mjs';
 import { deployCommand } from './commands/deploy.mjs';
+import { grantCommand, revokeCommand, transferOwnerCommand } from './commands/grant.mjs';
 import { createWorkspaceCommand } from './commands/create-workspace.mjs';
 import { createCommand } from './commands/create.mjs';
 import { generateZ2HTokenCommand } from './commands/generate-z2h-token.mjs';
 import { migrateCommand } from './commands/migrate.mjs';
+import { editCommand } from './commands/edit.mjs';
 import { fail, errorLog, getOutputMode } from './util/logger.mjs';
 import { trackDuration } from './util/tracker.mjs';
+import { getCwdAppName } from './util/app-name.mjs';
 
 const { version } = createRequire(import.meta.url)('../package.json');
 const UPDATE_SCRIPT = path.join(os.homedir(), 'Development', 'bigbrain-z2h', 'z2h', 'setup', 'update.sh');
@@ -28,15 +31,14 @@ function selfUpdate() {
         errorLog(`Z2H auto-update failed to start: ${err.message}`);
     }
 }
-function getCwdAppName() {
-    try {
-        return JSON.parse(readFileSync('package.json', 'utf8')).name;
-    }
-    catch {
-        return undefined;
+const CONFLICTING_ENV_VARS = ['AWS_PROFILE'];
+function stripConflictingEnvVars() {
+    for (const name of CONFLICTING_ENV_VARS) {
+        delete process.env[name];
     }
 }
 async function main() {
+    stripConflictingEnvVars();
     const program = new Command();
     program
         .name('z2h-cli')
@@ -91,9 +93,11 @@ async function main() {
     });
     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')
+        .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) => {
         try {
             await trackDuration('z2h_app_deploy_success', () => deployCommand(opts), {
@@ -106,7 +110,7 @@ async function main() {
     });
     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) => {
         try {
@@ -132,7 +136,7 @@ async function main() {
     });
     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)')
@@ -150,6 +154,59 @@ async function main() {
             await fail(`create failed: ${err.message}`, { command: 'create' }, 1);
         }
     });
+    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, opts) => {
+        try {
+            await trackDuration('z2h_app_edit_pulled', () => editCommand(appName, opts), {
+                app_name: appName,
+            });
+        }
+        catch (err) {
+            await fail(`edit failed: ${err.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, opts) => {
+        try {
+            await grantCommand(email, opts);
+        }
+        catch (err) {
+            await fail(`grant failed: ${err.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, opts) => {
+        try {
+            await revokeCommand(email, opts);
+        }
+        catch (err) {
+            await fail(`revoke failed: ${err.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, opts) => {
+        try {
+            await transferOwnerCommand(email, opts);
+        }
+        catch (err) {
+            await fail(`transfer-owner failed: ${err.message}`, { command: 'transfer-owner' }, 1);
+        }
+    });
     program
         .command('migrate')
         .description('Run pending workspace migrations')

package/dist/esm/shadow/prepare.d.ts

@@ -1,3 +1,3 @@
 import type { PreparedShadow } from '../types';
-export declare function prepareShadow(): Promise<PreparedShadow>;
+export declare function prepareShadow(consumerDir?: string): Promise<PreparedShadow>;
 //# sourceMappingURL=prepare.d.ts.map

package/dist/esm/shadow/prepare.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prepare.d.ts","sourceRoot":"","sources":["../../../src/shadow/prepare.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAA8B,cAAc,EAAkB,MAAM,UAAU,CAAC;AAE3F,wBAAsB,aAAa,IAAI,OAAO,CAAC,cAAc,CAAC,CAgC7D"}
+{"version":3,"file":"prepare.d.ts","sourceRoot":"","sources":["../../../src/shadow/prepare.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAA8B,cAAc,EAAkB,MAAM,UAAU,CAAC;AAE3F,wBAAsB,aAAa,CAAC,WAAW,GAAE,MAAsB,GAAG,OAAO,CAAC,cAAc,CAAC,CAgChG"}

package/dist/esm/shadow/prepare.mjs

@@ -9,8 +9,8 @@ import { readMetadata, writeMetadata } from './metadata.mjs';
 import { isPortFree, pickPort } from './port.mjs';
 import { syncShadow } from './sync.mjs';
 
-async function prepareShadow() {
-    const paths = resolveConsumerPaths(process.cwd());
+async function prepareShadow(consumerDir = process.cwd()) {
+    const paths = resolveConsumerPaths(consumerDir);
     if (!(await pathExists(paths.consumerPkg))) {
         throw new Error(`No package.json found in ${paths.consumerDir}`);
     }

package/dist/esm/util/app-name.d.ts

@@ -3,6 +3,7 @@
  * e.g. `@trident/customer-viewer` → `customer-viewer`, `foo` → `foo`.
  */
 export declare function cleanAppName(name: string): string;
+export declare function getCwdAppName(): string | 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/dist/esm/util/app-name.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app-name.d.ts","sourceRoot":"","sources":["../../../src/util/app-name.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9C"}
+{"version":3,"file":"app-name.d.ts","sourceRoot":"","sources":["../../../src/util/app-name.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED,wBAAgB,aAAa,IAAI,MAAM,GAAG,SAAS,CAMlD;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9C"}

package/dist/esm/util/app-name.mjs

@@ -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`.
@@ -5,6 +7,14 @@
 function cleanAppName(name) {
     return name.replace(/^@[^/]+\//, '');
 }
+function getCwdAppName() {
+    try {
+        return JSON.parse(readFileSync('package.json', 'utf8')).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>`,
@@ -14,4 +24,4 @@ function mfAppName(name) {
     return `mf-${cleanAppName(name)}`;
 }
 
-export { cleanAppName, mfAppName };
+export { cleanAppName, getCwdAppName, mfAppName };

package/dist/esm/util/auth/auth-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth-store.d.ts","sourceRoot":"","sources":["../../../../src/util/auth/auth-store.ts"],"names":[],"mappings":"AAOA,eAAO,MAAM,YAAY,QAAkC,CAAC;AAC5D,eAAO,MAAM,aAAa,QAAuC,CAAC;AAElE,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,qBAAa,mBAAoB,SAAQ,KAAK;aAChB,YAAY,EAAE,MAAM;gBAApB,YAAY,EAAE,MAAM;CAIjD;AAED,wBAAsB,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC,CASpD;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,GAAG,IAAI,CAOpD"}
+{"version":3,"file":"auth-store.d.ts","sourceRoot":"","sources":["../../../../src/util/auth/auth-store.ts"],"names":[],"mappings":"AAOA,eAAO,MAAM,YAAY,QAAkC,CAAC;AAC5D,eAAO,MAAM,aAAa,QAAuC,CAAC;AAElE,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,qBAAa,mBAAoB,SAAQ,KAAK;aAChB,YAAY,EAAE,MAAM;gBAApB,YAAY,EAAE,MAAM;CAIjD;AAED,wBAAsB,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC,CAkBpD;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,GAAG,IAAI,CAUpD"}

package/dist/esm/util/auth/auth-store.mjs

@@ -16,6 +16,13 @@ class Z2hAuthMissingError extends Error {
     }
 }
 async function readZthAuth() {
+    if (process.env.Z2H_AUTH_TOKEN) {
+        const token = process.env.Z2H_AUTH_TOKEN;
+        if (!/^[\w-]+\.[\w-]+\.[\w-]+$/.test(token)) {
+            throw new Error('Z2H_AUTH_TOKEN is not a valid JWT (expected three dot-separated segments). Please re-set the environment variable.');
+        }
+        return { token };
+    }
     if (!(await pathExists(Z2H_AUTH_FILE))) {
         throw new Z2hAuthMissingError(Z2H_AUTH_FILE);
     }
@@ -35,6 +42,9 @@ async function readZthAuth() {
  * blow up — and where an inline sync read keeps the spawn call site simple.
  */
 function tryReadAuthTokenSync() {
+    if (process.env.Z2H_AUTH_TOKEN) {
+        return process.env.Z2H_AUTH_TOKEN;
+    }
     try {
         const parsed = readJsonSync(Z2H_AUTH_FILE);
         return parsed?.token ?? null;

package/dist/esm/util/auth/broker-credential-provider.d.ts

@@ -1,9 +1,17 @@
 import type { AwsCredentialIdentityProvider } from '@aws-sdk/types';
 export declare const STS_BROKER_PATH = "/z2h-cli/sts/credentials";
+export declare const DEPLOY_VERSION_PATH = "/z2h-cli/apps/version";
+/**
+ * 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 declare function fetchDeployVersion(appName: string): Promise<number>;
 /**
  * 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 declare function brokerCredentialProvider({ appName }: {
     appName: string;

package/dist/esm/util/auth/broker-credential-provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"broker-credential-provider.d.ts","sourceRoot":"","sources":["../../../../src/util/auth/broker-credential-provider.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAyB,6BAA6B,EAAE,MAAM,gBAAgB,CAAC;AAE3F,eAAO,MAAM,eAAe,6BAA6B,CAAC;AAwD1D;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,EAAE,OAAO,EAAE,EAAE;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,6BAA6B,CAuBxG"}
+{"version":3,"file":"broker-credential-provider.d.ts","sourceRoot":"","sources":["../../../../src/util/auth/broker-credential-provider.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAyB,6BAA6B,EAAE,MAAM,gBAAgB,CAAC;AAE3F,eAAO,MAAM,eAAe,6BAA6B,CAAC;AAC1D,eAAO,MAAM,mBAAmB,0BAA0B,CAAC;AA4C3D;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAUzE;AAuBD;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,EAAE,OAAO,EAAE,EAAE;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,6BAA6B,CAuBxG"}

package/dist/esm/util/auth/broker-credential-provider.mjs

@@ -1,32 +1,53 @@
-import { brokerBaseUrl } from '../../constants.mjs';
+import { brokerBaseUrl, routingHeaders } from '../../constants.mjs';
 import { readZthAuth } from './auth-store.mjs';
 
 const STS_BROKER_PATH = '/z2h-cli/sts/credentials';
+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;
-async function fetchCredentialsOnce(appName) {
+async function postToBroker(path, body) {
     const { token } = await readZthAuth();
-    const url = `${brokerBaseUrl()}${STS_BROKER_PATH}`;
-    let res;
     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) {
     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.
+ */
+async function fetchDeployVersion(appName) {
+    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());
+    return body.version ?? 0;
+}
+async function fetchStsOnce(appName) {
+    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)}`);
@@ -44,8 +65,9 @@ async function fetchCredentialsOnce(appName) {
 }
 /**
  * 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.
  */
 function brokerCredentialProvider({ appName }) {
     let cached;
@@ -58,10 +80,10 @@ function brokerCredentialProvider({ appName }) {
         if (inflight) {
             return inflight;
         }
-        inflight = fetchCredentialsOnce(appName)
-            .then(creds => {
-            cached = creds;
-            return creds;
+        inflight = fetchStsOnce(appName)
+            .then(credentials => {
+            cached = credentials;
+            return credentials;
         })
             .finally(() => {
             inflight = undefined;
@@ -70,4 +92,4 @@ function brokerCredentialProvider({ appName }) {
     };
 }
 
-export { STS_BROKER_PATH, brokerCredentialProvider };
+export { DEPLOY_VERSION_PATH, STS_BROKER_PATH, brokerCredentialProvider, fetchDeployVersion };

package/dist/esm/util/broker/app.d.ts

@@ -0,0 +1,14 @@
+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 declare function fetchApp(appName: string): Promise<AppInfo | null>;
+//# sourceMappingURL=app.d.ts.map

package/dist/esm/util/broker/app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../../../src/util/broker/app.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,OAAO;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAiBvE"}

package/dist/esm/util/broker/app.mjs

@@ -0,0 +1,27 @@
+import { brokerBaseUrl, routingHeaders } from '../../constants.mjs';
+import { readZthAuth } from '../auth/auth-store.mjs';
+
+/**
+ * Fetches a single app's current state from the broker.
+ * Returns null if the app has never been deployed (404).
+ */
+async function fetchApp(appName) {
+    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();
+}
+
+export { fetchApp };

package/dist/esm/util/git/git-env.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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 declare function resolveGitEnv(appName: string, gitRemote: string | undefined): Promise<Record<string, string> | undefined>;
+//# sourceMappingURL=git-env.d.ts.map

package/dist/esm/util/git/git-env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-env.d.ts","sourceRoot":"","sources":["../../../../src/util/git/git-env.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAAG,SAAS,GAC5B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC,CAU7C"}

package/dist/esm/util/git/git-env.mjs

@@ -0,0 +1,22 @@
+import { brokerCredentialProvider } from '../auth/broker-credential-provider.mjs';
+
+/**
+ * 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.
+ */
+async function resolveGitEnv(appName, gitRemote) {
+    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 ?? '',
+    };
+}
+
+export { resolveGitEnv };

package/dist/esm/util/git/remote-options.d.ts

@@ -0,0 +1,17 @@
+export declare const REMOTE_TYPES: readonly ["s3", "github"];
+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 declare function validateRemoteOptions(opts: RemoteOptions, requireRemote?: boolean): void;
+/**
+ * Resolves the git remote URL from --remote / --repo-url options.
+ * Call after validateRemoteOptions.
+ */
+export declare function resolveRemoteUrl(remote: RemoteType, appName: string, repoUrl?: string): string;
+//# sourceMappingURL=remote-options.d.ts.map

package/dist/esm/util/git/remote-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-options.d.ts","sourceRoot":"","sources":["../../../../src/util/git/remote-options.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,YAAY,2BAA4B,CAAC;AAEtD,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvD,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,aAAa,EAAE,aAAa,UAAQ,GAAG,IAAI,CAatF;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAE9F"}

package/dist/esm/util/git/remote-options.mjs

@@ -0,0 +1,30 @@
+import { defaultS3Remote } from './repo.mjs';
+
+const REMOTE_TYPES = ['s3', 'github'];
+/**
+ * Validates --remote and --repo-url option values.
+ * Pass `requireRemote: true` when the flag is mandatory (e.g. create).
+ */
+function validateRemoteOptions(opts, requireRemote = false) {
+    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.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.
+ */
+function resolveRemoteUrl(remote, appName, repoUrl) {
+    return remote === 's3' ? defaultS3Remote(appName) : repoUrl;
+}
+
+export { REMOTE_TYPES, resolveRemoteUrl, validateRemoteOptions };

package/dist/esm/util/git/repo.d.ts

@@ -1,13 +1,31 @@
 export declare class GitConflictError extends Error {
     constructor(message: string);
 }
+export interface ConflictInfo {
+    localCommits: string[];
+    remoteCommits: string[];
+    conflictingFiles: string[];
+}
 export declare function defaultS3Remote(app: string): string;
 export declare function initRepo(dir: string, remote: string): Promise<void>;
 export declare function getRemoteUrl(dir: string): Promise<string | undefined>;
-export declare function cloneRepo(remote: string, dir: string): Promise<void>;
+/**
+ * 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 declare function guardCleanTree(dir: string): Promise<void>;
+export declare function cloneRepo(remote: string, dir: string, env?: Record<string, string>): Promise<void>;
 export declare function safeBackupIfDirty(dir: string): Promise<void>;
-export declare function pullAndResolve(dir: string): Promise<void>;
+export declare function pullAndResolve(dir: string, env?: Record<string, string>): Promise<void>;
+/**
+ * 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 declare function pushToRemote(dir: string, env?: Record<string, string>): Promise<void>;
 export declare function remoteHead(dir: string): Promise<string>;
 export declare function localHead(dir: string): Promise<string>;
-export declare function commitDetailedAndPush(dir: string, version: number): Promise<void>;
 //# sourceMappingURL=repo.d.ts.map

package/dist/esm/util/git/repo.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"repo.d.ts","sourceRoot":"","sources":["../../../../src/util/git/repo.ts"],"names":[],"mappings":"AAMA,qBAAa,gBAAiB,SAAQ,KAAK;gBAC7B,OAAO,EAAE,MAAM;CAI5B;AAID,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,wBAAsB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAMzE;AAED,wBAAsB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAI3E;AAED,wBAAsB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE1E;AAED,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAclE;AAED,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAS/D;AAED,wBAAsB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAO7D;AAED,wBAAsB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAG5D;AAED,wBAAsB,qBAAqB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAoBvF"}
+{"version":3,"file":"repo.d.ts","sourceRoot":"","sources":["../../../../src/util/git/repo.ts"],"names":[],"mappings":"AAkBA,qBAAa,gBAAiB,SAAQ,KAAK;gBAC7B,OAAO,EAAE,MAAM;CAI5B;AAED,MAAM,WAAW,YAAY;IAC3B,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,gBAAgB,EAAE,MAAM,EAAE,CAAC;CAC5B;AAKD,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,wBAAsB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAOzE;AAED,wBAAsB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAI3E;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAK/D;AAED,wBAAsB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAG5G;AAED,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAclE;AAED,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAe7F;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAqB3F;AAED,wBAAsB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAO7D;AAED,wBAAsB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAG5D"}