apm-cli 0.1.0__tar.gz

apm_cli-0.1.0/AUTHORS

@@ -0,0 +1,13 @@
+# Authors
+
+## Project Maintainers
+
+* Daniel Meppiel (@danielmeppiel) - Creator and Lead Maintainer
+
+## Contributors
+
+Thank you to all our contributors! 
+
+[This space will be updated as contributors join the project]
+
+Want to contribute? Check out our [Contributing Guidelines](CONTRIBUTING.md).

apm_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Daniel Meppiel
+
+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.

apm_cli-0.1.0/PKG-INFO

@@ -0,0 +1,407 @@
+Metadata-Version: 2.4
+Name: apm-cli
+Version: 0.1.0
+Summary: MCP configuration tool
+Author-email: Daniel Meppiel <user@example.com>
+License: MIT License
+        
+        Copyright (c) 2025 Daniel Meppiel
+        
+        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.
+        
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: AUTHORS
+Requires-Dist: click>=8.0.0
+Requires-Dist: colorama>=0.4.6
+Requires-Dist: pyyaml>=6.0.0
+Requires-Dist: requests>=2.28.0
+Requires-Dist: python-frontmatter>=1.0.0
+Requires-Dist: llm>=0.17.0
+Requires-Dist: llm-github-models>=0.1.0
+Requires-Dist: tomli>=1.2.0; python_version < "3.11"
+Requires-Dist: rich>=13.0.0
+Requires-Dist: rich-click>=1.7.0
+Requires-Dist: watchdog>=3.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: isort>=5.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Provides-Extra: build
+Requires-Dist: pyinstaller>=6.0.0; extra == "build"
+Dynamic: license-file
+
+# Agent Primitives Manager (APM)
+
+**Make any project compatible with AI-Native Development** - Stop the trial-and-error cycle of inconsistent AI results. APM implements the proven [AI-Native Development framework](https://danielmeppiel.github.io/awesome-ai-native/) that delivers reliable, repeatable workflows with any coding agent.
+
+**Works with Any Coding Agent** - From GitHub Copilot to Cursor, Codex to Aider. APM creates portable Agent Primitives that ensure consistent AI behavior across all tools through the emerging [agents.md standard](https://agents.md).
+
+**Think npm + Node.js, but for AI-Native Development.**
+
+| Traditional Web Dev | AI-Native Development | Role |
+|---------------------|----------------------|------|
+| **npm** | **APM Package Manager** | Dependency resolution, distribution |
+| **TypeScript Compiler** | **APM Primitives Compiler** | Transform Agent Primitives → agents.md format |
+| **Node.js** | **Coding Agent Runtimes** | Execute compiled AI workflows |
+| **JavaScript** | **Natural Language** | What runtimes actually understand |
+
+## Quick Start (2 minutes)
+
+> [!NOTE] 
+> **📋 Prerequisites**: Get a GitHub fine-grained Personal Access Token with **read-only Models permissions** at [github.com/settings/personal-access-tokens/new](https://github.com/settings/personal-access-tokens/new)
+
+```bash
+# 1. Install APM CLI (zero dependencies)
+curl -sSL https://raw.githubusercontent.com/danielmeppiel/apm-cli/main/install.sh | sh
+
+# 2. Set up your GitHub PAT and an Agent CLI
+export GITHUB_TOKEN=your_token_here
+apm runtime setup codex # Installs OpenAI Codex CLI
+
+# 3. Transform your project with AI-Native structure
+apm init my-ai-native-project
+
+# 4. Compile Agent Primitives for any coding agent
+cd my-ai-native-project
+apm compile  # Generates agents.md compatible with multiple Agent CLIs
+
+# 5. Install MCP dependencies and execute agentic workflows (*.prompt.md files)
+apm install
+apm run start --param name="Developer"
+```
+
+**That's it!** Your project now has reliable AI-Native Development workflows that work with any coding agent.
+
+## What You Just Built
+
+You just created an AI-native project with:
+
+- **Agent Primitives** - Configurable tools that deploy proven prompt + context engineering techniques
+- **Universal Compatibility** - Works with GitHub Copilot, Cursor, Codex, Aider, and any agent supporting agents.md
+- **Reliable Workflows** - Replace one-off prompting with reusable, structured AI workflows
+- **Team Knowledge** - Capture and share AI patterns across your entire development team
+
+## Why This Matters
+
+Most developers experience AI as inconsistent and unreliable:
+- ❌ **Ad-hoc prompting** that produces different results each time
+- ❌ **Context overload** that confuses AI agents and wastes tokens  
+- ❌ **Vendor lock-in** to specific AI tools and platforms
+- ❌ **No knowledge persistence** across sessions and team members
+
+**APM solves this** by implementing the complete [3-layer AI-Native Development framework](https://danielmeppiel.github.io/awesome-ai-native/docs/concepts/):
+
+**🔧 Layer 1: Markdown Prompt Engineering** - Structured, repeatable AI instructions  
+**⚙️ Layer 2: Agent Primitives** - Configurable tools that deploy prompt + context engineering  
+**🎯 Layer 3: Context Engineering** - Strategic LLM memory management for reliability
+
+**Result**: Transform from supervising every AI interaction to architecting systems that delegate complete workflows to AI agents.
+
+## AI-Native Development Maturity Journey
+
+**From Manual Supervision → Engineered Architecture**
+
+Most developers start by manually supervising every AI interaction. APM enables the transformation to AI-Native engineering:
+
+### 🔴 Before APM: Manual Agent Supervision
+- Write one-off prompts for each task  
+- Manually guide every AI conversation
+- Start from scratch each time
+- *You're the bottleneck - every AI task needs your attention*
+
+### 🟢 With APM: Engineered Agent Delegation  
+- Build reusable Agent Primitives once
+- Engineer context strategically 
+- Delegate complete workflows to AI
+- *You're the architect - AI handles execution autonomously*
+
+> **Learn the Complete Framework**: Explore the [AI-Native Development Guide](https://danielmeppiel.github.io/awesome-ai-native/) for approaches to Markdown Prompt Engineering, Agent Primitives, and Context Engineering.
+
+## How Agent Primitives Work
+
+APM implements Agent Primitives - the configurable tools that deploy prompt engineering and context engineering techniques:
+
+**🏗️ Initialize a project with AI-Native structure:**
+
+```bash
+apm init my-project  # Creates complete Agent Primitives scaffolding + apm.yml
+```
+
+**⚙️ Generated Project Structure:**
+
+```yaml
+my-project/
+├── apm.yml              # Project configuration and script definitions
+└── .apm/
+    ├── chatmodes/       # Role-based AI expertise with tool boundaries
+    │   ├── backend-dev.chatmode.md     # API development specialist
+    │   └── frontend-dev.chatmode.md    # UI development specialist
+    ├── instructions/    # Targeted guidance by file type and domain  
+    │   ├── security.instructions.md    # applyTo: "auth/**"
+    │   └── testing.instructions.md     # applyTo: "**/*test*"
+    ├── prompts/         # Reusable agentic workflows
+    │   ├── code-review.prompt.md       # Systematic review process
+    │   └── feature-spec.prompt.md      # Spec-first development
+    ├── context/         # Optimized information retrieval
+    │   └── architecture.context.md     # Project patterns and decisions
+    └── specs/           # Implementation-ready blueprints
+        └── api-endpoint.spec.md         # Deterministic outcomes
+```
+
+**🔄 Compile for Universal Agent CLI Compatibility:**
+
+```bash
+apm compile  # Transforms .apm/ primitives → agents.md standard
+```
+
+This generates an `AGENTS.md` file compatible with all major coding agents.
+
+## Example: Structured AI Workflows
+
+**Traditional Prompt** (inconsistent, manual):
+```
+"Add authentication to the API"
+```
+
+**Agent Primitives Workflow** (reliable, reusable):
+
+```markdown
+---
+description: Implement secure authentication system
+mode: backend-dev
+mcp:
+  - ghcr.io/github/github-mcp-server
+input: [auth_method, session_duration]
+---
+
+# Secure Authentication Implementation
+
+## Context Loading
+Review [security standards](../context/security-standards.md) and [existing auth patterns](../context/auth-patterns.md).
+
+## Implementation Requirements
+- Use ${input:auth_method} authentication 
+- Session duration: ${input:session_duration}
+- Follow [security checklist](../specs/auth-security.spec.md)
+
+## Validation Gates
+🚨 **STOP**: Confirm security review before implementation
+```
+
+**Execute with any coding agent:**
+```bash
+apm run implement-auth --param auth_method=jwt --param session_duration=24h
+```
+
+## Supported AI Runtimes
+
+APM manages AI runtime installation and provides MCP tool integration:
+
+- **⚡ OpenAI Codex CLI** (recommended) - Advanced code understanding with GitHub Models integration
+- **🔧 LLM Library** - 100+ models from OpenAI, Anthropic, GitHub, local Ollama
+
+```bash
+# APM manages runtime installation
+apm runtime setup codex        # Install Codex with GitHub Models  
+apm runtime setup llm          # Install LLM library
+apm runtime list               # Show installed runtimes
+```
+
+## Packaging & Distribution
+
+**Manage like npm packages:**
+
+```yaml
+# apm.yml - Project configuration
+name: my-ai-native-app
+version: 1.0.0
+scripts:
+  start: "RUST_LOG=debug codex implement-feature.prompt.md"
+  review: "codex code-review.prompt.md" 
+  docs: "llm generate-docs.prompt.md -m github/gpt-4o-mini"
+dependencies:
+  mcp:
+    - ghcr.io/github/github-mcp-server
+```
+
+**Share and reuse across projects:**
+```bash
+apm install                    # Install MCP dependencies
+apm run start --param feature="user-auth"
+apm run review --param files="src/auth/"
+```
+
+## Why APM? The Missing Infrastructure for AI-Native Development
+
+**The Problem**: Developers have powerful AI coding assistants but lack systematic approaches to make them reliable and scalable. Every team reinvents their AI workflows, can't share effective patterns, and struggles with inconsistent results.
+
+**The Solution**: APM provides the missing infrastructure layer that makes AI-Native Development portable and reliable.
+
+### Key Benefits
+
+**🎯 Reliable Results** - Replace trial-and-error with proven AI-Native Development patterns  
+**🔄 Universal Portability** - Works with any coding agent through the agents.md standard  
+**📦 Knowledge Packaging** - Share AI workflows like code packages with versioning  
+**🧠 Compound Intelligence** - Primitives improve through iterative team refinement  
+**⚡ Team Scaling** - Transform any project for reliable AI-Native Development workflows
+
+### The Infrastructure Analogy
+
+Just as npm revolutionized JavaScript by creating package ecosystem infrastructure, APM creates the missing infrastructure for AI-Native Development:
+
+- **Package Management**: Share and version AI workflows like code dependencies
+- **Compilation**: Transform Agent Primitives into runtime-compatible formats  
+- **Runtime Management**: Install and configure AI tools automatically
+- **Standards Compliance**: Generate agents.md files for universal compatibility
+
+## The Complete AI-Native Framework
+
+APM implements the complete [AI-Native Development framework](https://danielmeppiel.github.io/awesome-ai-native/docs/concepts/) through engineering practices:
+
+```mermaid
+graph TD
+    A["📝 Agent Primitives<br/>.apm/ directory<br/>(.chatmode, .instructions, .prompt, .context, .spec)"] --> B["🔧 APM CLI"]
+    
+    B --> D["📦 APM Package Manager<br/>Dependencies<br/>Templates"]
+    B --> C["⚙️ APM Primitives Compiler<br/>Script Resolution<br/>Primitive Compilation"]
+    B --> E["🏗️ APM Runtime Manager<br/>Install & Configure<br/>Codex, LLM, etc."]
+    
+    C --> F["📄 AGENTS.md<br/>Portable Standard<br/>Cross-Runtime Compatible"]
+    
+    F --> G["⚡ AI Coding Agents<br/>GitHub Copilot, Cursor<br/>Codex, Aider, etc."]
+    
+    E --> H["🛠️ MCP Servers<br/>Tool Integration"]
+    E --> I["🧠 LLM Models<br/>GitHub Models<br/>Ollama, etc."]
+    
+    style A fill:#e3f2fd,stroke:#1976d2,stroke-width:2px,color:#000
+    style B fill:#f3e5f5,stroke:#7b1fa2,stroke-width:3px,color:#000
+    style C fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#000
+    style D fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#000
+    style E fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#000
+    style F fill:#fff3e0,stroke:#ff9800,stroke-width:2px,color:#000
+    style G fill:#fce4ec,stroke:#c2185b,stroke-width:2px,color:#000
+    style H fill:#e8f5e8,stroke:#388e3c,stroke-width:1px,color:#000
+    style I fill:#fff3e0,stroke:#ff9800,stroke-width:1px,color:#000
+```
+
+**Key Architecture**: APM CLI provides three core components: Package Manager (dependencies), Primitives Compiler (transforms .apm/ → agents.md), and Runtime Manager (install/configure AI tools). The compiled agents.md ensures your Agent Primitives work with any coding agent.
+
+**Learn the Complete Framework**: [AI-Native Development Guide →](https://danielmeppiel.github.io/awesome-ai-native/) 
+
+## Installation
+
+### Quick Install (Recommended)
+```bash
+curl -sSL https://raw.githubusercontent.com/danielmeppiel/apm-cli/main/install.sh | sh
+```
+
+### Python Package
+```bash
+pip install apm-cli
+```
+
+### Manual Download
+Download the binary for your platform from [GitHub Releases](https://github.com/danielmeppiel/apm-cli/releases/latest):
+
+```bash
+# Linux x86_64
+curl -L https://github.com/danielmeppiel/apm-cli/releases/latest/download/apm-linux-x86_64.tar.gz | tar -xz && sudo mv apm-linux-x86_64/apm /usr/local/bin/
+
+# macOS Intel
+curl -L https://github.com/danielmeppiel/apm-cli/releases/latest/download/apm-darwin-x86_64.tar.gz | tar -xz && sudo mv apm-darwin-x86_64/apm /usr/local/bin/
+
+# macOS Apple Silicon  
+curl -L https://github.com/danielmeppiel/apm-cli/releases/latest/download/apm-darwin-arm64.tar.gz | tar -xz && sudo mv apm-darwin-arm64/apm /usr/local/bin/
+```
+
+### From Source (Developers)
+```bash
+git clone https://github.com/danielmeppiel/apm-cli.git
+cd apm-cli && uv pip install -e .
+```
+
+## CLI Reference
+
+**Complete Documentation**: See [CLI Reference](docs/cli-reference.md) for detailed command documentation.
+
+```bash
+# Project initialization and setup
+apm init my-project                               # Initialize AI-native project structure
+apm runtime setup codex                           # Install Codex with GitHub Models
+apm install                                       # Install MCP dependencies
+
+# Agent Primitives compilation (run before AI workflows)
+apm compile                                       # Generate agents.md from .apm/ primitives  
+apm compile --watch                              # Auto-regenerate on changes
+apm compile --output custom.md                   # Custom output file
+
+# Workflow execution  
+apm run start --param key=value                   # Execute workflows with parameters
+apm run review --param files="src/**"            # Run code review workflow
+apm preview start --param key=value              # Preview compiled workflow
+
+# Runtime and debugging
+apm runtime list                                 # Show installed AI runtimes
+apm list                                         # Show available project scripts
+RUST_LOG=debug apm run start                     # Enable debug logging
+```
+
+## Beyond Simple Prompts: Advanced Workflows
+
+> [!TIP]
+> **Workflow Composition**: While complex prompt chaining is planned for future releases, current Agent Primitives already enable reliable AI workflows through structured context engineering and modular primitives.
+
+**Example: Multi-step Feature Development**
+```bash
+# 1. Generate specification from requirements
+apm run create-spec --param feature="user-auth"
+
+# 2. Review and validate specification  
+apm run review-spec --param spec="specs/user-auth.spec.md"
+
+# 3. Implement feature following specification
+apm run implement --param spec="specs/user-auth.spec.md"
+
+# 4. Generate tests and documentation
+apm run test-feature --param feature="user-authentication"
+```
+
+Each step leverages your project's Agent Primitives for consistent, reliable results.
+
+## Community & Resources
+
+- 📚 **[AI-Native Development Guide](https://danielmeppiel.github.io/awesome-ai-native/)** - Complete framework documentation
+- 📖 **[Documentation](docs/index.md)** - APM CLI guides and examples
+- 🤝 **[Contributing](CONTRIBUTING.md)** - Help build the AI-native ecosystem  
+- ⭐ **Star this repo** if APM helps transform your AI development workflow!
+
+---
+
+**APM transforms any project into reliable AI-Native Development.**