@friggframework/devtools 2.0.0--canary.474.a74bb09.0 → 2.0.0--canary.474.295ae1f.0

package/frigg-cli/{CLI.md → README.md}

@@ -1189,3 +1189,102 @@ frigg --version               # Show version
 - GitHub Issues: https://github.com/friggframework/frigg/issues
 - Documentation: https://docs.friggframework.org
 - Slack: Join via https://friggframework.org/#contact
+
+---
+
+## Package Structure & Global Installation
+
+### Overview
+
+The Frigg CLI is a standalone globally-installable npm package that can be installed via `npm i -g @friggframework/frigg-cli`. It includes version detection logic to automatically prefer local project installations when available.
+
+### Package Structure
+
+**@friggframework/frigg-cli** (standalone package)
+```
+├── package.json
+│   ├── dependencies: @friggframework/core@^2.0.0-next.0
+│   ├── dependencies: @friggframework/devtools@^2.0.0-next.0
+│   └── publishConfig: { access: "public" }
+└── index.js (with version detection wrapper)
+```
+
+**Key Changes from Previous Structure:**
+- ✅ Replaced `workspace:*` with concrete versions (`^2.0.0-next.0`)
+- ✅ Added `@friggframework/devtools` as dependency
+- ✅ Added `publishConfig` for public npm publishing
+- ✅ Removed bin entry from devtools package.json
+
+**Note:** Since `@friggframework/devtools` is a dependency, the global install size includes devtools. The main benefit is proper version resolution (no `workspace:*` errors) and automatic local CLI preference.
+
+### Version Detection Logic
+
+When you run `frigg` (globally installed), the CLI:
+
+1. **Checks for skip flag**
+   - If `FRIGG_CLI_SKIP_VERSION_CHECK=true`, skips detection (prevents recursion)
+
+2. **Looks for local installation**
+   - Searches for `node_modules/@friggframework/frigg-cli` in current directory
+
+3. **Compares versions**
+   - Uses `semver.compare(localVersion, globalVersion)`
+
+4. **Makes decision**:
+   - **Local ≥ Global**: Uses local CLI (spawns subprocess)
+   - **Global > Local**: Warns and uses global
+   - **No local**: Uses global silently
+
+### Benefits
+
+| Aspect | Before | After |
+|--------|--------|-------|
+| **Global Install** | `npm i -g @friggframework/devtools` | `npm i -g @friggframework/frigg-cli` |
+| **Dependencies** | workspace:* (broken) | Concrete versions (works) |
+| **Version Preference** | No detection | Automatic local preference |
+| **Version Warnings** | None | Mismatch alerts |
+| **Publishability** | ❌ Fails | ✅ Works |
+| **Local Project Isolation** | ❌ Uses global versions | ✅ Uses local versions when available |
+
+### Publishing Workflow
+
+```bash
+# Publish to npm
+cd packages/devtools/frigg-cli
+npm version patch  # or minor, major
+npm publish
+
+# Users can now install globally
+npm install -g @friggframework/frigg-cli
+
+# And it will automatically use local versions when available
+```
+
+### Migration Path
+
+**For existing users:**
+
+```bash
+# Step 1: Uninstall old global devtools
+npm uninstall -g @friggframework/devtools
+
+# Step 2: Install new global CLI
+npm install -g @friggframework/frigg-cli
+
+# Step 3: Update local project dependencies
+npm install @friggframework/frigg-cli@latest
+```
+
+**For new projects:**
+
+```bash
+# Global CLI (once per machine)
+npm install -g @friggframework/frigg-cli
+
+# Local project dependencies
+npx create-frigg-app my-app
+# (Will automatically include @friggframework/frigg-cli in package.json)
+```
+
+**Status:** ✅ Complete and tested (15 passing tests)
+

package/frigg-cli/__tests__/unit/version-detection.test.js

@@ -0,0 +1,171 @@
+/**
+ * Version Detection Tests
+ *
+ * Tests for the CLI version detection wrapper that prefers local installations
+ */
+
+const fs = require('fs');
+const path = require('path');
+const semver = require('semver');
+
+describe('Version Detection Logic', () => {
+    describe('semver comparison', () => {
+        test('should prefer local when local version is newer', () => {
+            const localVersion = '2.1.0';
+            const globalVersion = '2.0.0';
+
+            const comparison = semver.compare(localVersion, globalVersion);
+
+            expect(comparison).toBeGreaterThan(0);
+        });
+
+        test('should prefer local when versions are equal', () => {
+            const localVersion = '2.0.0';
+            const globalVersion = '2.0.0';
+
+            const comparison = semver.compare(localVersion, globalVersion);
+
+            expect(comparison).toBe(0);
+        });
+
+        test('should warn when global is newer than local', () => {
+            const localVersion = '2.0.0';
+            const globalVersion = '2.1.0';
+
+            const comparison = semver.compare(localVersion, globalVersion);
+
+            expect(comparison).toBeLessThan(0);
+        });
+
+        test('should handle prerelease versions correctly', () => {
+            const localVersion = '2.0.0-next.1';
+            const globalVersion = '2.0.0-next.0';
+
+            const comparison = semver.compare(localVersion, globalVersion);
+
+            expect(comparison).toBeGreaterThan(0);
+        });
+
+        test('should prefer release over prerelease', () => {
+            const localVersion = '2.0.0';
+            const globalVersion = '2.0.0-next.0';
+
+            const comparison = semver.compare(localVersion, globalVersion);
+
+            expect(comparison).toBeGreaterThan(0);
+        });
+    });
+
+    describe('local CLI detection', () => {
+        test('should find local installation in node_modules', () => {
+            const cwd = process.cwd();
+            const localCliPath = path.join(cwd, 'node_modules', '@friggframework', 'frigg-cli');
+
+            // This test validates the path construction logic
+            expect(localCliPath).toContain('node_modules');
+            expect(localCliPath).toContain('@friggframework');
+            expect(localCliPath).toContain('frigg-cli');
+        });
+
+        test('should construct correct paths for package.json and index.js', () => {
+            const cwd = process.cwd();
+            const localCliPath = path.join(cwd, 'node_modules', '@friggframework', 'frigg-cli');
+            const localCliPackageJson = path.join(localCliPath, 'package.json');
+            const localCliIndex = path.join(localCliPath, 'index.js');
+
+            expect(localCliPackageJson).toContain('package.json');
+            expect(localCliIndex).toContain('index.js');
+        });
+    });
+
+    describe('environment variable check', () => {
+        test('should skip version check when FRIGG_CLI_SKIP_VERSION_CHECK is true', () => {
+            const originalEnv = process.env.FRIGG_CLI_SKIP_VERSION_CHECK;
+
+            process.env.FRIGG_CLI_SKIP_VERSION_CHECK = 'true';
+            const shouldSkip = process.env.FRIGG_CLI_SKIP_VERSION_CHECK === 'true';
+            expect(shouldSkip).toBe(true);
+
+            // Restore
+            if (originalEnv !== undefined) {
+                process.env.FRIGG_CLI_SKIP_VERSION_CHECK = originalEnv;
+            } else {
+                delete process.env.FRIGG_CLI_SKIP_VERSION_CHECK;
+            }
+        });
+
+        test('should not skip when environment variable is not set', () => {
+            const originalEnv = process.env.FRIGG_CLI_SKIP_VERSION_CHECK;
+            delete process.env.FRIGG_CLI_SKIP_VERSION_CHECK;
+
+            const shouldSkip = process.env.FRIGG_CLI_SKIP_VERSION_CHECK === 'true';
+            expect(shouldSkip).toBe(false);
+
+            // Restore
+            if (originalEnv !== undefined) {
+                process.env.FRIGG_CLI_SKIP_VERSION_CHECK = originalEnv;
+            }
+        });
+    });
+
+    describe('version detection decision matrix', () => {
+        const scenarios = [
+            {
+                name: 'local newer than global',
+                local: '2.1.0',
+                global: '2.0.0',
+                expected: 'use_local',
+            },
+            {
+                name: 'local equal to global',
+                local: '2.0.0',
+                global: '2.0.0',
+                expected: 'use_local',
+            },
+            {
+                name: 'global newer than local',
+                local: '2.0.0',
+                global: '2.1.0',
+                expected: 'warn_and_use_global',
+            },
+            {
+                name: 'local prerelease newer',
+                local: '2.0.0-next.1',
+                global: '2.0.0-next.0',
+                expected: 'use_local',
+            },
+        ];
+
+        scenarios.forEach(({ name, local, global, expected }) => {
+            test(`should ${expected.replace('_', ' ')} when ${name}`, () => {
+                const comparison = semver.compare(local, global);
+
+                if (expected === 'use_local') {
+                    expect(comparison).toBeGreaterThanOrEqual(0);
+                } else if (expected === 'warn_and_use_global') {
+                    expect(comparison).toBeLessThan(0);
+                }
+            });
+        });
+    });
+
+    describe('argument forwarding', () => {
+        test('should extract arguments correctly from process.argv', () => {
+            // Simulate process.argv
+            const mockArgv = ['node', '/path/to/frigg', 'doctor', 'my-stack', '--region', 'us-east-1'];
+            const args = mockArgv.slice(2);
+
+            expect(args).toEqual(['doctor', 'my-stack', '--region', 'us-east-1']);
+        });
+
+        test('should forward all arguments to local CLI', () => {
+            const mockArgv = ['node', '/path/to/frigg', 'repair', 'my-stack', '--import', '--yes'];
+            const args = mockArgv.slice(2);
+
+            expect(args).toContain('repair');
+            expect(args).toContain('my-stack');
+            expect(args).toContain('--import');
+            expect(args).toContain('--yes');
+        });
+    });
+});

package/frigg-cli/index.js

@@ -1,5 +1,79 @@
 #!/usr/bin/env node
 
+// Version Detection Wrapper
+// This code runs when frigg-cli is installed globally
+// It checks for a local installation and prefers it if newer
+(function versionDetection() {
+    // Skip version detection if explicitly disabled (prevents recursion)
+    if (process.env.FRIGG_CLI_SKIP_VERSION_CHECK === 'true') {
+        return;
+    }
+
+    const path = require('path');
+    const fs = require('fs');
+    const semver = require('semver');
+    const { spawn } = require('child_process');
+
+    // Get the directory from which the command was invoked
+    const cwd = process.cwd();
+
+    // Try to find local frigg-cli installation
+    const localCliPath = path.join(cwd, 'node_modules', '@friggframework', 'frigg-cli');
+    const localCliPackageJson = path.join(localCliPath, 'package.json');
+    const localCliIndex = path.join(localCliPath, 'index.js');
+
+    // Get global version (this package)
+    const globalVersion = require('./package.json').version;
+
+    // Check if local installation exists
+    if (fs.existsSync(localCliPackageJson) && fs.existsSync(localCliIndex)) {
+        try {
+            const localPackage = JSON.parse(fs.readFileSync(localCliPackageJson, 'utf8'));
+            const localVersion = localPackage.version;
+
+            // Compare versions
+            const comparison = semver.compare(localVersion, globalVersion);
+
+            if (comparison >= 0) {
+                // Local version is newer or equal - use it
+                console.log(`Using local frigg-cli@${localVersion} (global: ${globalVersion})`);
+
+                // Execute local CLI as subprocess to avoid module resolution issues
+                const args = process.argv.slice(2); // Remove 'node' and script path
+                const child = spawn(process.execPath, [localCliIndex, ...args], {
+                    stdio: 'inherit',
+                    env: {
+                        ...process.env,
+                        FRIGG_CLI_SKIP_VERSION_CHECK: 'true', // Prevent recursion
+                    },
+                });
+
+                child.on('exit', (code) => {
+                    process.exit(code || 0);
+                });
+
+                // Signal that we've delegated to local CLI
+                process.on('SIGINT', () => {
+                    child.kill('SIGINT');
+                });
+
+                // Prevent further execution
+                return true; // Indicates we've delegated
+            } else {
+                // Global version is newer - warn user
+                console.warn(`⚠️  Version mismatch: global frigg-cli@${globalVersion} is newer than local frigg-cli@${localVersion}`);
+                console.warn(`   Consider updating local version: npm install @friggframework/frigg-cli@latest`);
+            }
+        } catch (error) {
+            // Failed to read local package.json or compare versions
+            // Continue with global version silently
+        }
+    }
+
+    // Return false to indicate we should continue with global version
+    return false;
+})();
+
 const { Command } = require('commander');
 const { initCommand } = require('./init-command');
 const { installCommand } = require('./install-command');

package/frigg-cli/package.json

@@ -12,8 +12,9 @@
   "dependencies": {
     "@babel/parser": "^7.25.3",
     "@babel/traverse": "^7.25.3",
-    "@friggframework/core": "workspace:*",
-    "@friggframework/schemas": "workspace:*",
+    "@friggframework/core": "^2.0.0-next.0",
+    "@friggframework/devtools": "^2.0.0-next.0",
+    "@friggframework/schemas": "^2.0.0-next.0",
     "@inquirer/prompts": "^5.3.8",
     "axios": "^1.7.2",
     "chalk": "^4.1.2",
@@ -50,5 +51,8 @@
   "homepage": "https://github.com/friggframework/frigg#readme",
   "engines": {
     "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
   }
 }