@squidcloud/cli 1.0.449 → 1.0.450

package/dist/index.js

@@ -29656,6 +29656,7 @@ Object.defineProperty(exports, "__esModule", ({ value: true }));
 exports.OPEN_AI_CREATE_SPEECH_FORMATS = exports.AI_AUDIO_CREATE_SPEECH_MODEL_NAMES = exports.AI_AUDIO_TRANSCRIPTION_MODEL_NAMES = exports.AI_IMAGE_MODEL_NAMES = exports.FLUX_MODEL_NAMES = exports.STABLE_DIFFUSION_MODEL_NAMES = exports.OPENAI_AUDIO_MODEL_NAMES = exports.OPENAI_AUDIO_CREATE_SPEECH_MODEL_NAMES = exports.OPENAI_AUDIO_TRANSCRIPTION_MODEL_NAMES = exports.OPENAI_IMAGE_MODEL_NAMES = exports.AI_EMBEDDINGS_MODEL_NAMES = exports.BEDROCK_EMBEDDING_MODEL_NAMES = exports.VOYAGE_EMBEDDING_MODEL_NAMES = exports.OPENAI_EMBEDDINGS_MODEL_NAMES = exports.VENDOR_AI_CHAT_MODEL_NAMES = exports.ANTHROPIC_CHAT_MODEL_NAMES = exports.GROK_CHAT_MODEL_NAMES = exports.GEMINI_CHAT_MODEL_NAMES = exports.OPENAI_CHAT_MODEL_NAMES = exports.AI_PROVIDER_TYPES = exports.RERANK_PROVIDERS = void 0;
 exports.isVendorAiChatModelName = isVendorAiChatModelName;
 exports.isAiEmbeddingsModelName = isAiEmbeddingsModelName;
+exports.isIntegrationEmbeddingModelSpec = isIntegrationEmbeddingModelSpec;
 exports.isIntegrationModelSpec = isIntegrationModelSpec;
 /**
  * @category AI
@@ -29742,6 +29743,13 @@ exports.AI_EMBEDDINGS_MODEL_NAMES = [
 function isAiEmbeddingsModelName(modelName) {
     return exports.AI_EMBEDDINGS_MODEL_NAMES.includes(modelName);
 }
+/**
+ * Type guard for `IntegrationEmbeddingModelSpec`.
+ * @category AI
+ */
+function isIntegrationEmbeddingModelSpec(model) {
+    return (typeof model === 'object' && model !== null && 'integrationId' in model && 'model' in model && 'dimensions' in model);
+}
 /**
  * The supported AI image generation model names.
  * @category AI
@@ -29893,6 +29901,7 @@ exports.INTEGRATION_TYPES = [
     'legend',
     'teams',
     'openai_compatible',
+    'openai_compatible_embedding',
 ];
 /**
  * @category Database
@@ -30325,7 +30334,11 @@ function isSquidDebugEnabledByDefault() {
     }
     return param === '1' || param === 'true';
 }
-enableDebugLogs(isSquidDebugEnabledByDefault());
+// Auto-initialize debug flag only if not explicitly set already.
+// This prevents bundled code from overriding the flag set by the host application.
+if (getGlobal()?.['SQUID_LOG_DEBUG_ENABLED'] === undefined) {
+    enableDebugLogs(isSquidDebugEnabledByDefault());
+}
 /** @internal */
 function disableTimestampsInLog() {
     const globalObj = getGlobal();
@@ -31236,6 +31249,7 @@ const process_env_utils_1 = __webpack_require__(9360);
 const resolve_1 = __webpack_require__(412);
 const tsoa_utils_1 = __webpack_require__(1431);
 const packageJson = __importStar(__webpack_require__(8330));
+const update_skills_1 = __webpack_require__(7286);
 const logging_1 = __webpack_require__(443);
 const process_utils_1 = __webpack_require__(8251);
 const resolve_2 = __webpack_require__(3878);
@@ -31247,15 +31261,6 @@ 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);
-async function displayVersionWarning(versionCheckPromise) {
-    try {
-        const versionWarning = await versionCheckPromise;
-        if (versionWarning) {
-            console.warn(versionWarning);
-        }
-    }
-    catch (_ignored) { }
-}
 async function build({ verbose, dev, skipVersionCheck }) {
     const buildPhaseStart = Date.now();
     (0, global_utils_1.enableDebugLogs)(verbose || (0, global_utils_1.isDebugEnabled)());
@@ -31276,7 +31281,7 @@ async function build({ verbose, dev, skipVersionCheck }) {
     const isSquidConnector = (0, process_env_utils_1.isEnvVarTruthy)('SQUID_CONNECTOR');
     const specsStart = Date.now();
     const openApiSpecAndControllers = await tsoa_utils_1.TsoaUtils.generateAllSpecs(verbose, !isSquidConnector);
-    console.debug((0, log_utils_1.timeSince)(specsStart, '⏱ TsoaUtils.generateAllSpecs '));
+    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);
     const webpackConfigPath = isUserConfigMode ? resolve_2.USER_WEBPACK_CONFIG_PATH : resolve_2.BUILT_IN_WEBPACK_CONFIG_PATH;
@@ -31291,7 +31296,7 @@ async function build({ verbose, dev, skipVersionCheck }) {
         await new Promise((resolve, reject) => {
             (0, webpack_1.default)(webpackConfig, (err, stats) => {
                 if (err) {
-                    console.debug((0, log_utils_1.timeSince)(webpackStart, '⏱ webpack build '));
+                    console.debug((0, log_utils_1.timeSince)(webpackStart, 'Webpack build time '));
                     console.error('Build failed a fatal error.');
                     return reject(err);
                 }
@@ -31308,10 +31313,10 @@ async function build({ verbose, dev, skipVersionCheck }) {
                     }));
                 }
                 if (stats?.hasErrors()) {
-                    console.debug((0, log_utils_1.timeSince)(webpackStart, '⏱ webpack build '));
+                    console.debug((0, log_utils_1.timeSince)(webpackStart, 'Webpack build time '));
                     return reject(new Error('Build failed with errors.'));
                 }
-                console.debug((0, log_utils_1.timeSince)(webpackStart, '⏱ webpack build '));
+                console.debug((0, log_utils_1.timeSince)(webpackStart, 'Webpack build time '));
                 console.log('Build succeeded.');
                 resolve();
             });
@@ -31321,21 +31326,25 @@ async function build({ verbose, dev, skipVersionCheck }) {
             console.debug('Generating connector metadata...');
             const metadataStart = Date.now();
             await generateConnectorMetadata(distPath);
-            console.debug((0, log_utils_1.timeSince)(metadataStart, '⏱ generateConnectorMetadata '));
+            console.debug((0, log_utils_1.timeSince)(metadataStart, 'Connector metadata generation time '));
             // Add metadata to bundle.zip.
+            const metadataBundleStart = Date.now();
             const zipPath = path_1.default.join(distPath, 'bundle.zip');
             const zip = new adm_zip_1.default(zipPath);
             zip.addLocalFile(path_1.default.join(distPath, connector_types_1.CONNECTOR_METADATA_JSON_FILE));
             zip.writeZip(zipPath);
             console.debug('Added connector metadata to bundle.zip');
+            console.debug((0, log_utils_1.timeSince)(metadataBundleStart, 'Connector metadata bundling time '));
         }
         // Show version check warning after successful build.
-        await displayVersionWarning(versionCheckPromise);
-        console.debug((0, log_utils_1.timeSince)(buildPhaseStart, '⏱ Total CLI build time '));
+        await (0, version_check_1.displayVersionWarningIfOutdated)(versionCheckPromise);
+        (0, update_skills_1.displaySkillsWarningIfOutdated)();
+        console.debug((0, log_utils_1.timeSince)(buildPhaseStart, 'Build time '));
     }
     catch (e) {
         // Show a version check warning even if the build failed.
-        await displayVersionWarning(versionCheckPromise);
+        await (0, version_check_1.displayVersionWarningIfOutdated)(versionCheckPromise);
+        (0, update_skills_1.displaySkillsWarningIfOutdated)();
         const errorMessage = (0, assertic_1.getMessageFromError)(e);
         console.debug(`Exiting with error: ${errorMessage}`);
         (0, process_utils_1.exitWithError)(errorMessage);
@@ -31443,11 +31452,14 @@ const enable_debug_decorator_utils_1 = __webpack_require__(8700);
 const global_utils_1 = __webpack_require__(6334);
 const http_1 = __webpack_require__(866);
 const shell_runner_1 = __webpack_require__(3089);
+const packageJson = __importStar(__webpack_require__(8330));
 const environment_1 = __webpack_require__(722);
 const process_utils_1 = __webpack_require__(8251);
+const version_check_1 = __webpack_require__(4827);
 async function deploy(consoleRegion, appId, bundlePath, apiKey, verbose, direct, isUserSpecifiedPath, skipBuild, internalApiKey, environmentId) {
     (0, global_utils_1.enableDebugLogs)(verbose || (0, global_utils_1.isDebugEnabled)());
     (0, logpipes_1.installConsoleOverrides)(enable_debug_decorator_utils_1.debugLogFilterPipe);
+    const versionCheckPromise = (0, version_check_1.checkCliVersion)(packageJson.version);
     if (!direct && !isUserSpecifiedPath && !skipBuild) {
         console.log('Building code bundle...');
         await (0, shell_runner_1.runInShell)('npm run build');
@@ -31477,8 +31489,10 @@ async function deploy(consoleRegion, appId, bundlePath, apiKey, verbose, direct,
             (0, process_utils_1.exitWithError)('Unable to deploy bundle:', await response.text());
         }
         console.log('Code deployed');
+        await (0, version_check_1.displayVersionWarningIfOutdated)(versionCheckPromise);
     }
     catch (error) {
+        await (0, version_check_1.displayVersionWarningIfOutdated)(versionCheckPromise);
         console.debug('Error deploying bundle:', error);
         const errorMessage = (0, assertic_1.getMessageFromError)(error, '');
         (0, process_utils_1.exitWithError)('Unable to deploy bundle:', errorMessage || error);
@@ -31690,6 +31704,7 @@ const init_webpack_1 = __webpack_require__(1134);
 const sample_1 = __webpack_require__(4328);
 const start_1 = __webpack_require__(496);
 const undeploy_1 = __webpack_require__(7097);
+const update_skills_1 = __webpack_require__(7286);
 const process_utils_1 = __webpack_require__(8251);
 const validate_1 = __webpack_require__(2246);
 function setupDotEnv(baseDir) {
@@ -31714,6 +31729,7 @@ function run() {
     setupInitWebpackCommand(yargs_1.default);
     setupStartCommand(yargs_1.default);
     setupUndeployCommand(yargs_1.default);
+    setupUpdateSkillsCommand(yargs_1.default);
     yargs_1.default.parse();
 }
 function setupStartCommand(yargs) {
@@ -31844,6 +31860,11 @@ function setupBuildCommand(yargs) {
         await (0, build_1.build)({ verbose: !!argv.verbose, dev: !!argv.dev, skipVersionCheck: !!argv['skip-version-check'] });
     });
 }
+function setupUpdateSkillsCommand(yargs) {
+    yargs.command('update-skills', 'Updates Squid Claude skills to the latest version', () => { }, async () => {
+        await (0, update_skills_1.updateSkills)();
+    });
+}
 run();
 function attachAppIdOption(yargs, demandOption) {
     yargs.option('appId', {
@@ -31973,6 +31994,39 @@ function getConsoleRegionFromAppRegion(appRegion) {
 
 "use strict";
 
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -31987,14 +32041,18 @@ const utils_1 = __webpack_require__(1215);
 const enable_debug_decorator_utils_1 = __webpack_require__(8700);
 const global_utils_1 = __webpack_require__(6334);
 const shell_runner_1 = __webpack_require__(3089);
+const packageJson = __importStar(__webpack_require__(8330));
+const update_skills_1 = __webpack_require__(7286);
 const git_utils_1 = __webpack_require__(954);
 const logging_1 = __webpack_require__(443);
 const process_utils_1 = __webpack_require__(8251);
 const report_utils_1 = __webpack_require__(3066);
+const version_check_1 = __webpack_require__(4827);
 const ORG = 'squid-cloud-samples';
 async function initSample(consoleRegion, isOnPremConsole, dirPath, appId, apiKey, environmentId, squidDeveloperId, region, templateName, verbose = false) {
     (0, global_utils_1.enableDebugLogs)(verbose || (0, global_utils_1.isDebugEnabled)());
     (0, logpipes_1.installConsoleOverrides)(enable_debug_decorator_utils_1.debugLogFilterPipe);
+    const versionCheckPromise = (0, version_check_1.checkCliVersion)(packageJson.version);
     try {
         await promises_1.default.stat(path_1.default.resolve(dirPath));
         (0, process_utils_1.exitWithError)(`Project already exists: ${dirPath}`);
@@ -32014,42 +32072,25 @@ async function initSample(consoleRegion, isOnPremConsole, dirPath, appId, apiKey
     catch {
         (0, process_utils_1.exitWithError)(`Unable to download repository: ${templateRepoPath}`);
     }
-    // Copy the squid-development and squid-react-development skills if they do not already exist.
+    // Copy Squid skills if they don't already exist.
     const projectPath = path_1.default.resolve(dirPath);
     const skillsDir = path_1.default.join(projectPath, '.claude', 'skills');
-    const squidSkillSourcePath = path_1.default.join(__dirname, 'resources', 'claude', 'skills', 'squid-development');
-    const squidSkillDestPath = path_1.default.join(skillsDir, 'squid-development');
-    if (await (0, utils_1.checkFileOrDirExists)(squidSkillDestPath)) {
-        console.debug('Squid development skill already exists, skipping...');
-    }
-    else {
-        // Skill doesn't exist, copy it.
-        try {
-            await promises_1.default.mkdir(skillsDir, { recursive: true });
-            await promises_1.default.cp(squidSkillSourcePath, squidSkillDestPath, { recursive: true });
-            console.debug('Squid development skill copied successfully');
-        }
-        catch (error) {
-            // Non-fatal: log the error but continue with initialization.
-            console.debug(`Warning: Could not copy Squid development skill: ${(0, assertic_1.getMessageFromError)(error)}`);
-        }
-    }
-    // Copy the squid-react-development skill if it doesn't already exist.
-    const reactSkillSourcePath = path_1.default.join(__dirname, 'resources', 'claude', 'skills', 'squid-react-development');
-    const reactSkillDestPath = path_1.default.join(skillsDir, 'squid-react-development');
-    if (await (0, utils_1.checkFileOrDirExists)(reactSkillDestPath)) {
-        console.debug('Squid React development skill already exists, skipping...');
-    }
-    else {
-        // Skill doesn't exist, copy it.
-        try {
-            await promises_1.default.mkdir(skillsDir, { recursive: true });
-            await promises_1.default.cp(reactSkillSourcePath, reactSkillDestPath, { recursive: true });
-            console.debug('Squid React development skill copied successfully');
+    for (const skillName of update_skills_1.SQUID_SKILLS) {
+        const sourcePath = path_1.default.join(__dirname, 'resources', 'claude', 'skills', skillName);
+        const destPath = path_1.default.join(skillsDir, skillName);
+        if (await (0, utils_1.checkFileOrDirExists)(destPath)) {
+            console.debug(`${skillName} skill already exists, skipping...`);
         }
-        catch (error) {
-            // Non-fatal: log the error but continue with initialization.
-            console.debug(`Warning: Could not copy Squid React development skill: ${(0, assertic_1.getMessageFromError)(error)}`);
+        else {
+            try {
+                await promises_1.default.mkdir(skillsDir, { recursive: true });
+                await promises_1.default.cp(sourcePath, destPath, { recursive: true });
+                console.debug(`${skillName} skill copied successfully`);
+            }
+            catch (error) {
+                // Non-fatal: log the error but continue with initialization.
+                console.debug(`Warning: Could not copy ${skillName} skill: ${(0, assertic_1.getMessageFromError)(error)}`);
+            }
         }
     }
     console.log('Installing dependencies...');
@@ -32112,6 +32153,7 @@ ${(0, logging_1.primary)('Done. Next steps:')}
   npm run start
 `);
     }
+    await (0, version_check_1.displayVersionWarningIfOutdated)(versionCheckPromise);
 }
 
 
@@ -32164,12 +32206,18 @@ const fs = __importStar(__webpack_require__(1943));
 const path_1 = __importDefault(__webpack_require__(6928));
 const resolve_1 = __webpack_require__(412);
 const shell_runner_1 = __webpack_require__(3089);
+const cliPackageJson = __importStar(__webpack_require__(8330));
+const update_skills_1 = __webpack_require__(7286);
 const logging_1 = __webpack_require__(443);
 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 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...'));
     const modulePath = await (0, resolve_1.findModulePath)('@squidcloud/local-backend');
     if (!modulePath) {
@@ -32250,6 +32298,149 @@ async function undeploy(consoleRegion, appId, apiKey, environmentId) {
 }
 
 
+/***/ },
+
+/***/ 7286
+(__unused_webpack_module, exports, __webpack_require__) {
+
+"use strict";
+
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", ({ value: true }));
+exports.SQUID_SKILLS = void 0;
+exports.getSkillsNeedingUpdate = getSkillsNeedingUpdate;
+exports.displaySkillsWarningIfOutdated = displaySkillsWarningIfOutdated;
+exports.updateSkills = updateSkills;
+const chalk_1 = __importDefault(__webpack_require__(7459));
+const fsSync = __importStar(__webpack_require__(9896));
+const fs = __importStar(__webpack_require__(1943));
+const path_1 = __importDefault(__webpack_require__(6928));
+const logging_1 = __webpack_require__(443);
+const validate_1 = __webpack_require__(2246);
+/** List of Squid-owned skills that can be copied/updated. */
+exports.SQUID_SKILLS = ['squid-development', 'squid-react-development'];
+/**
+ * Gets all files in a directory, sorted for consistent ordering.
+ */
+function getFilesSorted(dir) {
+    const files = fsSync.readdirSync(dir, { recursive: true });
+    return files.filter(file => fsSync.statSync(path_1.default.join(dir, file)).isFile()).sort();
+}
+/**
+ * Checks if a specific skill needs to be updated.
+ * Returns true if project is missing skill or any CLI file is missing/different.
+ * Extra files in project are ignored
+ */
+function skillNeedsUpdate(skillName) {
+    const projectSkillPath = path_1.default.join(process.cwd(), '.claude', 'skills', skillName);
+    const cliSkillPath = path_1.default.join(__dirname, 'resources', 'claude', 'skills', skillName);
+    // If CLI doesn't have this skill bundled, nothing to update.
+    if (!fsSync.existsSync(cliSkillPath)) {
+        return false;
+    }
+    // If project doesn't have this skill but CLI does, it needs to be added.
+    if (!fsSync.existsSync(projectSkillPath)) {
+        return true;
+    }
+    // Check each CLI file exists in project with same content.
+    const cliFiles = getFilesSorted(cliSkillPath);
+    for (const file of cliFiles) {
+        const cliFilePath = path_1.default.join(cliSkillPath, file);
+        const projectFilePath = path_1.default.join(projectSkillPath, file);
+        // Project missing a file that CLI has.
+        if (!fsSync.existsSync(projectFilePath)) {
+            return true;
+        }
+        // Content differs (normalize line endings for cross-platform compatibility).
+        const cliContent = fsSync.readFileSync(cliFilePath, 'utf8').replace(/\r\n/g, '\n');
+        const projectContent = fsSync.readFileSync(projectFilePath, 'utf8').replace(/\r\n/g, '\n');
+        if (cliContent !== projectContent) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Returns a list of skills that need to be updated (missing or outdated).
+ */
+function getSkillsNeedingUpdate() {
+    return exports.SQUID_SKILLS.filter(skillNeedsUpdate);
+}
+function displaySkillsWarningIfOutdated() {
+    try {
+        const skillsToUpdate = getSkillsNeedingUpdate();
+        if (skillsToUpdate.length > 0) {
+            console.warn(chalk_1.default.yellow(`⚠ Squid skills need updating (${skillsToUpdate.join(', ')}). Run: squid update-skills`));
+        }
+    }
+    catch (_ignored) { }
+}
+/**
+ * Updates all Squid-owned skills to the latest version bundled with the CLI.
+ */
+async function updateSkills() {
+    await (0, validate_1.validateSquidProject)();
+    const skillsToUpdate = getSkillsNeedingUpdate();
+    if (skillsToUpdate.length === 0) {
+        console.log(chalk_1.default.green('✓ Skills already up to date'));
+        return;
+    }
+    const skillsDir = path_1.default.join(process.cwd(), '.claude', 'skills');
+    let updatedCount = 0;
+    for (const skillName of skillsToUpdate) {
+        const cliSkillPath = path_1.default.join(__dirname, 'resources', 'claude', 'skills', skillName);
+        const projectSkillPath = path_1.default.join(skillsDir, skillName);
+        try {
+            await fs.mkdir(skillsDir, { recursive: true });
+            await fs.cp(cliSkillPath, projectSkillPath, { recursive: true });
+            console.log(`Updated ${(0, logging_1.primary)(skillName)} skill`);
+            updatedCount++;
+        }
+        catch (_error) {
+            console.warn(`Warning: Could not update ${skillName} skill`);
+        }
+    }
+    if (updatedCount > 0) {
+        console.log(chalk_1.default.green(`✓ ${updatedCount} skill(s) updated successfully`));
+    }
+}
+
+
 /***/ },
 
 /***/ 954
@@ -32505,6 +32696,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", ({ value: true }));
 exports.checkCliVersion = checkCliVersion;
+exports.displayVersionWarningIfOutdated = displayVersionWarningIfOutdated;
 const assertic_1 = __webpack_require__(3205);
 const chalk_1 = __importDefault(__webpack_require__(7459));
 const time_units_1 = __webpack_require__(1929);
@@ -32581,6 +32773,15 @@ function parseVersion(version) {
 function formatWarningMessage(currentVersion, latestVersion) {
     return chalk_1.default.yellow(`⚠ Your @squidcloud/cli (${currentVersion}) is outdated. Latest: ${latestVersion}. Update: npm install -g @squidcloud/cli@latest`);
 }
+async function displayVersionWarningIfOutdated(versionCheckPromise) {
+    try {
+        const versionWarning = await versionCheckPromise;
+        if (versionWarning) {
+            console.warn(versionWarning);
+        }
+    }
+    catch (_ignored) { }
+}
 
 
 /***/ },
@@ -36937,7 +37138,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.449","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.449","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.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"}}');
 
 /***/ }
 

package/dist/resources/claude/skills/squid-development/SKILL.md

@@ -18,7 +18,7 @@ Squid is a backend-as-a-service platform that provides:
 - **[client.md](reference/client.md)** → client SDK, initialization, setup, auth, login, tokens, OAuth, appId, region, environmentId, apiKey, authProvider, getToken, setAuthProvider, Squid client, frontend, collection, executeFunction, executeFunctionWithHeaders, getWebhookUrl, externalAuth, saveAuthCode, getAccessToken, storage, uploadFile, downloadUrl, queues, produce, consume, distributed locks, acquireLock, withLock, web, aiSearch, getUrlContent, createShortUrl, jobs, getJob, awaitJob, observability, metrics, reportMetric, queryMetrics, notifications, publishNotification, observeNotifications
 - **[console.md](reference/console.md)** → Squid Console, web UI, organizations, applications, AI Studio, knowledge bases, integrations, monitoring, logs, API keys, secrets, testing, debugging, profile settings, management API keys
 - **[ai.md](reference/ai.md)** → AI agents, chat, ask, askWithAnnotations, askAsync, askWithVoiceResponse, transcribeAndChat, transcribeAndAsk, knowledge bases, RAG, embeddings, image generation, audio, transcription, text-to-speech, TTS, connectedAgents, connectedIntegrations, connectedKnowledgeBases, @aiFunction, @secureAiAgent, @secureAiQuery, memory, memoryOptions, voiceOptions, OpenAI, Anthropic, Gemini, Grok, DALL-E, Whisper, MCP, @mcpServer, @mcpTool, executeAiQuery, executeAiApiCall, extraction, createPdf, upsert agent, listAgents
-- **[databases.md](reference/databases.md)** → collections, documents, queries, subscriptions, snapshots, insert, update, delete, CRUD, real-time, dereference, pagination, transactions, query operators, eq, neq, gt, gte, lt, lte, like, in, nin, arrayIncludesSome, arrayIncludesAll, sortBy, limit, join queries, OR queries, @trigger, native queries, SQL, MongoDB, Elasticsearch, incrementInPath, decrementInPath, watch changes, doc()
+- **[databases.md](reference/databases.md)** → collections, documents, queries, subscriptions, snapshots, insert, update, delete, CRUD, real-time, dereference, pagination, transactions, query operators, eq, neq, gt, gte, lt, lte, like, in, nin, arrayIncludesSome, arrayIncludesAll, sortBy, limit, join queries, OR queries, @trigger, native queries, SQL, MongoDB, Elasticsearch, incrementInPath, decrementInPath, watch changes, doc(), projectFields, field projection, __docId__, __id
 - **[backend.md](reference/backend.md)** → SquidService, @executable, @webhook, @trigger, TriggerRequest, @scheduler, @limits, rate limiting, quotas, decorators, backend functions, WebhookRequest, CronExpression, cron, file handling, SquidFile, getUserAuth, isAuthenticated, assertIsAuthenticated, createWebhookResponse, this.squid, this.secrets, @clientConnectionStateHandler, CLI, squid init, squid start, squid deploy, squid build, project structure
 - **[security.md](reference/security.md)** → security rules, @secureDatabase, @secureCollection, @secureTopic, @secureStorage, @secureApi, @secureNativeQuery, @secureAiQuery, @secureAiAgent, @secureDistributedLock, @secureGraphQL, QueryContext, MutationContext, isSubqueryOf, affectsPath, permissions, authorization, row-level security, role-based access
 - **[admin.md](reference/admin.md)** → ManagementClient, management API keys, organizations, applications, programmatic management, CI/CD, automation, integrations admin, secrets admin, upsertIntegration, discoverDataConnectionSchema, testDataConnection, createOrganization, createApplication

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

@@ -11,6 +11,7 @@ Squid provides database functionality similar to Firestore but more powerful, wi
 - OR Queries
 - Join Queries
 - Dereference
+- Field Projection
 - Pagination
 - Watch Changes
 - Transactions
@@ -314,6 +315,144 @@ const userData = await users.query()
 // - You need DocumentReference methods like .update() or .delete()
 ```
 
+## Field Projection
+
+Return only specific fields from queries to reduce bandwidth and improve performance.
+
+```typescript
+// Basic usage
+const results = await users.query()
+  .projectFields(['name', 'email'])
+  .dereference()
+  .snapshot();
+
+// Works with all query methods
+const results = await users.query()
+  .eq('status', 'active')
+  .sortBy('name')
+  .limit(50)
+  .projectFields(['name', 'email', 'status'])
+  .dereference()
+  .snapshot();
+```
+
+### Always-Included Fields
+
+These fields are **always** included in results regardless of projection:
+
+| Field | Present On | Description |
+|-------|------------|-------------|
+| `__docId__` | All integrations | JSON-stringified document identifier |
+| `__id` | `built_in_db` only | Primary key value |
+
+For **composite primary keys**, individual key fields are automatically spread to the top level:
+```typescript
+// Document with composite PK (pk1, pk2)
+// Result includes: { name: 'Alice', __docId__: '{"pk1":"a","pk2":1}', pk1: 'a', pk2: 1 }
+```
+
+### Nested Fields
+
+Use dot notation for nested paths:
+```typescript
+const results = await users.query()
+  .projectFields(['name', 'address.city', 'address.zip'])
+  .dereference()
+  .snapshot();
+// Result: { name: 'Alice', address: { city: 'NYC', zip: '10001' } }
+// Other address fields NOT included
+```
+
+### Validation Rules
+
+**Filter fields must be projected:**
+```typescript
+// ERROR: Cannot filter by 'email' not in projectFields
+users.query().eq('email', 'test@example.com').projectFields(['name']);
+
+// CORRECT: Include filter field
+users.query().eq('email', 'test@example.com').projectFields(['name', 'email']);
+```
+
+**Sort fields must be projected:**
+```typescript
+// ERROR: Cannot sort by 'email' not in projectFields
+users.query().sortBy('email').projectFields(['name']);
+
+// CORRECT: Include sort field
+users.query().sortBy('email').projectFields(['name', 'email']);
+```
+
+**Exception:** `__docId__` can always be used for filtering/sorting without being in projection:
+```typescript
+// ALLOWED: __docId__ is always available
+users.query().where('__docId__', '>=', 'user_100').projectFields(['name']);
+users.query().sortBy('__docId__').projectFields(['name']);
+```
+
+**Composite conditions must use projected fields:**
+```typescript
+// ERROR: Cannot filter by 'email' not in projectFields
+users.query().projectFields(['name']).addCompositeCondition([{ fieldName: 'email', operator: '>=', value: 'a' }]);
+
+// ALLOWED: __docId__ works without projection
+users.query().projectFields(['name']).addCompositeCondition([{ fieldName: '__docId__', operator: '>=', value: 'a' }]);
+```
+
+**Calling projectFields twice:** Second call must be a subset of the first:
+```typescript
+// ALLOWED: ['name'] is subset of ['name', 'age', 'email']
+users.query().projectFields(['name', 'age', 'email']).projectFields(['name']);
+
+// ERROR: 'email' was not in first projection
+users.query().projectFields(['name', 'age']).projectFields(['name', 'email']);
+```
+
+**Cloning:** `projectFields` returns a cloned QueryBuilder - original is unmodified:
+```typescript
+const base = collection.query().where('age', '>=', 18);
+const projected = base.projectFields(['name']);  // Returns clone
+// base still returns all fields, projected returns only 'name'
+```
+
+### Empty Array Behavior
+
+| Integration | Behavior |
+|-------------|----------|
+| `built_in_db` | Returns documents with only `__docId__` and `__id`, no user fields |
+| External DBs | **Throws error** - must specify at least one field |
+
+```typescript
+// built_in_db: returns { __docId__: '...', __id: '...' }
+await builtInCollection.query().projectFields([]).snapshot();
+
+// External DB: throws error
+await postgresCollection.query().projectFields([]); // Error!
+```
+
+### Edge Cases
+
+- **Non-existent fields:** Silently ignored, no error thrown
+- **Duplicate fields:** Handled gracefully, no duplication in results
+- **Including `__id` explicitly:** Not duplicated if already auto-included
+- **Optimistic updates:** Local updates respect the projection - document store only contains projected fields. Multiple subscriptions with different projections maintain isolated views of the same document.
+
+### Without dereference()
+
+When not using `dereference()`, you get `DocumentReference` objects. Access projected data via `.data`:
+```typescript
+const refs = await users.query().projectFields(['name']).snapshot();
+console.log(refs[0].data.name);  // Projected data on .data property
+```
+
+### Works With
+
+- One-time queries (`.snapshot()`)
+- Real-time subscriptions (`.snapshots()`)
+- Pagination (`.paginate()`)
+- Join queries
+- All database integrations (MongoDB, PostgreSQL, MySQL, ClickHouse, MS SQL, built_in_db)
+
 ## Pagination
 
 ```typescript

package/dist/resources/user-build.webpack.config.js

@@ -21,6 +21,15 @@ module.exports = function (env, argv) {
       'bufferutil': 'commonjs bufferutil',
       'utf-8-validate': 'commonjs utf-8-validate',
     },
+    // Suppress warnings from dependencies that use dynamic requires.
+    // These are typically dev dependencies used during build and don't affect runtime.
+    ignoreWarnings: [
+      { module: /tsoa/ },
+      { module: /@tsoa\/cli/ },
+      { module: /handlebars/ },
+      { module: /typescript/ },
+      { module: /yargs/ },
+    ],
     output: {
       path: path.resolve(process.cwd(), 'dist'),
       filename: 'index.js',

package/package.json

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