### Install Project Dependencies

Source: https://github.com/giselles-ai/giselle/blob/main/apps/playground/README.md

Installs all necessary project dependencies using the pnpm package manager. This command should be run after cloning the repository or making changes to the package.json file.

```sh
pnpm install
```

--------------------------------

### Verify Node.js installation

Source: https://github.com/giselles-ai/giselle/blob/main/docs/vibe/02-nodejs.md

Checks if Node.js has been installed correctly and displays its version. This command should be run after installing Node.js via NVM and setting the version.

```bash
node --version
```

--------------------------------

### Start Giselle Playground Development Server

Source: https://github.com/giselles-ai/giselle/blob/main/docs/vibe/01-introduction.md

Starts the development server for the Giselle playground. This command requires dependencies to be installed and environment variables to be configured. It typically runs on port 3000, but can be customized using the PORT environment variable.

```bash
pnpm dev
```

```bash
PORT=6180 pnpm dev
```

--------------------------------

### Install NVM using wget

Source: https://github.com/giselles-ai/giselle/blob/main/docs/vibe/02-nodejs.md

Installs Node Version Manager (NVM) using the wget command. This is an alternative method for downloading and executing the NVM installation script on macOS and Linux systems. Ensure wget is installed.

```bash
wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.2/install.sh | bash
```

--------------------------------

### Install pnpm package manager

Source: https://github.com/giselles-ai/giselle/blob/main/docs/vibe/02-nodejs.md

Installs the pnpm package manager using its recommended installation script. This script downloads and sets up pnpm globally on your system, making it available for managing project dependencies.

```bash
curl -fsSL https://get.pnpm.io/install.sh | sh -
```

--------------------------------

### Start Development Server

Source: https://github.com/giselles-ai/giselle/blob/main/apps/playground/README.md

Starts the development server using pnpm and turbo. By default, it runs on port 3000, which is the standard for Next.js applications. This command is essential for running the project locally.

```sh
pnpm turbo dev
```

--------------------------------

### Install Giselle Playground Dependencies

Source: https://github.com/giselles-ai/giselle/blob/main/docs/vibe/01-introduction.md

Installs all project dependencies required for the Giselle playground. This command relies on Node.js and pnpm being installed on your system.

```bash
pnpm install
```

--------------------------------

### Install NVM using curl

Source: https://github.com/giselles-ai/giselle/blob/main/docs/vibe/02-nodejs.md

Installs Node Version Manager (NVM) using the curl command. This is the primary method for downloading and executing the NVM installation script on macOS and Linux systems. Ensure curl is installed.

```bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.2/install.sh | bash
```

--------------------------------

### Verify pnpm installation

Source: https://github.com/giselles-ai/giselle/blob/main/docs/vibe/02-nodejs.md

Checks if pnpm has been installed correctly by displaying its version. This command should be run after installing pnpm and restarting the terminal.

```bash
pnpm --version
```

--------------------------------

### Start Development Server on Custom Port

Source: https://github.com/giselles-ai/giselle/blob/main/apps/playground/README.md

Starts the development server on a custom port by setting the PORT environment variable. This is useful if the default port 3000 is already in use by another application.

```sh
PORT=6180 pnpm turbo dev
```

--------------------------------

### Example Supabase Migration Filename

Source: https://github.com/giselles-ai/giselle/blob/main/apps/studio.giselles.ai/migrations/system/README.md

Provides a concrete example of a migration file adhering to the specified naming convention, indicating a patch for storage policies.

```text
20250422_storage_patch_add_policy_to_public_bucket.sql
```

--------------------------------

### Install Dependencies with pnpm

Source: https://github.com/giselles-ai/giselle/blob/main/apps/studio.giselles.ai/README.md

Installs all project dependencies using the pnpm package manager. This command should be executed after setting up the `.env` file.

```sh
pnpm install
```

--------------------------------

### Verify NVM installation

Source: https://github.com/giselles-ai/giselle/blob/main/docs/vibe/02-nodejs.md

Checks if Node Version Manager (NVM) has been installed correctly by displaying its version. This command should be run after installing NVM and restarting the terminal.

```bash
nvm --version
```

--------------------------------

### Install specific Node.js version with NVM

Source: https://github.com/giselles-ai/giselle/blob/main/docs/vibe/02-nodejs.md

Installs a specific version of Node.js, such as 22.14.0, using NVM. This command fetches and installs the requested Node.js runtime and its associated npm package manager.

```bash
nvm install 22.14.0
```

--------------------------------

### Start Development Server with pnpm turbo

Source: https://github.com/giselles-ai/giselle/blob/main/apps/studio.giselles.ai/README.md

Starts the development server using pnpm turbo. This command enables hot reloading and watches for code changes during the development process.

```sh
pnpm turbo dev
```

--------------------------------

### TypeScript Chunker Configuration Examples

Source: https://github.com/giselles-ai/giselle/blob/main/packages/rag/src/chunker/__golden__/markdown-doc/char-limit.txt

Illustrates how to instantiate the LineChunker with default settings, custom line and overlap limits, and character-based limits. These examples show common usage patterns for configuring the chunking process.

```typescript
// Default configuration
const chunker1 = new LineChunker();

// Custom line limit
const chunker2 = new LineChunker({
  maxLines: 50,
  overlap: 10
});

// Character-based limits
const chunker3 = new LineChunker({
  maxLines: 100,
  maxChars: 1000,
  overlap: 20
});
```

--------------------------------

### Create .env.local File

Source: https://github.com/giselles-ai/giselle/blob/main/apps/playground/README.md

Creates the necessary .env.local file in the project root directory. This file is used to store environment-specific configurations, such as API keys.

```sh
touch .env.local
```

--------------------------------

### TypeScript Chunker Configuration Examples

Source: https://github.com/giselles-ai/giselle/blob/main/packages/rag/src/chunker/__golden__/markdown-doc/large-chunks.txt

Demonstrates different ways to instantiate and configure the `LineChunker` class with various options for line limits, character limits, and overlap. These examples show practical usage scenarios for the chunking library.

```typescript
// Default configuration
const chunker1 = new LineChunker();

// Custom line limit
const chunker2 = new LineChunker({
  maxLines: 50,
  overlap: 10
});

// Character-based limits
const chunker3 = new LineChunker({
  maxLines: 100,
  maxChars: 1000,
  overlap: 20
});
```

--------------------------------

### TypeScript Chunker Configuration Examples

Source: https://github.com/giselles-ai/giselle/blob/main/packages/rag/src/chunker/__golden__/markdown-doc/small-chunks.txt

Demonstrates various ways to instantiate and configure the LineChunker class. It covers default configuration, custom line limits with overlap, and character-based limits.

```typescript
// Default configuration
const chunker1 = new LineChunker();

// Custom line limit
const chunker2 = new LineChunker({
  maxLines: 50,
  overlap: 10
});

// Character-based limits
const chunker3 = new LineChunker({
  maxLines: 100,
  maxChars: 1000,
  overlap: 20
});
```

--------------------------------

### Configure Environment Variables

Source: https://github.com/giselles-ai/giselle/blob/main/apps/playground/README.md

Defines required and optional API keys within the .env.local file. At least one API key (OpenAI, Google Generative AI, or Anthropic) must be provided for the application to function correctly.

```.env
# Required (at least one of these)
OPENAI_API_KEY="YOUR_OPENAI_API_KEY"
# Optional
GOOGLE_GENERATIVE_AI_API_KEY="YOUR_GOOGLE_GENERATIVE_AI_API_KEY"
ANTHROPIC_API_KEY="YOUR_ANTHROPIC_API_KEY"
```

--------------------------------

### Supabase Vault Driver Initialization Example

Source: https://github.com/giselles-ai/giselle/blob/main/docs/adr/0003-managing-secrets.md

Demonstrates how to initialize a specific `VaultDriver` implementation using Supabase. It requires Supabase connection details and an optional encryption key for an additional layer of security.

```ts
// Example using Supabase Vault Driver
const supabaseVault = supabaseVaultDriver({
  url: process.env.SUPABASE_URL,
  privateKey: process.env.SUPABASE_PRIVATE_KEY,
  tableName: "secrets", // optional, default is "secrets"
  encryptionKey: process.env.ENCRYPTION_KEY, // optional additional encryption layer
});
```

--------------------------------

### Install Playwright Browsers in GitHub Actions Workflow

Source: https://github.com/giselles-ai/giselle/wiki/.pr_agent_accepted_suggestions

Adds a step to the GitHub Actions workflow (`e2e.yml`) to install Playwright browser dependencies. This ensures that Playwright has the necessary browser binaries available before running end-to-end tests.

```yaml
- name: Install Playwright browsers
  run: pnpm exec playwright install --with-deps
  working-directory: apps/studio.giselles.ai
```

--------------------------------

### Set Node.js version as default with NVM

Source: https://github.com/giselles-ai/giselle/blob/main/docs/vibe/02-nodejs.md

Sets the currently installed Node.js version (e.g., 22.14.0) as the default for the current shell session. This ensures the specified version is used for subsequent Node.js commands.

```bash
nvm use 22.14.0
```

--------------------------------

### Local Environment Port Configuration

Source: https://github.com/giselles-ai/giselle/blob/main/docs/vibe/03-clean-prs.md

Example of how to configure a local development port using a `.env.local` file. This avoids modifying `package.json` directly for port changes.

```dotenv
PORT=3001
```

--------------------------------

### TypeScript Chunker Configuration Examples

Source: https://github.com/giselles-ai/giselle/blob/main/packages/rag/src/chunker/__golden__/markdown-doc/no-overlap.txt

Demonstrates different ways to instantiate and configure the LineChunker class in TypeScript, including default settings and custom limits for lines, characters, and overlap.

```typescript
// Default configuration
const chunker1 = new LineChunker();

// Custom line limit
const chunker2 = new LineChunker({
  maxLines: 50,
  overlap: 10
});

// Character-based limits
const chunker3 = new LineChunker({
  maxLines: 100,
  maxChars: 1000,
  overlap: 20
});
```

--------------------------------

### TypeScript: Add Filesystem Error Handling (Blob Download)

Source: https://github.com/giselles-ai/giselle/wiki/.pr_agent_auto_best_practices

Provides an example of implementing error handling for filesystem operations within an asynchronous generator function, specifically for directory walking, to catch and log errors during traversal.

```typescript
async function* walk(dir: string): AsyncGenerator<string> {
    // Implementation details for walking a directory with error handling
}
```

--------------------------------

### Supabase Vault Driver SQL RPC Setup

Source: https://github.com/giselles-ai/giselle/blob/main/packages/supabase-driver/README.md

These SQL functions must be executed in the Supabase dashboard to create the necessary RPC endpoints for the Supabase Vault driver. The `create_secret` function encrypts plaintext, and `decrypt_secret` retrieves the decrypted secret using its ID.

```sql
create or replace function create_secret(plaintext text) returns text as $$
  select vault.create_secret(plaintext);
$$ language sql;

create or replace function decrypt_secret(secret_id uuid) returns text as $$
  select decrypted_secret
  from vault.decrypted_secrets
  where id = secret_id;
$$ language sql;
```

--------------------------------

### Build SDK Packages

Source: https://github.com/giselles-ai/giselle/blob/main/AGENTS.md

Builds all SDK packages using Turbo. Use the --filter flag to target specific packages.

```shell
turbo build --filter '@giselle-sdk/*' --filter giselle-sdk --cache=local:rw
```

--------------------------------

### Run Migration with .env File

Source: https://github.com/giselles-ai/giselle/blob/main/tools/storage-migration/README.md

Shows how to create a `.env` file with necessary credentials and run the migration script using Node.js's built-in `.env` file support.

```bash
# Create a .env file with the following content:
# SUPABASE_URL=https://your-project.supabase.co
# SUPABASE_SERVICE_KEY=your-service-key
# VERCEL_BLOB_KEY=your-vercel-blob-key

# Run with built-in env file support
node --env-file=.env --experimental-strip-types ./index.ts
```

--------------------------------

### Run Migration with Environment Variables

Source: https://github.com/giselles-ai/giselle/blob/main/tools/storage-migration/README.md

Demonstrates setting environment variables for Supabase and Vercel Blob, then executing the migration script using Node.js with experimental TypeScript support.

```bash
export SUPABASE_URL="https://your-project.supabase.co"
export SUPABASE_SERVICE_KEY="your-service-key"
export VERCEL_BLOB_KEY="your-vercel-blob-key"

node --experimental-strip-types index.ts
```

--------------------------------

### Format Code with Turbo

Source: https://github.com/giselles-ai/giselle/blob/main/AGENTS.md

Formats the entire project using Turbo. For individual files, prefer using the Biome CLI.

```shell
turbo format --cache=local:rw
```

--------------------------------

### Run Project Tests

Source: https://github.com/giselles-ai/giselle/blob/main/AGENTS.md

Executes all tests defined in the project using Turbo. For package-specific tests, use the pnpm command.

```shell
turbo test --cache=local:rw
```

--------------------------------

### Security: Strengthen Redirect URL Validation

Source: https://github.com/giselles-ai/giselle/wiki/.pr_agent_accepted_suggestions

Enhances security by strengthening the validation of redirect URLs to prevent open redirect attacks. The fix prevents protocol-relative URLs (e.g., `//evil.com`) by adding a check to ensure the URL does not start with `//`, in addition to the existing check for starting with `/`.

```TypeScript
// Validate returnUrl to prevent open redirect attacks
const validReturnUrl = returnUrl?.startsWith("/") && !returnUrl.startsWith("//") ? returnUrl : "/apps";
redirect(validReturnUrl);
```

--------------------------------

### Configure Environment Variables for LLM API Keys

Source: https://github.com/giselles-ai/giselle/blob/main/docs/vibe/01-introduction.md

Sets up environment variables by creating a `.env.local` file in the `apps/playground` directory. This file is crucial for providing API keys for various LLM providers like OpenAI, Anthropic, Google AI, Perplexity, and FAL AI, enabling the playground to function.

```env
# OpenAI API Key
OPENAI_API_KEY=your_openai_api_key

# Anthropic API Key
ANTHROPIC_API_KEY=your_anthropic_api_key

# Google AI API Key
GOOGLE_AI_API_KEY=your_google_ai_api_key

# Perplexity API Key
PERPLEXITY_API_KEY=your_perplexity_api_key

# FAL AI API Key
FAL_API_KEY=your_fal_api_key
```

--------------------------------

### Web Search Tool Initialization and Usage

Source: https://github.com/giselles-ai/giselle/blob/main/packages/web-search/README.md

Demonstrates how to create and use the web search tool with the self-made provider. It shows fetching URL content and accessing the HTML result.

```typescript
import { webSearch } from "@giselle-sdk/web-search";

const tool = webSearch({ provider: "self-made" });

const result = await tool.fetchUrl("https://example.com", ["html"]);
console.log(result.html); // HTML content
```

--------------------------------

### Environment Variables Configuration (.env)

Source: https://github.com/giselles-ai/giselle/blob/main/tools/storage-migration/README.md

Specifies the required environment variables for the migration tool, including Supabase URL, Supabase Service Key, and Vercel Blob Key, formatted for a `.env` file.

```env
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_KEY=your-service-key
VERCEL_BLOB_KEY=your-vercel-blob-key
```

--------------------------------

### TypeScript: Validate Environment Variables Early

Source: https://github.com/giselles-ai/giselle/wiki/.pr_agent_auto_best_practices

Demonstrates validating essential environment variables at the beginning of a test function. This prevents unnecessary setup and potential errors if required credentials or configurations are missing.

```typescript
const loginEmail = process.env.PLAYWRIGHT_LOGIN_EMAIL;
const loginPassword = process.env.PLAYWRIGHT_LOGIN_PASSWORD;

if (!loginEmail || !loginPassword) {
    throw new Error(
        "PLAYWRIGHT_LOGIN_EMAIL and PLAYWRIGHT_LOGIN_PASSWORD must be set in environment variables."
    );
}

// Clear authentication state
await context.clearCookies();

// Try to access a protected page with query parameters
const protectedPath = "/settings/team?foo=bar&baz=qux";
await page.goto(`${baseUrl}${protectedPath}`);
```

--------------------------------

### Format Individual Files with Biome

Source: https://github.com/giselles-ai/giselle/blob/main/AGENTS.md

Formats a specific file using the Biome formatter. This command should be run after every code change.

```shell
pnpm biome check --write [filename]
```

--------------------------------

### Immediate Actions After Code Changes

Source: https://github.com/giselles-ai/giselle/blob/main/CLAUDE.md

A sequence of commands that must be executed immediately after using the `edit_file` tool to ensure code consistency, build integrity, and test coverage.

```APIDOC
Post-edit_file Actions:

1. pnpm format
   - Purpose: Ensures code is consistently formatted.

2. pnpm build-sdk
   - Purpose: Rebuilds the SDK packages.

3. pnpm check-types
   - Purpose: Verifies type correctness across the project.

4. pnpm tidy
   - Purpose: Identifies unused files and dependencies.

5. pnpm test
   - Purpose: Runs the project's test suite to confirm functionality.

Note: These steps are also performed by CI, and failure in any step will cause the PR to fail.
```

--------------------------------

### Prevent path traversal in blob download loader

Source: https://github.com/giselles-ai/giselle/wiki/.pr_agent_accepted_suggestions

Enhances security by preventing path traversal attacks in the `loadDocument` function. It validates that the constructed `fullPath` starts with the expected `root` directory, returning null and logging a warning if a traversal attempt is detected.

```typescript
const loadDocument = async (
 	metadata: GitHubBlobMetadata,
 ): Promise<Document<GitHubBlobMetadata> | null> => {
 	const root = await prepare();
 	const fullPath = join(root, metadata.path);
 	
 	// Prevent path traversal attacks
 	if (!fullPath.startsWith(root)) {
 		console.warn(`Path traversal attempt detected: ${metadata.path}`);
 		return null;
 	}
 	
 	let contentBytes: Buffer;
 	try {
 		contentBytes = await fs.readFile(fullPath);
 	} catch {
 		return null;
 	}
 	if (contentBytes.length > maxBlobSize) {
 		console.warn(
 			`Blob size is too large: ${contentBytes.length} bytes, skipping: ${metadata.path}`,
 		);
 		return null;
 	}
 	const textDecoder = new TextDecoder("utf-8", { fatal: true });
 	try {
 		const decodedContent = textDecoder.decode(contentBytes);
 		return { content: decodedContent, metadata };
 	} catch {
 		return null;
 	}
 };
```

--------------------------------

### Testing with Network Access

Source: https://github.com/giselles-ai/giselle/blob/main/packages/web-search/README.md

Shows how to enable tests that require network requests by setting a specific environment variable before running tests.

```sh
VITEST_WITH_EXTERNAL_API=1 pnpm test
```

--------------------------------

### Validate environment variables early in e2e tests

Source: https://github.com/giselles-ai/giselle/wiki/.pr_agent_accepted_suggestions

Implements a best practice in end-to-end tests by validating the presence of essential environment variables (PLAYWRIGHT_LOGIN_EMAIL, PLAYWRIGHT_LOGIN_PASSWORD) at the beginning of each test. This prevents unnecessary setup and navigation when credentials are missing, improving test efficiency and reliability.

```typescript
const loginEmail = process.env.PLAYWRIGHT_LOGIN_EMAIL;
const loginPassword = process.env.PLAYWRIGHT_LOGIN_PASSWORD;

if (!loginEmail || !loginPassword) {
    throw new Error(
        "PLAYWRIGHT_LOGIN_EMAIL and PLAYWRIGHT_LOGIN_PASSWORD must be set in environment variables."
    );
}

// Clear authentication state
await context.clearCookies();

// Try to access a protected page with query parameters
const protectedPath = "/settings/team?foo=bar&baz=qux";
await page.goto(`${baseUrl}${protectedPath}`);
```

--------------------------------

### Supabase Migration File Naming Convention

Source: https://github.com/giselles-ai/giselle/blob/main/apps/studio.giselles.ai/migrations/system/README.md

Defines the standard format for naming SQL migration files to ensure chronological order and clarity. The convention includes a date prefix followed by a descriptive name.

```text
YYYYMMDD_description.sql
```

--------------------------------

### Run Package-Specific Tests

Source: https://github.com/giselles-ai/giselle/blob/main/AGENTS.md

Runs tests for a particular package using pnpm's filter flag.

```shell
pnpm -F <package> test
```

--------------------------------

### Supabase System Migrations Directory Structure

Source: https://github.com/giselles-ai/giselle/blob/main/apps/studio.giselles.ai/migrations/system/README.md

Illustrates the organization of SQL migration files for Supabase system schemas, distinguishing them from application schema migrations managed by Drizzle.

```text
migrations/\n  system/             # Supabase system schema migrations\n    *.sql            # SQL migration files\n  schema/            # Application schema migrations (managed by Drizzle)
```

--------------------------------

### GiselleEngine Initialization with Vault

Source: https://github.com/giselles-ai/giselle/blob/main/docs/adr/0003-managing-secrets.md

Shows how to integrate a configured `Vault` instance into the `GiselleEngine`. The `vault` option is mandatory and must be provided during engine initialization.

```ts
export const giselleEngine = NextGiselleEngine({
  basePath: "/api/giselle",
  storage,
  vault: supabaseVault,
});
```

--------------------------------

### Configure LineChunker with TypeScript

Source: https://github.com/giselles-ai/giselle/blob/main/packages/rag/src/chunker/__fixtures__/markdown-doc.md

Demonstrates how to instantiate and configure the `LineChunker` class with different options in TypeScript. Shows default, line-based, and character-based configurations.

```typescript
// Default configuration
const chunker1 = new LineChunker();

// Custom line limit
const chunker2 = new LineChunker({
  maxLines: 50,
  overlap: 10
});

// Character-based limits
const chunker3 = new LineChunker({
  maxLines: 100,
  maxChars: 1000,
  overlap: 20
});
```

--------------------------------

### Post Data Structures and Service

Source: https://github.com/giselles-ai/giselle/blob/main/packages/rag/src/chunker/__golden__/code-sample/large-chunks.txt

Defines the Post interface and the PostService class for managing blog posts. Includes methods for finding posts by ID, author, or published status, creating, and publishing posts.

```typescript
export interface Post {
	id: string;
	title: string;
	content: string;
	authorId: string;
	tags: string[];
	published: boolean;
	publishedAt?: Date;
	createdAt: Date;
	updatedAt: Date;
}

export interface CreatePostInput {
	title: string;
	content: string;
	authorId: string;
	tags: string[];
}

export class PostService {
	constructor(private readonly db: Database) {}

	async findById(id: string): Promise<Post | null> {
		const post = await this.db.posts.findUnique({
			where: { id },
			include: { author: true },
		});
		return post;
	}

	async findByAuthor(authorId: string): Promise<Post[]> {
		const posts = await this.db.posts.findMany({
			where: { authorId },
			orderBy: { createdAt: "desc" },
		});
		return posts;
	}

	async findPublished(): Promise<Post[]> {
		const posts = await this.db.posts.findMany({
			where: { published: true },
			orderBy: { publishedAt: "desc" },
		});
		return posts;
	}

	async create(data: CreatePostInput): Promise<Post> {
		const post = await this.db.posts.create({
			data: {
				...data,
				createdAt: new Date(),
				updatedAt: new Date(),
			},
		});
		return post;
	}

	async publish(id: string): Promise<Post> {
		const post = await this.db.posts.update({
			where: { id },
			data: {
				published: true,
				publishedAt: new Date(),
				updatedAt: new Date(),
			},
		});
		return post;
	}
}
```

--------------------------------

### PostService Methods

Source: https://github.com/giselles-ai/giselle/blob/main/packages/rag/src/chunker/__golden__/code-sample/small-chunks.txt

Handles operations related to posts, including retrieving posts by ID, author, or published status, creating new posts, and publishing existing posts. It leverages a database for data management and includes author information in retrieval.

```TypeScript
export class PostService {
	constructor(private readonly db: Database) {}

	async findById(id: string): Promise<Post | null> {
		const post = await this.db.posts.findUnique({
			where: { id },
			include: { author: true },
		});
		return post;
	}

	async findByAuthor(authorId: string): Promise<Post[]> {
		const posts = await this.db.posts.findMany({
			where: { authorId },
			orderBy: { createdAt: "desc" },
		});
		return posts;
	}

	async findPublished(): Promise<Post[]> {
		const posts = await this.db.posts.findMany({
			where: { published: true },
			orderBy: { publishedAt: "desc" },
		});
		return posts;
	}

	async create(data: CreatePostInput): Promise<Post> {
		const post = await this.db.posts.create({
			data: {
				...data,
				createdAt: new Date(),
				updatedAt: new Date(),
			},
		});
		return post;
	}

	async publish(id: string): Promise<Post> {
		const post = await this.db.posts.update({
			where: { id },
			data: {
				published: true,
				publishedAt: new Date(),
				updatedAt: new Date(),
			},
		});
		return post;
	}
}
```

--------------------------------

### TypeScript PostService API

Source: https://github.com/giselles-ai/giselle/blob/main/packages/rag/src/chunker/__golden__/code-sample/char-limit.txt

Provides methods for managing blog posts. This service allows fetching posts by ID, author, or publication status, creating new posts, and publishing existing ones.

```TypeScript
export class PostService {
	constructor(private readonly db: Database) {}

	async findById(id: string): Promise<Post | null> {
		const post = await this.db.posts.findUnique({
			where: { id },
			include: { author: true },
		});
		return post;
	}

	async findByAuthor(authorId: string): Promise<Post[]> {
		const posts = await this.db.posts.findMany({
			where: { authorId },
			orderBy: { createdAt: "desc" },
		});
		return posts;
	}

	async findPublished(): Promise<Post[]> {
		const posts = await this.db.posts.findMany({
			where: { published: true },
			orderBy: { publishedAt: "desc" },
		});
		return posts;
	}

	async create(data: CreatePostInput): Promise<Post> {
		const post = await this.db.posts.create({
			data: {
				...data,
				createdAt: new Date(),
				updatedAt: new Date(),
			},
		});
		return post;
	}

	async publish(id: string): Promise<Post> {
		const post = await this.db.posts.update({
			where: { id },
			data: {
				published: true,
				publishedAt: new Date(),
				updatedAt: new Date(),
			},
		});
		return post;
	}
}
```

--------------------------------

### PNPM Commands for Project Management

Source: https://github.com/giselles-ai/giselle/blob/main/CLAUDE.md

A collection of essential pnpm commands used for building, testing, formatting, and managing dependencies within the Giselle project. These commands are critical for maintaining code quality and project integrity.

```APIDOC
PNPM Commands:

- pnpm build-sdk:
  - Description: Builds the SDK packages for the project.
  - Usage: Run this command to compile and package the Software Development Kit.

- pnpm -F playground build:
  - Description: Builds the playground application.
  - Usage: Use this to compile the interactive playground environment.

- pnpm -F studio.giselles.ai build:
  - Description: Builds the Giselle Cloud application.
  - Usage: Execute this command to build the main Giselle Cloud platform.

- pnpm check-types:
  - Description: Performs type-checking across the entire project.
  - Usage: Run this to ensure type safety and catch potential errors.

- pnpm format:
  - Description: Formats the project's code according to established style guidelines.
  - Usage: Apply this command to maintain consistent code formatting.

- pnpm tidy --fix:
  - Description: Diagnoses and automatically deletes unused files and dependencies.
  - Usage: Use this to clean up the project and remove dead code.

- pnpm tidy:
  - Description: Diagnoses unused files and dependencies without making changes.
  - Usage: Run this to identify potential areas for cleanup.

- pnpm test:
  - Description: Executes all project tests.
  - Usage: Run this command to verify the functionality and stability of the codebase.
```

--------------------------------

### Add filesystem error handling to walk function

Source: https://github.com/giselles-ai/giselle/wiki/.pr_agent_accepted_suggestions

Improves the robustness of the `walk` function by adding a `try...catch` block around filesystem operations. This prevents crashes due to permission issues or corrupted files during directory traversal, logging a warning instead.

```typescript
async function* walk(dir: string): AsyncGenerator<string> {
 	try {
 		const entries = await fs.readdir(dir, { withFileTypes: true });
 		for (const entry of entries) {
 			const full = join(dir, entry.name);
 			if (entry.isDirectory()) {
 				yield* walk(full);
 			} else if (entry.isFile()) {
 				yield full;
 			}
 		}
 	} catch (error) {
 		console.warn(`Failed to read directory ${dir}:`, error);
 	}
 }
```

--------------------------------

### Ingest Pipeline: Process Documents with Chunking and Embedding (TypeScript)

Source: https://github.com/giselles-ai/giselle/blob/main/packages/rag/README.md

Shows how to set up and run the ingest pipeline for processing documents. It covers creating a chunk store, defining document loaders, configuring metadata transformation, and executing the ingestion process with progress tracking.

```typescript
import {
  createChunkStore,
  createPipeline,
  type Document,
} from "@giselle-sdk/rag";
import { z } from "zod/v4";

// Define schemas
const ChunkMetadataSchema = z.object({
  repositoryId: z.string(),
  filePath: z.string(),
  commitSha: z.string(),
});

type ChunkMetadata = z.infer<typeof ChunkMetadataSchema>;

// Create chunk store
const chunkStore = createChunkStore<ChunkMetadata>({
  database: {
    connectionString: process.env.DATABASE_URL!,
    poolConfig: { max: 20 },
  },
  tableName: "document_embeddings",
  metadataSchema: ChunkMetadataSchema,
  staticContext: { processed_at: new Date().toISOString() },
});

const DocumentMetadata = {
  owner: z.string(),
  repo: z.string(),
  filePath: z.string(),
  commitSha: z.string(),
};

// Create document loader
const documentLoader = {
  async *load(params: unknown): AsyncIterable<Document<DocumentMetadata>> {
    // Your document loading logic here
    yield {
      content: "Example document content...",
      metadata: {
        owner: "owner",
        repo: "repo",
        filePath: "src/example.ts",
        commitSha: "abc123",
      },
    };
  },
};

// additional data for chunk metadata
const repositoryId = getRepositoryId();

// Create ingest pipeline function
const ingest = createPipeline({
  documentLoader,
  chunkStore,
  documentKey: (doc) => doc.metadata.filePath,
  documentVersion: (doc) => doc.metadata.commitSha,
  metadataTransform: (documentMetadata) => ({
    repositoryId,
    filePath: documentMetadata.filePath,
    commitSha: documentMetadata.commitSha,
  }),
  maxBatchSize: 50,
  onProgress: (progress) => {
    console.log(`Processed: ${progress.processedDocuments}`);
  },
});

// Run ingestion
const result = await ingest();
console.log(`Successfully processed ${result.successfulDocuments} documents`);
```

--------------------------------

### UserService Methods

Source: https://github.com/giselles-ai/giselle/blob/main/packages/rag/src/chunker/__golden__/code-sample/small-chunks.txt

Manages user-related operations, including finding users by ID or email, creating new users, updating existing user information, and deleting users. It interacts with a database layer for persistence.

```TypeScript
export class UserService {
	constructor(private readonly db: Database) {}

	async findById(id: string): Promise<User | null> {
		const user = await this.db.users.findUnique({
			where: { id },
		});
		return user;
	}

	async findByEmail(email: string): Promise<User | null> {
		const user = await this.db.users.findUnique({
			where: { email },
		});
		return user;
	}

	async create(data: CreateUserInput): Promise<User> {
		const user = await this.db.users.create({
			data: {
				...data,
				createdAt: new Date(),
				updatedAt: new Date(),
			},
		});
		return user;
	}

	async update(id: string, data: UpdateUserInput): Promise<User> {
		const user = await this.db.users.update({
			where: { id },
			data: {
				...data,
				updatedAt: new Date(),
			},
		});
		return user;
	}

	async delete(id: string): Promise<void> {
		await this.db.users.delete({
			where: { id },
		});
	}
}
```

--------------------------------

### Create Post Method

Source: https://github.com/giselles-ai/giselle/blob/main/packages/rag/src/chunker/__golden__/code-sample/high-overlap.txt

Asynchronously creates a new post entry in the database. It takes a CreatePostInput object containing post details and automatically sets creation and update timestamps.

```TypeScript
async create(data: CreatePostInput): Promise<Post> {
		const post = await this.db.posts.create({
			data: {
				...data,
				createdAt: new Date(),
				updatedAt: new Date(),
			},
		});
		return post;
	}
```