@tyvm/knowhow 0.0.158 → 0.0.160

package/docs/multi-worker-management.md

@@ -1,142 +0,0 @@
-# Multi-Worker Management
-
-This feature allows you to manage and start multiple knowhow workers from different directories using a centralized registry.
-
-## Overview
-
-The multi-worker management system provides:
-- Registration of worker directories in a global config (`~/.knowhow/workers.json`)
-- A single command to start all registered workers simultaneously
-- Management commands to list, register, and unregister workers
-
-## Usage
-
-### Register a Worker
-
-Navigate to a project directory and register it as a worker:
-
-```bash
-cd /path/to/project1
-knowhow worker --register
-```
-
-This will:
-1. Register the current directory in `~/.knowhow/workers.json`
-2. Ensure the worker configuration is set up in the local `.knowhow/knowhow.json`
-
-### Start All Workers
-
-Start all registered workers at once:
-
-```bash
-knowhow workers
-```
-
-This command will:
-- Read all registered worker paths from the global config
-- Start each worker by executing `knowhow worker` in its directory
-- Keep all workers running until you press Ctrl+C
-- Gracefully shut down all workers on exit
-
-### List Registered Workers
-
-View all registered worker paths:
-
-```bash
-knowhow workers --list
-```
-
-Output example:
-```
-Registered workers (3):
-  1. /Users/username/project1
-  2. /Users/username/project2
-  3. /Users/username/project3
-```
-
-### Unregister a Worker
-
-Remove a worker from the registry:
-
-```bash
-knowhow workers --unregister /path/to/project
-```
-
-### Clear All Workers
-
-Remove all registered workers:
-
-```bash
-knowhow workers --clear
-```
-
-## Configuration
-
-The worker registry is stored in:
-```
-~/.knowhow/workers.json
-```
-
-Example format:
-```json
-{
-  "workers": [
-    "/Users/username/project1",
-    "/Users/username/project2",
-    "/Users/username/project3"
-  ]
-}
-```
-
-## Typical Workflow
-
-1. **Set up multiple projects as workers:**
-   ```bash
-   cd ~/project1
-   knowhow worker --register
-   
-   cd ~/project2
-   knowhow worker --register
-   
-   cd ~/project3
-   knowhow worker --register
-   ```
-
-2. **Start all workers:**
-   ```bash
-   knowhow workers
-   ```
-
-3. **Check worker status:**
-   ```bash
-   knowhow workers --list
-   ```
-
-4. **Stop all workers:**
-   Press `Ctrl+C` in the terminal where workers are running
-
-## Benefits
-
-- **Centralized Management**: Manage multiple workers from a single command
-- **Simplified Deployment**: No need to manually start workers in each directory
-- **Persistent Configuration**: Worker registrations persist across sessions
-- **Graceful Shutdown**: All workers shut down cleanly when stopped
-
-## Implementation Details
-
-### Files Created
-
-- `src/workerRegistry.ts` - Core registry management functions
-- `~/.knowhow/workers.json` - Global worker registry storage
-
-### CLI Commands Modified
-
-- `knowhow worker` - Added `--register` flag to register current directory
-- `knowhow workers` - New command with subcommands for management and starting workers
-
-### Process Management
-
-- Each worker runs as a child process
-- Workers inherit stdio from the parent process (you see all logs)
-- SIGINT/SIGTERM signals are properly handled for graceful shutdown
-- Workers are not detached, so they stop when the parent process stops

package/docs/shell-commands.md

@@ -1,174 +0,0 @@
-# Shell Command Execution
-
-Knowhow provides multiple ways to execute shell commands during chat sessions, both for interactive terminal use and for sending command output to the AI agent.
-
-## Quick Commands: `/!` and `/!!`
-
-Available in `agent` and `agent:attached` modes:
-
-### `/!` - Interactive Shell Command
-Execute a command and display output in the console. The command runs interactively, allowing you to interact with it if needed.
-
-```
-/! git status
-/! npm test
-/! terraform plan
-```
-
-Output is displayed to you but **not sent to the AI agent**.
-
-### `/!!` - Send Output to AI
-Execute a command and send the output to the AI agent for analysis.
-
-```
-/!! git diff
-/!! npm run lint
-/!! cat error.log
-```
-
-Output is displayed to you **and sent to the AI agent** for processing.
-
-## Custom Commands via Language Config
-
-You can define custom shell commands in `.knowhow/language.json` that integrate with the language plugin system.
-
-### Example: `/git` Command
-
-```json
-{
-  "/git": {
-    "events": [],
-    "handled": true,
-    "sources": [
-      {
-        "kind": "exec",
-        "data": [
-          "git status"
-        ]
-      }
-    ]
-  }
-}
-```
-
-This creates a `/git` command that runs `git status` when invoked.
-
-### Example: `/tfplan` Command
-
-```json
-{
-  "/tfplan": {
-    "events": [],
-    "handled": true,
-    "sources": [
-      {
-        "kind": "exec",
-        "data": [
-          "cd terraform && terraform plan"
-        ]
-      }
-    ]
-  }
-}
-```
-
-### The `handled` Property
-
-- **`handled: true`** - Command output is displayed to the user only, **not sent to the AI agent**
-- **`handled: false`** (default) - Command output is sent to the AI agent for processing
-
-This allows you to:
-- Use `handled: true` for commands where you just want to see output (like `/tfplan`)
-- Use `handled: false` for commands where you want the AI to analyze the output
-
-### Multiple Commands
-
-You can also chain multiple commands or execute more complex operations:
-
-```json
-{
-  "/deploy-status": {
-    "events": [],
-    "handled": false,
-    "sources": [
-      {
-        "kind": "exec",
-        "data": [
-          "kubectl get pods && kubectl get services"
-        ]
-      }
-    ]
-  }
-}
-```
-
-## Exec Plugin
-
-The exec plugin is automatically enabled and allows language config entries to execute shell commands. It's used internally by the custom command system.
-
-### Plugin Configuration
-
-The exec plugin is enabled by default in `.knowhow/knowhow.json`:
-
-```json
-{
-  "plugins": {
-    "enabled": [
-      "exec",
-      // ... other plugins
-    ]
-  }
-}
-```
-
-## Use Cases
-
-### Development Workflow
-```json
-{
-  "/build": {
-    "handled": false,
-    "sources": [{ "kind": "exec", "data": ["npm run build"] }]
-  },
-  "/test": {
-    "handled": false,
-    "sources": [{ "kind": "exec", "data": ["npm test"] }]
-  }
-}
-```
-
-### Infrastructure Management
-```json
-{
-  "/infra": {
-    "handled": true,
-    "sources": [{ "kind": "exec", "data": ["terraform plan"] }]
-  },
-  "/pods": {
-    "handled": false,
-    "sources": [{ "kind": "exec", "data": ["kubectl get pods"] }]
-  }
-}
-```
-
-### Git Workflows
-```json
-{
-  "/changes": {
-    "handled": false,
-    "sources": [{ "kind": "exec", "data": ["git diff --cached"] }]
-  },
-  "/branches": {
-    "handled": true,
-    "sources": [{ "kind": "exec", "data": ["git branch -a"] }]
-  }
-}
-```
-
-## Security Notes
-
-- Commands are executed in your current working directory
-- Commands run with your user permissions
-- Be cautious with commands that modify system state
-- The exec plugin has a 10MB output buffer limit
-- Interactive commands work with `/!` but not with language config exec sources

package/jest.config.js

@@ -1,19 +0,0 @@
-module.exports = {
-  extensionsToTreatAsEsm: ['.ts'],
-  moduleNameMapper: {
-    '^(\\.{1,2}/.*)\\.js$': '$1',
-  },
-  transform: {
-    '^.+\\.ts?$': [
-      'ts-jest',
-      {
-        useESM: true,
-      },
-    ],
-  },
-  testEnvironment: 'node',
-  testRegex: '/tests/.*\.(test|spec)\.(ts|tsx|js)$',
-  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node'],
-  modulePathIgnorePatterns: ["ts_build", "benchmarks"],
-  testPathIgnorePatterns: ["<rootDir>/benchmarks/", "<rootDir>/tests/manual/"],
-};

package/jest.manual.config.js

@@ -1,19 +0,0 @@
-module.exports = {
-  extensionsToTreatAsEsm: ['.ts'],
-  moduleNameMapper: {
-    '^(\\.{1,2}/.*)\\.js$': '$1',
-  },
-  transform: {
-    '^.+\\.ts?$': [
-      'ts-jest',
-      {
-        useESM: true,
-      },
-    ],
-  },
-  testEnvironment: 'node',
-  testRegex: '/tests/manual/.*\.(test|spec)\.(ts|tsx|js)$',
-  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node'],
-  modulePathIgnorePatterns: ["ts_build", "benchmarks"],
-  testPathIgnorePatterns: [],
-};

package/scripts/README.md

@@ -1,119 +0,0 @@
-# AI Keys Management Scripts
-
-These bash scripts help you temporarily unset and restore AI API keys in your terminal session. This is useful for testing CLI behavior without authentication or when you want to work in a clean environment.
-
-## Installation
-
-Add these functions to your `~/.bashrc` or `~/.zshrc`:
-
-```bash
-# AI Keys Management
-unset_keys() {
-    source /path/to/knowhow/scripts/unset_keys.sh
-}
-
-restore_keys() {
-    source /path/to/knowhow/scripts/restore_keys.sh
-}
-```
-
-Replace `/path/to/knowhow` with the actual path to your knowhow repository.
-
-Then reload your shell:
-```bash
-source ~/.bashrc  # or source ~/.zshrc
-```
-
-## Usage
-
-### Unset Keys
-
-Temporarily remove AI API keys from your current shell session:
-
-```bash
-unset_keys
-```
-
-This will:
-- Backup all your API keys to `BACKUP_*` environment variables
-- Unset the following environment variables:
-  - `OPENAI_KEY`
-  - `OPENAI_API_KEY`
-  - `ANTHROPIC_API_KEY`
-  - `ANTHROPIC_KEY`
-  - `GEMINI_API_KEY`
-  - `GOOGLE_API_KEY`
-  - `XAI_API_KEY`
-
-### Restore Keys
-
-Restore your API keys from the backup:
-
-```bash
-restore_keys
-```
-
-This will:
-- Read the backup from `BACKUP_*` environment variables
-- Restore all previously unset environment variables
-- Clear the `BACKUP_*` environment variables
-
-## Example Workflow
-
-```bash
-# Check that you have keys set
-echo $OPENAI_KEY
-# Output: sk-proj-...
-
-# Unset the keys for testing
-unset_keys
-# Output: ✓ Successfully backed up and unset 5 API key(s)
-
-# Verify keys are unset
-echo $OPENAI_KEY
-# Output: (empty)
-
-# Test your CLI without keys
-knowhow --help
-
-# Restore your keys when done
-restore_keys
-# Output: ✓ Successfully restored 5 API key(s)
-
-# Verify keys are restored
-echo $OPENAI_KEY
-# Output: sk-proj-...
-```
-
-## Notes
-
-- These commands only affect the **current terminal session**
-- The backup variables (`BACKUP_*`) are stored in the current shell session only
-- If you close your terminal before running `restore_keys`, the backups are **lost** and you'll need to restart your terminal or re-source your shell configuration to get your keys back from your original bashrc/zshrc
-- The scripts must be **sourced** (not executed) to affect your current shell environment
-
-## Troubleshooting
-
-### Keys lost after closing terminal
-
-If you close your terminal after running `unset_keys`, the backup environment variables are lost. To restore your keys, simply open a new terminal (which will reload your bashrc/zshrc with the original key values) or run:
-
-```bash
-source ~/.bashrc  # or source ~/.zshrc
-```
-
-### Permission denied
-
-Make sure the scripts are executable:
-
-```bash
-chmod +x scripts/unset_keys.sh scripts/restore_keys.sh
-```
-
-### Commands not found
-
-Make sure you've added the functions to your shell configuration and reloaded it:
-
-```bash
-source ~/.bashrc  # or source ~/.zshrc
-```

package/scripts/build-for-node.sh

@@ -1,148 +0,0 @@
-#!/usr/bin/env bash
-# Usage: bash scripts/build-for-node.sh [node-version]
-# Example: bash scripts/build-for-node.sh 24        # any Node 24.x
-# Example: bash scripts/build-for-node.sh 20.19.0   # exact version
-# Example: npm run node:build 24
-#
-# This script:
-#   1. Compiles TypeScript with Node 24 (falls back to current node if unavailable)
-#   2. Creates /tmp/knowhow-node-<major> with the compiled output
-#   3. Symlinks the package globally for ALL installed nvm versions matching the target
-#
-# Note: isolated-vm is now in @tyvm/knowhow-module-script — install that separately
-# for the correct node version if you need script execution support.
-
-set -e
-
-TARGET_VERSION="${1:-}"
-
-if [ -z "$TARGET_VERSION" ]; then
-  echo "Usage: $0 <node-version>"
-  echo "Example: $0 24"
-  echo "Example: $0 20.19.0"
-  exit 1
-fi
-
-# Extract the major version number for staging dir naming and glob matching
-TARGET_MAJOR="$(echo "$TARGET_VERSION" | cut -d. -f1)"
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-PACKAGE_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
-
-echo "📦 Package dir: $PACKAGE_DIR"
-
-# --- Find Node 24 for compiling TypeScript ---
-NODE20_BIN=""
-for dir in "$HOME/.nvm/versions/node"/v24.*/bin; do
-  if [ -f "$dir/node" ]; then
-    NODE20_BIN="$dir/node"
-    break
-  fi
-done
-
-if [ -z "$NODE20_BIN" ]; then
-  echo "⚠️  Node 24 not found via nvm, falling back to current node for TS compile"
-  NODE20_BIN="$(which node)"
-fi
-
-NODE20_NPM="$(dirname "$NODE20_BIN")/npm"
-echo "🔨 Compiling TypeScript with: $NODE20_BIN ($(${NODE20_BIN} --version))"
-
-# --- Compile TypeScript ---
-cd "$PACKAGE_DIR"
-"$NODE20_NPM" run compile
-echo "✅ TypeScript compiled"
-
-# --- Find target Node binaries ---
-# If exact version given (e.g. 20.19.0), match exactly. Otherwise match all patch versions.
-TARGET_NODE_BINS=()
-
-if echo "$TARGET_VERSION" | grep -qE '^\d+\.\d+\.\d+$'; then
-  # Exact version like 20.19.0
-  exact_dir="$HOME/.nvm/versions/node/v${TARGET_VERSION}/bin"
-  if [ -f "$exact_dir/node" ]; then
-    TARGET_NODE_BINS+=("$exact_dir/node")
-  fi
-else
-  # Major only — collect all patch versions
-  for dir in "$HOME/.nvm/versions/node"/v${TARGET_MAJOR}.*/bin; do
-    if [ -f "$dir/node" ]; then
-      TARGET_NODE_BINS+=("$dir/node")
-    fi
-  done
-fi
-
-if [ ${#TARGET_NODE_BINS[@]} -eq 0 ]; then
-  echo "❌ Node $TARGET_VERSION not found in ~/.nvm/versions/node/"
-  echo "   Run: nvm install $TARGET_VERSION"
-  exit 1
-fi
-
-# Use the last (latest patch) for building
-TARGET_NODE_BIN="${TARGET_NODE_BINS[${#TARGET_NODE_BINS[@]}-1]}"
-TARGET_NODE_ACTUAL_VERSION="$("$TARGET_NODE_BIN" --version)"
-
-echo "🎯 Found Node $TARGET_VERSION installs: ${TARGET_NODE_BINS[*]}"
-echo "🔨 Building with: $TARGET_NODE_BIN ($TARGET_NODE_ACTUAL_VERSION)"
-
-# --- Create staging directory ---
-STAGING_DIR="/tmp/knowhow-node-${TARGET_MAJOR}"
-rm -rf "$STAGING_DIR"
-mkdir -p "$STAGING_DIR"
-echo ""
-echo "📁 Staging dir: $STAGING_DIR"
-
-# --- Copy compiled output and package files into staging dir ---
-echo "📋 Copying compiled output to staging dir..."
-cp -r "$PACKAGE_DIR/ts_build" "$STAGING_DIR/ts_build"
-cp -r "$PACKAGE_DIR/bin" "$STAGING_DIR/bin" 2>/dev/null || true
-cp "$PACKAGE_DIR/package.json" "$STAGING_DIR/package.json"
-for item in README.md LICENSE .npmignore; do
-  [ -e "$PACKAGE_DIR/$item" ] && cp "$PACKAGE_DIR/$item" "$STAGING_DIR/" || true
-done
-
-# --- Patch package.json to remove workspace protocol deps ---
-echo "📝 Patching package.json..."
-"$NODE20_BIN" -e "
-  const fs = require('fs');
-  const pkg = JSON.parse(fs.readFileSync('$STAGING_DIR/package.json', 'utf8'));
-  if (pkg.dependencies) {
-    for (const [k, v] of Object.entries(pkg.dependencies)) {
-      if (String(v).startsWith('workspace:')) delete pkg.dependencies[k];
-    }
-  }
-  fs.writeFileSync('$STAGING_DIR/package.json', JSON.stringify(pkg, null, 2));
-  console.log('✅ package.json patched');
-"
-
-# --- Install dependencies in staging dir with target Node ---
-TARGET_NODE_NPM="$(dirname "$TARGET_NODE_BIN")/npm"
-echo ""
-echo "📦 Installing dependencies in staging dir with Node $TARGET_MAJOR..."
-cd "$STAGING_DIR"
-"$TARGET_NODE_NPM" install --omit=dev
-echo "✅ Dependencies installed"
-cd "$PACKAGE_DIR"
-
-# --- Symlink globally for ALL matching Node version installs ---
-PKG_NAME="$("$NODE20_BIN" -e "console.log(require('$STAGING_DIR/package.json').name)")"
-PKG_BIN_NAME="$("$NODE20_BIN" -e "const b=require('$STAGING_DIR/package.json').bin; console.log(Object.keys(b)[0])")"
-PKG_BIN_FILE="$("$NODE20_BIN" -e "const b=require('$STAGING_DIR/package.json').bin; console.log(Object.values(b)[0])")"
-
-echo ""
-echo "🔗 Linking $PKG_NAME globally for all Node $TARGET_MAJOR installs..."
-for node_bin in "${TARGET_NODE_BINS[@]}"; do
-  node_prefix="$("$node_bin" -e "const p=require('path');console.log(p.join(p.dirname(process.execPath),'..'))" 2>/dev/null)"
-  global_modules="$node_prefix/lib/node_modules"
-  global_bin="$node_prefix/bin"
-  mkdir -p "$global_modules/@tyvm"
-  rm -rf "$global_modules/$PKG_NAME"
-  ln -sf "$STAGING_DIR" "$global_modules/$PKG_NAME"
-  rm -f "$global_bin/$PKG_BIN_NAME"
-  ln -sf "$global_modules/$PKG_NAME/$PKG_BIN_FILE" "$global_bin/$PKG_BIN_NAME"
-  echo "✅ $("$node_bin" --version): $global_modules/$PKG_NAME → $STAGING_DIR"
-done
-
-echo ""
-echo "🎉 Done! Switch to Node $TARGET_MAJOR and run: knowhow"
-echo "   nvm use $TARGET_MAJOR && knowhow"