gitspace 0.2.0-rc.17 → 0.2.0-rc.18

package/.gitspace/{select → scripts/select}/01-status.sh

@@ -3,8 +3,8 @@
 #
 # This runs every time you switch to an existing workspace.
 #
-# Bundle values are available as environment variables using bundle key names.
-# Example: DEVELOPERNAME, EXAMPLEAPITOKEN
+# Bundle values are available using exact keys and uppercase snake-case aliases.
+# Example aliases: DEVELOPER_NAME, EXAMPLE_API_TOKEN
 
 WORKSPACE_NAME=$1
 REPOSITORY=$2
@@ -14,14 +14,14 @@ echo "=== Workspace: $WORKSPACE_NAME ==="
 echo ""
 
 # Show bundle values (proof of concept)
-if [ -n "$DEVELOPERNAME" ]; then
-  echo "Welcome back, $DEVELOPERNAME!"
+if [ -n "$DEVELOPER_NAME" ]; then
+  echo "Welcome back, $DEVELOPER_NAME!"
 fi
 
 # Show that we have access to the secret (masked)
-if [ -n "$EXAMPLEAPITOKEN" ]; then
+if [ -n "$EXAMPLE_API_TOKEN" ]; then
   # Only show first 4 characters to prove we have access
-  TOKEN_PREVIEW="${EXAMPLEAPITOKEN:0:4}..."
+  TOKEN_PREVIEW="${EXAMPLE_API_TOKEN:0:4}..."
   echo "API Token available: $TOKEN_PREVIEW (stored in OS keychain)"
 fi
 

package/README.md

@@ -183,7 +183,7 @@ A bundle is a directory (typically `.gitspace/`) containing:
 Bundle values are passed to scripts as environment variables using the configured bundle keys:
 
 - `<KEY>` - Regular or secret value using the exact `configKey` from `bundle.json`
-- Legacy aliases `SPACE_VALUE_<KEY>` / `SPACE_SECRET_<KEY>` are also provided for compatibility
+- `<NORMALIZED_KEY>` - Uppercase snake-case alias (for example, `teamName` -> `TEAM_NAME`)
 
 **Example script:**
 
@@ -195,12 +195,12 @@ WORKSPACE_NAME=$1
 REPOSITORY=$2
 
 # Access bundle values
-if [ -n "$TEAMNAME" ]; then
-  echo "Welcome, $TEAMNAME team!"
+if [ -n "$TEAM_NAME" ]; then
+  echo "Welcome, $TEAM_NAME team!"
 fi
 
 # Access secrets (stored securely in OS keychain)
-if [ -n "$APIKEY" ]; then
+if [ -n "$API_KEY" ]; then
   echo "API Key configured"
 fi
 ```
@@ -393,9 +393,8 @@ inside each workspace so they can vary by branch:
 export SPACES_CURRENT_PROJECT="my-app"
 
 # Available in scripts (from bundle onboarding):
-# <KEY>                - Value by bundle config key name
-# SPACE_VALUE_<KEY>    - Legacy alias for regular values
-# SPACE_SECRET_<KEY>   - Legacy alias for secret values
+# <KEY>                - Value by exact bundle config key name
+# <NORMALIZED_KEY>     - Uppercase snake-case alias (e.g. teamName -> TEAM_NAME)
 ```
 
 ## Directory Structure

package/bun.lock

@@ -39,10 +39,10 @@
         "typescript": "^5.9.3",
       },
       "optionalDependencies": {
-        "@gitspace/darwin-arm64": "0.2.0-rc.15",
-        "@gitspace/darwin-x64": "0.2.0-rc.15",
-        "@gitspace/linux-arm64": "0.2.0-rc.15",
-        "@gitspace/linux-x64": "0.2.0-rc.15",
+        "@gitspace/darwin-arm64": "0.2.0-rc.17",
+        "@gitspace/darwin-x64": "0.2.0-rc.17",
+        "@gitspace/linux-arm64": "0.2.0-rc.17",
+        "@gitspace/linux-x64": "0.2.0-rc.17",
       },
     },
   },
@@ -63,7 +63,7 @@
 
     "@eslint/js": ["@eslint/js@8.57.1", "", {}, "sha512-d9zaMRSTIKDLhctzH12MtXvJKSSUhaHcjV+2Z+GK+EEY7XKpP5yR4x+N3TAcHTcu963nIr+TMcCb4DBCYX1z6Q=="],
 
-    "@gitspace/darwin-arm64": ["@gitspace/darwin-arm64@0.2.0-rc.15", "", { "os": "darwin", "cpu": "arm64", "bin": { "gssh-darwin-arm64": "bin/gssh" } }, "sha512-gjqsRdz2f7cOOTbj97wmQ4Z0nh7jWUVN4Dxj1N/Ex4fp6dJ8qu2d5izbsCHWVIPX4uN+gK/qqzxuwLwCdaEqlQ=="],
+    "@gitspace/darwin-arm64": ["@gitspace/darwin-arm64@0.2.0-rc.17", "", { "os": "darwin", "cpu": "arm64", "bin": { "gssh-darwin-arm64": "bin/gssh" } }, "sha512-aPei17D31di296UBdqOt59HrdvcIRL2oVGVRWT4etCIESgjTyhZQcCLsIezsWI4E4/9DQAqaLAfTif7TsuCRHQ=="],
 
     "@graphql-typed-document-node/core": ["@graphql-typed-document-node/core@3.2.0", "", { "peerDependencies": { "graphql": "^0.8.0 || ^0.9.0 || ^0.10.0 || ^0.11.0 || ^0.12.0 || ^0.13.0 || ^14.0.0 || ^15.0.0 || ^16.0.0 || ^17.0.0" } }, "sha512-mB9oAsNCm9aM3/SOv4YtBMqZbYj10R7dkq8byBqxGY/ncFwhf2oQzMV+LCRlWoDSEBJ3COiR1yeDvMtsoOsuFQ=="],
 

package/docs/SITE_DOCS_FIGMA_MAKE.md

@@ -377,15 +377,14 @@ Using bundle values in scripts:
 ```bash
 #!/bin/bash
 # Values available as environment variables:
-# <KEY>               - Value by bundle config key name
-# SPACE_VALUE_<KEY>   - Legacy alias for regular values
-# SPACE_SECRET_<KEY>  - Legacy alias for secret values
+# <KEY>               - Value by exact bundle config key name
+# <NORMALIZED_KEY>    - Uppercase snake-case alias (e.g. teamName -> TEAM_NAME)
 
-if [ -n "$TEAMNAME" ]; then
-  echo "Welcome, $TEAMNAME team!"
+if [ -n "$TEAM_NAME" ]; then
+  echo "Welcome, $TEAM_NAME team!"
 fi
 
-if [ -n "$APIKEY" ]; then
+if [ -n "$API_KEY" ]; then
   echo "API Key configured"
 fi
 ```
@@ -960,8 +959,8 @@ Bundles allow teams to share onboarding configurations. Place in `.gitspace/`:
 
 **Using values in scripts:**
 ```bash
-echo "Team: $TEAMNAME"
-echo "Has API key: $APIKEY"
+echo "Team: $TEAM_NAME"
+echo "Has API key: $API_KEY"
 ```
 
 ---

package/landing-page/src/components/docs/DocsContent.tsx

@@ -378,8 +378,8 @@ git status`} />
           </div>
 
           <h3 className="text-xl font-semibold text-white mb-4">Using Values in Scripts</h3>
-          <JsonBlock code={`echo "Team: $TEAMNAME"
-echo "Has API key: $APIKEY"`} />
+          <JsonBlock code={`echo "Team: $TEAM_NAME"
+echo "Has API key: $API_KEY"`} />
         </div>
       );
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitspace",
-  "version": "0.2.0-rc.17",
+  "version": "0.2.0-rc.18",
   "description": "CLI for managing GitHub workspaces with git worktrees and secure remote terminal access",
   "bin": {
     "gssh": "./bin/gssh"
@@ -17,10 +17,10 @@
     "relay": "bun src/relay/index.ts"
   },
   "optionalDependencies": {
-    "@gitspace/darwin-arm64": "0.2.0-rc.17",
-    "@gitspace/darwin-x64": "0.2.0-rc.17",
-    "@gitspace/linux-x64": "0.2.0-rc.17",
-    "@gitspace/linux-arm64": "0.2.0-rc.17"
+    "@gitspace/darwin-arm64": "0.2.0-rc.18",
+    "@gitspace/darwin-x64": "0.2.0-rc.18",
+    "@gitspace/linux-x64": "0.2.0-rc.18",
+    "@gitspace/linux-arm64": "0.2.0-rc.18"
   },
   "keywords": [
     "cli",

package/src/core/__tests__/bundle.test.ts

@@ -0,0 +1,209 @@
+import { describe, expect, it } from 'bun:test';
+import { validateBundle } from '../bundle';
+
+describe('validateBundle', () => {
+  it('allows unique config keys with distinct normalized aliases', () => {
+    expect(() =>
+      validateBundle({
+        version: '1.0',
+        name: 'Valid Bundle',
+        onboarding: [
+          {
+            id: 'env-name',
+            type: 'input',
+            title: 'Environment Name',
+            description: 'Name of environment',
+            configKey: 'vercelEnv',
+          },
+          {
+            id: 'api-token',
+            type: 'secret',
+            title: 'API Token',
+            description: 'Service token',
+            configKey: 'apiToken',
+          },
+        ],
+      })
+    ).not.toThrow();
+  });
+
+  it('throws helpful error when configKey is duplicated across steps', () => {
+    expect(() =>
+      validateBundle({
+        version: '1.0',
+        name: 'Duplicate Key Bundle',
+        onboarding: [
+          {
+            id: 'api-token-input',
+            type: 'input',
+            title: 'API token input',
+            description: 'input',
+            configKey: 'apiToken',
+          },
+          {
+            id: 'api-token-secret',
+            type: 'secret',
+            title: 'API token secret',
+            description: 'secret',
+            configKey: 'apiToken',
+          },
+        ],
+      })
+    ).toThrow(/Bundle configKey collision/);
+  });
+
+  it('throws helpful error when normalized aliases collide', () => {
+    expect(() =>
+      validateBundle({
+        version: '1.0',
+        name: 'Alias Collision Bundle',
+        onboarding: [
+          {
+            id: 'api-token-dash',
+            type: 'input',
+            title: 'API token dash',
+            description: 'dash',
+            configKey: 'api-token',
+          },
+          {
+            id: 'api-token-camel',
+            type: 'secret',
+            title: 'API token camel',
+            description: 'camel',
+            configKey: 'apiToken',
+          },
+        ],
+      })
+    ).toThrow(/Bundle configKey alias collision/);
+
+    expect(() =>
+      validateBundle({
+        version: '1.0',
+        name: 'Alias Collision Bundle',
+        onboarding: [
+          {
+            id: 'api-token-dash',
+            type: 'input',
+            title: 'API token dash',
+            description: 'dash',
+            configKey: 'api-token',
+          },
+          {
+            id: 'api-token-camel',
+            type: 'secret',
+            title: 'API token camel',
+            description: 'camel',
+            configKey: 'apiToken',
+          },
+        ],
+      })
+    ).toThrow(/API_TOKEN/);
+  });
+
+  it('treats acronym boundaries as part of normalized alias collisions', () => {
+    expect(() =>
+      validateBundle({
+        version: '1.0',
+        name: 'Acronym Collision Bundle',
+        onboarding: [
+          {
+            id: 'http-client-acronym',
+            type: 'input',
+            title: 'HTTP client acronym',
+            description: 'acronym',
+            configKey: 'myHTTPClient',
+          },
+          {
+            id: 'http-client-camel',
+            type: 'secret',
+            title: 'HTTP client camel',
+            description: 'camel',
+            configKey: 'myHttpClient',
+          },
+        ],
+      })
+    ).toThrow(/Bundle configKey alias collision/);
+
+    expect(() =>
+      validateBundle({
+        version: '1.0',
+        name: 'Acronym Collision Bundle',
+        onboarding: [
+          {
+            id: 'http-client-acronym',
+            type: 'input',
+            title: 'HTTP client acronym',
+            description: 'acronym',
+            configKey: 'myHTTPClient',
+          },
+          {
+            id: 'http-client-camel',
+            type: 'secret',
+            title: 'HTTP client camel',
+            description: 'camel',
+            configKey: 'myHttpClient',
+          },
+        ],
+      })
+    ).toThrow(/MY_HTTP_CLIENT/);
+  });
+
+  it('throws helpful error when normalized alias is not shell-safe', () => {
+    expect(() =>
+      validateBundle({
+        version: '1.0',
+        name: 'Digit Prefix Bundle',
+        onboarding: [
+          {
+            id: 'two-fa-token',
+            type: 'secret',
+            title: '2FA token',
+            description: '2FA token',
+            configKey: '2faToken',
+          },
+        ],
+      })
+    ).toThrow(/non-shell env alias/);
+
+    expect(() =>
+      validateBundle({
+        version: '1.0',
+        name: 'Digit Prefix Bundle',
+        onboarding: [
+          {
+            id: 'two-fa-token',
+            type: 'secret',
+            title: '2FA token',
+            description: '2FA token',
+            configKey: '2faToken',
+          },
+        ],
+      })
+    ).toThrow(/2FA_TOKEN/);
+  });
+
+  it('detects exact key and normalized alias collisions', () => {
+    expect(() =>
+      validateBundle({
+        version: '1.0',
+        name: 'Exact Alias Collision Bundle',
+        onboarding: [
+          {
+            id: 'exact-upper',
+            type: 'input',
+            title: 'Exact upper',
+            description: 'exact',
+            configKey: 'API_TOKEN',
+          },
+          {
+            id: 'camel-key',
+            type: 'secret',
+            title: 'Camel key',
+            description: 'camel',
+            configKey: 'apiToken',
+          },
+        ],
+      })
+    ).toThrow(/Bundle configKey alias collision/);
+  });
+});

package/src/core/bundle.ts

@@ -17,6 +17,7 @@ import { exec } from 'child_process';
 import { promisify } from 'util';
 import { SpacesError } from '../types/errors.js';
 import { logger } from '../utils/logger.js';
+import { isShellEnvKey, normalizeEnvKey } from '../utils/normalize-env-key.js';
 import type { SpacesBundle, LoadedBundle } from '../types/bundle.js';
 
 const BUNDLE_FILENAME = 'bundle.json';
@@ -211,6 +212,9 @@ export function validateBundle(bundle: SpacesBundle): void {
   // Validate onboarding steps if present
   if (bundle.onboarding) {
     const ids = new Set<string>();
+    const configKeys = new Map<string, string>();
+    const normalizedAliases = new Map<string, { stepId: string; configKey: string }>();
+
     for (const step of bundle.onboarding) {
       if (!step.id) {
         throw new SpacesError('Each onboarding step must have an id', 'USER_ERROR', 1);
@@ -235,6 +239,72 @@ export function validateBundle(bundle: SpacesBundle): void {
             1
           );
         }
+
+        const existingConfigKeyStepId = configKeys.get(stepWithKey.configKey);
+        if (existingConfigKeyStepId) {
+          throw new SpacesError(
+            [
+              'Bundle configKey collision',
+              '',
+              `The configKey "${stepWithKey.configKey}" is used by multiple onboarding steps.`,
+              `- step "${existingConfigKeyStepId}"`,
+              `- step "${step.id}"`,
+              '',
+              'Fix: each input/secret step must use a unique configKey.',
+            ].join('\n'),
+            'USER_ERROR',
+            1
+          );
+        }
+        configKeys.set(stepWithKey.configKey, step.id);
+
+        const normalizedAlias = normalizeEnvKey(stepWithKey.configKey);
+        if (!normalizedAlias) {
+          throw new SpacesError(
+            `Step "${step.id}" has invalid configKey "${stepWithKey.configKey}" (no usable env alias)`,
+            'USER_ERROR',
+            1
+          );
+        }
+
+        if (!isShellEnvKey(normalizedAlias)) {
+          throw new SpacesError(
+            [
+              'Bundle configKey produces non-shell env alias',
+              '',
+              `Step "${step.id}" configKey "${stepWithKey.configKey}" normalizes to "${normalizedAlias}".`,
+              `Scripts cannot access this via $${normalizedAlias}.`,
+              '',
+              'Shell variable names must match: [A-Za-z_][A-Za-z0-9_]*',
+              'Fix: rename the configKey so its normalized alias starts with a letter or underscore.',
+            ].join('\n'),
+            'USER_ERROR',
+            1
+          );
+        }
+
+        const existingAlias = normalizedAliases.get(normalizedAlias);
+        if (existingAlias && existingAlias.configKey !== stepWithKey.configKey) {
+          throw new SpacesError(
+            [
+              'Bundle configKey alias collision',
+              '',
+              `Multiple config keys normalize to the same script env alias: ${normalizedAlias}`,
+              `- step "${existingAlias.stepId}" configKey "${existingAlias.configKey}"`,
+              `- step "${step.id}" configKey "${stepWithKey.configKey}"`,
+              '',
+              `Scripts would read an ambiguous value from $${normalizedAlias}.`,
+              'Fix: rename one of the conflicting configKey values so each exported env var is unique.',
+            ].join('\n'),
+            'USER_ERROR',
+            1
+          );
+        }
+
+        normalizedAliases.set(normalizedAlias, {
+          stepId: step.id,
+          configKey: stepWithKey.configKey,
+        });
       }
     }
   }

package/src/utils/__tests__/run-scripts.test.ts

@@ -333,22 +333,22 @@ echo "$TOKEN" >> "${outputFile}"
       expect(output.trim()).toBe('super-secret-token');
     });
 
-    it('keeps legacy SPACE_* aliases for backwards compatibility', async () => {
+    it('provides uppercase snake-case aliases for camelCase keys', async () => {
       const outputFile = join(testDir, 'aliases.txt');
       const scriptPath = join(scriptsDir, '01-aliases.sh');
       writeFileSync(scriptPath, `#!/bin/bash
-echo "$SPACE_VALUE_TEAM_NAME" >> "${outputFile}"
-echo "$SPACE_SECRET_API_TOKEN" >> "${outputFile}"
+echo "$TEAM_NAME" >> "${outputFile}"
+echo "$API_TOKEN" >> "${outputFile}"
 `);
       chmodSync(scriptPath, 0o755);
 
       await runScriptsInTerminal(scriptsDir, workspacePath, 'test-workspace', 'test/repo', {
         nonInteractive: true,
         bundleValues: {
-          TEAM_NAME: 'platform',
+          teamName: 'platform',
         },
         bundleSecrets: {
-          API_TOKEN: 'shh',
+          apiToken: 'shh',
         },
       });
 
@@ -357,6 +357,107 @@ echo "$SPACE_SECRET_API_TOKEN" >> "${outputFile}"
       expect(lines[0]).toBe('platform');
       expect(lines[1]).toBe('shh');
     });
+
+    it('splits acronym boundaries when normalizing aliases', async () => {
+      const outputFile = join(testDir, 'acronyms.txt');
+      const scriptPath = join(scriptsDir, '01-acronyms.sh');
+      writeFileSync(scriptPath, `#!/bin/bash
+echo "$MY_HTTP_CLIENT" >> "${outputFile}"
+echo "$XML_PARSER" >> "${outputFile}"
+`);
+      chmodSync(scriptPath, 0o755);
+
+      await runScriptsInTerminal(scriptsDir, workspacePath, 'test-workspace', 'test/repo', {
+        nonInteractive: true,
+        bundleValues: {
+          myHTTPClient: 'client-a',
+          XMLParser: 'parser-b',
+        },
+      });
+
+      const output = await Bun.file(outputFile).text();
+      const lines = output.trim().split('\n');
+      expect(lines[0]).toBe('client-a');
+      expect(lines[1]).toBe('parser-b');
+    });
+
+    it('throws helpful error when normalized alias is not shell-safe', async () => {
+      const scriptPath = join(scriptsDir, '01-noop.sh');
+      writeFileSync(scriptPath, '#!/bin/bash\necho "ok"');
+      chmodSync(scriptPath, 0o755);
+
+      await expect(
+        runScriptsInTerminal(scriptsDir, workspacePath, 'test-workspace', 'test/repo', {
+          nonInteractive: true,
+          bundleValues: {
+            '2faToken': 'secret',
+          },
+        })
+      ).rejects.toThrow(/not shell-safe/);
+
+      await expect(
+        runScriptsInTerminal(scriptsDir, workspacePath, 'test-workspace', 'test/repo', {
+          nonInteractive: true,
+          bundleValues: {
+            '2faToken': 'secret',
+          },
+        })
+      ).rejects.toThrow(/2FA_TOKEN/);
+    });
+
+    it('throws a helpful error when normalized aliases collide', async () => {
+      const scriptPath = join(scriptsDir, '01-noop.sh');
+      writeFileSync(scriptPath, '#!/bin/bash\necho "ok"');
+      chmodSync(scriptPath, 0o755);
+
+      await expect(
+        runScriptsInTerminal(scriptsDir, workspacePath, 'test-workspace', 'test/repo', {
+          nonInteractive: true,
+          bundleValues: {
+            apiToken: 'a',
+            'api-token': 'b',
+          },
+        })
+      ).rejects.toThrow(/Bundle script env collision/);
+
+      await expect(
+        runScriptsInTerminal(scriptsDir, workspacePath, 'test-workspace', 'test/repo', {
+          nonInteractive: true,
+          bundleValues: {
+            apiToken: 'a',
+            'api-token': 'b',
+          },
+        })
+      ).rejects.toThrow(/apiToken/);
+
+      await expect(
+        runScriptsInTerminal(scriptsDir, workspacePath, 'test-workspace', 'test/repo', {
+          nonInteractive: true,
+          bundleValues: {
+            apiToken: 'a',
+            'api-token': 'b',
+          },
+        })
+      ).rejects.toThrow(/API_TOKEN/);
+    });
+
+    it('throws when same key is exported with conflicting values', async () => {
+      const scriptPath = join(scriptsDir, '01-noop.sh');
+      writeFileSync(scriptPath, '#!/bin/bash\necho "ok"');
+      chmodSync(scriptPath, 0o755);
+
+      await expect(
+        runScriptsInTerminal(scriptsDir, workspacePath, 'test-workspace', 'test/repo', {
+          nonInteractive: true,
+          bundleValues: {
+            sharedKey: 'from-value',
+          },
+          bundleSecrets: {
+            sharedKey: 'from-secret',
+          },
+        })
+      ).rejects.toThrow(/Bundle script env conflict/);
+    });
   });
 
   describe('no scripts', () => {

package/src/utils/normalize-env-key.ts

@@ -0,0 +1,13 @@
+export function normalizeEnvKey(key: string): string {
+  return key
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1_$2')
+    .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+    .replace(/[^A-Za-z0-9]+/g, '_')
+    .replace(/_+/g, '_')
+    .replace(/^_+|_+$/g, '')
+    .toUpperCase();
+}
+
+export function isShellEnvKey(key: string): boolean {
+  return /^[A-Za-z_][A-Za-z0-9_]*$/.test(key);
+}

package/src/utils/run-scripts.ts

@@ -8,6 +8,7 @@ import { spawn } from 'child_process';
 import { join } from 'path';
 import { SpacesError } from '../types/errors.js';
 import { logger } from './logger.js';
+import { isShellEnvKey, normalizeEnvKey } from './normalize-env-key.js';
 
 const FAILURE_OUTPUT_TAIL_MAX_LINES = 25;
 const FAILURE_OUTPUT_TAIL_MAX_CHARS = 4000;
@@ -112,24 +113,118 @@ export interface RunScriptsOptions {
   onOutput?: (data: Buffer) => void;
 }
 
-function normalizeEnvKey(key: string): string {
-  return key.toUpperCase().replace(/[^A-Z0-9]/g, '_');
+type BundleValueKind = 'value' | 'secret';
+
+interface EnvBinding {
+  envName: string;
+  configKey: string;
+  sourceKind: BundleValueKind;
+  exportKind: 'exact' | 'normalized';
+  value: string;
+}
+
+function describeBinding(binding: EnvBinding): string {
+  return `${binding.configKey} (${binding.exportKind} ${binding.sourceKind})`;
+}
+
+function describeValue(binding: EnvBinding): string {
+  return binding.sourceKind === 'secret' ? '[redacted]' : JSON.stringify(binding.value);
+}
+
+function formatEnvCollisionMessage(existing: EnvBinding, incoming: EnvBinding): string {
+  return [
+    'Bundle script env collision',
+    '',
+    `Multiple config keys resolve to the same environment variable: ${incoming.envName}`,
+    `- ${incoming.envName} <- ${describeBinding(existing)}`,
+    `- ${incoming.envName} <- ${describeBinding(incoming)}`,
+    '',
+    `Scripts would read an ambiguous value from $${incoming.envName}.`,
+    'Fix: rename one of the conflicting configKey values in .gitspace/bundle.json so each exported env var is unique.',
+  ].join('\n');
 }
 
-function setCompatibilityAliases(
+function formatDuplicateValueMessage(existing: EnvBinding, incoming: EnvBinding): string {
+  return [
+    'Bundle script env conflict',
+    '',
+    `The same configKey is exported with different values: ${incoming.configKey}`,
+    `- ${describeBinding(existing)} => ${describeValue(existing)}`,
+    `- ${describeBinding(incoming)} => ${describeValue(incoming)}`,
+    '',
+    `This would silently overwrite $${incoming.envName}.`,
+    `Fix: ensure configKey "${incoming.configKey}" is defined once with a single value.`,
+  ].join('\n');
+}
+
+function formatInvalidNormalizedAliasMessage(configKey: string, normalizedAlias: string): string {
+  return [
+    'Bundle script env alias is not shell-safe',
+    '',
+    `configKey "${configKey}" normalizes to "${normalizedAlias}".`,
+    `Scripts cannot access this via $${normalizedAlias}.`,
+    '',
+    'Shell variable names must match: [A-Za-z_][A-Za-z0-9_]*',
+    'Fix: rename the configKey so its normalized alias starts with a letter or underscore.',
+  ].join('\n');
+}
+
+function registerEnvBinding(
   env: Record<string, string>,
+  bindings: Map<string, EnvBinding>,
+  binding: EnvBinding
+): void {
+  const existing = bindings.get(binding.envName);
+
+  if (existing && existing.configKey !== binding.configKey) {
+    throw new SpacesError(formatEnvCollisionMessage(existing, binding), 'USER_ERROR', 1);
+  }
+
+  if (existing && existing.configKey === binding.configKey && existing.value !== binding.value) {
+    throw new SpacesError(formatDuplicateValueMessage(existing, binding), 'USER_ERROR', 1);
+  }
+
+  bindings.set(binding.envName, binding);
+  env[binding.envName] = binding.value;
+}
+
+function setScriptEnvVars(
+  env: Record<string, string>,
+  bindings: Map<string, EnvBinding>,
   key: string,
   value: string,
-  prefix: 'SPACE_VALUE_' | 'SPACE_SECRET_'
+  sourceKind: BundleValueKind
 ): void {
+  registerEnvBinding(env, bindings, {
+    envName: key,
+    configKey: key,
+    sourceKind,
+    exportKind: 'exact',
+    value,
+  });
+
   const normalizedKey = normalizeEnvKey(key);
+  if (!normalizedKey) {
+    return;
+  }
+
+  if (!isShellEnvKey(normalizedKey)) {
+    throw new SpacesError(formatInvalidNormalizedAliasMessage(key, normalizedKey), 'USER_ERROR', 1);
+  }
 
-  // Legacy namespaced key for backwards compatibility.
-  env[`${prefix}${normalizedKey}`] = value;
+  if (normalizedKey === key) {
+    return;
+  }
 
-  // Uppercase normalized alias for shell-friendly access when key contains
-  // non-shell characters (for example, api-key -> API_KEY).
-  env[normalizedKey] = value;
+  // Uppercase snake-case alias for shell-friendly access when key uses
+  // camelCase or punctuation (for example, apiToken -> API_TOKEN).
+  registerEnvBinding(env, bindings, {
+    envName: normalizedKey,
+    configKey: key,
+    sourceKind,
+    exportKind: 'normalized',
+    value,
+  });
 }
 
 /**
@@ -138,7 +233,8 @@ function setCompatibilityAliases(
  *
  * Bundle values are passed as environment variables:
  * - <KEY> using the exact bundle config key name
- * - Backward-compatible aliases: SPACE_VALUE_<KEY>, SPACE_SECRET_<KEY>, and normalized <KEY>
+ * - <NORMALIZED_KEY> uppercase snake-case alias (for example, apiToken -> API_TOKEN)
+ * - Throws a user-facing error when multiple keys collide on the same env name
  */
 export async function runScriptsInTerminal(
   scriptsDir: string,
@@ -159,20 +255,19 @@ export async function runScriptsInTerminal(
 
   // Build environment variables from bundle values
   const scriptEnv: Record<string, string> = { ...process.env } as Record<string, string>;
+  const envBindings = new Map<string, EnvBinding>();
 
   // Add bundle values using configured key names.
   if (options?.bundleValues) {
     for (const [key, value] of Object.entries(options.bundleValues)) {
-      scriptEnv[key] = value;
-      setCompatibilityAliases(scriptEnv, key, value, 'SPACE_VALUE_');
+      setScriptEnvVars(scriptEnv, envBindings, key, value, 'value');
     }
   }
 
   // Add bundle secrets using configured key names.
   if (options?.bundleSecrets) {
     for (const [key, value] of Object.entries(options.bundleSecrets)) {
-      scriptEnv[key] = value;
-      setCompatibilityAliases(scriptEnv, key, value, 'SPACE_SECRET_');
+      setScriptEnvVars(scriptEnv, envBindings, key, value, 'secret');
     }
   }