@squidcloud/cli 1.0.450 → 1.0.452

package/dist/index.js

@@ -11221,6 +11221,43 @@ const packageJson = __webpack_require__(2108)
 
 const version = packageJson.version
 
+// Array of tips to display randomly
+const TIPS = [
+  '🔐 encrypt with Dotenvx: https://dotenvx.com',
+  '🔐 prevent committing .env to code: https://dotenvx.com/precommit',
+  '🔐 prevent building .env in docker: https://dotenvx.com/prebuild',
+  '🤖 agentic secret storage: https://dotenvx.com/as2',
+  '⚡️ secrets for agents: https://dotenvx.com/as2',
+  '🛡️ auth for agents: https://vestauth.com',
+  '🛠️  run anywhere with `dotenvx run -- yourcommand`',
+  '⚙️  specify custom .env file path with { path: \'/custom/path/.env\' }',
+  '⚙️  enable debug logging with { debug: true }',
+  '⚙️  override existing env vars with { override: true }',
+  '⚙️  suppress all logs with { quiet: true }',
+  '⚙️  write to custom object with { processEnv: myObject }',
+  '⚙️  load multiple .env files with { path: [\'.env.local\', \'.env\'] }'
+]
+
+// Get a random tip from the tips array
+function _getRandomTip () {
+  return TIPS[Math.floor(Math.random() * TIPS.length)]
+}
+
+function parseBoolean (value) {
+  if (typeof value === 'string') {
+    return !['false', '0', 'no', 'off', ''].includes(value.toLowerCase())
+  }
+  return Boolean(value)
+}
+
+function supportsAnsi () {
+  return process.stdout.isTTY // && process.env.TERM !== 'dumb'
+}
+
+function dim (text) {
+  return supportsAnsi() ? `\x1b[2m${text}\x1b[0m` : text
+}
+
 const LINE = /(?:^|^)\s*(?:export\s+)?([\w.-]+)(?:\s*=\s*?|:\s+?)(\s*'(?:\\'|[^'])*'|\s*"(?:\\"|[^"])*"|\s*`(?:\\`|[^`])*`|[^#\r\n]+)?\s*(?:#.*)?(?:$|$)/mg
 
 // Parse src into an Object
@@ -11306,7 +11343,7 @@ function _parseVault (options) {
 }
 
 function _warn (message) {
-  console.log(`[dotenv@${version}][WARN] ${message}`)
+  console.error(`[dotenv@${version}][WARN] ${message}`)
 }
 
 function _debug (message) {
@@ -11404,8 +11441,8 @@ function _resolveHome (envPath) {
 }
 
 function _configVault (options) {
-  const debug = Boolean(options && options.debug)
-  const quiet = options && 'quiet' in options ? options.quiet : true
+  const debug = parseBoolean(process.env.DOTENV_CONFIG_DEBUG || (options && options.debug))
+  const quiet = parseBoolean(process.env.DOTENV_CONFIG_QUIET || (options && options.quiet))
 
   if (debug || !quiet) {
     _log('Loading env from encrypted .env.vault')
@@ -11426,8 +11463,12 @@ function _configVault (options) {
 function configDotenv (options) {
   const dotenvPath = path.resolve(process.cwd(), '.env')
   let encoding = 'utf8'
-  const debug = Boolean(options && options.debug)
-  const quiet = options && 'quiet' in options ? options.quiet : true
+  let processEnv = process.env
+  if (options && options.processEnv != null) {
+    processEnv = options.processEnv
+  }
+  let debug = parseBoolean(processEnv.DOTENV_CONFIG_DEBUG || (options && options.debug))
+  let quiet = parseBoolean(processEnv.DOTENV_CONFIG_QUIET || (options && options.quiet))
 
   if (options && options.encoding) {
     encoding = options.encoding
@@ -11467,15 +11508,14 @@ function configDotenv (options) {
     }
   }
 
-  let processEnv = process.env
-  if (options && options.processEnv != null) {
-    processEnv = options.processEnv
-  }
+  const populated = DotenvModule.populate(processEnv, parsedAll, options)
 
-  DotenvModule.populate(processEnv, parsedAll, options)
+  // handle user settings DOTENV_CONFIG_ options inside .env file(s)
+  debug = parseBoolean(processEnv.DOTENV_CONFIG_DEBUG || debug)
+  quiet = parseBoolean(processEnv.DOTENV_CONFIG_QUIET || quiet)
 
   if (debug || !quiet) {
-    const keysCount = Object.keys(parsedAll).length
+    const keysCount = Object.keys(populated).length
     const shortPaths = []
     for (const filePath of optionPaths) {
       try {
@@ -11489,7 +11529,7 @@ function configDotenv (options) {
       }
     }
 
-    _log(`injecting env (${keysCount}) from ${shortPaths.join(',')}`)
+    _log(`injecting env (${keysCount}) from ${shortPaths.join(',')} ${dim(`-- tip: ${_getRandomTip()}`)}`)
   }
 
   if (lastError) {
@@ -11553,6 +11593,7 @@ function decrypt (encrypted, keyStr) {
 function populate (processEnv, parsed, options = {}) {
   const debug = Boolean(options && options.debug)
   const override = Boolean(options && options.override)
+  const populated = {}
 
   if (typeof parsed !== 'object') {
     const err = new Error('OBJECT_REQUIRED: Please check the processEnv argument being passed to populate')
@@ -11565,6 +11606,7 @@ function populate (processEnv, parsed, options = {}) {
     if (Object.prototype.hasOwnProperty.call(processEnv, key)) {
       if (override === true) {
         processEnv[key] = parsed[key]
+        populated[key] = parsed[key]
       }
 
       if (debug) {
@@ -11576,8 +11618,11 @@ function populate (processEnv, parsed, options = {}) {
       }
     } else {
       processEnv[key] = parsed[key]
+      populated[key] = parsed[key]
     }
   }
+
+  return populated
 }
 
 const DotenvModule = {
@@ -29682,7 +29727,7 @@ exports.AI_PROVIDER_TYPES = [
  * Public OpenAI chat model names (active models only).
  * @category AI
  */
-exports.OPENAI_CHAT_MODEL_NAMES = ['gpt-5-mini', 'gpt-5-nano', 'gpt-5.2', 'gpt-5.2-pro'];
+exports.OPENAI_CHAT_MODEL_NAMES = ['gpt-5-mini', 'gpt-5-nano', 'gpt-5.2', 'gpt-5.2-pro', 'gpt-5.4'];
 /**
  * Public Gemini chat model names (active models only).
  * @category AI
@@ -30167,6 +30212,7 @@ Object.defineProperty(exports, "__esModule", ({ value: true }));
 exports.extractFromBuffer = extractFromBuffer;
 exports.checkFileOrDirExists = checkFileOrDirExists;
 exports.assertFileOrDirExists = assertFileOrDirExists;
+exports.getRuntimeVmLabel = getRuntimeVmLabel;
 const assertic_1 = __webpack_require__(3205);
 const decompress_1 = __importDefault(__webpack_require__(482));
 const fs = __importStar(__webpack_require__(9896));
@@ -30187,6 +30233,14 @@ async function assertFileOrDirExists(path, errorProvider) {
     const exists = await checkFileOrDirExists(path);
     (0, assertic_1.assertTruthy)(exists, errorProvider || `File not exists: ${path}`);
 }
+function getRuntimeVmLabel() {
+    // @ts-expect-error Bun is not defined in Node.js types
+    if (typeof Bun !== 'undefined') {
+        // @ts-expect-error Bun is not defined in Node.js types
+        return `Bun v${Bun.version}`;
+    }
+    return `Node ${process.version}`;
+}
 
 
 /***/ },
@@ -30400,14 +30454,12 @@ exports.KOTLIN_CONTROLLERS = [
     'mutation',
     'native-query',
     'observability',
-    'openapi',
     'query',
     'queue',
     'quota',
     'scheduler',
     'secret',
     'storage',
-    'webhooks',
     'ws',
     'internal-extraction',
     'notification',
@@ -30564,6 +30616,7 @@ async function getOpenApiSpecAndControllersFromFile(codeDir) {
  */
 async function populateOpenApiControllersMap(bundleData, codeDir, codeType) {
     const openApiControllersMap = {};
+    const openApiSpecsMap = {};
     const openApiSpecAndControllers = await getOpenApiSpecAndControllersFromFile(codeDir);
     for (const [key, value] of Object.entries(openApiSpecAndControllers.openApiControllersMap)) {
         if (key === 'default' && codeType === 'connector') {
@@ -30572,7 +30625,14 @@ async function populateOpenApiControllersMap(bundleData, codeDir, codeType) {
         }
         openApiControllersMap[key] = JSON.parse(value);
     }
+    for (const [key, value] of Object.entries(openApiSpecAndControllers.openApiSpecsMap)) {
+        if (key === 'default' && codeType === 'connector') {
+            continue;
+        }
+        openApiSpecsMap[key] = value;
+    }
     bundleData.openApiControllersMap = openApiControllersMap;
+    bundleData.openApiSpecsMap = openApiSpecsMap;
 }
 
 
@@ -30879,10 +30939,15 @@ const resolve_1 = __webpack_require__(412);
 const shell_runner_1 = __webpack_require__(3089);
 class TsoaUtils {
     constructor() { }
-    static async generateAllSpecs(verbose = false, supportsDefault = true) {
+    /**
+     * @param projectDir - Root directory of the user's backend project.
+     * @param supportsDefault - Include the default tsoa spec (pass false for connectors).
+     * @param verbose - Log detailed progress and diagnostic messages.
+     */
+    static async generateAllSpecs(projectDir, supportsDefault, verbose) {
         const specsMap = {};
         // Read files in the current directory.
-        let files = await fsPromises.readdir(process.cwd());
+        let files = await fsPromises.readdir(projectDir);
         // Filter files matching the TSOA pattern (e.g. "tsoa.json", "tsoa-myapp.json", "tsoaAnother.json").
         files = files.filter(file => /^tsoa.*\.json$/.test(file));
         // If an exact "tsoa.json" is not present, get the fallback path.
@@ -30890,7 +30955,7 @@ class TsoaUtils {
             const hasAnyTsoaFilesProvidedByUser = files.length > 0;
             const localBackendModule = await (0, resolve_1.findModulePath)('@squidcloud/local-backend');
             if (localBackendModule) {
-                const fallback = path.relative(process.cwd(), path.resolve(localBackendModule, '../../tsoa.json'));
+                const fallback = path.relative(projectDir, path.resolve(localBackendModule, '../../tsoa.json'));
                 if (verbose) {
                     console.log(`"tsoa.json" not found in current directory. Using fallback: ${fallback}`);
                 }
@@ -30901,7 +30966,7 @@ class TsoaUtils {
                 // If this directory contains no '@Route' annotations - there are no tsoa controllers and there is no need to
                 // run tsoa at all.
                 if (!hasAnyTsoaFilesProvidedByUser) {
-                    const hasTsoaAnnotationsInUserCode = await checkUserCodeUsesTsoa(path.resolve(process.cwd(), 'src'));
+                    const hasTsoaAnnotationsInUserCode = await checkUserCodeUsesTsoa(path.resolve(projectDir, 'src'));
                     if (!hasTsoaAnnotationsInUserCode) {
                         if (verbose) {
                             console.log('No TSOA annotations were found in the user code; skipping API generation with TSOA.');
@@ -30928,14 +30993,16 @@ class TsoaUtils {
                 console.log(`Processing config file: ${file}`);
             }
             // Use native join to create the folder.
-            const outputDir = path.join('dist', specName);
-            if (!fs.existsSync(outputDir)) {
-                fs.mkdirSync(outputDir, { recursive: true });
+            // absOutputDir is used for Node fs operations; relOutputDir is passed to tsoa (which runs in projectDir).
+            const relOutputDir = path.join('dist', specName);
+            const absOutputDir = path.resolve(projectDir, relOutputDir);
+            if (!fs.existsSync(absOutputDir)) {
+                fs.mkdirSync(absOutputDir, { recursive: true });
             }
             // Read the original TSOA config.
             let configContent;
             try {
-                configContent = await fsPromises.readFile(file, { encoding: 'utf8' });
+                configContent = await fsPromises.readFile(path.resolve(projectDir, file), { encoding: 'utf8' });
             }
             catch (e) {
                 if (verbose) {
@@ -30954,10 +31021,11 @@ class TsoaUtils {
                 throw e;
             }
             // Override the output directories for both spec and routes.
+            // Use relative paths so tsoa (running in projectDir) resolves them correctly.
             config.spec = config.spec || {};
             config.routes = config.routes || {};
-            config.spec.outputDirectory = outputDir;
-            config.routes.routesDir = outputDir;
+            config.spec.outputDirectory = relOutputDir;
+            config.routes.routesDir = relOutputDir;
             // Fix middlewareTemplate path when using fallback from local-backend
             if (config.routes.middlewareTemplate && !path.isAbsolute(file)) {
                 const localBackendModule = await (0, resolve_1.findModulePath)('@squidcloud/local-backend');
@@ -30979,7 +31047,7 @@ class TsoaUtils {
                         // Rewrite the middlewareTemplate path to be relative to the current working directory.
                         const templatePath = path.resolve(packageRoot, 'dist/local-backend/openapi-template.hbs');
                         // Calculate relative path from current working directory (which might be backend/ or test-tsoa/backend/)
-                        config.routes.middlewareTemplate = path.relative(process.cwd(), templatePath);
+                        config.routes.middlewareTemplate = path.relative(projectDir, templatePath);
                         if (verbose) {
                             console.log(`Rewritten middlewareTemplate path to: ${config.routes.middlewareTemplate}`);
                             console.log(`Template absolute path: ${templatePath}`);
@@ -30988,27 +31056,28 @@ class TsoaUtils {
                     }
                 }
             }
-            // Use a relative path for the temporary config file.
-            const tempConfigPath = `temp-tsoa-config-${specName}.json`;
+            // Use a relative name for the tsoa command (tsoa runs in projectDir) and absolute path for Node fs operations.
+            const tempConfigName = `temp-tsoa-config-${specName}.json`;
+            const absTempConfigPath = path.resolve(projectDir, tempConfigName);
             try {
-                await fsPromises.writeFile(tempConfigPath, JSON.stringify(config, null, 2), { encoding: 'utf8' });
+                await fsPromises.writeFile(absTempConfigPath, JSON.stringify(config, null, 2), { encoding: 'utf8' });
             }
             catch (e) {
                 if (verbose) {
-                    console.error(`Error writing temporary config file ${tempConfigPath}:`, e);
+                    console.error(`Error writing temporary config file ${absTempConfigPath}:`, e);
                 }
                 throw e;
             }
             // Build the TSOA commands (without using -o) that reference the temporary config.
-            const specCmd = `npx tsoa spec -c ${tempConfigPath}`;
-            const routesCmd = `npx tsoa routes -c ${tempConfigPath}`;
+            const specCmd = `npx tsoa spec -c ${tempConfigName}`;
+            const routesCmd = `npx tsoa routes -c ${tempConfigName}`;
             if (verbose) {
-                console.log(`Processing ${file} as "${specName}" with temporary config ${tempConfigPath}`);
+                console.log(`Processing ${file} as "${specName}" with temporary config ${tempConfigName}`);
                 console.log(`Running: ${specCmd}`);
                 console.log(`Running: ${routesCmd}`);
             }
             try {
-                await Promise.all([(0, shell_runner_1.runInShell)(specCmd, false, process.cwd()), (0, shell_runner_1.runInShell)(routesCmd, false, process.cwd())]);
+                await Promise.all([(0, shell_runner_1.runInShell)(specCmd, false, projectDir), (0, shell_runner_1.runInShell)(routesCmd, false, projectDir)]);
             }
             catch (e) {
                 const combinedOutput = e?.combinedOutput;
@@ -31018,18 +31087,18 @@ class TsoaUtils {
                         console.log(`No controllers found for ${file}, skipping...`);
                     }
                     // Clean up the temporary config file before continuing.
-                    await fsPromises.unlink(tempConfigPath);
+                    await fsPromises.unlink(absTempConfigPath);
                     continue;
                 }
                 if (verbose) {
                     console.error(`Error processing ${file}:\n`, errorMessage);
                 }
-                await fsPromises.unlink(tempConfigPath);
+                await fsPromises.unlink(absTempConfigPath);
                 throw new Error(`Failed to process ${file}: ` + errorMessage);
             }
-            // Define output file paths.
-            const swaggerOutput = path.join(outputDir, 'swagger.json');
-            const routesOutput = path.join(outputDir, 'routes.ts');
+            // Define output file paths using absolute paths for Node fs operations.
+            const swaggerOutput = path.join(absOutputDir, 'swagger.json');
+            const routesOutput = path.join(absOutputDir, 'routes.ts');
             try {
                 const swaggerContent = await fsPromises.readFile(swaggerOutput, { encoding: 'utf8' });
                 const modifiedSwaggerContent = await TsoaUtils.attachCodeSamples(swaggerContent);
@@ -31043,11 +31112,11 @@ class TsoaUtils {
                 if (verbose) {
                     console.error(`Error reading generated files for ${file}:`, e);
                 }
-                await fsPromises.unlink(tempConfigPath);
+                await fsPromises.unlink(absTempConfigPath);
                 throw e;
             }
             // Clean up the temporary config file.
-            await fsPromises.unlink(tempConfigPath);
+            await fsPromises.unlink(absTempConfigPath);
         }
         const openApiControllersMap = {};
         const openApiSpecsMap = {};
@@ -31261,12 +31330,38 @@ const version_check_1 = __webpack_require__(4827);
 // - Default: colors only if TTY (stdout is a terminal).
 const isTerminal = process.stdout.isTTY;
 const useColorsInOutput = (0, process_env_utils_1.isEnvVarTruthy)('FORCE_COLOR') || (!(0, process_env_utils_1.isEnvVarTruthy)('NO_COLOR') && isTerminal);
+/**
+ * Add Python source files and requirements.txt to a zip archive.
+ * Used by both Python-only and hybrid builds.
+ */
+function addPythonFilesToBundle(zip) {
+    const SKIP_DIRS = new Set(['__pycache__', '__python_deps__']);
+    function addPyFiles(dirPath, zipDir) {
+        for (const entry of fsSync.readdirSync(dirPath, { withFileTypes: true })) {
+            if (entry.name.startsWith('.'))
+                continue;
+            const fullPath = path_1.default.join(dirPath, entry.name);
+            if (entry.isDirectory()) {
+                if (SKIP_DIRS.has(entry.name))
+                    continue;
+                addPyFiles(fullPath, path_1.default.join(zipDir, entry.name));
+            }
+            else if (entry.isFile() && !entry.name.endsWith('.pyc')) {
+                zip.addLocalFile(fullPath, zipDir || undefined);
+            }
+        }
+    }
+    addPyFiles('src', '');
+    if (fsSync.existsSync('requirements.txt')) {
+        zip.addLocalFile('requirements.txt');
+    }
+}
 async function build({ verbose, dev, skipVersionCheck }) {
     const buildPhaseStart = Date.now();
     (0, global_utils_1.enableDebugLogs)(verbose || (0, global_utils_1.isDebugEnabled)());
     (0, logpipes_1.installConsoleOverrides)(enable_debug_decorator_utils_1.debugLogFilterPipe);
     console.debug(`Starting Squid project build. CLI package version: ${packageJson.version}`);
-    await (0, validate_1.validateSquidProject)();
+    const projectInfo = await (0, validate_1.validateSquidProject)();
     // Start version checks in the background if not disabled.
     const shouldSkipVersionCheck = skipVersionCheck || (0, process_env_utils_1.isEnvVarTruthy)('SQUID_SKIP_BUILD_TIME_VERSION_CHECK');
     // SQUID_CURRENT_CLI_VERSION_OVERRIDE is used for testing.
@@ -31278,9 +31373,23 @@ async function build({ verbose, dev, skipVersionCheck }) {
         await fs_1.promises.rm(distPath, { recursive: true, force: true });
     }
     await fs_1.promises.mkdir(distPath);
+    // Python-only projects: zip src/ + requirements.txt, no webpack.
+    if (projectInfo.isPython && !projectInfo.isHybrid) {
+        console.log((0, logging_1.primary)('Building Python bundle...'));
+        const bundlePath = path_1.default.join(distPath, 'bundle.zip');
+        const zip = new adm_zip_1.default();
+        addPythonFilesToBundle(zip);
+        zip.writeZip(bundlePath);
+        const stats = fsSync.statSync(bundlePath);
+        console.log(`Python bundle created: ${bundlePath} (${(stats.size / 1024).toFixed(1)} KB)`);
+        await (0, version_check_1.displayVersionWarningIfOutdated)(versionCheckPromise);
+        (0, update_skills_1.displaySkillsWarningIfOutdated)();
+        console.debug((0, log_utils_1.timeSince)(buildPhaseStart, 'Build time '));
+        return;
+    }
     const isSquidConnector = (0, process_env_utils_1.isEnvVarTruthy)('SQUID_CONNECTOR');
     const specsStart = Date.now();
-    const openApiSpecAndControllers = await tsoa_utils_1.TsoaUtils.generateAllSpecs(verbose, !isSquidConnector);
+    const openApiSpecAndControllers = await tsoa_utils_1.TsoaUtils.generateAllSpecs(process.cwd(), !isSquidConnector, verbose);
     console.debug((0, log_utils_1.timeSince)(specsStart, 'OpenAPI specs generation time '));
     await fs_1.promises.writeFile(path_1.default.join(distPath, '', 'openapi-spec-and-controllers.json'), JSON.stringify(openApiSpecAndControllers));
     const isUserConfigMode = fsSync.existsSync(resolve_2.USER_WEBPACK_CONFIG_PATH);
@@ -31321,6 +31430,15 @@ async function build({ verbose, dev, skipVersionCheck }) {
                 resolve();
             });
         });
+        // For hybrid projects, add Python files to the webpack-produced bundle.
+        if (projectInfo.isHybrid) {
+            console.log('Adding Python files to hybrid bundle...');
+            const zipPath = path_1.default.join(distPath, 'bundle.zip');
+            const zip = new adm_zip_1.default(zipPath);
+            addPythonFilesToBundle(zip);
+            zip.writeZip(zipPath);
+            console.log('Python files added to bundle.');
+        }
         // Generate connector metadata if this is a connector build.
         if (isSquidConnector) {
             console.debug('Generating connector metadata...');
@@ -31461,6 +31579,7 @@ async function deploy(consoleRegion, appId, bundlePath, apiKey, verbose, direct,
     (0, logpipes_1.installConsoleOverrides)(enable_debug_decorator_utils_1.debugLogFilterPipe);
     const versionCheckPromise = (0, version_check_1.checkCliVersion)(packageJson.version);
     if (!direct && !isUserSpecifiedPath && !skipBuild) {
+        // `squid build` handles all project types: TS, Python-only, and hybrid.
         console.log('Building code bundle...');
         await (0, shell_runner_1.runInShell)('npm run build');
     }
@@ -31708,7 +31827,8 @@ const update_skills_1 = __webpack_require__(7286);
 const process_utils_1 = __webpack_require__(8251);
 const validate_1 = __webpack_require__(2246);
 function setupDotEnv(baseDir) {
-    dotenv.config({ path: path_1.default.resolve(baseDir || './', '.env') });
+    const envPath = path_1.default.resolve(baseDir || './', '.env');
+    dotenv.config({ path: envPath });
 }
 function run() {
     (0, yargs_1.default)(process.argv.slice(2))
@@ -32202,6 +32322,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", ({ value: true }));
 exports.start = start;
+const fs_1 = __webpack_require__(9896);
 const fs = __importStar(__webpack_require__(1943));
 const path_1 = __importDefault(__webpack_require__(6928));
 const resolve_1 = __webpack_require__(412);
@@ -32213,47 +32334,108 @@ const process_utils_1 = __webpack_require__(8251);
 const validate_1 = __webpack_require__(2246);
 const version_check_1 = __webpack_require__(4827);
 async function start() {
-    const packageJson = await (0, validate_1.validateSquidProject)();
+    const projectInfo = await (0, validate_1.validateSquidProject)();
     const versionCheckPromise = (0, version_check_1.checkCliVersion)(cliPackageJson.version);
     console.log((0, logging_1.primary)('Please note:'), 'to debug your application, you need to run the "start" npm script in your IDE in debug mode');
     await (0, version_check_1.displayVersionWarningIfOutdated)(versionCheckPromise);
     (0, update_skills_1.displaySkillsWarningIfOutdated)();
     console.log((0, logging_1.primary)('Starting...'));
+    if (projectInfo.isPython && !projectInfo.isHybrid) {
+        await startPython();
+        return;
+    }
+    // For hybrid projects, log Python detection
+    if (projectInfo.isHybrid) {
+        console.log((0, logging_1.primary)('Hybrid project detected:'), 'TypeScript + Python');
+    }
+    const packageJson = projectInfo.packageJson;
+    // Check for local development override
+    const localBackendPath = process.env['SQUID_LOCAL_BACKEND_PATH'];
+    if (localBackendPath) {
+        // Local development mode: use nest start from local-backend with SQUID_BACKEND_PATH
+        console.log('Using local-backend from SQUID_LOCAL_BACKEND_PATH:', localBackendPath);
+        const backendPath = process.cwd();
+        await (0, shell_runner_1.runInShell)(`npx nest start --exec "node -r ts-node/register -r tsconfig-paths/register src/main.ts"`, true, localBackendPath, { SQUID_BACKEND_PATH: backendPath });
+        return;
+    }
     const modulePath = await (0, resolve_1.findModulePath)('@squidcloud/local-backend');
     if (!modulePath) {
         (0, process_utils_1.exitWithError)(validate_1.INVALID_PROJECT_ERROR);
     }
     if (packageJson.scripts?.['start-squid']) {
         await (0, shell_runner_1.runInShell)(`npm run start-squid`);
+        return;
     }
-    else {
-        // Detect if CLI is running as TypeScript (dev mode)
-        const isDevMode = __filename.endsWith('.ts');
-        let mainPath;
-        // In dev mode, try to use local-backend source files
-        if (isDevMode) {
-            const localBackendSrc = path_1.default.resolve(__dirname, '../../local-backend/src/main.ts');
-            try {
-                await fs.access(localBackendSrc);
-                mainPath = localBackendSrc;
-                console.log((0, logging_1.primary)('Dev mode detected:'), `using local-backend source files: ${mainPath}`);
-            }
-            catch (_) {
-                // Fall back to built version if source files not found
-                mainPath = path_1.default.resolve(modulePath, '../main.js');
-            }
+    // Detect if CLI is running as TypeScript (dev mode)
+    const isDevMode = __filename.endsWith('.ts');
+    let mainPath;
+    // In dev mode, try to use local-backend source files
+    if (isDevMode) {
+        const localBackendSrc = path_1.default.resolve(__dirname, '../../local-backend/src/main.ts');
+        try {
+            await fs.access(localBackendSrc);
+            mainPath = localBackendSrc;
+            console.log((0, logging_1.primary)('Dev mode detected:'), `using local-backend source files: ${mainPath}`);
         }
-        else {
+        catch (_) {
+            // Fall back to built version if source files not found
             mainPath = path_1.default.resolve(modulePath, '../main.js');
         }
-        try {
-            await fs.access(mainPath);
-            await (0, shell_runner_1.runInShell)(`npx nodemon --watch ./src --watch ./.env --ext ts,js,json --quiet --exec node -r ts-node/register -r tsconfig-paths/register "${mainPath}"`);
+    }
+    else {
+        mainPath = path_1.default.resolve(modulePath, '../main.js');
+    }
+    try {
+        await fs.access(mainPath);
+        const ext = projectInfo.isHybrid ? 'py,ts,js,json' : 'ts,js,json';
+        const ignore = projectInfo.isHybrid ? ' --ignore __python_deps__' : '';
+        await (0, shell_runner_1.runInShell)(`npx nodemon --watch ./src --watch ./.env${ignore} --ext ${ext} --quiet --exec node -r ts-node/register -r tsconfig-paths/register "${mainPath}"`);
+    }
+    catch (_) {
+        (0, process_utils_1.exitWithError)(validate_1.INVALID_PROJECT_ERROR);
+    }
+}
+async function startPython() {
+    console.log((0, logging_1.primary)('Python backend detected.'));
+    const backendPath = process.cwd();
+    // Resolve local-backend path (realpathSync handles symlinks from npm link)
+    const modulePath = await (0, resolve_1.findModulePath)('@squidcloud/local-backend');
+    let localBackendDir;
+    // This Dev Mode is referring to running using the internal codebase's CLI, as a Squid engineer.
+    // It is NOT referring to Squid local development.
+    const isDevMode = __filename.endsWith('.ts');
+    if (isDevMode) {
+        localBackendDir = path_1.default.resolve(__dirname, '../../local-backend');
+    }
+    else if (modulePath) {
+        // modulePath points to the package entry (e.g. dist/index.js), resolve to package root
+        localBackendDir = (0, fs_1.realpathSync)(path_1.default.resolve(modulePath, '..'));
+    }
+    else {
+        (0, process_utils_1.exitWithError)(validate_1.INVALID_PROJECT_ERROR);
+    }
+    const mainPath = isDevMode ? path_1.default.resolve(localBackendDir, 'src/main.ts') : path_1.default.resolve(localBackendDir, 'main.js');
+    // Python requirements are installed by the local-backend process (with --target for isolation).
+    // No global pip install needed here.
+    const envVars = {
+        SQUID_BACKEND_PATH: backendPath,
+    };
+    try {
+        await fs.access(mainPath);
+        if (isDevMode) {
+            // Dev mode: run TypeScript source with ts-node
+            const tsconfigPath = path_1.default.resolve(localBackendDir, 'tsconfig.json');
+            envVars['TS_NODE_PROJECT'] = tsconfigPath;
+            await (0, shell_runner_1.runInShell)(`npx nodemon --watch ./src --watch ./.env --ignore __python_deps__ --ext py,ts,js,json --quiet --exec node -r ts-node/register -r tsconfig-paths/register "${mainPath}"`, true, backendPath, envVars);
         }
-        catch (_) {
-            (0, process_utils_1.exitWithError)(validate_1.INVALID_PROJECT_ERROR);
+        else {
+            // Published package: main.js is already compiled, no ts-node needed
+            await (0, shell_runner_1.runInShell)(`npx nodemon --watch ./src --watch ./.env --ignore __python_deps__ --ext py,ts,js,json --quiet --exec node "${mainPath}"`, true, backendPath, envVars);
         }
     }
+    catch (_) {
+        (0, process_utils_1.exitWithError)(validate_1.INVALID_PROJECT_ERROR);
+    }
 }
 
 
@@ -32589,6 +32771,7 @@ async function reportLocalBackendInitialized(consoleRegion, appId, apiKey) {
     try {
         const headers = new Headers();
         headers.append('Authorization', `ApiKey ${apiKey}`);
+        headers.append('Content-Type', 'application/json');
         const response = await fetch(url, { method: 'POST', body: JSON.stringify({ appId }), headers });
         if (!response.ok) {
             const responseText = await response.text();
@@ -32668,15 +32851,40 @@ exports.validateSquidProject = validateSquidProject;
 const promises_1 = __importDefault(__webpack_require__(1943));
 const process_utils_1 = __webpack_require__(8251);
 exports.INVALID_PROJECT_ERROR = 'Please make sure you are running this command in your Squid project directory';
+async function fileExists(filePath) {
+    try {
+        await promises_1.default.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 async function validateSquidProject() {
+    const hasPython = (await fileExists('src/main.py')) || (await fileExists('src/index.py'));
+    const hasTs = await fileExists('src/index.ts');
+    const isHybrid = hasPython && hasTs;
+    const isPythonOnly = hasPython && !hasTs;
+    if (isPythonOnly) {
+        // Python-only projects may not have package.json with start scripts
+        let packageJson = {};
+        try {
+            const raw = await promises_1.default.readFile('package.json', 'utf8');
+            packageJson = JSON.parse(raw);
+        }
+        catch {
+            // No package.json is fine for Python projects
+        }
+        return { packageJson, isPython: true, isHybrid: false };
+    }
     try {
-        const packageJson = await promises_1.default.readFile('package.json', 'utf8');
-        const parsedJson = JSON.parse(packageJson);
+        const packageJsonRaw = await promises_1.default.readFile('package.json', 'utf8');
+        const parsedJson = JSON.parse(packageJsonRaw);
         const { scripts } = parsedJson;
         if (!scripts?.['start-squid'] && !scripts?.['start']) {
             (0, process_utils_1.exitWithError)(exports.INVALID_PROJECT_ERROR);
         }
-        return parsedJson;
+        return { packageJson: parsedJson, isPython: hasPython, isHybrid };
     }
     catch (_) {
         (0, process_utils_1.exitWithError)(exports.INVALID_PROJECT_ERROR);
@@ -37122,7 +37330,7 @@ terminalLink.stderr.isSupported = supports_hyperlinks.stderr;
 (module) {
 
 "use strict";
-module.exports = /*#__PURE__*/JSON.parse('{"name":"dotenv","version":"16.6.1","description":"Loads environment variables from .env file","main":"lib/main.js","types":"lib/main.d.ts","exports":{".":{"types":"./lib/main.d.ts","require":"./lib/main.js","default":"./lib/main.js"},"./config":"./config.js","./config.js":"./config.js","./lib/env-options":"./lib/env-options.js","./lib/env-options.js":"./lib/env-options.js","./lib/cli-options":"./lib/cli-options.js","./lib/cli-options.js":"./lib/cli-options.js","./package.json":"./package.json"},"scripts":{"dts-check":"tsc --project tests/types/tsconfig.json","lint":"standard","pretest":"npm run lint && npm run dts-check","test":"tap run --allow-empty-coverage --disable-coverage --timeout=60000","test:coverage":"tap run --show-full-coverage --timeout=60000 --coverage-report=text --coverage-report=lcov","prerelease":"npm test","release":"standard-version"},"repository":{"type":"git","url":"git://github.com/motdotla/dotenv.git"},"homepage":"https://github.com/motdotla/dotenv#readme","funding":"https://dotenvx.com","keywords":["dotenv","env",".env","environment","variables","config","settings"],"readmeFilename":"README.md","license":"BSD-2-Clause","devDependencies":{"@types/node":"^18.11.3","decache":"^4.6.2","sinon":"^14.0.1","standard":"^17.0.0","standard-version":"^9.5.0","tap":"^19.2.0","typescript":"^4.8.4"},"engines":{"node":">=12"},"browser":{"fs":false}}');
+module.exports = /*#__PURE__*/JSON.parse('{"name":"dotenv","version":"17.3.1","description":"Loads environment variables from .env file","main":"lib/main.js","types":"lib/main.d.ts","exports":{".":{"types":"./lib/main.d.ts","require":"./lib/main.js","default":"./lib/main.js"},"./config":"./config.js","./config.js":"./config.js","./lib/env-options":"./lib/env-options.js","./lib/env-options.js":"./lib/env-options.js","./lib/cli-options":"./lib/cli-options.js","./lib/cli-options.js":"./lib/cli-options.js","./package.json":"./package.json"},"scripts":{"dts-check":"tsc --project tests/types/tsconfig.json","lint":"standard","pretest":"npm run lint && npm run dts-check","test":"tap run tests/**/*.js --allow-empty-coverage --disable-coverage --timeout=60000","test:coverage":"tap run tests/**/*.js --show-full-coverage --timeout=60000 --coverage-report=text --coverage-report=lcov","prerelease":"npm test","release":"standard-version"},"repository":{"type":"git","url":"git://github.com/motdotla/dotenv.git"},"homepage":"https://github.com/motdotla/dotenv#readme","funding":"https://dotenvx.com","keywords":["dotenv","env",".env","environment","variables","config","settings"],"readmeFilename":"README.md","license":"BSD-2-Clause","devDependencies":{"@types/node":"^18.11.3","decache":"^4.6.2","sinon":"^14.0.1","standard":"^17.0.0","standard-version":"^9.5.0","tap":"^19.2.0","typescript":"^4.8.4"},"engines":{"node":">=12"},"browser":{"fs":false}}');
 
 /***/ },
 
@@ -37138,7 +37346,7 @@ module.exports = /*#__PURE__*/JSON.parse('{"name":"seek-bzip","version":"1.0.6",
 (module) {
 
 "use strict";
-module.exports = /*#__PURE__*/JSON.parse('{"name":"@squidcloud/cli","version":"1.0.450","description":"The Squid CLI","main":"dist/index.js","scripts":{"start":"node dist/index.js","start-ts":"ts-node -r tsconfig-paths/register src/index.ts","prebuild":"rimraf dist","build":"webpack --mode=production","build:dev":"webpack --mode=development","lint":"eslint","link":"npm run build && chmod 755 dist/index.js && npm link","watch":"webpack --watch","deploy":"npm run build && npm pack --silent | xargs -I {} mv {} package.tgz && npm install -g package.tgz && rm -rf package.tgz","publish:public":"npm run build && npm publish --access public"},"files":["dist/**/*"],"bin":{"squid":"dist/index.js"},"keywords":[],"author":"","license":"ISC","engines":{"node":">=18.0.0"},"dependencies":{"@squidcloud/local-backend":"^1.0.450","adm-zip":"^0.5.16","copy-webpack-plugin":"^12.0.2","decompress":"^4.2.1","logpipes":"^1.11.0","nodemon":"^3.1.9","terser-webpack-plugin":"^5.3.10","ts-loader":"^9.5.1","ts-node":"^10.9.2","tsconfig-paths":"^4.2.0","tsconfig-paths-webpack-plugin":"^4.1.0","webpack":"^5.101.3","zip-webpack-plugin":"^4.0.1"},"devDependencies":{"@types/adm-zip":"^0.5.7","@types/decompress":"^4.2.7","@types/node":"^20.19.9","terminal-link":"^3.0.0"}}');
+module.exports = /*#__PURE__*/JSON.parse('{"name":"@squidcloud/cli","version":"1.0.452","description":"The Squid CLI","main":"dist/index.js","scripts":{"start":"node dist/index.js","start-ts":"ts-node -r tsconfig-paths/register src/index.ts","prebuild":"rimraf dist","build":"webpack --mode=production","build:dev":"webpack --mode=development","lint":"eslint","link":"npm run build && chmod 755 dist/index.js && npm link","watch":"webpack --watch","deploy":"npm run build && npm pack --silent | xargs -I {} mv {} package.tgz && npm install -g package.tgz && rm -rf package.tgz","publish:public":"npm run build && npm publish --access public"},"files":["dist/**/*"],"bin":{"squid":"dist/index.js"},"keywords":[],"author":"","license":"ISC","engines":{"node":">=18.0.0"},"dependencies":{"@squidcloud/local-backend":"^1.0.452","adm-zip":"^0.5.16","copy-webpack-plugin":"^12.0.2","decompress":"^4.2.1","logpipes":"^1.11.0","nodemon":"^3.1.9","terser-webpack-plugin":"^5.3.10","ts-loader":"^9.5.1","ts-node":"^10.9.2","tsconfig-paths":"^4.2.0","tsconfig-paths-webpack-plugin":"^4.1.0","webpack":"^5.101.3","zip-webpack-plugin":"^4.0.1"},"devDependencies":{"@types/adm-zip":"^0.5.7","@types/decompress":"^4.2.7","@types/node":"^20.19.9","terminal-link":"^3.0.0"}}');
 
 /***/ }
 

package/dist/resources/claude/skills/squid-development/reference/backend.md

@@ -393,8 +393,8 @@ export class MyService extends SquidService {
 Handle client connection and disconnection events.
 
 ```typescript
-import { SquidService, clientConnectionStateHandler, ClientConnectionState } from '@squidcloud/backend';
-import { ClientId } from '@squidcloud/client';
+import { SquidService, clientConnectionStateHandler } from '@squidcloud/backend';
+import { ClientConnectionState, ClientId } from '@squidcloud/client';
 
 export class MyService extends SquidService {
   @clientConnectionStateHandler()

package/dist/resources/claude/skills/squid-development/reference/databases.md

@@ -84,8 +84,8 @@ const docRef = collection.doc({ id1: 'part1' }); // id2 generated on insert
 ## CRUD Operations
 
 ```typescript
-// Insert
-await userDoc.insert({ name: 'John', email: 'john@example.com' });
+// Upsert (insert or update if the document already exists)
+await userDoc.upsert({ name: 'John', email: 'john@example.com' });
 
 // Update (partial)
 await userDoc.update({ name: 'Jane' });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@squidcloud/cli",
-  "version": "1.0.450",
+  "version": "1.0.452",
   "description": "The Squid CLI",
   "main": "dist/index.js",
   "scripts": {
@@ -28,7 +28,7 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@squidcloud/local-backend": "^1.0.450",
+    "@squidcloud/local-backend": "^1.0.452",
     "adm-zip": "^0.5.16",
     "copy-webpack-plugin": "^12.0.2",
     "decompress": "^4.2.1",