agentic-beacon 1.1.0__tar.gz

agentic_beacon-1.1.0/.gitignore

@@ -0,0 +1,34 @@
+# Editor and IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Temporary files
+*.tmp
+*.bak
+.session-handoff.md
+
+# Build outputs
+dist/
+build/
+*.pyc
+__pycache__/
+.venv/
+*.egg-info/
+
+# Logs
+*.log
+logs/
+
+# Environment
+.env
+.env.local
+
+# Distributed warehouse content (project-specific)
+.opencode/

agentic_beacon-1.1.0/.release-trigger

@@ -0,0 +1 @@
+manual-release-trigger: 2026-03-07T13:50:35Z

agentic_beacon-1.1.0/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## [1.1.0](https://github.com/Shadowsong27/agentic-beacon/compare/agentic-beacon@v1.0.0...agentic-beacon@v1.1.0) (2026-03-07)
+
+
+### Features
+
+* add Beacon CLI tool for warehouse distribution ([48c9dae](https://github.com/Shadowsong27/agentic-beacon/commit/48c9daeaa2b967f55ab461c713ab6fdd5b1c0802))
+* add beacon init command to bootstrap warehouses ([3cf5a52](https://github.com/Shadowsong27/agentic-beacon/commit/3cf5a52387b63dcf9fd1ee0fde383d847e3e395e))
+
+
+### Bug Fixes
+
+* force release for agentic-beacon ([7d92917](https://github.com/Shadowsong27/agentic-beacon/commit/7d929170e01c172843e68a8d937e9f78896d2c03))
+
+
+### Code Refactoring
+
+* rename to Agentic Beacon with abc CLI command ([b2e6ab9](https://github.com/Shadowsong27/agentic-beacon/commit/b2e6ab9b331990ce01436278e103d4e8e4c9b3bc))
+
+
+### Miscellaneous Chores
+
+* prepare for public PyPI release ([8fe4a68](https://github.com/Shadowsong27/agentic-beacon/commit/8fe4a68c44df27a9b219a1bba25869f13e76cb1c))
+
+
+### CI/CD
+
+* add GitHub Actions workflows for PyPI publishing ([87e15a4](https://github.com/Shadowsong27/agentic-beacon/commit/87e15a4f5821b8e5d02ae8e7c2824346f523fb25))

agentic_beacon-1.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Beacon Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentic_beacon-1.1.0/PKG-INFO

@@ -0,0 +1,385 @@
+Metadata-Version: 2.4
+Name: agentic-beacon
+Version: 1.1.0
+Summary: Agentic Beacon CLI - Distribute knowledge contexts and skills for AI-assisted development teams
+Project-URL: Homepage, https://github.com/Shadowsong27/agentic-beacon
+Project-URL: Documentation, https://github.com/Shadowsong27/agentic-beacon/tree/main/libs/beacon
+Project-URL: Repository, https://github.com/Shadowsong27/agentic-beacon
+Project-URL: Issues, https://github.com/Shadowsong27/agentic-beacon/issues
+Author: Agentic Beacon Contributors
+License: MIT
+License-File: LICENSE
+Keywords: agentic,agents,ai,beacon,context,developer-tools,knowledge-management
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.12
+Requires-Dist: click>=8.1.0
+Requires-Dist: loguru>=0.7.0
+Requires-Dist: pyyaml>=6.0.0
+Requires-Dist: rich>=13.0.0
+Provides-Extra: dev
+Requires-Dist: build>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: twine>=4.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Agentic Warehouse CLI
+
+CLI tool for distributing agentic engineering contexts, knowledge, and skills from a warehouse repository to project `.opencode` directories.
+
+## Overview
+
+This tool enables the **DRY (Don't Repeat Yourself)** principle for agentic knowledge management:
+
+- **Centralized warehouse**: Store all contexts, knowledge, and skills in one place
+- **Fork workflow**: Fork the warehouse template to create your organization's warehouse
+- **Local distribution**: Use the CLI to distribute content to gitignored `.opencode` folders in projects
+- **Easy updates**: Sync latest changes from the warehouse with one command
+
+## Installation
+
+### From Warehouse Repository
+
+When using your organization's warehouse:
+
+```bash
+# Clone your organization's warehouse
+git clone https://github.com/your-org/agentic-warehouse.git
+cd agentic-warehouse
+
+# Install the CLI tool
+pip install -e libs/agentic_warehouse_cli
+
+# Verify installation
+agentic --help
+```
+
+### As a Standalone Package
+
+```bash
+pip install agentic-warehouse-cli
+```
+
+## Usage
+
+### 1. List Available Content
+
+```bash
+# List all available contexts, knowledge, and skills
+agentic list
+
+# From a specific warehouse location
+agentic list --warehouse /path/to/warehouse
+```
+
+### 2. Setup (First Time)
+
+```bash
+# Interactive mode (recommended for first time)
+agentic setup --interactive
+
+# Install specific content
+agentic setup \
+  --context global \
+  --context python \
+  --knowledge global \
+  --knowledge languages/python \
+  --skill example-skill
+
+# Install everything
+agentic setup --all
+
+# Specify warehouse and project locations
+agentic setup --all \
+  --warehouse /path/to/warehouse \
+  --project /path/to/project
+```
+
+**What it does:**
+- Creates `.opencode/` directory in your project (gitignored)
+- Copies selected contexts to `.opencode/contexts/`
+- Copies selected knowledge to `.opencode/knowledge/`
+- Copies selected skills to `.opencode/skills/`
+- Saves configuration for future updates
+
+### 3. Update Existing Installation
+
+```bash
+# Update all installed content from warehouse
+agentic update
+
+# From a specific warehouse location
+agentic update --warehouse /path/to/warehouse
+```
+
+**What it does:**
+- Reads existing `.opencode/.warehouse-config.yml`
+- Re-copies all previously selected content
+- Overwrites with latest versions from warehouse
+
+### 4. Check Installation Status
+
+```bash
+# Show what's currently installed
+agentic status
+
+# For a specific project
+agentic status --project /path/to/project
+```
+
+### 5. Clean Installation
+
+```bash
+# Remove .opencode directory
+agentic clean
+
+# Will prompt for confirmation
+```
+
+## Workflow
+
+### For Organization Admins
+
+1. **Create warehouse**: Fork the template repository
+   ```bash
+   # Use GitHub's "Use this template" button
+   # Name it: your-org-agentic-warehouse
+   ```
+
+2. **Customize content**: Add your organization's contexts, knowledge, and skills
+   ```
+   your-org-agentic-warehouse/
+   ├── contexts/
+   │   ├── AGENTS.global.md
+   │   ├── AGENTS.python.md
+   │   └── AGENTS.your-domain.md
+   ├── knowledge/
+   │   ├── global/
+   │   ├── languages/python/
+   │   └── domains/your-domain/
+   └── skills/
+       └── your-skill/
+   ```
+
+3. **Distribute to teams**: Team members clone and install
+
+### For Team Members
+
+1. **Clone warehouse** (one time):
+   ```bash
+   git clone https://github.com/your-org/agentic-warehouse.git ~/agentic-warehouse
+   cd ~/agentic-warehouse
+   pip install -e libs/agentic_warehouse_cli
+   ```
+
+2. **Setup in project** (per project):
+   ```bash
+   cd ~/your-project
+   agentic setup --warehouse ~/agentic-warehouse --interactive
+   ```
+
+3. **Update when needed**:
+   ```bash
+   cd ~/your-project
+   agentic update --warehouse ~/agentic-warehouse
+   ```
+
+4. **Add to .gitignore**:
+   ```
+   # Add to your project's .gitignore
+   .opencode/
+   ```
+
+## Directory Structure
+
+### Warehouse Structure
+```
+your-org-agentic-warehouse/
+├── contexts/
+│   ├── AGENTS.global.md
+│   ├── AGENTS.python.md
+│   └── AGENTS.data-platform.md
+├── knowledge/
+│   ├── global/
+│   │   ├── decisions/
+│   │   ├── lessons/
+│   │   └── facts/
+│   ├── languages/
+│   │   └── python/
+│   └── domains/
+│       └── data-platform/
+├── skills/
+│   └── example-skill/
+│       └── SKILL.md
+└── libs/
+    └── agentic_warehouse_cli/  # This CLI tool
+```
+
+### Project Structure (After Setup)
+```
+your-project/
+├── .opencode/                    # gitignored
+│   ├── .warehouse-config.yml    # Tracks what's installed
+│   ├── contexts/
+│   │   ├── AGENTS.global.md
+│   │   └── AGENTS.python.md
+│   ├── knowledge/
+│   │   ├── global/
+│   │   └── languages/
+│   │       └── python/
+│   └── skills/
+│       └── example-skill/
+├── .gitignore                    # Contains .opencode/
+└── ...
+```
+
+## Configuration
+
+The CLI auto-saves configuration to `.opencode/.warehouse-config.yml`:
+
+```yaml
+contexts:
+  - global
+  - python
+knowledge_scopes:
+  - global
+  - languages/python
+skills:
+  - example-skill
+```
+
+This configuration is used by the `update` command to know what to refresh.
+
+## Auto-Detection
+
+The CLI automatically detects:
+
+- **Warehouse root**: Looks for directories containing `contexts/`, `knowledge/`, and `skills/`
+- **Project root**: Looks for `.git` directory or uses current directory
+
+You can override with `--warehouse` and `--project` options.
+
+## Examples
+
+### Example 1: Setup Python Project
+
+```bash
+cd ~/my-python-project
+
+# Interactive setup
+agentic setup --interactive
+
+# Select:
+#   Contexts: global, python
+#   Knowledge: global, languages/python
+#   Skills: none
+
+# Result: .opencode/ created with selected content
+```
+
+### Example 2: Setup Data Platform Project
+
+```bash
+cd ~/data-platform-project
+
+# Non-interactive setup
+agentic setup \
+  --context global \
+  --context python \
+  --context data-platform \
+  --knowledge global \
+  --knowledge languages/python \
+  --knowledge domains/data-platform \
+  --skill deploy-airflow
+
+# Result: Full data platform context installed
+```
+
+### Example 3: Update After Warehouse Changes
+
+```bash
+cd ~/my-project
+
+# Warehouse maintainers updated content
+# Pull latest warehouse changes
+cd ~/agentic-warehouse
+git pull origin main
+
+# Update project installation
+cd ~/my-project
+agentic update
+
+# Result: Latest content synced to .opencode/
+```
+
+### Example 4: Check What's Installed
+
+```bash
+cd ~/my-project
+agentic status
+
+# Output:
+# Installation: /Users/you/my-project/.opencode
+# 
+# Installed Contexts
+# ┌─────────┐
+# │ Context │
+# ├─────────┤
+# │ global  │
+# │ python  │
+# └─────────┘
+```
+
+## Development
+
+### Running Tests
+
+```bash
+cd libs/agentic_warehouse_cli
+pytest
+```
+
+### Building Package
+
+```bash
+pip install build
+python -m build
+```
+
+## Troubleshooting
+
+### CLI not found after installation
+
+```bash
+# Make sure you're in the right environment
+which agentic
+
+# Reinstall
+pip install -e libs/agentic_warehouse_cli --force-reinstall
+```
+
+### Warehouse not auto-detected
+
+```bash
+# Explicitly specify warehouse path
+agentic setup --warehouse /path/to/warehouse
+```
+
+### .opencode not in .gitignore
+
+```bash
+# Add to .gitignore
+echo ".opencode/" >> .gitignore
+```
+
+## License
+
+MIT

agentic_beacon-1.1.0/PRIVATE_DEPLOYMENT.md

@@ -0,0 +1,199 @@
+# Private Deployment Guide (Optional)
+
+**Note:** Agentic Beacon is publicly available on PyPI. This guide is for organizations that want to host it on their own private PyPI server.
+
+## When to Use Private Deployment
+
+- Your organization has security requirements for dependency management
+- You want to control package versions internally
+- You need to host in air-gapped environments
+- You want to add organization-specific customizations
+
+## Prerequisites
+
+1. **Private PyPI server** - Running (devpi, PyPI server, Artifactory, etc.)
+2. **uv or twine** - For publishing packages
+3. **Python 3.12+** - Required for building and using agentic-beacon
+
+## Build the Package
+
+```bash
+cd libs/beacon
+
+# Build with uv
+uv build
+
+# This creates:
+# - dist/agentic-beacon-0.2.0-py3-none-any.whl
+# - dist/agentic-beacon-0.2.0.tar.gz
+```
+
+## Publish to Private PyPI
+
+### Option 1: Using uv publish (Recommended)
+
+```bash
+cd libs/beacon
+
+# Publish to your private PyPI
+uv publish \
+  --publish-url https://your-private-pypi.local/simple/ \
+  --username your-username \
+  --password your-password
+
+# Or with token authentication:
+uv publish \
+  --publish-url https://your-private-pypi.local/simple/ \
+  --token your-api-token
+```
+
+### Option 2: Using Environment Variables
+
+Create a `.pypirc` file or set environment variables:
+
+```bash
+# In ~/.pypirc
+[distutils]
+index-servers =
+    homelab
+
+[homelab]
+repository = https://your-private-pypi.local/simple/
+username = your-username
+password = your-password
+```
+
+Then publish:
+
+```bash
+cd libs/beacon
+uv publish --index homelab
+```
+
+### Option 3: Using twine (Alternative)
+
+```bash
+cd libs/beacon
+
+# Install twine in dev environment
+uv pip install twine
+
+# Upload to private PyPI
+twine upload --repository-url https://your-private-pypi.local/simple/ dist/*
+```
+
+## Install from Homelab PyPI
+
+Once published, users can install beacon from your private PyPI:
+
+```bash
+# Install from private PyPI
+pip install beacon --index-url https://your-private-pypi.local/simple/
+
+# Or with uv:
+uv pip install beacon --index-url https://your-private-pypi.local/simple/
+
+# Or add to requirements:
+echo "beacon" >> requirements.txt
+pip install -r requirements.txt --index-url https://your-private-pypi.local/simple/
+```
+
+## Verify Installation
+
+```bash
+# Check version
+beacon --help
+
+# Should show:
+# Beacon - Guide your agents with distributed knowledge.
+#
+# Commands:
+#   clean   Remove .opencode directory from project.
+#   delta   Compare target installation with warehouse...
+#   list    List available warehouse content.
+#   setup   Setup warehouse content in project...
+#   status  Show current warehouse installation status.
+#   update  Update existing .opencode content...
+```
+
+## Upgrade Package
+
+When you release a new version:
+
+1. Update version in `pyproject.toml`
+2. Rebuild: `uv build`
+3. Republish: `uv publish --publish-url ...`
+
+Users upgrade with:
+
+```bash
+pip install --upgrade beacon --index-url https://your-private-pypi.local/simple/
+```
+
+## Troubleshooting
+
+### Build fails with Python version error
+
+Make sure you're using Python 3.12+:
+
+```bash
+python --version  # Should be 3.12 or higher
+uv python install 3.12  # Install Python 3.12 with uv
+uv build --python 3.12  # Build with specific Python version
+```
+
+### Publish authentication fails
+
+Check your credentials:
+
+```bash
+# Test connection
+curl -u username:password https://your-private-pypi.local/simple/
+
+# Or use token
+curl -H "Authorization: Bearer your-token" https://your-private-pypi.local/simple/
+```
+
+### SSL certificate issues
+
+If using self-signed certificates:
+
+```bash
+# Option 1: Add --no-verify-ssl (not recommended for production)
+uv publish --publish-url ... --no-verify-ssl
+
+# Option 2: Add cert to trusted store
+pip install --cert /path/to/ca-bundle.crt beacon --index-url ...
+```
+
+## Next Steps
+
+After testing in homelab:
+
+1. Gather feedback from homelab users
+2. Fix any issues
+3. Increment version (e.g., 0.1.1, 0.2.0)
+4. Rebuild and republish
+5. When ready for public release:
+   - `uv publish` (publishes to PyPI.org by default)
+   - Or `twine upload dist/*` for PyPI
+
+## Configuration Summary
+
+**Package Name:** `beacon`  
+**Version:** `0.1.0`  
+**Python Required:** `>=3.12`  
+**License:** MIT  
+**Repository:** https://github.com/Shadowsong27/agentic-engineering-warehouse-template
+
+**Installation:**
+```bash
+pip install beacon --index-url https://your-private-pypi.local/simple/
+```
+
+**Usage:**
+```bash
+beacon setup --all
+beacon status
+beacon delta
+```