### Example Build and Test Setup with Chomp

Source: https://github.com/blackriis/nobicha/blob/main/node_modules/es-module-lexer/README.md

This example demonstrates the command-line steps required to set up the build environment, including cloning repositories, installing Emscripten SDK, downloading and extracting the WASI SDK, and finally installing Chomp and running tests. It assumes a Linux-like environment.

```bash
git clone https://github.com:guybedford/es-module-lexer
git clone https://github.com/emscripten-core/emsdk
cd emsdk
git checkout 1.40.1-fastcomp
./emsdk install 1.40.1-fastcomp
cd ..
wget https://github.com/WebAssembly/wasi-sdk/releases/download/wasi-sdk-12/wasi-sdk-12.0-linux.tar.gz
gunzip wasi-sdk-12.0-linux.tar.gz
tar -xf wasi-sdk-12.0-linux.tar
mv wasi-sdk-12.0-linux.tar wasi-sdk-12.0
CARGO_HOME=~/.cargo cargo install chompbuild
cd es-module-lexer
chomp test
```

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

### Set Up Test Payroll Data with Node.js

Source: https://github.com/blackriis/nobicha/blob/main/PAYROLL_SETUP_GUIDE.md

This script uses Node.js to populate your database with test employee and time entry data. This is useful for development and testing purposes.

```bash
node setup-test-payroll-data.js
```

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

### Run Database Migrations with Node.js

Source: https://github.com/blackriis/nobicha/blob/main/PAYROLL_SETUP_GUIDE.md

This command executes the database migration script using Node.js. It applies necessary schema changes to your Supabase database.

```bash
node run-migration-direct.cjs
```

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

### Run Next.js Development Server

Source: https://github.com/blackriis/nobicha/blob/main/apps/web/README.md

Commands to start the development server for a Next.js application. These commands are executed in the project's root directory using different package managers.

```bash
npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev
```

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

### Byterover Onboarding Workflow

Source: https://github.com/blackriis/nobicha/blob/main/AGENTS.md

This workflow guides the initial setup and synchronization of the Byterover handbook. It ensures the handbook exists, analyzes code gaps, and updates the handbook with current project modules. Key tools include byterover-check-handbook-existence, byterover-create-handbook, byterover-check-handbook-sync, byterover-update-handbook, byterover-list-modules, byterover-store-modules, and byterover-update-modules.

```python
byterover-check-handbook-existence()
byterover-create-handbook()
byterover-check-handbook-sync()
byterover-update-handbook()
byterover-list-modules()
byterover-store-modules()
byterover-update-modules()
```

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

### Supabase Client Integration (JavaScript/TypeScript)

Source: https://github.com/blackriis/nobicha/blob/main/docs/stories/1.1.project-setup.md

Installs and configures the Supabase client library for interacting with the Supabase database. This involves setting up the client instance with environment variables.

```javascript
import { createClient } from '@supabase/supabase-js';

const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL!;
const supabaseAnonKey = process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!;

export const supabase = createClient(supabaseUrl, supabaseAnonKey);
```

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

### Configure Supabase Credentials in .env.local

Source: https://github.com/blackriis/nobicha/blob/main/PAYROLL_SETUP_GUIDE.md

This snippet shows how to configure Supabase credentials in the .env.local file. Ensure you replace the placeholder values with your actual Supabase project URL and API keys for full functionality.

```env
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-real-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-real-service-role-key
```

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

### Local Development Environment Variables (.env.local)

Source: https://github.com/blackriis/nobicha/blob/main/docs/ci-cd-setup.md

Configuration for local development using a .env.local file. This file sets up Supabase connection details and development-specific settings like the local URL and Node environment.

```bash
# Supabase Configuration
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

# Development Settings
NODE_ENV=development
NEXT_PUBLIC_APP_URL=http://localhost:3000
```

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

### Install Dependencies with npm

Source: https://github.com/blackriis/nobicha/blob/main/node_modules/data-urls/node_modules/whatwg-url/README.md

Fetches and installs all necessary project dependencies using npm. Ensure Node.js is installed before running this command.

```bash
npm install
```

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

### Installation

Source: https://github.com/blackriis/nobicha/blob/main/node_modules/ws/README.md

Instructions for installing the ws library and optional performance-enhancing modules.

```APIDOC
## Installing

```bash
npm install ws
```

### Opt-in for performance

[bufferutil][] is an optional module that can be installed alongside the ws module:

```bash
npm install --save-optional bufferutil
```

This module enhances performance for operations like masking and unmasking data payloads. Prebuilt binaries are available for popular platforms.

To disable bufferutil, use the environment variable `WS_NO_BUFFER_UTIL`.

#### Legacy opt-in for performance

For older Node.js versions (prior to v18.14.0), ws also supports the [utf-8-validate][] module:

```bash
npm install --save-optional utf-8-validate
```

To disable utf-8-validate, use the environment variable `WS_NO_UTF_8_VALIDATE`.
```

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

### Install Playwright and Browsers (Shell)

Source: https://github.com/blackriis/nobicha/blob/main/node_modules/@playwright/test/README.md

Installs Playwright as a development dependency and then installs all supported browsers. This is the manual method for setting up Playwright in a project.

```Shell
npm i -D @playwright/test
# install supported browsers
npx playwright install
```

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

### Node.js Debugging - HTTP Server Example

Source: https://github.com/blackriis/nobicha/blob/main/node_modules/debug/README.md

Demonstrates how to use the 'debug' utility in a Node.js HTTP server. It shows how to initialize debug instances with namespaces like 'http' and log messages during server boot and request handling. Requires the 'debug' module to be installed.

```javascript
var debug = require('debug')('http')
  , http = require('http')
  , name = 'My App';

// fake app

debug('booting %o', name);

http.createServer(function(req, res){
  debug(req.method + ' ' + req.url);
  res.end('hello\n');
}).listen(3000, function(){
  debug('listening');
});

// fake worker of some kind

require('./worker');
```

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

### E2E Test Debug Commands

Source: https://github.com/blackriis/nobicha/blob/main/docs/ci-cd-setup.md

A collection of bash commands to run End-to-End (E2E) tests locally with various debugging options. These commands allow specifying specific test files, enabling debug mode, or targeting particular browsers for testing.

```bash
# Run E2E tests locally
npm run test:e2e

# Run specific test file
npm run test:e2e -- branch-management-simple.spec.ts

# Run with debug mode
npm run test:e2e -- --debug

# Run with specific browser
npm run test:e2e -- --project=chromium
```

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

### React Hook Form Quickstart Example

Source: https://github.com/blackriis/nobicha/blob/main/node_modules/react-hook-form/README.md

This snippet demonstrates a basic implementation of React Hook Form in a React component. It shows how to register input fields, handle form submission, and display validation errors. Dependencies include React and React Hook Form.

```jsx
import {
  useForm
} from 'react-hook-form';

function App() {
  const {
    register,
    handleSubmit,
    formState: { errors },
  } = useForm();

  return (
    <form onSubmit={handleSubmit((data) => console.log(data))}>
      <input {...register('firstName')} />
      <input {...register('lastName', { required: true })} />
      {errors.lastName && <p>Last name is required.</p>}
      <input {...register('age', { pattern: /\d+/ })} />
      {errors.age && <p>Please enter number for age.</p>}
      <input type="submit" />
    </form>
  );
}
```

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

### Install @types/prop-types with npm

Source: https://github.com/blackriis/nobicha/blob/main/node_modules/@types/prop-types/README.md

This command installs the type definitions for prop-types as a development dependency using npm. Ensure you have Node.js and npm installed.

```bash
npm install --save @types/prop-types
```

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

### Structured Prompting Framework for AI

Source: https://github.com/blackriis/nobicha/blob/main/AGENTS.md

A four-part framework for creating high-quality AI prompts. It includes defining the high-level goal, providing detailed instructions, including code examples and constraints, and defining a strict scope. This method ensures clarity and guides the AI effectively.

```markdown
# Structured Prompting Framework

1. **High-Level Goal**: Start with a clear, concise summary of the overall objective.
   - _Example: "Create a responsive user registration form with client-side validation and API integration."_
2. **Detailed, Step-by-Step Instructions**: Provide a granular, numbered list of actions the AI should take.
   - _Example: "1. Create a new file named `RegistrationForm.js`. 2. Use React hooks for state management. 3. Add styled input fields for 'Name', 'Email', and 'Password'. 4. For the email field, ensure it is a valid email format. 5. On submission, call the API endpoint defined below."_
3. **Code Examples, Data Structures & Constraints**: Include any relevant snippets of existing code, data structures, or API contracts. State what _not_ to do.
   - _Example: "Use this API endpoint: `POST /api/register`. The expected JSON payload is `{ "name": "string", "email": "string", "password": "string" }`. Do NOT include a 'confirm password' field. Use Tailwind CSS for all styling."_
4. **Define a Strict Scope**: Explicitly define the boundaries of the task.
   - _Example: "You should only create the `RegistrationForm.js` component and add it to the `pages/register.js` file. Do NOT alter the `Navbar.js` component or any other existing page or component."_
```

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

### Install Tinybench

Source: https://github.com/blackriis/nobicha/blob/main/node_modules/tinybench/README.md

This command installs Tinybench as a development dependency in your project using npm.

```bash
npm install -D tinybench
```

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

### Install pretty-format using Yarn

Source: https://github.com/blackriis/nobicha/blob/main/node_modules/pretty-format/README.md

This command installs the pretty-format library using the Yarn package manager. It adds the library as a dependency to your project.

```sh
$ yarn add pretty-format
```

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

### GitHub Actions Secrets for Supabase and App Configuration

Source: https://github.com/blackriis/nobicha/blob/main/docs/ci-cd-setup.md

These are required environment variables to be added as secrets in GitHub repository settings for CI/CD. They include Supabase URL, Anon Key, Service Role Key, Node Environment, and the application's public URL.

```env
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
NODE_ENV=production
NEXT_PUBLIC_APP_URL=https://your-app-domain.com
```

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

### Add Command Example with command.example

Source: https://github.com/blackriis/nobicha/blob/main/node_modules/cac/README.md

Shows how to add example usage for a command using `command.example`. These examples are displayed at the end of the help message, providing users with clear usage scenarios. The example can be a string or a function.

```typescript
type CommandExample = ((name: string) => string) | string

const cli = cac()

cli.command('generate <component>', 'Generate a new component')
  .example('generate MyComponent')
  .example(name => `  ${name} --skip-tests\n  ${name} --template=vue`)
  .action((component, options) => {
    console.log(`Generating ${component}...`)
  })

cli.parse()
```

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

### Install picomatch with npm

Source: https://github.com/blackriis/nobicha/blob/main/node_modules/picomatch/README.md

This command installs the picomatch library as a dependency for your project using npm.

```sh
npm install --save picomatch
```

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

### Install electron-to-chromium

Source: https://github.com/blackriis/nobicha/blob/main/node_modules/electron-to-chromium/README.md

Installs the electron-to-chromium package using npm. This is the first step to integrating its version mapping capabilities into your project.

```bash
npm install electron-to-chromium
```

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

### Install min-indent using npm

Source: https://github.com/blackriis/nobicha/blob/main/node_modules/min-indent/readme.md

This snippet shows how to install the 'min-indent' package using npm. It's a prerequisite for using the module in your JavaScript projects.

```bash
npm install --save min-indent
```

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

### Install Postgrest-JS via npm

Source: https://github.com/blackriis/nobicha/blob/main/node_modules/@supabase/postgrest-js/README.md

Installs the postgrest-js package using npm, a prerequisite for using the library in JavaScript projects.

```bash
npm install @supabase/postgrest-js
```

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

### Onboarding Workflow: Handbook and Module Management

Source: https://github.com/blackriis/nobicha/blob/main/CLAUDE.md

This sequence outlines the steps for initiating the Byterover onboarding workflow. It includes checking handbook existence, creating or syncing the handbook, updating it with codebase changes, listing and storing modules, and finally saving new knowledge. This ensures a consistent and up-to-date Byterover environment.

```tool_calls
byterover-check-handbook-existence()
byterover-create-handbook()
byterover-check-handbook-sync()
byterover-update-handbook()
byterover-list-modules()
byterover-store-modules()
byterover-update-modules()
byterover-store-knowledge()
```

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

### Get Error Message with check-error

Source: https://github.com/blackriis/nobicha/blob/main/node_modules/check-error/README.md

Provides an example of using checkError.getMessage to extract the message from an error object. It includes a try-catch block to get an error and then retrieves its message using the getMessage function.

```javascript
var checkError = require('check-error');

var funcThatThrows = function() { throw new TypeError('I am a TypeError') };
var caughtErr;

try {
  funcThatThrows();
} catch(e) {
  caughtErr = e;
}

var sameInstance = caughtErr;

checkError.getMessage(caughtErr) // 'I am a TypeError'
```

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

### Get Constructor Name with check-error

Source: https://github.com/blackriis/nobicha/blob/main/node_modules/check-error/README.md

Demonstrates the usage of checkError.getConstructorName to retrieve the name of an error's constructor. The example captures an error and then calls getConstructorName on it to get its constructor's string name.

```javascript
var checkError = require('check-error');

var funcThatThrows = function() { throw new TypeError('I am a TypeError') };
var caughtErr;

try {
  funcThatThrows();
} catch(e) {
  caughtErr = e;
}

var sameInstance = caughtErr;

checkError.getConstructorName(caughtErr) // 'TypeError'
```

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

### Middleware Usage

Source: https://github.com/blackriis/nobicha/blob/main/docs/rate-limiting-optimization.md

Example of how the rate limiter is integrated into the middleware for automatic enforcement.

```APIDOC
## Middleware Usage

### Automatic Rate Limiter in Middleware

```typescript
// middleware.ts
const rateLimiter = getRateLimiterForEndpoint(pathname)
const { limited, resetTime } = rateLimiter.isRateLimited(req)

if (limited && resetTime) {
  return createRateLimitResponse(resetTime, rateLimiter)
}
```
```

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

### Vitest Basic Test Setup (TypeScript)

Source: https://github.com/blackriis/nobicha/blob/main/docs/stories/1.1.project-setup.md

Initial configuration and a sample test file for Vitest, a Vite-native unit testing framework. This demonstrates setting up the testing environment.

```typescript
// vitest.config.ts
import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    globals: true,
    environment: 'jsdom',
    setupFiles: './src/setupTests.ts',
  },
})

// src/setupTests.ts
// Import necessary setup for your testing environment, e.g., RTL setup

// src/components/Button.test.tsx
import { render, screen } from '@testing-library/react'
import '@testing-library/jest-dom'
import Button from './Button' // Assuming Button component exists

it('renders a button with text', () => {
  render(<Button>Click Me</Button>)
  expect(screen.getByText('Click Me')).toBeInTheDocument()
})
```

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

### Developer Usage: Retry Mechanism

Source: https://github.com/blackriis/nobicha/blob/main/docs/rate-limiting-optimization.md

Example code demonstrating how developers can utilize the retry mechanism for API calls.

```APIDOC
## Developer Usage: Retry Mechanism

### Using the Retry Mechanism

```typescript
import { createRetryableApiCall } from '@/lib/utils/retry.utils'

const retryableApiCall = createRetryableApiCall(
  () => fetch('/api/some-endpoint'),
  { maxAttempts: 3, baseDelayMs: 1000 }
)

const result = await retryableApiCall()
if (result.success) {
  console.log('Success:', result.data)
} else {
  console.error('Failed after retries:', result.error)
}
```
```

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

### Database Configuration (YAML)

Source: https://github.com/blackriis/nobicha/blob/main/docs/qa/database-setup-completion-report.md

This YAML configuration outlines the database setup, specifying the provider as Supabase PostgreSQL, the development environment using .env.local, server-side connection with service role support, and the status of a specific migration script.

```yaml
Provider: Supabase PostgreSQL
URL: https://nyhwnafkybuxneqiaffq.supabase.co  
Environment: Development with .env.local
Connection: Server-side with service role support
Migration Status: 006_storage_setup.sql executed successfully
```

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

### Admin Usage: Analytics and Dashboard

Source: https://github.com/blackriis/nobicha/blob/main/docs/rate-limiting-optimization.md

Instructions and examples for administrators to access rate limit analytics and use the monitoring dashboard.

```APIDOC
## Admin Usage: Analytics and Dashboard

### Checking Analytics

```typescript
const response = await fetch('/api/admin/rate-limit/analytics')
const analytics = await response.json()

console.log('Total requests:', analytics.data.analytics.totalRequests)
console.log('Blocked requests:', analytics.data.analytics.blockedRequests)
console.log('Recommendations:', analytics.data.recommendations)
```

### Using the Admin Dashboard

1. Log in as an administrator.
2. Navigate to the Admin Dashboard.
3. Locate the "Rate Limit Monitor" section.
4. Review usage statistics and recommendations.
```

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

### Developer Usage: Rate Limit Status Check

Source: https://github.com/blackriis/nobicha/blob/main/docs/rate-limiting-optimization.md

Example code for developers to check the current rate limit status of an endpoint.

```APIDOC
## Developer Usage: Rate Limit Status Check

### Checking Rate Limit Status

```typescript
const response = await fetch('/api/rate-limit/status')
const status = await response.json()

console.log('Usage:', status.data.current.count, '/', status.data.current.limit)
console.log('Remaining:', status.data.current.remaining)
console.log('Reset in:', status.data.current.timeUntilReset, 'ms')
```
```

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

### Test Environment Configuration (YAML)

Source: https://github.com/blackriis/nobicha/blob/main/docs/qa/database-setup-completion-report.md

This YAML configuration outlines the test environment, specifying the Next.js version, Playwright test framework, granted permissions (camera, geolocation), authentication method using Supabase auth, and the local development server network setup.

```yaml
Application: Next.js 15.5.2 with Turbopack
Test Framework: Playwright with Chromium
Permissions: Camera and Geolocation granted
Authentication: Real Supabase auth with test users
Network: Local development server on localhost:3000
```

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

### SQL Migration: Add Employee Rate Fields

Source: https://github.com/blackriis/nobicha/blob/main/PAYROLL_SETUP_GUIDE.md

This SQL script adds the `hourly_rate` and `daily_rate` fields to the employee table, which are necessary for payroll calculations.

```sql
ALTER TABLE employees ADD COLUMN hourly_rate numeric;
ALTER TABLE employees ADD COLUMN daily_rate numeric;
```

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

### Install and Use Entities Library in Node.js

Source: https://github.com/blackriis/nobicha/blob/main/node_modules/entities/readme.md

Demonstrates how to install the 'entities' library using npm and provides code examples for encoding and decoding HTML and XML entities. It covers different encoding strategies like UTF8, XML, and HTML, as well as decoding methods for XML and HTML.

```javascript
const entities = require("entities");

// Encoding
entities.escapeUTF8("&#38; ü"); // "&amp;#38; ü"
entities.encodeXML("&#38; ü"); // "&amp;#38; &#xfc;"
entities.encodeHTML("&#38; ü"); // "&amp;&num;38&semi; &uuml;"

// Decoding
entities.decodeXML("asdf &amp; &#xFF; &#xFC; &apos;"); // "asdf & ÿ ü '"
entities.decodeHTML("asdf &amp; &yuml; &uuml; &apos;"); // "asdf & ÿ ü '"
```

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

###  vite-node CLI Options Help

Source: https://github.com/blackriis/nobicha/blob/main/node_modules/vite-node/README.md

Display help information for the vite-node command-line interface, showing available options and their usage.

```bash
npx vite-node -h
```

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

### Webpack Nonce Configuration Example (JavaScript)

Source: https://github.com/blackriis/nobicha/blob/main/node_modules/get-nonce/README.md

Demonstrates how to set the `__webpack_nonce__` global variable, which is used by Webpack for Content Security Policy (CSP). This needs to be done before the Webpack bundle is executed.

```javascript
// Assume 'uuid' is a library that generates unique IDs
// import { v4 as uuid } from 'uuid'; // Example import

// When using with Webpack, you'd typically set this early in your entry script
// __webpack_nonce__ = uuid(); // For example, using a generated UUID

// Note: This code snippet is illustrative and assumes 'uuid' and '__webpack_nonce__' are available in the execution context.
// The actual 'get-nonce' library abstracts this interaction.
```

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

### Install @standard-schema/utils Package

Source: https://github.com/blackriis/nobicha/blob/main/node_modules/@standard-schema/utils/README.md

Instructions for installing the @standard-schema/utils package using various package managers like npm, yarn, pnpm, bun, and deno.

```shell
npm install @standard-schema/utils   # npm
yarn add @standard-schema/utils      # yarn
pnpm add @standard-schema/utils      # pnpm
bun add @standard-schema/utils       # bun
deno add jsr:@standard-schema/utils  # deno
```

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

### Build Docs with Verb

Source: https://github.com/blackriis/nobicha/blob/main/node_modules/picomatch/README.md

Installs the 'verbose/verb' and 'verb-generate-readme' packages globally and then runs the 'verb' command to generate the project's documentation. This process relies on a '.verb.md' template file.

```shell
npm install -g verbose/verb#dev verb-generate-readme && verb
```

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

### Risk-Based Recommendations Structure (Text)

Source: https://github.com/blackriis/nobicha/blob/main/AGENTS.md

A structured list of risk-based recommendations covering testing priority, development focus, deployment strategy, and monitoring setup. This section guides actionable steps based on the identified risk profile.

```text
1. **Testing Priority**
   - Which tests to run first
   - Additional test types needed
   - Test environment requirements

2. **Development Focus**
   - Code review emphasis areas
   - Additional validation needed
   - Security controls to implement

3. **Deployment Strategy**
   - Phased rollout for high-risk changes
   - Feature flags for risky features
   - Rollback procedures

4. **Monitoring Setup**
   - Metrics to track
   - Alerts to configure
   - Dashboard requirements
```

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

### Next.js Project Initialization with TypeScript

Source: https://github.com/blackriis/nobicha/blob/main/docs/stories/1.1.project-setup.md

Initializes a new Next.js project using the create-next-app CLI with TypeScript support. This sets up the foundational structure for the web application.

```bash
npx create-next-app@latest .
```

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

### Use HttpProxyAgent with Node.js http.get

Source: https://github.com/blackriis/nobicha/blob/main/node_modules/http-proxy-agent/README.md

This example demonstrates how to use the HttpProxyAgent to make an HTTP GET request through a proxy server. It imports necessary modules, creates an HttpProxyAgent instance with the proxy URL, and then uses this agent with http.get.

```typescript
import * as http from 'http';
import { HttpProxyAgent } from 'http-proxy-agent';

const agent = new HttpProxyAgent('http://168.63.76.32:3128');

http.get('http://nodejs.org/api/', { agent }, (res) => {
  console.log('"response" event!', res.headers);
  res.pipe(process.stdout);
});
```

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

### Build Live Viewer with npm

Source: https://github.com/blackriis/nobicha/blob/main/node_modules/data-urls/node_modules/whatwg-url/README.md

Builds the live viewer application for the project. This involves preparing the environment and then compiling the viewer.

```bash
npm run prepare
npm run build-live-viewer
```

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

### Example Breadcrumb Structure

Source: https://github.com/blackriis/nobicha/blob/main/docs/stories/5.3.enhanced-ux-components-design-consistency.md

Illustrates a hierarchical navigation structure for breadcrumbs, showing typical paths within an admin interface. This pattern guides the implementation of breadcrumb components for different sections of the application.

```plaintext
Admin → Employees → John Doe → Edit Profile
Admin → Reports → Materials → Material Detail
```

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

### Start Supabase Local Development and Run Integration Tests

Source: https://github.com/blackriis/nobicha/blob/main/node_modules/@supabase/supabase-js/README.md

Starts a local Supabase instance and then runs integration tests. This is used to test the client library against a running Supabase backend in a development environment.

```bash
supabase start
npm run test:integration
```

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

### Bash: Infrastructure Setup Commands

Source: https://github.com/blackriis/nobicha/blob/main/docs/qa/e2e-test-report-story-1.5.md

This Bash script provides commands for setting up infrastructure dependencies. It includes running storage migrations to ensure a bucket exists and seeding test users with proper credentials. These commands are crucial for enabling full end-to-end validation.

```bash
# Run storage migration to ensure bucket exists
npm run migration:storage

# Create test user with proper credentials
npm run seed:test-users
```

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

### Storage Migration Script Execution (Shell)

Source: https://github.com/blackriis/nobicha/blob/main/docs/qa/database-setup-completion-report.md

This output indicates the successful execution of a JavaScript file named 'run-storage-migration.js'. It confirms the creation and verification of a storage bucket, readiness for upload functionality, and a specific test failure related to MIME type restrictions.

```shell
✅ Storage bucket created and verified successfully!
✅ Upload functionality infrastructure ready
⚠️ Upload test failed (expected - MIME type restriction working correctly)
```

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

### Install auth-js Client

Source: https://github.com/blackriis/nobicha/blob/main/node_modules/@supabase/auth-js/README.md

This snippet shows how to install the auth-js client library using npm. This is the first step to using the Supabase Auth client in your JavaScript project.

```bash
npm install --save @supabase/auth-js
```

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

### Asynchronous source map reading from URL (Browser)

Source: https://github.com/blackriis/nobicha/blob/main/node_modules/convert-source-map/README.md

This example demonstrates how to asynchronously fetch and read a source map file from a URL in a browser environment. It uses the `fetch` API to make an HTTP request and `res.text()` to get the source map content, which is then passed to `convert.fromMapFileComment`.

```javascript
var convert = require('convert-source-map');

async function readMap(url) {
  const res = await fetch(url);
  return res.text();
}

const converter = await convert.fromMapFileComment('//# sourceMappingURL=map-file-comment.css.map', readMap)
var json = converter.toJSON();
console.log(json);
```

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

### Deployment Extensions and Environment Management

Source: https://github.com/blackriis/nobicha/blob/main/BYTEROVER_HANDBOOK_backup_20250908_133836.md

Details deployment strategies, including leveraging Vercel for serverless deployment, managing different environment configurations (development/production), and automating database migrations using the Supabase CLI.

```typescript
🚀 Deployment Extensions
├── Vercel Platform: Serverless deployment
├── Environment Management: Development/Production configs
└── Database Migrations: Automated via Supabase CLI
```

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

### Install Semver Package

Source: https://github.com/blackriis/nobicha/blob/main/node_modules/semver/README.md

Installs the semver package using npm, a command-line utility for managing Node.js packages. This is the initial step before using semver in a project.

```bash
npm install semver
```

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

### E2E Selfie Workflow Initiation Test Results (Shell)

Source: https://github.com/blackriis/nobicha/blob/main/docs/qa/database-setup-completion-report.md

This output describes the partial success of the E2E selfie workflow initiation test. It confirms successful interaction with the check-in button and display of the branch selection interface, while noting that the UI requires additional logic and the current status.

```shell
✅ Check-in button clicked successfully
✅ Branch selection interface displayed  
⚠️ Branch selection UI requires additional interaction logic
📝 Status: "เลือกสาขาสำหรับ Check-In" screen reached
```

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

### iOS Specific Error Handling (TypeScript)

Source: https://github.com/blackriis/nobicha/blob/main/docs/CoreLocationErrorPrevention.md

Provides an example of specific error handling for iOS devices, particularly when encountering location errors (code 2). It suggests user actions like moving to an open area and enabling Wi-Fi/Mobile Data to improve signal reception.

```typescript
// ข้อความเฉพาะ iOS Safari
if (isIOS && error.code === 2) {
  return 'ออกไปยังที่เปิดโล่ง เปิด Wi-Fi และ Mobile Data แล้วลองใหม่'
}
```

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

### Development Workflow: Testing and Deployment

Source: https://github.com/blackriis/nobicha/blob/main/BYTEROVER_HANDBOOK_backup_20250909_100721.md

Outlines the testing strategies, including unit, API, and E2E tests using Playwright, along with GPS mocking capabilities. It also covers deployment extensions, specifying the use of Vercel for serverless deployment, environment management, and automated database migrations via the Supabase CLI.

```typescript
🧪 Testing Patterns
├── Unit Tests: apps/web/src/__tests__/
├── API Tests: Integration testing for endpoints
├── E2E Tests: Playwright for user workflows
└── GPS Mocking: Test location-based features

🚀 Deployment Extensions
├── Vercel Platform: Serverless deployment
├── Environment Management: Development/Production configs
└── Database Migrations: Automated via Supabase CLI
```

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

### Node.js WebSocket Client IP Address Retrieval Example (X-Forwarded-For)

Source: https://github.com/blackriis/nobicha/blob/main/node_modules/ws/README.md

This Node.js code demonstrates how to get the client's IP address when the WebSocket server is behind a proxy, such as NGINX. It specifically looks for the 'X-Forwarded-For' header and extracts the first IP address from the comma-separated list.

```javascript
wss.on('connection', function connection(ws, req) {
  const ip = req.headers['x-forwarded-for'].split(',')[0].trim();

  ws.on('error', console.error);
});
```

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

### KB Mode Interaction Task Instructions

Source: https://github.com/blackriis/nobicha/blob/main/AGENTS.md

Markdown instructions for the 'kb-mode-interaction' task, guiding users on how to enter and interact with the knowledge base mode. It outlines steps for welcoming the user, presenting topic areas, responding contextually, facilitating interactive exploration, and exiting gracefully.

```markdown
<!-- Powered by BMAD™ Core -->

# KB Mode Interaction Task

## Purpose

Provide a user-friendly interface to the BMad knowledge base without overwhelming users with information upfront.

## Instructions

When entering KB mode (\*kb-mode), follow these steps:

### 1. Welcome and Guide

Announce entering KB mode with a brief, friendly introduction.

### 2. Present Topic Areas

Offer a concise list of main topic areas the user might want to explore:

**What would you like to know more about?**

1. **Setup & Installation** - Getting started with BMad
2. **Workflows** - Choosing the right workflow for your project
3. **Web vs IDE** - When to use each environment
4. **Agents** - Understanding specialized agents and their roles
5. **Documents** - PRDs, Architecture, Stories, and more
6. **Agile Process** - How BMad implements Agile methodologies
7. **Configuration** - Customizing BMad for your needs
8. **Best Practices** - Tips for effective BMad usage

Or ask me about anything else related to BMad-Method!

### 3. Respond Contextually

- Wait for user's specific question or topic selection
- Provide focused, relevant information from the knowledge base
- Offer to dive deeper or explore related topics
- Keep responses concise unless user asks for detailed explanations

### 4. Interactive Exploration

- After answering, suggest related topics they might find helpful
- Maintain conversational flow rather than data dumping
- Use examples when appropriate
- Reference specific documentation sections when relevant

### 5. Exit Gracefully

When user is done or wants to exit KB mode:

- Summarize key points discussed if helpful
- Remind them they can return to KB mode anytime with \*kb-mode
- Suggest next steps based on what was discussed

```

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

### Install Supabase JS Client

Source: https://github.com/blackriis/nobicha/blob/main/node_modules/@supabase/supabase-js/README.md

Installs the @supabase/supabase-js package using npm. This is the first step to using the Supabase client library in a JavaScript project.

```sh
npm install @supabase/supabase-js
```

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

### Install @types/babel__core with npm

Source: https://github.com/blackriis/nobicha/blob/main/node_modules/@types/babel__core/README.md

This command installs the @types/babel__core package, which provides TypeScript type definitions for the @babel/core JavaScript library. Ensure you have Node.js and npm installed.

```bash
npm install --save @types/babel__core
```

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

### Generate Formatted CSS with Custom Indentation using @adobe/css-tools

Source: https://github.com/blackriis/nobicha/blob/main/node_modules/@adobe/css-tools/docs/EXAMPLES.md

Shows how to produce formatted CSS with custom indentation using the `stringify` function from `@adobe/css-tools` by providing an `indent` option (e.g., `{ indent: '    ' }`). This is useful for generating human-readable CSS during development or for style guides. It requires both `parse` and `stringify`.

```javascript
import { parse, stringify } from '@adobe/css-tools';

const css = 'body { font-size: 12px; color: #333; }';
const ast = parse(css);

// Custom indentation
const formatted = stringify(ast, { indent: '    ' });
console.log(formatted);
// Output:
// body {
//     font-size: 12px;
//     color: #333;
// }
```

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

### Monorepo Structure Setup (npm workspaces)

Source: https://github.com/blackriis/nobicha/blob/main/docs/stories/1.1.project-setup.md

Configures the project to use npm workspaces for managing a monorepo structure. This allows for shared packages and a unified project organization.

```json
{
  "name": "employee-management-system",
  "private": true,
  "workspaces": [
    "apps/*",
    "packages/*"
  ]
}
```

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

### Progressive Enhancement Strategies (TypeScript)

Source: https://github.com/blackriis/nobicha/blob/main/docs/CoreLocationErrorPrevention.md

Defines an array of location strategies with different accuracy and timeout configurations, primarily for iOS. This progressive approach starts with faster, less accurate settings and gradually increases accuracy and timeout duration if needed, optimizing for various network conditions and GPS signal strengths.

```typescript
// iOS Strategy: เริ่มจากเร็ว -> แม่นยำ
const strategies = [
  { enableHighAccuracy: false, timeout: 8000, maximumAge: 300000 },  // เร็ว
  { enableHighAccuracy: true, timeout: 15000, maximumAge: 60000 },   // สมดุล
  { enableHighAccuracy: true, timeout: 25000, maximumAge: 30000 }    // แม่นยำ
]
```

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

### Initialize Playwright Project (Shell)

Source: https://github.com/blackriis/nobicha/blob/main/node_modules/@playwright/test/README.md

Initializes a new Playwright project from your project's root directory. This command sets up the necessary configuration files, example tests, and optionally a GitHub Actions workflow.

```Shell
# Run from your project's root directory
npm init playwright@latest
# Or create a new project
npm init playwright@latest new-project
```

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

### Install Playwright and Browsers (npm)

Source: https://github.com/blackriis/nobicha/blob/main/node_modules/playwright/README.md

Installs Playwright as a development dependency and downloads all supported browsers. This is the manual installation method after adding the dependency.

```Shell
npm i -D @playwright/test
npx playwright install
```

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

### Install and Test Supabase Functions JS Library

Source: https://github.com/blackriis/nobicha/blob/main/node_modules/@supabase/functions-js/README.md

Instructions for setting up and running tests for the Supabase Functions JS client library. This requires Node.js version 20 or higher and a running Docker daemon. The commands install dependencies and execute the test suite.

```sh
npm i
npm run test
```

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

### Vitest Snapshot Client Initialization and Usage

Source: https://github.com/blackriis/nobicha/blob/main/node_modules/@vitest/snapshot/README.md

Demonstrates initializing the SnapshotClient with custom equality checks and environment, and performing snapshot assertions. It requires 'equals', 'iterableEquality', and 'subsetEquality' for custom comparisons, and utilizes NodeSnapshotEnvironment for file operations. The code includes examples for both inline and file-based snapshots, as well as starting and finishing snapshot runs.

```javascript
import { SnapshotClient } from '@vitest/snapshot'
import { NodeSnapshotEnvironment } from '@vitest/snapshot/environment'
import { SnapshotManager } from '@vitest/snapshot/manager'

const client = new SnapshotClient({
  // you need to provide your own equality check implementation if you use it
  // this function is called when `.toMatchSnapshot({ property: 1 })` is called
  isEqual: (received, expected) =>
    equals(received, expected, [iterableEquality, subsetEquality]),
})

// class that implements snapshot saving and reading
// by default uses fs module, but you can provide your own implementation depending on the environment
const environment = new NodeSnapshotEnvironment()

// you need to implement this yourselves,
// this depends on your runner
function getCurrentFilepath() {
  return '/file.spec.js'
}
function getCurrentTestName() {
  return 'test1'
}

// example for inline snapshots, nothing is required to support regular snapshots,
// just call `assert` with `isInline: false`
function wrapper(received) {
  function __INLINE_SNAPSHOT__(inlineSnapshot, message) {
    client.assert({
      received,
      message,
      isInline: true,
      inlineSnapshot,
      filepath: getCurrentFilepath(),
      name: getCurrentTestName(),
    })
  }
  return {
    // the name is hard-coded, it should be inside another function, so Vitest can find the actual test file where it was called (parses call stack trace + 2)
    // you can override this behaviour in SnapshotState's `_inferInlineSnapshotStack` method by providing your own SnapshotState to SnapshotClient constructor
    toMatchInlineSnapshot: (...args) => __INLINE_SNAPSHOT__(...args),
  }
}

const options = {
  updateSnapshot: 'new',
  snapshotEnvironment: environment,
}

await client.startCurrentRun(
  getCurrentFilepath(),
  getCurrentTestName(),
  options
)

// this will save snapshot to a file which is returned by "snapshotEnvironment.resolvePath"
client.assert({
  received: 'some text',
  isInline: false,
})

// uses "pretty-format", so it requires quotes
// also naming is hard-coded when parsing test files
wrapper('text 1').toMatchInlineSnapshot()
wrapper('text 2').toMatchInlineSnapshot('"text 2"')

const result = await client.finishCurrentRun() // this saves files and returns SnapshotResult

// you can use manager to manage several clients
const manager = new SnapshotManager(options)
manager.add(result)

// do something
// and then read the summary

console.log(manager.summary)

```

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

### E2E Authentication Flow Test Results (Shell)

Source: https://github.com/blackriis/nobicha/blob/main/docs/qa/database-setup-completion-report.md

This output details the successful validation of the E2E authentication flow, confirming a successful employee login, dashboard loading, and the presence of a functional check-in button. It also notes the language interface and the URL of the loaded dashboard.

```shell
✅ Login successful - Dashboard loaded
✅ URL: http://localhost:3000/dashboard  
✅ Dashboard content loaded with Thai interface
✅ Check-in button "เช็คอิน + เซลฟี่" detected and functional
```

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

### Project Configuration and Dependencies

Source: https://github.com/blackriis/nobicha/blob/main/BYTEROVER_HANDBOOK_backup_20250908_133836.md

Outlines the environment variables, database types, and shared UI components used across the project. These are managed through separate packages for modularity and reusability.

```typescript
// Environment Variables (via packages/config)
SUPABASE_URL, SUPABASE_ANON_KEY, SUPABASE_SERVICE_ROLE_KEY

// Database Types (via packages/database)
import { User, Branch, WorkShift } from '@employee-management/database'

// Shared UI Components (via packages/ui)
import { Button, Form, Input } from '@employee-management/ui'
```

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

### Storage Configuration (YAML)

Source: https://github.com/blackriis/nobicha/blob/main/docs/qa/database-setup-completion-report.md

This YAML configuration details the storage setup, including the bucket name, access level (Public with RLS policies), file restrictions (size and format), upload path structure, and security measures based on user-level access control.

```yaml
Bucket Name: employee-selfies
Access Level: Public with RLS policies
File Restrictions: 2MB max, image formats only
Upload Path Structure: employee-selfies/{year}/{month}/{employee_id}/
Security: User-based access control with UUID validation
```

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

### Install Chai Type Definitions with npm

Source: https://github.com/blackriis/nobicha/blob/main/node_modules/@types/chai/README.md

Installs the @types/chai package, which provides TypeScript type definitions for the chai testing framework. This is a development dependency.

```bash
npm install --save @types/chai
```

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

### Rate Limiter Configuration Overview

Source: https://github.com/blackriis/nobicha/blob/main/docs/rate-limiting-optimization.md

Overview of the different rate limiter tiers and their limits, along with the automatic selection mechanism.

```APIDOC
## Rate Limiter Configuration Overview

### Rate Limiter Tiers

- **Auth Rate Limiter**: 10 requests/15 minutes (increased from 5)
- **Critical APIs**: 20 requests/minute (e.g., payroll, time tracking)
- **Important APIs**: 50 requests/minute (e.g., admin operations)
- **General APIs**: 200 requests/minute (increased from 100)
- **Public APIs**: 500 requests/minute (e.g., location services)

### Automatic Rate Limiter Selection

```typescript
// The system automatically selects the appropriate rate limiter based on the endpoint.
const rateLimiter = getRateLimiterForEndpoint(pathname)
```
```

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

### Testing Procedures

Source: https://github.com/blackriis/nobicha/blob/main/docs/rate-limiting-optimization.md

Guidelines for conducting unit, integration, and load tests for the rate limiting system.

```APIDOC
## Testing Procedures

### Unit Tests

```bash
npm test -- rate-limit.test.ts
npm test -- retry.utils.test.ts
```

### Integration Tests

```bash
npm test -- api/rate-limit
```

### Load Testing

```bash
# Test rate limiting under high load conditions
npm run test:load
```
```

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

### Install @types/babel__generator with npm

Source: https://github.com/blackriis/nobicha/blob/main/node_modules/@types/babel__generator/README.md

This command installs the @types/babel__generator package as a development dependency. This package is essential for using TypeScript with @babel/generator, providing type safety and autocompletion.

```bash
npm install --save @types/babel__generator
```

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

### Install @types/phoenix using npm

Source: https://github.com/blackriis/nobicha/blob/main/node_modules/@types/phoenix/README.md

This command installs the type definitions for the Phoenix framework as a development dependency using npm. It is essential for TypeScript projects that use Phoenix.

```bash
npm install --save-dev @types/phoenix
```

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

### Install Node.js Type Definitions with npm

Source: https://github.com/blackriis/nobicha/blob/main/node_modules/@types/node/README.md

This command installs the necessary type definitions for Node.js, enabling better TypeScript support in your project. It is a development dependency.

```bash
npm install --save @types/node
```

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

### Install Pathe via npm, yarn, or pnpm

Source: https://github.com/blackriis/nobicha/blob/main/node_modules/pathe/README.md

Instructions for installing the 'pathe' package using different package managers. This is the initial step before using the library's functionalities.

```bash
# npm
npm i pathe

# yarn
yarn add pathe

# pnpm
pnpm i pathe
```