collavre_github 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 50424fdf0088dc86fb97487d9f97f57fdeefecd21cfdb0e3986a00cb60907afa
-  data.tar.gz: ac0121978c125fa9afad5a1fda087d7e5c2a34a3c50ca7e4f6b1ce5cd5fdcc74
+  metadata.gz: 9ce895f4545efb354576c1a9636f85a7e3146ce3eb25a49d2a7e0f8af44ebd15
+  data.tar.gz: cdc47306b0603e03c024ed34aaff62ef5015a74846977e9f2880137adf254527
 SHA512:
-  metadata.gz: a3fdc3d50981d0822a4ab672f6e2eaffce62ab1f44529c4412494c22e9dd7fec5414b27411b786367db34477f126d128d766ca74b3849657bad6d3ba405bcee9
-  data.tar.gz: f9e54531d9d676e41fa77f95ce6869ff42731c46e8426272d0d0bf1056aef0ad9da246de37d7e1aae5b0cc1ecbb6017833f22642d3eeac504b8ffab512965510
+  metadata.gz: 0633fc7163c737da1f884a3844139d644f04728c8e851dff5421d2ab0712df8b5225cd97ac61c9af0a36289470d7ee7dda192a19c00884478ce6178a47bacc0b
+  data.tar.gz: 66d8add3b1092206f2af6e02005f22e41348b24dda7f32c0133a1f21cd6e050a01f6974c7e4215551dd98ad84a6cac937b4888658b413967ac749eded6337c1d

data/README.md

@@ -2,126 +2,52 @@
 
 GitHub integration engine for Collavre.
 
+## Documentation
+
+**→ [Full Setup Guide](docs/SETUP.md)** — OAuth, webhooks, AI agent, on-premises deployment
+
 ## Features
 
-- OAuth authentication with GitHub
+- OAuth authentication with GitHub (including GitHub Enterprise)
 - Repository linking to Creatives
 - Webhook → System Comment automatic creation
 - **MCP Tools** for AI Agents to analyze PRs
-- **Seed AI Agent**: GitHub PR Analyzer
+- **Seed AI Agent**: GitHub PR Analyzer (minimal context: `chat_history: 1`)
 
 ## Architecture
 
 ```
-GitHub Webhook (push, pull_request, etc.)
+GitHub Webhook (pull_request event)
      │
      ▼
 System Comment created in linked Creative
      │
      ▼
-comment_created event dispatched
-     │
-     ▼
 AI Agent (GitHub PR Analyzer) triggered
      │
-     ├── github_pr_details - Get PR info
-     ├── github_pr_diff - Get code changes
-     ├── github_pr_commits - Get commit messages
-     └── creative_retrieval_service - Get task tree
+     ├── github_pr_details
+     ├── github_pr_diff
+     ├── github_pr_commits
+     └── creative_retrieval_service
      │
      ▼
-Action Comment response (JSON format)
-     │
-     ▼
-User approval → Creative updates
+Action Comment → User approval → Creative updates
 ```
 
-## MCP Tools
-
-Tools for AI Agents to interact with GitHub:
-
-| Tool | Description |
-|------|-------------|
-| `github_pr_details` | Get PR title, body, author, files, additions/deletions |
-| `github_pr_diff` | Get PR diff with truncation support (default: 10K chars) |
-| `github_pr_commits` | Get list of commit messages in the PR |
-
-### Tool Parameters
+## Quick Start
 
-All tools require:
-- `creative_id` - The Creative with GitHub integration
-- `repo` - Repository full name (e.g., `owner/repo`)
-- `pr_number` - Pull request number
-
-The tools automatically find the GitHub account through:
-```
-Creative → RepositoryLink → GithubAccount → GitHub API
-```
-
-## Seed AI Agent
-
-Running `rails db:seed` creates the **GitHub PR Analyzer** agent:
-
-- **Name**: GitHub PR Analyzer
-- **Email**: `github-pr-analyzer@collavre.local`
-- **Trigger**: GitHub PR merged events (system comments)
-- **Tools**: github_pr_details, github_pr_diff, github_pr_commits, creative_retrieval_service, creative_update_service
-- **Output**: Action comments for updating Creative progress
-
-### Routing Expression
-
-```liquid
-event_name == "comment_created" and chat.comment.user_id == nil and chat.comment.content contains "GitHub: Pull Request merged"
-```
+1. Register a GitHub OAuth App ([details](docs/SETUP.md#1-register-a-github-oauth-application))
+2. Set `GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET`
+3. Run `rails db:seed` to create the PR Analyzer agent
+4. Link a repository to a Creative via the integration modal
 
 ## Installation
 
-Add to your Gemfile:
-
 ```ruby
+# Gemfile
 gem "collavre_github", path: "engines/collavre_github"
 ```
 
-## Configuration
-
-### OAuth Setup
-
-1. Create a GitHub OAuth App at https://github.com/settings/developers
-2. Set callback URL to: `https://your-domain.com/auth/github/callback`
-3. Add credentials:
-
-```bash
-bin/rails credentials:edit
-```
-
-```yaml
-github:
-  client_id: your_client_id
-  client_secret: your_client_secret
-  webhook_secret: optional_fallback_secret
-```
-
-### OmniAuth Configuration
-
-In `config/initializers/omniauth.rb`:
-
-```ruby
-Rails.application.config.middleware.use OmniAuth::Builder do
-  provider :github,
-           Rails.application.credentials.dig(:github, :client_id),
-           Rails.application.credentials.dig(:github, :client_secret),
-           scope: "repo,read:org"
-end
-```
-
-## Usage
-
-1. Connect GitHub account via OAuth
-2. Link repository to a Creative
-3. Webhook events automatically create system comments
-4. AI Agent analyzes PRs and suggests task updates
-5. User approves action comments to update Creatives
-
 ## License
 
 AGPL

data/app/controllers/collavre_github/creatives/integrations_controller.rb

@@ -2,6 +2,7 @@ module CollavreGithub
   module Creatives
     class IntegrationsController < ApplicationController
       before_action :set_creative
+      before_action :set_origin
       before_action :ensure_read_permission
       before_action :ensure_admin_permission, only: [ :show, :update ]
 
@@ -9,6 +10,10 @@ module CollavreGithub
         account = Current.user.github_account
         links = linked_repository_links(account)
 
+        # Also include repositories linked by other users for this creative
+        all_links = @creative.github_repository_links.includes(:github_account)
+        all_repositories = all_links.map(&:repository_full_name).uniq
+
         render json: {
           connected: account.present?,
           account: account && {
@@ -17,8 +22,8 @@ module CollavreGithub
             avatar_url: account.avatar_url
           },
           selected_repositories: links.map(&:repository_full_name),
-          webhooks: serialize_webhooks(links),
-          github_gemini_prompt: @creative.github_gemini_prompt_template
+          all_repositories: all_repositories,
+          webhooks: serialize_webhooks(links)
         }
       end
 
@@ -31,7 +36,6 @@ module CollavreGithub
 
         integration_attributes = integration_params
         repositories = Array(integration_attributes[:repositories]).map(&:to_s).uniq
-        prompt_param = integration_attributes[:github_gemini_prompt] if integration_attributes.key?(:github_gemini_prompt)
 
         links = nil
 
@@ -41,17 +45,13 @@ module CollavreGithub
             .delete_all
 
           repositories.each do |full_name|
-            @creative.github_repository_links.find_or_create_by!(
+            @origin.github_repository_links.find_or_create_by!(
               github_account: account,
               repository_full_name: full_name
             )
           end
 
           links = linked_repository_links(account).to_a
-
-          if prompt_param
-            @creative.update!(github_gemini_prompt: prompt_param.presence)
-          end
         end
 
         CollavreGithub::WebhookProvisioner.ensure_for_links(
@@ -63,8 +63,7 @@ module CollavreGithub
         render json: {
           success: true,
           selected_repositories: links.map(&:repository_full_name),
-          webhooks: serialize_webhooks(links),
-          github_gemini_prompt: @creative.github_gemini_prompt_template
+          webhooks: serialize_webhooks(links)
         }
       rescue ActiveRecord::RecordInvalid => e
         render json: { error: e.message }, status: :unprocessable_entity
@@ -132,8 +131,7 @@ module CollavreGithub
         render json: {
           success: true,
           selected_repositories: links.pluck(:repository_full_name),
-          webhooks: serialize_webhooks(links),
-          github_gemini_prompt: @creative.github_gemini_prompt_template
+          webhooks: serialize_webhooks(links)
         }
       end
 
@@ -143,6 +141,10 @@ module CollavreGithub
         @creative = Collavre::Creative.find(params[:creative_id])
       end
 
+      def set_origin
+        @origin = @creative.effective_origin
+      end
+
       def ensure_read_permission
         return if @creative.has_permission?(Current.user, :read)
 
@@ -158,11 +160,11 @@ module CollavreGithub
       def linked_repository_links(account)
         return CollavreGithub::RepositoryLink.none unless account
 
-        @creative.github_repository_links.where(github_account: account)
+        @origin.github_repository_links.where(github_account: account)
       end
 
       def integration_params
-        params.permit(:github_gemini_prompt, repositories: [])
+        params.permit(repositories: [])
       end
 
       def serialize_webhooks(links)

data/app/views/collavre_github/integrations/_modal.html.erb

@@ -50,20 +50,6 @@
       <p id="github-summary-empty" class="github-modal-empty" style="display:none;"><%= t('collavre_github.integration.summary_empty', default: 'No repositories selected.') %></p>
     </div>
 
-    <div class="github-wizard-step" id="github-step-prompt" style="display:none;">
-      <p class="github-modal-subtext"><%= t('collavre_github.integration.prompt_title', default: 'Review the Gemini analysis prompt and edit it if needed.') %></p>
-      <textarea id="github-gemini-prompt" style="width:100%;min-height:220px;padding:0.75em;border:1px solid var(--color-border);border-radius:4px;font-family:monospace;font-size:0.95em;"></textarea>
-      <p class="github-modal-subtext" style="margin-top:0.75em;font-size:0.9em;">
-        <%= t('collavre_github.integration.prompt_help', default: 'Use the placeholders below to inject runtime details as needed:') %>
-        <code>#{pr_title}</code>,
-        <code>#{pr_body}</code>,
-        <code>#{commit_messages}</code>,
-        <code>#{diff}</code>,
-        <code>#{creative_tree}</code>,
-        <code>#{language_instructions}</code>
-      </p>
-    </div>
-
     <div id="github-wizard-error" style="display:none;margin:0.5em 0;color:#c0392b;font-weight:bold;"></div>
 
     <div class="github-wizard-footer" style="display:flex;justify-content:space-between;gap:0.5em;margin-top:1.5em;">

data/config/locales/en.yml

@@ -23,8 +23,6 @@ en:
       summary: "The following repositories will be linked to this Creative:"
       webhook_instructions: "Configure each repository with the webhook details below."
       summary_empty: "No repositories selected."
-      prompt_title: "Review the Gemini analysis prompt and edit it if needed."
-      prompt_help: "Use the placeholders below to inject runtime details as needed:"
     auth:
       login_first: "Please log in first to connect your GitHub account"
       connected: "GitHub account connected successfully"

data/config/locales/ko.yml

@@ -23,8 +23,6 @@ ko:
       summary: "다음 저장소가 이 Creative에 연동됩니다:"
       webhook_instructions: "각 저장소에 아래 웹훅 정보를 설정하세요."
       summary_empty: "선택된 저장소가 없습니다."
-      prompt_title: "Gemini 분석 프롬프트를 검토하고 필요시 수정하세요."
-      prompt_help: "다음 플레이스홀더를 사용하여 런타임 정보를 주입할 수 있습니다:"
     auth:
       login_first: "GitHub 계정을 연결하려면 먼저 로그인하세요"
       connected: "GitHub 계정이 연결되었습니다"

data/db/seeds.rb

@@ -10,11 +10,17 @@ module CollavreGithub
     SYSTEM_PROMPT = <<~PROMPT
       You are a GitHub Pull Request Analyzer. Your role is to analyze merged PRs and help maintain the project task tree (Creatives).
 
+      ## Context
+      When triggered, you receive the creative context in the first message. The creative ID is provided
+      in the system event. **Always use that creative ID** when calling GitHub tools (`creative_id` parameter).
+      The repository name (e.g., "owner/repo") is included in the webhook event message.
+
       ## When you receive a GitHub PR merged event:
-      1. Use `github_pr_details` to get PR information
-      2. Use `github_pr_diff` to analyze code changes
-      3. Use `github_pr_commits` to understand the work done
-      4. Use `creative_retrieval_service` to see the current task tree
+      1. Extract the `repo` (e.g., "sh1nj1/plan42") and `pr_number` from the event message
+      2. Use `github_pr_details(creative_id: <creative_id from context>, repo: <repo>, pr_number: <number>)` to get PR information
+      3. Use `github_pr_diff` to analyze code changes
+      4. Use `github_pr_commits` to understand the work done
+      5. Use `creative_retrieval_service` to see the current task tree
 
       ## Analysis Guidelines:
       - Match PR changes to existing tasks in the Creative tree
@@ -23,33 +29,32 @@ module CollavreGithub
       - Consider the PR title, description, and commit messages for context
 
       ## Response Format:
-      After your analysis, if you identify tasks to update or create, respond with an action comment.
+      After your analysis, use the `creative_batch_service` tool to apply all changes at once.
+      This tool accepts an array of operations (create, update, delete) and executes them in a single transaction.
 
-      For completed tasks, suggest updating progress to 1.0:
-      ```json
-      {
-        "actions": [
-          { "action": "update_creative", "creative_id": <id>, "attributes": { "progress": 1.0 } }
-        ]
-      }
+      Example tool call:
       ```
-
-      For new tasks discovered:
-      ```json
-      {
-        "actions": [
-          { "action": "create_creative", "parent_id": <parent_id>, "attributes": { "description": "Task description" } }
+      creative_batch_service({
+        operations: [
+          { action: "update", id: 123, progress: 1.0 },
+          { action: "create", parent_id: 456, description: "New task discovered" },
+          { action: "delete", id: 789 }
         ]
-      }
+      })
       ```
 
-      You can combine multiple actions in a single response.
-
       ## Important:
       - Only suggest updates for tasks that are clearly addressed by the PR
       - Be conservative - don't mark tasks complete unless the PR clearly resolves them
-      - Provide a brief summary of your analysis before the action JSON
-      - If no task updates are needed, just provide your analysis summary without action JSON
+      - Provide a brief summary of your analysis before calling the tool
+      - If no task updates are needed, just provide your analysis summary without calling any tool
+      - The batch tool requires approval — a human will review and approve your changes before they are applied
+
+      ## Progress Update Rules:
+      - You can ONLY set progress to 1.0 (100% complete) — partial progress values are NOT allowed
+      - You can ONLY update progress on LEAF Creatives (Creatives with no children)
+      - Parent Creative progress is automatically calculated from their children — never try to update it directly
+      - Use `creative_retrieval_service` to navigate the tree and find the correct leaf Creative before updating
     PROMPT
 
     # Matches GitHub PR merged events
@@ -58,12 +63,19 @@ module CollavreGithub
       event_name == "comment_created" and comment.user_id == nil and comment.content contains "GitHub: Pull Request Merged"
     EXPR
 
+    AGENT_CONF = <<~YAML
+      context:
+        chat_history: 1
+        chat_history_size: 1000
+        creative_children_level: 0
+    YAML
+
     TOOLS = %w[
       github_pr_details
       github_pr_diff
       github_pr_commits
       creative_retrieval_service
-      creative_update_service
+      creative_batch_service
     ].freeze
 
     def self.call
@@ -94,6 +106,7 @@ module CollavreGithub
         llm_model: default_llm_model,
         system_prompt: SYSTEM_PROMPT,
         routing_expression: ROUTING_EXPRESSION,
+        agent_conf: AGENT_CONF,
         tools: TOOLS,
         searchable: true # Can analyze PRs for any Creative with GitHub integration
       )

data/lib/collavre_github/version.rb

@@ -1,3 +1,3 @@
 module CollavreGithub
-  VERSION = "0.2.1"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: collavre_github
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Collavre