dotguides

Author: yarabaelish-demo

.gemini/settings.json

@@ -2,7 +2,7 @@
   "experimental": {
     "extensionManagement": true
   },
-    "mcp": {
+  "mcp": {
     "enabled": true,
     "excluded": ["gemini-cloud-assist-mcp", "firebase", "julesServer", "securityServer", "osvScanner", "observability"]
   }

.gitignore

@@ -14,4 +14,5 @@ function_output.json
 serverlog_stderr.txt
 serverlog_stdout.txt
 temp
-test/conformance/package-lock.json
+test/conformance/package-lock.json
+firebase-debug.log

.guides/config.json

@@ -0,0 +1 @@
+{}

.guides/docs/runFunctions.prompt

@@ -0,0 +1,15 @@
+---
+title: run a function from a plain Node.js script
+description: when to invoke a function from the server code instead of using the Functions Framework CLI
+---
+It is possible to serve a remote function directly from a plain script instead of the Functions Framework CLI.
+
+The benefits include:
+
+- Functions can be started with node directly: `node src/server.js`
+- Furnctions can be used with node watcher without extra setup: `node watch src/server.js`
+- Better Typescript support with ts-node/tsx: `tsx --watch src/server.ts`
+- Easier debugging in IDEs because it is much easier to attach a debugger (like in VS Code or WebStorm) a plain Node.js script (node main.js) than to a command-line tool spawned via npx
+- Custom initialization code because running code before server starts can be useful
+
+When adding integration tests, choose this option so that you can easily stop the server instance within your test suite, rather than spawning a child process to run the CLI.

.guides/usage.prompt

@@ -0,0 +1,2 @@
+This is a local development version of the package.
+

.kiro/steering/product.md

@@ -0,0 +1,19 @@
+# Product Overview
+
+The Google Cloud Functions Framework for Node.js is an open-source FaaS (Function as a Service) framework built on Express.js for writing portable Node.js functions.
+
+## Core Purpose
+- Enables writing lightweight functions that run across multiple environments (Google Cloud Functions, Cloud Run, local development, Knative)
+- Provides automatic request handling and event unmarshalling
+- Supports multiple function signatures: HTTP, background events, and CloudEvents
+- Eliminates the need to write HTTP server boilerplate
+
+## Key Features
+- Local development server for testing
+- Automatic CloudEvents spec compliance
+- Portable between serverless platforms
+- Express.js-based request/response handling
+- Support for Google Cloud Functions event payloads
+
+## Target Users
+Developers building serverless functions for Google Cloud Platform and other Knative-compatible environments.

.kiro/steering/structure.md

@@ -0,0 +1,57 @@
+# Project Structure
+
+## Root Directory
+- `package.json` - Main package configuration and dependencies
+- `tsconfig.json` - TypeScript configuration extending gts
+- `api-extractor.json` - API documentation extraction config
+- `.eslintrc.json` - ESLint configuration extending gts
+- `.prettierrc.js` - Prettier configuration via gts
+
+## Source Code (`src/`)
+- `index.ts` - Main public API exports
+- `main.ts` - CLI entry point and server startup
+- `functions.ts` - Core function registration and handling
+- `function_registry.ts` - Function registration system
+- `function_wrappers.ts` - Function signature adapters
+- `server.ts` - Express server setup and configuration
+- `invoker.ts` - Function invocation logic
+- `loader.ts` - Dynamic function loading
+- `types.ts` - TypeScript type definitions
+- `options.ts` - Configuration and command-line options
+- `logger.ts` - Logging utilities
+- `testing.ts` - Testing utilities (exported separately)
+
+### Middleware (`src/middleware/`)
+- `background_event_to_cloud_event.ts` - Event format conversion
+- `cloud_event_to_background_event.ts` - Reverse event conversion
+- `timeout.ts` - Request timeout handling
+
+### Other Core Files
+- `cloud_events.ts` - CloudEvents specification handling
+- `execution_context.ts` - Request execution context
+- `async_local_storage.ts` - Async context management
+- `pubsub_middleware.ts` - Pub/Sub specific middleware
+
+## Testing (`test/`)
+- Mirror structure of `src/` directory
+- `integration/` - Integration tests for different function types
+- `system-test/` - End-to-end system tests
+- `conformance/` - Conformance test setup
+- `data/` - Test fixtures and sample functions
+
+## Build Output (`build/`)
+- Generated JavaScript and type definitions
+- Mirrors `src/` structure
+- Main exports: `build/src/index.js` and `build/src/index.d.ts`
+
+## Documentation (`docs/`)
+- `generated/` - Auto-generated API documentation
+- Various markdown guides for specific features
+- `esm/` - ESM usage examples
+
+## Conventions
+- TypeScript source files in `src/`
+- Corresponding test files in `test/` with same name
+- Middleware components in dedicated subdirectory
+- Integration tests grouped by function signature type
+- All exports go through `src/index.ts` for clean public API

.kiro/steering/tech.md

@@ -0,0 +1,56 @@
+# Technology Stack
+
+## Core Technologies
+- **Language**: TypeScript/JavaScript (Node.js >=10.0.0)
+- **Framework**: Express.js for HTTP handling
+- **Build System**: TypeScript compiler with Google TypeScript Style (gts)
+- **Testing**: Mocha test framework
+- **Package Manager**: npm
+
+## Key Dependencies
+- `express` - HTTP server framework
+- `cloudevents` - CloudEvents specification support
+- `body-parser` - Request body parsing
+- `minimist` - Command-line argument parsing
+
+## Development Tools
+- **Linting**: ESLint with Google TypeScript Style (gts)
+- **Formatting**: Prettier (configured via gts)
+- **Type Checking**: TypeScript 5.8.2
+- **API Documentation**: Microsoft API Extractor
+
+## Common Commands
+
+### Development
+```bash
+npm run build          # Clean, compile TypeScript
+npm run compile        # Compile TypeScript only
+npm run watch          # Compile with watch mode
+npm run clean          # Clean build directory
+```
+
+### Testing
+```bash
+npm test              # Run unit tests
+npm run conformance   # Run conformance tests (requires Go 1.16+)
+npm run pretest       # Compile before testing
+```
+
+### Code Quality
+```bash
+npm run check         # Run gts linting
+npm run fix           # Auto-fix linting issues
+npm run docs          # Generate API documentation
+```
+
+### Local Development
+```bash
+npx @google-cloud/functions-framework --target=functionName
+functions-framework --target=functionName  # If globally installed
+```
+
+## Build Output
+- Compiled JavaScript: `build/src/`
+- Type definitions: `build/src/**/*.d.ts`
+- Main entry: `build/src/index.js`
+- CLI binary: `build/src/main.js`