### Install @funish/build

Source: https://github.com/funish/basis/blob/main/packages/build/README.md

Install @funish/build as a development dependency.

```bash
npm install -D @funish/build
```

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

### Setup Git Hooks with Basis

Source: https://github.com/funish/basis/blob/main/packages/basis/README.md

Install Git hooks defined in your Basis configuration.

```bash
# Setup Git hooks
basis git setup            # Install hooks from config
```

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

### Install and Initialize Funish Basis CLI

Source: https://context7.com/funish/basis/llms.txt

Install the @funish/basis package as a dev dependency and initialize the project configuration, which creates `basis.config.ts` and scaffolds Git hooks. Options allow for overwriting existing configurations, skipping Git checks, or skipping dependency installation.

```bash
# Install as dev dependency
npm install -D @funish/basis
# or
pnpm add -D @funish/basis
# or
yarn add -D @funish/basis

# Initialize — creates basis.config.ts and scaffolds Git hooks
npx basis init

# Options
basis init --force           # Overwrite existing configuration
basis init --skip-git-check  # Skip git directory check
basis init --skip-install    # Skip dependency installation
```

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

### Install Dependencies for Funish Basis

Source: https://github.com/funish/basis/blob/main/README.md

Install project dependencies using pnpm after cloning the repository.

```bash
pnpm install
```

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

### setupGitHooks

Source: https://context7.com/funish/basis/llms.txt

Installs Git hooks by reading the `git.hooks` map from `basis.config.ts` and writing executable shell scripts into the `.git/hooks/` directory.

```APIDOC
## setupGitHooks

### Description
Installs Git hooks by reading the `git.hooks` map from `basis.config.ts` and writing executable shell scripts into the `.git/hooks/` directory.

### Method Signature
```typescript
setupGitHooks(cwd: string): Promise<boolean>
```

### Parameters
* **cwd** (string) - Required - The current working directory.

### Request Example
```typescript
import { setupGitHooks } from "@funish/basis";

const ok = await setupGitHooks(process.cwd());
```

### CLI Equivalent
```bash
basis git setup
```
```

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

### Install @funish/basis

Source: https://github.com/funish/basis/blob/main/packages/basis/README.md

Install the Basis package as a development dependency using npm, yarn, or pnpm. Global installation or direct execution with npx are also options.

```bash
# Install with npm
$ npm install -D @funish/basis

# Install with yarn
$ yarn add -D @funish/basis

# Install with pnpm
$ pnpm add -D @funish/basis

# Install globally (optional)
$ pnpm add -g @funish/basis

# Or use directly without installation
$ npx @funish/basis init
```

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

### Install @funish/basis CLI

Source: https://github.com/funish/basis/blob/main/README.md

Install the Funish Basis CLI tool as a development dependency using npm, yarn, or pnpm. It can also be installed globally.

```bash
# Install with npm
$ npm install -D @funish/basis

# Install with yarn
$ yarn add -D @funish/basis

# Install with pnpm
$ pnpm add -D @funish/basis

# Install globally (optional)
$ pnpm add -g @funish/basis
```

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

### Install Git Hooks from Config

Source: https://context7.com/funish/basis/llms.txt

Reads the `git.hooks` map from `basis.config.ts` and writes executable shell scripts into `.git/hooks/`. This function is automatically called by the `basis git setup` CLI command.

```typescript
import { setupGitHooks } from "@funish/basis";

// Reads hooks from basis.config.ts and writes them to .git/hooks/
const ok = await setupGitHooks(process.cwd());
// Creates .git/hooks/pre-commit and .git/hooks/commit-msg as executable scripts
```

```bash
# CLI equivalent
basis git setup
# Output:
# ✔ Created pre-commit hook
# ✔ Created commit-msg hook
# ✔ Git setup completed
```

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

### Run Funish Basis in Development Mode

Source: https://github.com/funish/basis/blob/main/README.md

Start the Funish Basis project in development mode, which typically includes watch capabilities.

```bash
pnpm dev
```

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

### Define Build Configuration

Source: https://github.com/funish/basis/blob/main/packages/build/README.md

Configure build settings by creating a `build.config.ts` file. This example shows how to define multiple entries with specific output directories and minification.

```typescript
import { defineBuildConfig } from "@funish/build/config";

export default defineBuildConfig({
  entries: [
    {
      entry: "src/index",
      minify: true,
    },
    {
      entry: "src/cli/**/*",
      outDir: "dist/cli/",
    },
  ],
});
```

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

### Execute Package Binaries with Basis

Source: https://github.com/funish/basis/blob/main/packages/basis/README.md

Execute package binaries without installing them globally, useful for one-off tasks.

```bash
# Execute package without installation
basis dlx prettier --write .
```

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

### Initialize Basis Project

Source: https://github.com/funish/basis/blob/main/packages/basis/README.md

Initialize Basis in your project directory. This command creates a `basis.config.ts` file and sets up Git hooks. Options include overwriting existing configurations, skipping git checks, or skipping dependency installation.

```bash
cd your-project
basis init

# Options
basis init --force           # Overwrite existing configuration
basis init --skip-git-check  # Skip git directory check
basis init --skip-install    # Skip dependency installation

# This creates:
# ✅ basis.config.ts with Git hooks
# ✅ Git hooks setup (run 'basis git setup' to activate)
```

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

### Run Bundled CLI Tool with runTool

Source: https://context7.com/funish/basis/llms.txt

Synchronously spawns a bundled Node.js CLI tool. Ensure the package is installed in your project. The `bin` path is relative to the package's `node_modules`.

```typescript
import { runTool } from "@funish/basis";

// Run oxlint with arguments
runTool({
  pkg: "oxlint",
  bin: "../bin/oxlint",
  args: ["--fix", "--type-aware", "src/"],
});

// Run oxfmt
runTool({
  pkg: "oxfmt",
  bin: "../bin/oxfmt",
  args: ["--write", "."],
});
```

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

### Programmatically Initialize Project Configuration

Source: https://context7.com/funish/basis/llms.txt

Use the `initProject` function to programmatically initialize `basis.config.ts` in a target directory. It auto-detects the package manager and supports options like forcing overwrites, skipping Git checks, or skipping dependency installation.

```typescript
import { initProject } from "@funish/basis";

// Basic initialization
const success = await initProject(process.cwd(), {
  force: false,        // Don't overwrite if config already exists
  skipGitCheck: false, // Verify git is available
  skipInstall: false,  // Run package install after init
});

if (success) {
  console.log("Project initialized — run 'basis git setup' to activate hooks");
} else {
  console.error("Initialization failed or config already exists");
}

// Force overwrite existing config
await initProject("/path/to/project", { force: true });
```

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

### Contribute to Funish Basis

Source: https://github.com/funish/basis/blob/main/README.md

Steps for contributing to the Funish Basis project, including forking, cloning, installing, developing, testing, and committing changes.

```bash
1. **Fork** the repository
2. **Clone** your fork: `git clone https://github.com/YOUR_USERNAME/basis.git`
3. **Install**: `pnpm install`
4. **Develop**: `pnpm dev`
5. **Test**: `pnpm build && basis <your-command>`
6. **Commit**: Use conventional commits (`feat:`, `fix:`, etc.)
7. **Push** to your fork and create a Pull Request
```

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

### Build Project with Basis

Source: https://github.com/funish/basis/blob/main/packages/basis/README.md

Build your project using the default configuration or specify a different directory. Stub files can also be generated.

```bash
# Build project
basis build                    # Build with default config
basis build --cwd ./packages   # Build specific directory
basis build --stub             # Generate stub files
```

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

### Basic CLI Usage for @funish/build

Source: https://github.com/funish/basis/blob/main/packages/build/README.md

Use the `isbuild` command to build your project. You can specify entry files, generate stubs, and apply various build options.

```bash
# Build with config file
isbuild

# Build specific entry
isbuild src/index.ts

# Build multiple entries
isbuild src/index.ts src/cli.ts

# Generate stubs
isbuild --stub src/index.ts

# With options
isbuild src/index.ts --format esm --minify --dts
```

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

### build(options)

Source: https://github.com/funish/basis/blob/main/packages/build/README.md

Initiates the build process with specified options. It can handle multiple entries and supports various configurations like stub generation and custom hooks.

```APIDOC
## build(options)

### Description
Initiates the build process with specified options. It can handle multiple entries and supports various configurations like stub generation and custom hooks.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **options** (object) - Required - Configuration options for the build process.
  - **cwd?** (string) - Optional - Project directory.
  - **entries** (array) - Required - An array of entry files or BuildEntry objects.
    - Each element can be a string (entry path) or a BuildEntry object.
    - **BuildEntry** extends [tsdown's InlineConfig](https://tsdown.dev) with:
      - **stub?** (boolean) - Optional - Generate Jiti stub instead of bundling.
      - **entry** (string) - Required - The entry point for the build.
      - **outDir?** (string) - Optional - The output directory.
      - **minify?** (boolean) - Optional - Minify the output.
      - **format?** (string) - Optional - Output format (e.g., 'esm', 'cjs', 'iife', 'umd').
  - **hooks?** (object) - Optional - Lifecycle hooks for the build process.
    - **start?** (function) - Optional - A function to execute at the start of the build.
    - **end?** (function) - Optional - A function to execute at the end of the build.

### Request Example
```typescript
import { build } from "@funish/build";

await build({
  entries: [
    { entry: "src/index", stub: true, outDir: "dist/commands/" },
    "src/cli.ts"
  ],
  hooks: {
    start: async (ctx) => {
      console.log("Build started");
    },
    end: async (ctx) => {
      console.log("Build ended");
    }
  }
});
```

### Response
#### Success Response (200)
This function returns a Promise that resolves when the build is complete. No specific data is returned upon success.

#### Response Example
```json
// No explicit response body for success, promise resolves.
```
```

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

### CLI Options for @funish/build

Source: https://github.com/funish/basis/blob/main/packages/build/README.md

Reference for available command-line options for the `isbuild` command.

```bash
Options:
  _                    Entry files
  --cwd <path>         Project directory (default: ".")
  --stub               Generate stub files
  --format <format>    Output format: esm, cjs, iife, umd
  --minify             Minify output
  --dts                Generate type declarations
  --out-dir <dir>      Output directory
  --clean              Clean output before build (default: true)
  --external <mods>    External dependencies (comma-separated)
  --watch              Watch mode
  --config <path>      Path to config file
  --no-config          Disable config file
```

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

### Get List of Staged Files

Source: https://context7.com/funish/basis/llms.txt

Returns an array of currently staged file paths, automatically excluding deleted files. Useful for pre-commit hooks to determine which files need processing.

```typescript
import { getStagedFiles } from "@funish/basis";

const files = await getStagedFiles(process.cwd());
console.log(files);
// ["src/index.ts", "src/utils.ts", "README.md"]
// Deleted files are automatically excluded
```

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

### Initialize and Use Funish Basis CLI

Source: https://github.com/funish/basis/blob/main/README.md

Initialize Funish Basis in your project and use its commands for various development tasks like adding packages, linting, versioning, and publishing.

```bash
# Initialize in your project
basis init

# Use commands
basis add lodash
basis lint
basis version patch
basis publish
```

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

### Integrate with Basis CLI

Source: https://github.com/funish/basis/blob/main/packages/build/README.md

Commands for building projects using @funish/build when integrated with the Basis CLI.

```bash
basis build
basis build --stub
basis build src/index.ts --minify
```

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

### Build All Funish Basis Packages

Source: https://github.com/funish/basis/blob/main/README.md

Build all packages within the Funish Basis monorepo.

```bash
pnpm build
```

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

### Add Dependencies with Basis

Source: https://github.com/funish/basis/blob/main/packages/basis/README.md

Add new dependencies to your project. Use the `-D` flag to add development dependencies.

```bash
# Add dependencies
basis add lodash
basis add -D typescript
```

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

### Format Code with Basis

Source: https://github.com/funish/basis/blob/main/packages/basis/README.md

Format your code according to the project's style guidelines.

```bash
# Format code
basis fmt
```

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

### Development Commands for Funish Basis

Source: https://github.com/funish/basis/blob/main/README.md

Common commands for development, including running in watch mode, building, and linting.

```bash
pnpm dev            # Development mode with watch
pnpm build          # Build all packages
pnpm lint           # Run linting
```

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

### Basis CLI for Code Quality (lint/fmt)

Source: https://context7.com/funish/basis/llms.txt

These commands delegate to oxlint and oxfmt, respectively. Configuration is read from `basis.config.ts`, but can be overridden with inline flags.

```bash
# Linting (powered by oxlint — Rust-based)
basis lint                         # Uses config from basis.config.ts
basis lint --fix --type-aware      # Override with inline flags

# Formatting (powered by oxfmt — Rust-based)
basis fmt                          # Uses config from basis.config.ts
basis fmt --write .                # Format all files in place

# Building
basis build                        # Build with @funish/build (tsdown + Rolldown + Oxc)
basis build --stub                 # Generate Jiti stub files for development
basis build --cwd ./packages/core  # Build a specific package
```

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

### Manage Versions with Basis

Source: https://github.com/funish/basis/blob/main/packages/basis/README.md

Increment project versions using semantic versioning (patch, minor, major) or set specific versions. Prerelease versions can also be managed.

```bash
# Semantic version increments
basis version patch        # 1.0.0 → 1.0.1
basis version minor        # 1.0.0 → 1.1.0
basis version major        # 1.0.0 → 2.0.0

# Prerelease versions
basis version prerelease        # 1.0.0 → 1.0.1-edge.0
basis version prerelease --preid beta  # 1.0.0 → 1.0.1-beta.0

# Advanced prerelease
basis version premajor     # 2.0.0-alpha.0
basis version preminor     # 1.1.0-alpha.0
basis version prepatch     # 1.0.1-alpha.0

# Specific version
basis version 2.0.0
```

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

### Clone Funish Basis Repository

Source: https://github.com/funish/basis/blob/main/README.md

Clone the Funish Basis repository from GitHub to set up the development environment.

```bash
git clone https://github.com/funish/basis.git
cd basis
```

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

### Publish Package with Basis

Source: https://github.com/funish/basis/blob/main/packages/basis/README.md

Publish your package to a registry. Basis can auto-detect the tag based on the version or allow a custom tag. Git operations like tagging and committing can be included.

```bash
# Publish with tag detection
basis publish              # Auto-detect tag based on version
basis publish --tag beta   # Custom tag

# With git operations
basis publish --git        # Also create git tag and commit
```

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

### runTool

Source: https://context7.com/funish/basis/llms.txt

Resolves and synchronously spawns a bundled Node.js CLI tool (e.g., oxlint, oxfmt) using `require.resolve` for the package entry point.

```APIDOC
## `runTool` — Run Bundled CLI Tool

Resolves and synchronously spawns a bundled Node.js CLI tool (e.g., oxlint, oxfmt) using `require.resolve` for the package entry point.

```typescript
import { runTool } from "@funish/basis";

// Run oxlint with arguments
runTool({
  pkg: "oxlint",
  bin: "../bin/oxlint",
  args: ["--fix", "--type-aware", "src/"],
});

// Run oxfmt
runTool({
  pkg: "oxfmt",
  bin: "../bin/oxfmt",
  args: ["--write", "."],
});
```
```

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

### basis lint / basis fmt CLI

Source: https://context7.com/funish/basis/llms.txt

Delegates to oxlint and oxfmt respectively, passing CLI args from the `lint.config` and `fmt.config` arrays in `basis.config.ts`.

```APIDOC
## `basis lint` / `basis fmt` CLI — Code Quality

Delegates to oxlint and oxfmt respectively, passing CLI args from the `lint.config` and `fmt.config` arrays in `basis.config.ts`.

```bash
# Linting (powered by oxlint — Rust-based)
basis lint                         # Uses config from basis.config.ts
basis lint --fix --type-aware      # Override with inline flags

# Formatting (powered by oxfmt — Rust-based)
basis fmt                          # Uses config from basis.config.ts
basis fmt --write .                # Format all files in place

# Building
basis build                        # Build with @funish/build (tsdown + Rolldown + Oxc)
basis build --stub                 # Generate Jiti stub files for development
basis build --cwd ./packages/core  # Build a specific package
```
```

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

### Link and Test Funish Basis Locally

Source: https://github.com/funish/basis/blob/main/README.md

Link the Funish Basis package globally and test its commands locally after making changes.

```bash
# Link the package globally
cd packages/basis
pnpm link --global

# Test your changes
basis --version
```

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

### Run Scripts or Files with Basis

Source: https://github.com/funish/basis/blob/main/packages/basis/README.md

Execute scripts defined in your `package.json` or run TypeScript/JavaScript files directly.

```bash
# Run package.json scripts
basis run dev
basis run build

# Run TypeScript/JavaScript files directly
basis run src/index.ts
basis run scripts/setup.js
```

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

### CLI Equivalents for `publishToNpm`

Source: https://context7.com/funish/basis/llms.txt

Command-line interface commands for publishing packages to npm, mirroring the functionality of the `publishToNpm` function.

```bash
# CLI equivalents
basis publish              # Auto-detect tag from version
basis publish --tag beta   # Override tag
basis publish --git        # Also create git commit + tag
basis publish --dry-run    # Preview without publishing
basis publish --otp 123456 # Two-factor authentication
```

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

### CLI Version Management with `basis version`

Source: https://context7.com/funish/basis/llms.txt

Manages package versions via the command line using `calculateNewVersion`. Supports patch, minor, major, prerelease, and specific version setting.

```bash
# Increment types
basis version patch        # 1.0.0 → 1.0.1
basis version minor        # 1.0.0 → 1.1.0
basis version major        # 1.0.0 → 2.0.0

# Prerelease
basis version prerelease                   # 1.0.0 → 1.0.1-edge.0 (default preid)
basis version prerelease --preid beta      # 1.0.0 → 1.0.1-beta.0
basis version premajor                     # 1.0.0 → 2.0.0-edge.0
basis version preminor                     # 1.0.0 → 1.1.0-edge.0
basis version prepatch                     # 1.0.0 → 1.0.1-edge.0

# Set specific version
basis version 2.5.0

# Output: ✔ @my/package 1.0.0 → 1.0.1
```

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

### Consola Logging Best Practices

Source: https://github.com/funish/basis/blob/main/CONTRIBUTING.md

Use specific log types like success, error, info, and warn for clear communication. Employ tags for module identification and use colors sparingly for emphasis. Avoid manual emojis and verbose formatting.

```javascript
// ✅ Good - Direct and clear
consola.success(`Version updated: ${oldVersion} → ${newVersion}`);
consola.error("Failed to build:", error);
consola.info("Processing files...");

// ❌ Bad - Verbose and unnecessary
consola.start("Step 1...");
consola.success("Step 1 done!");
consola.start("Step 2...");
consola.success("Step 2 done!");
```

```javascript
// ✅ Use specific log types
consola.start("Building project..."); // Beginning of an operation
consola.success("Build completed!"); // Successful completion
consola.error("Build failed:", error); // Errors with context
consola.info("Processing files..."); // Informational messages
consola.warn("Deprecated feature"); // Warnings

// ✅ Use tags for module identification
const logger = consola.withTag("[module-name]");
logger.info("Module specific message");

// ✅ Use colors for emphasis (when needed)
import { colors as c } from "consola/utils";
consola.info(`${c.magenta("[stub]")} Creating stub for ${path}`);

// ❌ Avoid manual emoji and verbose formatting
consola.log("📦 Building project..."); // Use consola.start instead
consola.log("✅ Success!"); // Use consola.success instead
```

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

### basis add / basis remove / basis dlx CLI

Source: https://context7.com/funish/basis/llms.txt

Uses `nypm` under the hood to auto-detect the active package manager (npm, yarn, pnpm, bun, deno) and run the appropriate command.

```APIDOC
## `basis add` / `basis remove` / `basis dlx` CLI — Package Management

Uses `nypm` under the hood to auto-detect the active package manager (npm, yarn, pnpm, bun, deno) and run the appropriate command.

```bash
# Add dependencies
basis add lodash              # Production dependency
basis add -D typescript       # Dev dependency
basis add lodash axios zod    # Multiple at once

# Remove dependencies
basis remove lodash

# Execute without installing (dlx / npx equivalent)
basis dlx prettier --write .
basis dlx create-next-app my-app

# Run scripts or TypeScript/JavaScript files
basis run dev                  # Runs package.json "dev" script
basis run src/seed.ts          # Executes TypeScript file directly via jiti
basis run scripts/setup.js     # Executes JavaScript file directly
```
```

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

### basis version CLI

Source: https://context7.com/funish/basis/llms.txt

Command-line interface for managing package versions, utilizing `calculateNewVersion`.

```APIDOC
## `basis version` CLI — Version Management

Updates `package.json` version using `calculateNewVersion` and logs the transition.

### Usage

```bash
# Increment types
basis version patch        # 1.0.0 → 1.0.1
basis version minor        # 1.0.0 → 1.1.0
basis version major        # 1.0.0 → 2.0.0

# Prerelease
basis version prerelease                   # 1.0.0 → 1.0.1-edge.0 (default preid)
basis version prerelease --preid beta      # 1.0.0 → 1.0.1-beta.0
basis version premajor                     # 1.0.0 → 2.0.0-edge.0
basis version preminor                     # 1.0.0 → 1.1.0-edge.0
basis version prepatch                     # 1.0.0 → 1.0.1-edge.0

# Set specific version
basis version 2.5.0

# Output: ✔ @my/package 1.0.0 → 1.0.1
```
```

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

### Basis CLI for Publishing with Automatic Tag Detection

Source: https://context7.com/funish/basis/llms.txt

Automatically derives the npm dist-tag from the version string in `package.json`. Use `--tag` to override auto-detection. The `--git` flag performs publish and git operations.

```bash
# package.json version: "1.2.3" (stable)
basis publish
# → Publishes with --tag latest
# → Also runs: npm dist-tag add pkg@1.2.3 edge  (if additionalTag: "edge")

# package.json version: "1.2.3-beta.1" (prerelease)
basis publish
# → Publishes with --tag beta  (extracted from prerelease identifier)
# → Also runs: npm dist-tag add pkg@1.2.3-beta.1 edge

# Override auto-detection
basis publish --tag canary

# Full workflow with git operations
basis version minor             # Bump 1.0.0 → 1.1.0
basis publish --git             # Publish + commit + tag v1.1.0 + push
```

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

### Basis CLI for Package Management (add/remove/dlx)

Source: https://context7.com/funish/basis/llms.txt

Manages dependencies using `nypm` to auto-detect and use the active package manager. `dlx` is equivalent to `npx` or `yarn dlx`.

```bash
# Add dependencies
basis add lodash              # Production dependency
basis add -D typescript       # Dev dependency
basis add lodash axios zod    # Multiple at once

# Remove dependencies
basis remove lodash

# Execute without installing (dlx / npx equivalent)
basis dlx prettier --write .
basis dlx create-next-app my-app

# Run scripts or TypeScript/JavaScript files
basis run dev                  # Runs package.json "dev" script
basis run src/seed.ts          # Executes TypeScript file directly via jiti
basis run scripts/setup.js     # Executes JavaScript file directly
```

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

### loadConfig

Source: https://context7.com/funish/basis/llms.txt

Loads configuration files with upward directory traversal and supports runtime overrides.

```APIDOC
## `loadConfig` — Intelligent Config Loading

Loads `basis.config.ts` with upward directory traversal from cwd to workspace root. Used internally by all commands; also available as a public API.

### Usage

```typescript
import { loadConfig } from "@funish/basis";

// Load with auto-discovery (searches upward from process.cwd())
const { config, _configFile } = await loadConfig();
console.log("Config loaded from:", _configFile);
console.log("Git hooks:", config.git?.hooks);

// Load from a specific directory
const { config: projectConfig } = await loadConfig({ cwd: "/path/to/project" });

// Load with runtime overrides (merged over file config via defu)
const { config: overridden } = await loadConfig({
  overrides: {
    audit: {
      dependencies: { security: true, outdated: false },
    },
  },
});
```

### Parameters

- `options` (object) - Optional. Configuration options.
  - `cwd` (string) - The directory to start searching for configuration files from.
  - `overrides` (object) - Configuration values to merge over the loaded file configuration.
```

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

### basis git CLI

Source: https://context7.com/funish/basis/llms.txt

All unrecognized subcommands are passed directly to the underlying git binary via dugite, enabling full git CLI usage through the `basis` entrypoint.

```APIDOC
## `basis git` CLI — Git Passthrough

All unrecognized subcommands are passed directly to the underlying git binary via dugite, enabling full git CLI usage through the `basis` entrypoint.

```bash
basis git setup              # Install hooks from basis.config.ts
basis git staged             # Run lint-staged (used in pre-commit hook)
basis git lint-commit        # Validate commit message (used in commit-msg hook)

# Git passthrough — all standard git commands work
basis git status
basis git log --oneline --graph
basis git branch -a
basis git stash list
basis git diff HEAD~1
```
```

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

### Remove Dependencies with Basis

Source: https://github.com/funish/basis/blob/main/packages/basis/README.md

Remove existing dependencies from your project.

```bash
# Remove dependencies
basis remove lodash
```

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

### Lint Code with Basis

Source: https://github.com/funish/basis/blob/main/packages/basis/README.md

Run the code linter to check for code quality issues.

```bash
# Lint code
basis lint
```

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

### Publishing Strategy

Source: https://context7.com/funish/basis/llms.txt

Basis automatically derives the npm dist-tag from the version string. No manual `--tag` flag is needed for standard workflows.

```APIDOC
## Publishing Strategy — Automatic Tag Detection

Basis automatically derives the npm dist-tag from the version string. No manual `--tag` flag is needed for standard workflows.

```bash
# package.json version: "1.2.3" (stable)
basis publish
# → Publishes with --tag latest
# → Also runs: npm dist-tag add pkg@1.2.3 edge  (if additionalTag: "edge")

# package.json version: "1.2.3-beta.1" (prerelease)
basis publish
# → Publishes with --tag beta  (extracted from prerelease identifier)
# → Also runs: npm dist-tag add pkg@1.2.3-beta.1 edge

# Override auto-detection
basis publish --tag canary

# Full workflow with git operations
basis version minor             # Bump 1.0.0 → 1.1.0
basis publish --git             # Publish + commit + tag v1.1.0 + push
```
```

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

### Stub Mode Configuration

Source: https://github.com/funish/basis/blob/main/packages/build/README.md

Configure stub generation for development. Stubs use Jiti to load source files at runtime, enabling faster iteration.

```typescript
import { defineBuildConfig } from "@funish/build/config";

export default defineBuildConfig({
  entries: [
    {
      entry: "src/commands/**/*",
      stub: true,
      outDir: "dist/commands/",
    },
  ],
});
```

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

### Check Staged Files with Basis

Source: https://github.com/funish/basis/blob/main/packages/basis/README.md

Check the status of staged files in your Git repository.

```bash
# Check staged files
basis git staged
```

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

### Execute Git Passthrough Commands with Basis

Source: https://github.com/funish/basis/blob/main/packages/basis/README.md

Execute any standard Git command directly through the Basis CLI.

```bash
# Git passthrough (all other git commands)
basis git status
basis git log --oneline
basis git branch -a
```

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

### Define Build Configuration API

Source: https://github.com/funish/basis/blob/main/packages/build/README.md

Use `defineBuildConfig` to create a build configuration object. This function is typically used in `build.config.ts`.

```typescript
import { defineBuildConfig } from "@funish/build/config";

export default defineBuildConfig({
  entries: [...],
});
```

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

### Audit Code Quality with Basis

Source: https://github.com/funish/basis/blob/main/packages/basis/README.md

Perform a comprehensive audit of your code quality, including dependencies and project structure. Issues can be automatically fixed.

```bash
# Audit code quality
basis audit                    # Run all audits
basis audit --dependencies     # Audit dependencies only
basis audit --structure        # Audit structure only
basis audit --fix              # Auto-fix issues
```

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

### auditAll

Source: https://context7.com/funish/basis/llms.txt

Runs both `auditDependencies` and `auditStructure` in parallel using settings from `basis.config.ts`.

```APIDOC
## `auditAll` — Run All Audits

Runs both `auditDependencies` and `auditStructure` in parallel using settings from `basis.config.ts`.

```typescript
import { auditAll } from "@funish/basis";

const passed = await auditAll(process.cwd(), false /* fix */);
// Output:
// ◐ Running comprehensive project audit...
// ✔ Dependencies audit passed
// ✔ Structure audit passed
// ✔ All audits passed
```
```

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

### Load Configuration with `loadConfig`

Source: https://context7.com/funish/basis/llms.txt

Loads configuration from `basis.config.ts` with upward directory traversal. Supports auto-discovery from cwd, loading from a specific directory, and runtime overrides.

```typescript
import { loadConfig } from "@funish/basis";

// Load with auto-discovery (searches upward from process.cwd())
const { config, _configFile } = await loadConfig();
console.log("Config loaded from:", _configFile);
console.log("Git hooks:", config.git?.hooks);

// Load from a specific directory
const { config: projectConfig } = await loadConfig({ cwd: "/path/to/project" });

// Load with runtime overrides (merged over file config via defu)
const { config: overridden } = await loadConfig({
  overrides: {
    audit: {
      dependencies: { security: true, outdated: false },
    },
  },
});
```

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

### Programmatic Build API

Source: https://github.com/funish/basis/blob/main/packages/build/README.md

Use the `build` function programmatically to configure and execute builds. It accepts options such as `cwd`, `entries`, and build `hooks`.

```typescript
import { build } from "@funish/build";

await build({
  cwd?: string;
  entries: (BuildEntry | string)[];
  hooks?: {
    start?: (ctx: BuildContext) => void | Promise<void>;
    end?: (ctx: BuildContext) => void | Promise<void>;
  };
});
```

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

### Configure Basis Git Hooks

Source: https://github.com/funish/basis/blob/main/packages/basis/README.md

Define git hooks for pre-commit and commit-msg using Basis commands. Supports string, array, and function definitions for staged file commands.

```typescript
import { defineBasisConfig } from "@funish/basis/config";

export default defineBasisConfig({
  git: {
    hooks: {
      "pre-commit": "basis git staged",
      "commit-msg": "basis git lint-commit",
    },
    staged: {
      rules: {
        // String: filenames auto-appended
        "*.ts": "basis lint --fix",
        "*.md": "basis fmt --write",
        // Array: multiple commands
        "*.{js,jsx}": ["basis lint --fix", "basis fmt --write"],
        // Function: full control
        "*.tsx": (files) => `basis lint --fix ${files.slice(0, 10).join(" ")}`,
      },
    },
  },
  audit: {
    dependencies: {
      outdated: true,
      security: true,
    },
  },
});
```

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

### Git Operations on Publish with `publishGitOperations`

Source: https://context7.com/funish/basis/llms.txt

Performs Git operations upon publishing, including creating a release commit (staging `package.json` only), creating a Git tag, and optionally pushing to the remote repository.

```typescript
import { publishGitOperations } from "@funish/basis";

await publishGitOperations("1.2.0", {
  tagPrefix: "v",                                 // Tag name: "v1.2.0"
  message: (v) => `chore: release v${v}`,         // Commit message
  push: true,                                     // Push commit + tags to remote
  signTag: false,                                 // Don't GPG-sign the tag
});
// Creates: commit "chore: release v1.2.0", tag "v1.2.0", pushes both
```

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

### Publish Package to npm with `publishToNpm`

Source: https://context7.com/funish/basis/llms.txt

Publishes the current package to npm, automatically detecting the tag from the version string. Supports additional dist-tags, dry runs, and OTP for 2FA.

```typescript
import { publishToNpm } from "@funish/basis";

// Publish stable release → tagged as "latest" + "edge" (additionalTag)
await publishToNpm(
  { tag: undefined, dryRun: false },
  { npm: { tag: "latest", additionalTag: "edge", access: "public" } },
);

// Publish a prerelease (version: "1.0.0-beta.1") → auto-tagged as "beta"
await publishToNpm(
  {},
  { npm: { additionalTag: "edge" } },
);

// Dry run (does not actually publish)
await publishToNpm({ dryRun: true }, {});

// With OTP for 2FA
await publishToNpm({ otp: "123456" }, { npm: { access: "public" } });

// Publish with restricted access (private scoped package)
await publishToNpm({}, { npm: { access: "restricted" } });
```

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

### Basis CLI for Git Passthrough

Source: https://context7.com/funish/basis/llms.txt

Unrecognized `basis` subcommands are passed directly to `git`. This enables full git CLI usage through the `basis` entrypoint, including custom hooks.

```bash
basis git setup              # Install hooks from basis.config.ts
basis git staged             # Run lint-staged (used in pre-commit hook)
basis git lint-commit        # Validate commit message (used in commit-msg hook)

# Git passthrough — all standard git commands work
basis git status
basis git log --oneline --graph
basis git branch -a
basis git stash list
basis git diff HEAD~1
```

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

### Configure Funish Basis

Source: https://github.com/funish/basis/blob/main/README.md

Define the configuration for Funish Basis in `basis.config.ts`. This includes settings for linting, formatting, and Git hooks.

```typescript
// basis.config.ts
import { defineBasisConfig } from "@funish/basis/config";

export default defineBasisConfig({
  lint: {
    config: ["--fix", "--fix-suggestions", "--type-aware", "--type-check"],
  },
  fmt: {
    config: ["--write", "."],
  },
  git: {
    hooks: {
      "pre-commit": "pnpm basis git staged",
      "commit-msg": "pnpm basis git lint-commit",
    },
    staged: {
      rules: {
        "**/*.{ts,tsx,js,jsx}": "basis lint",
        "**/*.{json,md,yml,yaml}": "basis fmt",
      },
    },
  },
});
```

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

### publishToNpm

Source: https://context7.com/funish/basis/llms.txt

Publishes the current package to npm, automatically determining the tag from the version string and allowing for additional tags.

```APIDOC
## `publishToNpm` — Publish Package to npm

Publishes the current package to npm, auto-detecting the tag from the version string (prerelease identifier becomes the dist-tag), and optionally adds an additional dist-tag.

### Usage

```typescript
import { publishToNpm } from "@funish/basis";

// Publish stable release → tagged as "latest" + "edge" (additionalTag)
await publishToNpm(
  { tag: undefined, dryRun: false },
  { npm: { tag: "latest", additionalTag: "edge", access: "public" } },
);

// Publish a prerelease (version: "1.0.0-beta.1") → auto-tagged as "beta"
await publishToNpm(
  {},
  { npm: { additionalTag: "edge" } },
);

// Dry run (does not actually publish)
await publishToNpm({ dryRun: true }, {});

// With OTP for 2FA
await publishToNpm({ otp: "123456" }, { npm: { access: "public" } });

// Publish with restricted access (private scoped package)
await publishToNpm({}, { npm: { access: "restricted" } });
```

### CLI Equivalents

```bash
basis publish              # Auto-detect tag from version
basis publish --tag beta   # Override tag
basis publish --git        # Also create git commit + tag
basis publish --dry-run    # Preview without publishing
basis publish --otp 123456 # Two-factor authentication
```

### Parameters

- `options` (object) - Options for publishing.
  - `tag` (string | undefined) - The npm dist-tag to use. If undefined, it's inferred from the version string.
  - `dryRun` (boolean) - If true, simulates the publish process without actually publishing.
  - `otp` (string) - One-time password for two-factor authentication.
- `npmOptions` (object) - Options specific to npm publishing.
  - `tag` (string) - Explicitly set the npm dist-tag.
  - `additionalTag` (string) - An additional dist-tag to apply.
  - `access` (string) - The access level for the package (`"public"` or `"restricted"`).
```

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

### Run All Audits with auditAll

Source: https://context7.com/funish/basis/llms.txt

Runs both dependency and structure audits in parallel. Use `false` for the `fix` argument to only report issues without attempting to fix them.

```typescript
import { auditAll } from "@funish/basis";

const passed = await auditAll(process.cwd(), false /* fix */);
// Output:
// ◐ Running comprehensive project audit...
// ✔ Dependencies audit passed
// ✔ Structure audit passed
// ✔ All audits passed
```

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

### lintStagedFiles

Source: https://context7.com/funish/basis/llms.txt

Runs commands on Git staged files. It reads the staged file list, matches files against glob patterns in `git.staged.rules`, executes mapped commands, and re-stages modified files.

```APIDOC
## lintStagedFiles

### Description
Runs commands on Git staged files. It reads the staged file list, matches files against glob patterns in `git.staged.rules`, executes mapped commands, and re-stages modified files.

### Method Signature
```typescript
lintStagedFiles(cwd: string): Promise<boolean>
```

### Parameters
* **cwd** (string) - Required - The current working directory.

### Request Example
```typescript
import { lintStagedFiles } from "@funish/basis";

const passed = await lintStagedFiles(process.cwd());
if (!passed) {
  process.exit(1);
}
```

### CLI Equivalent
```bash
basis git staged
```
```

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

### publishGitOperations

Source: https://context7.com/funish/basis/llms.txt

Performs git operations related to publishing, including creating a release commit, tagging, and optionally pushing to the remote repository.

```APIDOC
## `publishGitOperations` — Git Commit and Tag on Publish

Creates a release commit (staging only `package.json`), creates a git tag, and optionally pushes to remote.

### Usage

```typescript
import { publishGitOperations } from "@funish/basis";

await publishGitOperations("1.2.0", {
  tagPrefix: "v",                                 // Tag name: "v1.2.0"
  message: (v) => `chore: release v${v}`,         // Commit message
  push: true,                                     // Push commit + tags to remote
  signTag: false,                                 // Don't GPG-sign the tag
});
// Creates: commit "chore: release v1.2.0", tag "v1.2.0", pushes both
```

### Parameters

- `version` (string) - The new version string.
- `options` (object) - Git operation options.
  - `tagPrefix` (string) - Prefix for the git tag (e.g., `"v"`).
  - `message` (function) - A function that returns the commit message, receiving the version as an argument.
  - `push` (boolean) - Whether to push the commit and tags to the remote repository.
  - `signTag` (boolean) - Whether to GPG-sign the git tag.
```

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

### Configure Funish Basis with `defineBasisConfig`

Source: https://context7.com/funish/basis/llms.txt

Use `defineBasisConfig` in `basis.config.ts` for type-safe configuration of linting, formatting, versioning, publishing, Git hooks, and project auditing. This helper function enforces the `BasisConfig` type.

```typescript
// basis.config.ts
import { defineBasisConfig } from "@funish/basis/config";

export default defineBasisConfig({
  lint: {
    // Passed as CLI args to oxlint
    config: ["--fix", "--fix-suggestions", "--type-aware", "--type-check"],
  },
  fmt: {
    // Passed as CLI args to oxfmt
    config: ["--write", "."],
  },
  version: {
    preid: "beta", // Default prerelease identifier (default: "edge")
  },
  publish: {
    npm: {
      tag: "latest",         // Default dist-tag
      additionalTag: "edge", // Also tag as "edge" after publish
      access: "public",
    },
    git: {
      tagPrefix: "v",
      message: (version) => `chore: release v${version}`,
      push: true,
      signTag: false,
    },
  },
  git: {
    hooks: {
      "pre-commit": "pnpm basis git staged",
      "commit-msg": "pnpm basis git lint-commit",
    },
    staged: {
      rules: {
        // String: command run as-is
        "**/*.{ts,tsx,js,jsx}": "basis lint --fix",
        // Array: multiple commands run in sequence
        "**/*.{json,md,yml,yaml}": ["basis fmt --write", "basis lint"],
        // Function: full control over matched files
        "*.tsx": (files) => `basis lint --fix ${files.slice(0, 10).join(" ")}`,
      },
    },
    commitMsg: {
      types: ["feat", "fix", "docs", "chore", "refactor", "test", "ci"],
      maxLength: 72,
      minLength: 10,
      scopeRequired: false,
      allowedScopes: ["cli", "config", "git", "publish"],
    },
  },
  audit: {
    dependencies: {
      outdated: true,
      security: true,
      licenses: {
        allowed: ["MIT", "Apache-2.0", "ISC", "BSD-2-Clause", "BSD-3-Clause"],
        blocked: ["GPL-3.0"],
      },
      blocked: ["moment", "lodash"], // Packages that must not be used
    },
    structure: {
      required: ["README.md", "src/index.ts", "package.json"],
      files: [
        { pattern: "src/**/*.ts", rule: "^[a-z]", message: "Source files must start with lowercase" },
      ],
      dirs: [
        { pattern: "src/*", rule: "^[a-z]", message: "Source directories must be lowercase" },
      ],
    },
  },
});
```