knowhub

https://github.com/yujiosaka/knowhub
Admin
knowhub is a lightweight CLI tool designed to synchronize AI coding-agent knowledge files, rules,...
Tokens:6,377
Snippets:81
Trust Score:8.7
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install Knowhub dependencies

Source: https://github.com/yujiosaka/knowhub/blob/main/examples/README.md

Install the core Knowhub package and the Octokit REST client.

```bash
npm install knowhub @octokit/rest
```

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

### Authentication Setup

Source: https://github.com/yujiosaka/knowhub/blob/main/examples/README.md

Commands and configuration for setting up GitHub authentication via environment variables.

```bash
export GITHUB_TOKEN=your_token_here
```

```yaml
pluginConfig:
  token: '${GITHUB_TOKEN}'
```

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

### Configure Local Plugin

Source: https://github.com/yujiosaka/knowhub/blob/main/README.md

Configuration interface and example for the local filesystem plugin.

```typescript
// Plugin configuration
interface LocalPluginConfig {
  path: string;       // Local filesystem path
  symlink?: boolean;  // Create symlinks instead of copying (default: false)
}
```

```yaml
- plugin: "local"
  pluginConfig:
    path: "./shared-rules/common-style.md"
    symlink: true
  overwrite: true
  outputs: [".cursor/rules/common-style.md"]
```

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

### Basic File Fetching Configuration

Source: https://github.com/yujiosaka/knowhub/blob/main/examples/README.md

Example configuration for fetching a single file from a GitHub repository.

```yaml
# .knowhubrc.yaml
plugins:
  - "./examples/github-plugin.ts"

resources:
  # Fetch a single file from GitHub
  - plugin: 'github'
    pluginConfig:
      owner: 'company'
      repo: 'coding-standards'
      path: 'rules/typescript-style.md'
      ref: 'main'
      token: '${GITHUB_TOKEN}'  # Environment variable
    outputs: ['.cursor/rules/typescript.md']
    overwrite: true
```

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

### Install Knowhub

Source: https://github.com/yujiosaka/knowhub/blob/main/README.md

Add Knowhub as a development dependency using npm, yarn, or bun.

```bash
npm install --save-dev knowhub
# or
yarn add --dev knowhub
# or
bun add --dev knowhub
```

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

### Overwriting and Multi-File Configuration

Source: https://github.com/yujiosaka/knowhub/blob/main/examples/README.md

Configuration examples for overwriting existing files and fetching multiple files to different locations.

```yaml
resources:
  # Overwrite cursor rules with latest from GitHub
  - plugin: 'github'
    pluginConfig:
      owner: 'myorg'
      repo: 'development-standards'
      path: 'cursor/rules.md'
      ref: 'main'
      token: '${GITHUB_TOKEN}'
    overwrite: true  # This will replace existing .cursor/rules.md
    outputs: ['.cursor/rules.md']

  # Fetch multiple files to different locations
  - plugin: 'github'
    pluginConfig:
      owner: 'myorg'
      repo: 'eslint-config'
      path: '.eslintrc.json'
      ref: 'v2.1.0'  # Use specific version
      token: '${GITHUB_TOKEN}'
    overwrite: true
    outputs:
      - '.eslintrc.json'
      - 'config/eslint-base.json'
```

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

### Install Octokit Dependency

Source: https://github.com/yujiosaka/knowhub/blob/main/examples/README.md

Install the required Octokit package to enable GitHub API interactions.

```bash
npm install @octokit/rest
```

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

### Version Pinning Configuration

Source: https://github.com/yujiosaka/knowhub/blob/main/examples/README.md

Example of pinning a resource to a specific commit SHA.

```yaml
# Pin to specific commit SHA
pluginConfig:
  owner: 'company'
  repo: 'standards'
  path: 'rules.md'
  ref: 'a1b2c3d4e5f6'  # Specific commit
  token: '${GITHUB_TOKEN}'
```

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

### Configure HTTP Plugin

Source: https://github.com/yujiosaka/knowhub/blob/main/README.md

Configuration interface and example for the HTTP(S) resource fetching plugin.

```typescript
// Plugin configuration
interface HttpPluginConfig {
  url: string;                    // HTTP(S) URL to fetch
  headers?: Record<string, string>; // Custom headers
  timeout?: number;               // Timeout in milliseconds (default: 30000)
  method?: string;                // HTTP method (default: "GET")
  body?: string;                  // Request body for POST/PUT
}
```

```yaml
- plugin: "http"
  pluginConfig:
    url: "https://example.com/api-spec.json"
    headers:
      Authorization: "Bearer YOUR_API_TOKEN_HERE"
      Accept: "application/json"
    timeout: 10000
  overwrite: true
  outputs: ["src/assets/api-spec.json"]
```

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

### Bad Commit Messages

Source: https://github.com/yujiosaka/knowhub/blob/main/CLAUDE.md

Examples of commit messages that violate project standards and should be avoided.

```text
❌ Update files
❌ Fix bug
❌ Added new feature
❌ WIP: working on sync
❌ Fixed the thing that was broken
❌ docs: Update README.md.
❌ FEAT: Add new command
```

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

### Good Commit Messages

Source: https://github.com/yujiosaka/knowhub/blob/main/CLAUDE.md

Examples of commit messages that adhere to the project's conventional commit standards.

```text
feat(cli): add sync command for knowledge files
fix(config): resolve parsing error for nested configurations
docs(readme): update installation instructions
refactor(plugins): simplify plugin registry initialization
test(sync): add integration tests for GitHub plugin
chore(deps): update biome to v1.9.4
style(cli): fix formatting in help command
perf(sync): optimize file processing for large repositories
```

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

### Execute Knowhub

Source: https://github.com/yujiosaka/knowhub/blob/main/examples/README.md

Run the Knowhub CLI tool to process the configured plugins.

```bash
npx knowhub
```

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

### Run Knowhub in Dry-run Mode

Source: https://github.com/yujiosaka/knowhub/blob/main/README.md

Preview actions without modifying any files or directories.

```bash
npx knowhub --dry-run
```

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

### Knowhub YAML Configuration

Source: https://github.com/yujiosaka/knowhub/blob/main/README.md

A minimal .knowhubrc.yaml file demonstrating local file symlinking, remote HTTP fetching, and directory copying.

```yaml
# .knowhubrc.yaml

resources:
  # 1) Local Markdown file, symlink to two outputs, overwrite if exists
  - plugin: "local"
    pluginConfig:
      path: './shared-rules/common-style.md'
      symlink: true
    overwrite: true
    outputs:
      - '.cursor/rules/common-style.md'
      - '.github/copilot-instructions.md'

  # 2) Remote YAML (URL), copy to two outputs, skip overwriting existing files
  - plugin: "http"
    pluginConfig:
      url: 'https://raw.githubusercontent.com/YourOrg/ai-rules/main/security-guidelines.yaml'
    overwrite: false
    outputs:
      - '.windsurfrules'
      - 'docs/ai/security-guidelines.yaml'

  # 3) Local UI widgets directory, recursively copy into output, overwrite existing
  - plugin: "local"
    pluginConfig:
      path: './shared-rules/ui-widgets'
    overwrite: true
    outputs:
      - 'components/ui-widgets'

  # 4) Local PDF, copy and overwrite
  - plugin: "local"
    pluginConfig:
      path: './shared-rules/compliance.pdf'
    overwrite: true
    outputs:
      - 'docs/ai/compliance.pdf'

  # 5) Remote JSON with custom headers
  - plugin: "http"
    pluginConfig:
      url: 'https://example.com/api-spec.json'
      headers:
        Authorization: "Bearer YOUR_API_TOKEN_HERE"
        Accept: "application/json"
      timeout: 10000
    overwrite: true
    outputs:
      - 'src/assets/api-spec.json'
```

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

### Fetching Entire Directories

Source: https://github.com/yujiosaka/knowhub/blob/main/examples/README.md

Configuration for fetching entire directories or specific documentation folders.

```yaml
resources:
  # Fetch entire UI component library
  - plugin: 'github'
    pluginConfig:
      owner: 'company'
      repo: 'design-system'
      path: 'components/ui'  # Entire directory
      ref: 'v3.2.0'
      token: '${GITHUB_TOKEN}'
    overwrite: true
    outputs: ['src/shared/components']

  # Fetch documentation directory
  - plugin: 'github'
    pluginConfig:
      owner: 'company'
      repo: 'engineering-docs'
      path: 'standards'
      ref: 'main'
      token: '${GITHUB_TOKEN}'
    overwrite: false  # Don't overwrite existing docs
    outputs: ['docs/standards']
```

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

### Configure Plugin Loading

Source: https://github.com/yujiosaka/knowhub/blob/main/examples/README.md

Register the GitHub plugin in the Knowhub configuration file.

```yaml
plugins:
  - "./plugins/github-plugin.ts"
```

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

### Configure Dynamic Plugin Loading

Source: https://github.com/yujiosaka/knowhub/blob/main/examples/README.md

Register plugins by adding their file paths to the .knowhubrc.yaml configuration file.

```yaml
# .knowhubrc.yaml
plugins:
  - "./plugins/my-custom-plugin.ts"
  - "./plugins/github-plugin.ts"

resources:
  - plugin: "my-plugin"
    pluginConfig:
      # Plugin-specific configuration
    outputs: ["output/path"]
```

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

### Configure Knowhub plugin

Source: https://github.com/yujiosaka/knowhub/blob/main/examples/README.md

Define the plugin path and resource configuration in the .knowhubrc.yaml file.

```yaml
plugins:
  - "./plugins/github-plugin.ts"

resources:
  - plugin: 'github'
    pluginConfig:
      owner: 'company'
      repo: 'standards'
      path: 'cursor-rules.md'
      token: '${GITHUB_TOKEN}'
    overwrite: true
    outputs: ['.cursor/rules.md']
```

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

### Configure Environment Variables

Source: https://github.com/yujiosaka/knowhub/blob/main/README.md

Compare environment variable handling between static configuration files and dynamic JavaScript/TypeScript files.

```yaml
# ❌ This does NOT work in YAML/JSON files
headers:
  Authorization: "Bearer ${API_TOKEN}"

# ✅ Use literal values in YAML/JSON files
headers:
  Authorization: "Bearer YOUR_API_TOKEN_HERE"
```

```typescript
// ✅ This works in TypeScript/JavaScript files
headers: {
  Authorization: `Bearer ${process.env.API_TOKEN}`,
}
```

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

### Share Copilot Instructions with symlinks

Source: https://github.com/yujiosaka/knowhub/blob/main/README.md

Creates a symlink for Copilot instructions from a shared location to the project root.

```yaml
resources:
  - plugin: "local"
    pluginConfig:
      path: './ai-rules/copilot/instructions.md'
      symlink: true
    overwrite: true
    outputs:
      - '.github/copilot-instructions.md'
```

```text
.github/copilot-instructions.md → ../ai-rules/copilot/instructions.md
```

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

### Configure Plugin in .knowhubrc.yaml

Source: https://github.com/yujiosaka/knowhub/blob/main/examples/README.md

Registers the custom plugin and provides configuration values in the YAML configuration file.

```yaml
# .knowhubrc.yaml
plugins:
  - "./plugins/my-custom-plugin.ts"

resources:
  - plugin: "my-plugin"
    pluginConfig:
      url: "https://api.example.com/config.json"
      apiKey: "${API_KEY}"
      timeout: 10000
    outputs: ["config/api-settings.json"]
```

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

### Distribute remote Windsurf settings

Source: https://github.com/yujiosaka/knowhub/blob/main/README.md

Fetches a remote YAML configuration file and distributes it to multiple local paths.

```yaml
resources:
  - plugin: "http"
    pluginConfig:
      url: 'https://raw.githubusercontent.com/YourOrg/ai-rules/main/windsurf-config.yaml'
    overwrite: false
    outputs:
      - '.windsurfrules'
      - 'docs/ai/windsurf-config.yaml'
```

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

### Integrate Knowhub with GitHub Actions

Source: https://github.com/yujiosaka/knowhub/blob/main/README.md

Automate the synchronization of AI agent knowledge by running Knowhub and committing changes in a CI pipeline.

```yaml
name: Sync AI Agent Knowledge

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

jobs:
  sync-ai-agent-knowledge:
    runs-on: ubuntu-latest

    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v3

      - name: Install dependencies
        run: npm ci

      - name: Run knowhub
        run: npx knowhub

      - name: Commit updated outputs
        run: |
          git config user.name "github-actions"
          git config user.email "actions@github.com"
          git add .
          git diff --quiet || git commit -m "chore: update AI agent knowledge files"
          git push
```

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

### Public Repository Configuration

Source: https://github.com/yujiosaka/knowhub/blob/main/examples/README.md

Configuration for fetching from public repositories without requiring an authentication token.

```yaml
# No token needed for public repos
pluginConfig:
  owner: 'microsoft'
  repo: 'TypeScript'
  path: 'README.md'
  # token not required for public repos
```

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

### Specify Custom Configuration Path

Source: https://github.com/yujiosaka/knowhub/blob/main/README.md

Point the CLI to a configuration file located outside the default path.

```bash
npx knowhub --config ./config/my-knowhub.yaml
```

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

### Implement Custom Plugin Class

Source: https://github.com/yujiosaka/knowhub/blob/main/examples/README.md

Implements the Plugin interface, including schema definition, configuration validation, and the fetch method.

```typescript
import type {
  Plugin,
  PluginConfigSchema,
  PluginContext,
  PluginResult,
} from "knowhub";
import { PluginConfigurationError, PluginError } from "knowhub";

export default class MyCustomPlugin implements Plugin {
  readonly name = "my-plugin";
  readonly version = "1.0.0";
  readonly description = "Fetches resources from a custom API";

  readonly schema: PluginConfigSchema = {
    type: "object",
    properties: {
      url: { type: "string", description: "API endpoint URL" },
      apiKey: { type: "string", description: "API key for authentication" },
      timeout: { type: "number", description: "Request timeout in milliseconds" },
    },
    required: ["url"],
    additionalProperties: false,
  };

  async validate(config: unknown): Promise<void> {
    if (!config || typeof config !== "object") {
      throw new PluginConfigurationError(
        this.name,
        "config",
        "must be an object"
      );
    }

    const myConfig = config as Record<string, unknown>;

    if (typeof myConfig.url !== "string" || !myConfig.url) {
      throw new PluginConfigurationError(
        this.name,
        "url",
        "must be a non-empty string"
      );
    }
  }

  async fetch(config: unknown, context: PluginContext): Promise<PluginResult> {
    await this.validate(config);

    const myConfig = config as MyPluginConfig;
    
    try {
      // Implement your fetching logic here
      const response = await fetch(myConfig.url, {
        headers: myConfig.apiKey ? { 'Authorization': `Bearer ${myConfig.apiKey}` } : {},
        timeout: myConfig.timeout || 30000,
      });

      if (!response.ok) {
        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
      }

      const content = await response.text();

      context.logger.info(`Successfully fetched from ${myConfig.url}`);

      return {
        content,
        isDirectory: false,
        metadata: {
          lastModified: new Date(),
          size: content.length,
          url: myConfig.url,
        },
      };
    } catch (error) {
      throw new PluginError(
        `Failed to fetch from ${myConfig.url}: ${error instanceof Error ? error.message : String(error)}`,
        this.name,
        error instanceof Error ? error : undefined
      );
    }
  }
}
```

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

### Copy directory trees

Source: https://github.com/yujiosaka/knowhub/blob/main/README.md

Recursively copies an entire directory of templates to multiple destination paths.

```yaml
resources:
  - plugin: "local"
    pluginConfig:
      path: './ai-templates'
    overwrite: true
    outputs:
      - 'src/ai/prompt-templates'
      - 'docs/ai/prompt-templates'
```

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

### Implement the Plugin Interface

Source: https://github.com/yujiosaka/knowhub/blob/main/examples/README.md

Defines the structure for a custom plugin by implementing the Plugin interface, including name, version, schema, and fetch logic.

```typescript
import type {
  Plugin,
  PluginConfigSchema,
  PluginContext,
  PluginResult,
} from "knowhub";

export class MyCustomPlugin implements Plugin {
  readonly name = "my-plugin";           // Unique plugin identifier
  readonly version = "1.0.0";            // Plugin version
  readonly description = "Description";   // Plugin description
  readonly schema: PluginConfigSchema;    // JSON schema for configuration

  async validate(config: unknown): Promise<void> {
    // Validate plugin configuration
  }

  async fetch(config: unknown, context: PluginContext): Promise<PluginResult> {
    // Fetch resource and return result
  }
}
```

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

### GitHub Enterprise Configuration

Source: https://github.com/yujiosaka/knowhub/blob/main/examples/README.md

Configuration for connecting to a custom GitHub Enterprise instance.

```yaml
pluginConfig:
  owner: 'company'
  repo: 'standards'
  path: 'rules.md'
  token: '${GITHUB_TOKEN}'
  baseUrl: 'https://github.company.com/api/v3'  # Enterprise URL
```

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

### Sync Cursor Rules locally

Source: https://github.com/yujiosaka/knowhub/blob/main/README.md

Synchronizes a centralized folder of Cursor rules to a project-specific directory.

```yaml
# .knowhubrc.yaml
resources:
  - plugin: "local"
    pluginConfig:
      path: './ai-rules/cursor'
    overwrite: true
    outputs:
      - '.cursor/rules'
```

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

### Knowhub TypeScript Configuration

Source: https://github.com/yujiosaka/knowhub/blob/main/README.md

A .knowhubrc.ts file using the Config type for type-safe resource management.

```ts
// .knowhubrc.ts
import type { Config } from 'knowhub';

const config: Config = {
  resources: [
    {
      plugin: "local",
      pluginConfig: {
        path: './shared-rules/common-style.md',
        symlink: true,
      },
      overwrite: true,
      outputs: ['.cursor/rules/common-style.md', '.github/copilot-instructions.md'],
    },
    {
      plugin: "http",
      pluginConfig: {
        url: 'https://raw.githubusercontent.com/YourOrg/ai-rules/main/security-guidelines.yaml',
      },
      overwrite: false,
      outputs: ['.windsurfrules', 'docs/ai/security-guidelines.yaml'],
    },
    {
      plugin: "local",
      pluginConfig: {
        path: './shared-rules/ui-widgets',
      },
      overwrite: true,
      outputs: ['components/ui-widgets'],
    },
    {
      plugin: "local",
      pluginConfig: {
        path: './shared-rules/compliance.pdf',
      },
      overwrite: true,
      outputs: ['docs/ai/compliance.pdf'],
    },
    {
      plugin: "http",
      pluginConfig: {
        url: 'https://example.com/api-spec.json',
        headers: {
          Authorization: "Bearer ${API_TOKEN}",
          Accept: "application/json",
        },
        timeout: 10000,
      },
      overwrite: true,
      outputs: ['src/assets/api-spec.json'],
    },
  ],
};

export default config;
```

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

### Perform authenticated HTTP requests

Source: https://github.com/yujiosaka/knowhub/blob/main/README.md

Fetches remote configuration using custom headers and a specified timeout.

```yaml
resources:
  - plugin: "http"
    pluginConfig:
      url: 'https://api.internal.com/config.json'
      headers:
        Authorization: "Bearer YOUR_API_TOKEN_HERE"
        X-Team: "frontend"
        Accept: "application/json"
      timeout: 15000
    overwrite: true
    outputs:
      - 'config/api-settings.json'
```

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

### Register Plugins Manually

Source: https://github.com/yujiosaka/knowhub/blob/main/examples/README.md

Use the pluginRegistry to manually register a plugin instance, typically used for legacy support.

```typescript
import { pluginRegistry } from 'knowhub';
import { MyCustomPlugin } from './plugins/my-custom-plugin.js';

pluginRegistry.register(new MyCustomPlugin());
```

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

### Run Knowhub in Quiet Mode

Source: https://github.com/yujiosaka/knowhub/blob/main/README.md

Suppress all console output, which is useful for CI/CD environments.

```bash
npx knowhub --quiet
```

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

### Define Plugin Configuration Interface

Source: https://github.com/yujiosaka/knowhub/blob/main/examples/README.md

Defines the TypeScript interface for the plugin's configuration object.

```typescript
interface MyPluginConfig {
  url: string;
  apiKey?: string;
  timeout?: number;
}
```

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

### Define Resource Schema

Source: https://github.com/yujiosaka/knowhub/blob/main/README.md

Schema definition for entries in the resources array.

```typescript
/**
 * One resource to be synchronized using the plugin architecture.
 *
 * - `plugin`: string (required) - Name of the plugin to use (e.g., "local", "http")
 * - `pluginConfig`: object (required) - Plugin-specific configuration
 * - `overwrite`: boolean (default: true) - Whether to overwrite existing files
 * - `outputs`: string or string[] (required) - Output destination paths
 */
export type Resource = {
  plugin: string;           // e.g. "local", "http", "github"
  pluginConfig: unknown;    // Plugin-specific configuration object
  overwrite?: boolean;      // Default: true
  outputs: string | string[];
};
```

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

### Angular Commit Message Format

Source: https://github.com/yujiosaka/knowhub/blob/main/CLAUDE.md

The standard structure for all commit messages in the project.

```text
type(scope): description

[optional body]

[optional footer(s)]
```
Tokens:
Raw