neotoma 0.3.0 → 0.3.2

package/foundation/development/worktree_setup.sh

@@ -1,207 +0,0 @@
-#!/bin/bash
-# Git Worktree Setup Script
-# Creates a new git worktree for isolated feature development
-
-set -e
-
-# Colors for output
-RED='\033[0;31m'
-GREEN='\033[0;32m'
-YELLOW='\033[1;33m'
-NC='\033[0m' # No Color
-
-# Function to print colored output
-print_info() {
-    echo -e "${GREEN}[INFO]${NC} $1"
-}
-
-print_warn() {
-    echo -e "${YELLOW}[WARN]${NC} $1"
-}
-
-print_error() {
-    echo -e "${RED}[ERROR]${NC} $1"
-}
-
-# Check if we're in a git repository
-if ! git rev-parse --is-inside-work-tree > /dev/null 2>&1; then
-    print_error "Not in a git repository"
-    exit 1
-fi
-
-# Get repository root
-REPO_ROOT=$(git rev-parse --show-toplevel)
-REPO_NAME=$(basename "$REPO_ROOT")
-
-# Parse arguments
-BRANCH_NAME=""
-BASE_BRANCH="dev"
-WORKTREE_PATH=""
-FEATURE_PREFIX="feature"
-
-# Help message
-show_help() {
-    cat << EOF
-Usage: ./worktree-setup.sh [OPTIONS] <branch-name>
-
-Creates a new git worktree for isolated feature development.
-
-OPTIONS:
-    -h, --help              Show this help message
-    -b, --base <branch>     Base branch to branch from (default: dev)
-    -p, --path <path>       Custom worktree path (default: ../<repo>-<branch>)
-    -f, --prefix <prefix>   Branch prefix (default: feature)
-
-EXAMPLES:
-    # Create feature branch from dev
-    ./worktree-setup.sh my-feature
-
-    # Create feature branch with ID
-    ./worktree-setup.sh 123-my-feature
-
-    # Create from different base branch
-    ./worktree-setup.sh -b main my-feature
-
-    # Custom worktree path
-    ./worktree-setup.sh -p /tmp/my-feature my-feature
-
-    # Custom branch prefix
-    ./worktree-setup.sh -f bugfix fix-issue
-EOF
-}
-
-# Parse command line arguments
-while [[ $# -gt 0 ]]; do
-    case $1 in
-        -h|--help)
-            show_help
-            exit 0
-            ;;
-        -b|--base)
-            BASE_BRANCH="$2"
-            shift 2
-            ;;
-        -p|--path)
-            WORKTREE_PATH="$2"
-            shift 2
-            ;;
-        -f|--prefix)
-            FEATURE_PREFIX="$2"
-            shift 2
-            ;;
-        *)
-            if [ -z "$BRANCH_NAME" ]; then
-                BRANCH_NAME="$1"
-            else
-                print_error "Unknown argument: $1"
-                show_help
-                exit 1
-            fi
-            shift
-            ;;
-    esac
-done
-
-# Validate branch name
-if [ -z "$BRANCH_NAME" ]; then
-    print_error "Branch name is required"
-    show_help
-    exit 1
-fi
-
-# Construct full branch name with prefix
-FULL_BRANCH_NAME="${FEATURE_PREFIX}/${BRANCH_NAME}"
-
-# Set default worktree path if not provided
-if [ -z "$WORKTREE_PATH" ]; then
-    WORKTREE_PATH="../${REPO_NAME}-${BRANCH_NAME}"
-fi
-
-print_info "Setting up git worktree..."
-print_info "Repository: $REPO_NAME"
-print_info "Base branch: $BASE_BRANCH"
-print_info "New branch: $FULL_BRANCH_NAME"
-print_info "Worktree path: $WORKTREE_PATH"
-
-# Check if base branch exists
-if ! git rev-parse --verify "$BASE_BRANCH" > /dev/null 2>&1; then
-    print_error "Base branch '$BASE_BRANCH' does not exist"
-    exit 1
-fi
-
-# Fetch latest changes
-print_info "Fetching latest changes..."
-git fetch origin
-
-# Update base branch
-print_info "Updating base branch..."
-git checkout "$BASE_BRANCH"
-git pull origin "$BASE_BRANCH"
-
-# Check if branch already exists
-if git rev-parse --verify "$FULL_BRANCH_NAME" > /dev/null 2>&1; then
-    print_warn "Branch '$FULL_BRANCH_NAME' already exists"
-    read -p "Do you want to create a worktree for the existing branch? (y/n) " -n 1 -r
-    echo
-    if [[ ! $REPLY =~ ^[Yy]$ ]]; then
-        exit 1
-    fi
-    git worktree add "$WORKTREE_PATH" "$FULL_BRANCH_NAME"
-else
-    # Create worktree with new branch
-    print_info "Creating worktree..."
-    git worktree add -b "$FULL_BRANCH_NAME" "$WORKTREE_PATH" "$BASE_BRANCH"
-fi
-
-# Navigate to worktree
-cd "$WORKTREE_PATH"
-
-print_info "Worktree created successfully!"
-
-# Check for package manager
-if [ -f "package.json" ]; then
-    print_info "Installing dependencies..."
-    if command -v npm > /dev/null 2>&1; then
-        npm install
-    else
-        print_warn "npm not found, skipping dependency installation"
-    fi
-fi
-
-# Check for env copy script
-ENV_COPY_SCRIPT="scripts/copy-env-to-worktree.js"
-if [ -f "$REPO_ROOT/$ENV_COPY_SCRIPT" ]; then
-    print_info "Copying environment files..."
-    node "$REPO_ROOT/$ENV_COPY_SCRIPT"
-elif [ -f "$REPO_ROOT/.env" ]; then
-    print_info "Copying .env file..."
-    cp "$REPO_ROOT/.env" ./.env
-fi
-
-# Push branch to remote
-print_info "Pushing branch to remote..."
-git push -u origin "$FULL_BRANCH_NAME"
-
-print_info "Setup complete!"
-print_info ""
-print_info "Next steps:"
-print_info "  cd $WORKTREE_PATH"
-print_info "  # Make your changes"
-print_info "  git add ."
-print_info "  git commit -m \"${FULL_BRANCH_NAME}: Description\""
-print_info "  git push"
-print_info "  # Create PR via GitHub UI or: gh pr create --base $BASE_BRANCH"
-print_info ""
-print_info "When done, remove worktree with:"
-print_info "  cd $REPO_ROOT"
-print_info "  git worktree remove $WORKTREE_PATH"
-
-
-
-
-
-
-
-
-
-

package/foundation/scripts/README.md

@@ -1,230 +0,0 @@
-# Foundation Scripts
-
-This directory contains shared scripts used across repositories that integrate with the foundation framework.
-
-## Available Scripts
-
-### 1Password Environment Sync
-
-**Script:** `op_sync_env_from_1password.py`
-
-Syncs environment variables from 1Password to your local `.env` file.
-
-#### Features
-
-- **Automatic backup**: Creates timestamped backup in `.env.backups/` before modification
-- **Session check**: Verifies 1Password CLI session before proceeding
-- **Security**: NEVER prints secret values, only variable names
-- **MCP Integration**: Uses parquet MCP server for data access (per MCP access policy)
-- **Configurable exclusions**: Instance-specific exclusion lists via `foundation-config.local.yaml`
-- **Repository-agnostic**: Detects repo root and adapts to different repository structures
-- **Environment-based secrets**: Supports different secrets for development vs production
-
-#### Requirements
-
-- 1Password CLI (`op`) installed and signed in (`op signin`)
-- Python 3.9+ recommended
-- pandas and pyarrow for parquet file reading (fallback)
-- mcp package for MCP server integration (primary method)
-
-#### Configuration
-
-##### Environment Variable Mappings
-
-Mappings are stored in `data/env_var_mappings/env_var_mappings.parquet` and accessed via the parquet MCP server.
-
-**Parquet file columns:**
-- `env_var`: Environment variable name (e.g., `OPENAI_API_KEY`)
-- `op_reference`: 1Password `op://` reference (e.g., `op://Private/OpenAI/api_key`)
-- `environment_based`: Boolean flag for environment-specific secrets
-- `environment_key`: Environment name (`development` or `production`) if environment_based is true
-- Other metadata columns (service, notes, etc.)
-
-**To add/update mappings:**
-
-Use the parquet MCP server tools:
-
-```python
-# Example: Add a new mapping
-mcp_parquet_add_record(
-    data_type="env_var_mappings",
-    record={
-        "env_var": "NEW_API_KEY",
-        "op_reference": "op://Private/ServiceName/api_key",
-        "environment_based": False,
-        "optional": False,
-        "service": "ServiceName"
-    }
-)
-```
-
-**To find 1Password references:**
-
-```bash
-op item get "<item-name>" --format=json
-```
-
-##### Exclusion Lists
-
-Exclusion lists define variables that should be removed during sync (e.g., deprecated variables, renamed variables).
-
-**Repo-wide exclusions** (committed):
-Add to `foundation-config.yaml`:
-
-```yaml
-tooling:
-  env_management:
-    onepassword_sync:
-      default_exclusions:
-        - "DEPRECATED_VAR_NAME"
-        - "OLD_API_KEY"
-```
-
-**Instance-specific exclusions** (gitignored):
-Add to `foundation-config.local.yaml`:
-
-```yaml
-tooling:
-  env_management:
-    onepassword_sync:
-      exclusions:
-        - "COINBASE_API_KEY_ADVANCED"  # Deprecated
-        - "FALLBACK_ASSIGNEE_EMAIL"    # Replaced by ASANA_FALLBACK_ASSIGNEE_EMAIL
-```
-
-**Template file:**
-Copy `foundation-config.local.yaml.example` to `foundation-config.local.yaml` and customize.
-
-##### Environment-Based Secrets
-
-For secrets that differ between development and production (e.g., API keys), set `environment_based: true` in the parquet file and specify `environment_key`.
-
-The script uses the `ENVIRONMENT` environment variable (defaults to `development`) to select the correct secret.
-
-**Example:**
-
-```python
-# Development key
-{
-    "env_var": "OPENAI_API_KEY",
-    "op_reference": "op://Private/OpenAI/credential",
-    "environment_based": True,
-    "environment_key": "development"
-}
-
-# Production key
-{
-    "env_var": "OPENAI_API_KEY",
-    "op_reference": "op://Private/OpenAI/api_key",
-    "environment_based": True,
-    "environment_key": "production"
-}
-```
-
-#### Usage
-
-**From repository root:**
-
-```bash
-# Sync to .env in repo root
-python foundation/scripts/op_sync_env_from_1password.py
-
-# Sync to custom path
-python foundation/scripts/op_sync_env_from_1password.py path/to/.env.custom
-```
-
-**Via wrapper script** (if configured in consuming repository):
-
-```bash
-# Repository-specific wrapper
-python scripts/op_sync_env_from_1password.py
-```
-
-#### How It Works
-
-1. **Detects repository root** by looking for `foundation-config.yaml` or `.git` directory
-2. **Loads configuration** from YAML files (local first, then committed)
-3. **Reads mappings** from parquet file via MCP server (falls back to direct read if MCP unavailable)
-4. **Checks 1Password session** to ensure CLI is authenticated
-5. **Creates backup** of existing `.env` file in `.env.backups/`
-6. **Resolves secrets** from 1Password using `op read` command
-7. **Replaces `.env` file** with:
-   - Managed variables (from 1Password)
-   - Unmanaged variables (preserved from original file)
-   - Excludes variables in exclusion lists
-
-#### Security
-
-- **Never prints secret values** - only variable names
-- **Error messages sanitized** - no CLI output that might contain secrets
-- **Backups gitignored** - `.env.backups/` directory is automatically ignored
-- **MCP server integration** - follows MCP access policy for data operations
-- **Local execution only** - never run in CI/CD
-
-#### Troubleshooting
-
-**1Password CLI not authenticated:**
-
-```bash
-# Sign in to 1Password
-eval $(op signin)
-
-# Or if using desktop app integration
-op signin
-```
-
-**MCP server unavailable:**
-
-The script automatically falls back to direct parquet file reading if the MCP server is unavailable. You'll see a warning message.
-
-**Missing mappings file:**
-
-Create the parquet file using the MCP parquet server or migration script. See repository-specific documentation.
-
-**Placeholder values:**
-
-Variables with `PLACEHOLDER_` prefix in the `op_reference` field are skipped until configured. Update the parquet file with actual 1Password references.
-
-#### Integration with Consuming Repositories
-
-To use this script in your repository:
-
-1. **Install foundation** as a submodule or symlink
-2. **Create wrapper script** at `scripts/op_sync_env_from_1password.py`:
-
-```python
-#!/usr/bin/env python3
-"""Wrapper to call foundation 1Password sync script."""
-import sys
-from pathlib import Path
-
-repo_root = Path(__file__).parent.parent
-foundation_script = repo_root / "foundation" / "scripts" / "op_sync_env_from_1password.py"
-
-if not foundation_script.exists():
-    print("ERROR: Foundation script not found. Ensure foundation is installed.")
-    sys.exit(1)
-
-exec(open(foundation_script).read())
-```
-
-3. **Configure exclusions** in `foundation-config.local.yaml` (gitignored)
-4. **Create mappings** in `data/env_var_mappings/env_var_mappings.parquet` via MCP
-
-### Other Scripts
-
-- `install_foundation.sh` / `install-foundation.sh`: Foundation installation scripts
-- `setup_cursor_rules.sh`: Sets up Cursor rules symlinks
-- `sync_foundation.sh`: Syncs foundation updates
-- `validate_setup.sh`: Validates foundation setup
-- `report_error_*.sh`: Error reporting utilities
-
-## Contributing
-
-When adding new scripts to this directory:
-
-1. Make them repository-agnostic (detect repo root, use configuration)
-2. Document usage and configuration in this README
-3. Follow security best practices (never print secrets)
-4. Use MCP server for data access when applicable
-5. Provide clear error messages and troubleshooting guidance

package/foundation/scripts/install-foundation.sh

@@ -1,232 +0,0 @@
-#!/bin/bash
-# Foundation Installation Script
-# Sets up foundation in a consuming repository
-
-set -e
-
-# Colors
-GREEN='\033[0;32m'
-YELLOW='\033[1;33m'
-RED='\033[0;31m'
-NC='\033[0m'
-
-print_info() {
-    echo -e "${GREEN}[INFO]${NC} $1"
-}
-
-print_warn() {
-    echo -e "${YELLOW}[WARN]${NC} $1"
-}
-
-print_error() {
-    echo -e "${RED}[ERROR]${NC} $1"
-}
-
-# Parse arguments
-FOUNDATION_REPO=""
-INSTALL_METHOD="submodule"  # or "symlink", "copy"
-FOUNDATION_PATH="foundation"
-
-show_help() {
-    cat << EOF
-Usage: ./install-foundation.sh [OPTIONS] <foundation-repo>
-
-Installs the foundation into a consuming repository.
-
-OPTIONS:
-    -h, --help              Show this help message
-    -m, --method <method>   Installation method: submodule (default), symlink, copy
-    -p, --path <path>       Foundation path (default: foundation)
-
-EXAMPLES:
-    # Install as git submodule (recommended)
-    ./install-foundation.sh ../foundation
-
-    # Install as git submodule from remote
-    ./install-foundation.sh https://github.com/user/foundation.git
-
-    # Install as symlink (for local development)
-    ./install-foundation.sh -m symlink ../foundation
-
-    # Install as copy (for modification)
-    ./install-foundation.sh -m copy ../foundation
-EOF
-}
-
-# Parse command line arguments
-while [[ $# -gt 0 ]]; do
-    case $1 in
-        -h|--help)
-            show_help
-            exit 0
-            ;;
-        -m|--method)
-            INSTALL_METHOD="$2"
-            shift 2
-            ;;
-        -p|--path)
-            FOUNDATION_PATH="$2"
-            shift 2
-            ;;
-        *)
-            if [ -z "$FOUNDATION_REPO" ]; then
-                FOUNDATION_REPO="$1"
-            else
-                print_error "Unknown argument: $1"
-                show_help
-                exit 1
-            fi
-            shift
-            ;;
-    esac
-done
-
-# Validate arguments
-if [ -z "$FOUNDATION_REPO" ]; then
-    print_error "Foundation repository path/URL is required"
-    show_help
-    exit 1
-fi
-
-# Check if we're in a git repository
-if ! git rev-parse --is-inside-work-tree > /dev/null 2>&1; then
-    print_error "Not in a git repository"
-    exit 1
-fi
-
-print_info "Installing foundation..."
-print_info "Source: $FOUNDATION_REPO"
-print_info "Method: $INSTALL_METHOD"
-print_info "Path: $FOUNDATION_PATH"
-
-# Install based on method
-case $INSTALL_METHOD in
-    submodule)
-        print_info "Adding as git submodule..."
-        git submodule add "$FOUNDATION_REPO" "$FOUNDATION_PATH"
-        git submodule update --init --recursive
-        print_info "✅ Foundation added as submodule"
-        ;;
-    
-    symlink)
-        print_info "Creating symlink..."
-        if [ -e "$FOUNDATION_PATH" ]; then
-            print_error "Path already exists: $FOUNDATION_PATH"
-            exit 1
-        fi
-        ln -s "$FOUNDATION_REPO" "$FOUNDATION_PATH"
-        print_info "✅ Foundation symlinked"
-        ;;
-    
-    copy)
-        print_info "Copying foundation..."
-        if [ -e "$FOUNDATION_PATH" ]; then
-            print_error "Path already exists: $FOUNDATION_PATH"
-            exit 1
-        fi
-        cp -r "$FOUNDATION_REPO" "$FOUNDATION_PATH"
-        print_info "✅ Foundation copied"
-        ;;
-    
-    *)
-        print_error "Unknown installation method: $INSTALL_METHOD"
-        exit 1
-        ;;
-esac
-
-# Generate default config if it doesn't exist
-if [ ! -f "foundation-config.yaml" ]; then
-    print_info "Generating foundation-config.yaml..."
-    if [ -f "$FOUNDATION_PATH/config/foundation-config.yaml" ]; then
-        cp "$FOUNDATION_PATH/config/foundation-config.yaml" ./foundation-config.yaml
-        print_info "✅ Config file created: foundation-config.yaml"
-        print_warn "Please customize foundation-config.yaml for your repository"
-    else
-        print_warn "Foundation config template not found"
-    fi
-fi
-
-# Create .gitignore entries if needed
-if [ -f ".gitignore" ]; then
-    if ! grep -q "^foundation-config.local.yaml$" .gitignore 2>/dev/null; then
-        echo "" >> .gitignore
-        echo "# Foundation local overrides" >> .gitignore
-        echo "foundation-config.local.yaml" >> .gitignore
-        print_info "✅ Added foundation config to .gitignore"
-    fi
-fi
-
-# Setup private docs submodule (optional)
-PRIVATE_DOCS_URL=""
-
-# Check environment variable first
-if [ -n "$PRIVATE_DOCS_REPO_URL" ]; then
-    PRIVATE_DOCS_URL="$PRIVATE_DOCS_REPO_URL"
-    print_info "Found PRIVATE_DOCS_REPO_URL environment variable"
-# Check foundation-config.yaml if it exists
-elif [ -f "foundation-config.yaml" ]; then
-    # Try to extract private_docs.repo_url from config (requires yq or manual parsing)
-    if command -v yq &> /dev/null; then
-        CONFIG_URL=$(yq eval '.private_docs.repo_url' foundation-config.yaml 2>/dev/null)
-        if [ "$CONFIG_URL" != "null" ] && [ -n "$CONFIG_URL" ]; then
-            PRIVATE_DOCS_URL="$CONFIG_URL"
-            print_info "Found private docs URL in foundation-config.yaml"
-        fi
-    fi
-fi
-
-# If URL is set and docs/private doesn't exist, add submodule
-if [ -n "$PRIVATE_DOCS_URL" ] && [ ! -e "docs/private" ]; then
-    print_info ""
-    print_info "Setting up private docs submodule..."
-    
-    # Remove docs/private from .gitignore if present
-    if [ -f ".gitignore" ] && grep -q "^docs/private" .gitignore 2>/dev/null; then
-        print_warn "Removing docs/private from .gitignore to allow submodule..."
-        sed -i.bak '/^docs\/private/d' .gitignore && rm .gitignore.bak
-    fi
-    
-    # Add submodule
-    if git submodule add "$PRIVATE_DOCS_URL" docs/private; then
-        git submodule update --init --recursive
-        print_info "✅ Private docs submodule added"
-        
-        # Create required directories
-        mkdir -p docs/private/competitive
-        mkdir -p docs/private/partnerships
-        print_info "✅ Created competitive/ and partnerships/ directories"
-    else
-        print_warn "Failed to add private docs submodule. You can add it manually later:"
-        print_warn "  git submodule add \$PRIVATE_DOCS_REPO_URL docs/private"
-    fi
-elif [ -n "$PRIVATE_DOCS_URL" ] && [ -e "docs/private" ]; then
-    print_info "Private docs already exists at docs/private"
-else
-    print_info ""
-    print_info "ℹ️  Private docs submodule not configured"
-    print_info "To set up later, either:"
-    print_info "  1. Set PRIVATE_DOCS_REPO_URL environment variable, or"
-    print_info "  2. Add to foundation-config.yaml:"
-    print_info "     private_docs:"
-    print_info "       enabled: true"
-    print_info "       repo_url: \"https://github.com/user/private-docs.git\""
-    print_info "  3. Then run: git submodule add \$PRIVATE_DOCS_REPO_URL docs/private"
-fi
-
-# Setup cursor rules (optional)
-if [ -f "$FOUNDATION_PATH/scripts/setup-cursor-rules.sh" ]; then
-    print_info ""
-    print_info "Setting up cursor rules..."
-    "$FOUNDATION_PATH/scripts/setup-cursor-rules.sh"
-fi
-
-print_info ""
-print_info "✅ Foundation installation complete!"
-print_info ""
-print_info "Next steps:"
-print_info "  1. Customize foundation-config.yaml for your repository"
-print_info "  2. Run ./foundation/scripts/validate-setup.sh to verify installation"
-print_info "  3. See foundation/README.md for usage documentation"
-print_info "  4. See foundation/agent_instructions/README.md for cursor rules documentation"
-
-