coplan-engine 0.1.0

data/app/controllers/coplan/api/v1/base_controller.rb

@@ -0,0 +1,75 @@
+module CoPlan
+  module Api
+    module V1
+      class BaseController < ActionController::API
+        before_action :authenticate_api!
+
+        private
+
+        def authenticate_api!
+          token = request.headers["Authorization"]&.delete_prefix("Bearer ")
+          if token.present?
+            authenticate_via_token!(token)
+            return if @api_token
+          end
+
+          if CoPlan.configuration.api_authenticate
+            attrs = CoPlan.configuration.api_authenticate.call(request)
+            if attrs && attrs[:external_id].present?
+              provision_user_from_hook!(attrs)
+              return
+            end
+          end
+
+          render json: { error: "Unauthorized" }, status: :unauthorized
+        end
+
+        def provision_user_from_hook!(attrs)
+          external_id = attrs[:external_id].to_s
+          @current_api_user = CoPlan::User.find_or_initialize_by(external_id: external_id)
+          @current_api_user.assign_attributes(attrs.slice(:name, :admin, :metadata).compact)
+          if @current_api_user.new_record? || @current_api_user.changed?
+            @current_api_user.save!
+          end
+        rescue ActiveRecord::RecordNotUnique
+          @current_api_user = CoPlan::User.find_by!(external_id: external_id)
+        end
+
+        def authenticate_via_token!(token)
+          @api_token = CoPlan::ApiToken.authenticate(token)
+        end
+
+        def current_user
+          @current_api_user || @api_token&.user
+        end
+
+        # Unique identifier for the API caller — used as actor_id, holder_id, author_id.
+        # With token auth this is the token's ID; with hook auth it's the user's ID.
+        def api_actor_id
+          @api_token&.id || @current_api_user&.id
+        end
+
+        # The type of actor making the API call.
+        # Token auth → "local_agent"; hook auth → "human".
+        def api_author_type
+          @api_token ? ApiToken::HOLDER_TYPE : "human"
+        end
+
+        def set_plan
+          @plan = CoPlan::Plan.find_by(id: params[:plan_id] || params[:id])
+          unless @plan
+            render json: { error: "Plan not found" }, status: :not_found
+          end
+        end
+
+        def authorize_plan_access!
+          return unless @plan
+          policy = CoPlan::PlanPolicy.new(current_user, @plan)
+          unless policy.show?
+            render json: { error: "Plan not found" }, status: :not_found
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/coplan/api/v1/comments_controller.rb

@@ -0,0 +1,135 @@
+module CoPlan
+  module Api
+    module V1
+      class CommentsController < BaseController
+        before_action :set_plan
+        before_action :authorize_plan_access!
+
+        def create
+          thread = @plan.comment_threads.new(
+            plan_version: @plan.current_plan_version,
+            anchor_text: params[:anchor_text].presence,
+            anchor_occurrence: params[:anchor_occurrence]&.to_i,
+            start_line: params[:start_line].presence,
+            end_line: params[:end_line].presence,
+            created_by_user: current_user
+          )
+
+          thread.save!
+
+          comment = thread.comments.create!(
+            author_type: api_author_type,
+            author_id: api_actor_id,
+            body_markdown: params[:body_markdown],
+            agent_name: params[:agent_name]
+          )
+
+          broadcast_new_thread(thread)
+
+          render json: {
+            thread_id: thread.id,
+            comment_id: comment.id,
+            status: thread.status,
+            created_at: thread.created_at
+          }, status: :created
+
+        rescue ActiveRecord::RecordInvalid => e
+          render json: { error: e.message }, status: :unprocessable_entity
+        end
+
+        def resolve
+          thread = @plan.comment_threads.find_by(id: params[:id])
+          unless thread
+            render json: { error: "Comment thread not found" }, status: :not_found
+            return
+          end
+
+          policy = CommentThreadPolicy.new(current_user, thread)
+          unless policy.resolve?
+            render json: { error: "Not authorized" }, status: :forbidden
+            return
+          end
+
+          thread.resolve!(current_user)
+          broadcast_thread_update(thread)
+
+          render json: { thread_id: thread.id, status: thread.status }
+        end
+
+        def dismiss
+          thread = @plan.comment_threads.find_by(id: params[:id])
+          unless thread
+            render json: { error: "Comment thread not found" }, status: :not_found
+            return
+          end
+
+          policy = CommentThreadPolicy.new(current_user, thread)
+          unless policy.dismiss?
+            render json: { error: "Not authorized" }, status: :forbidden
+            return
+          end
+
+          thread.dismiss!(current_user)
+          broadcast_thread_update(thread)
+
+          render json: { thread_id: thread.id, status: thread.status }
+        end
+
+        def reply
+          thread = @plan.comment_threads.find_by(id: params[:id])
+          unless thread
+            render json: { error: "Comment thread not found" }, status: :not_found
+            return
+          end
+
+          comment = thread.comments.create!(
+            author_type: api_author_type,
+            author_id: api_actor_id,
+            body_markdown: params[:body_markdown],
+            agent_name: params[:agent_name]
+          )
+
+          broadcast_new_comment(thread, comment)
+
+          render json: {
+            comment_id: comment.id,
+            thread_id: thread.id,
+            created_at: comment.created_at
+          }, status: :created
+
+        rescue ActiveRecord::RecordInvalid => e
+          render json: { error: e.message }, status: :unprocessable_entity
+        end
+
+        private
+
+        def broadcast_new_thread(thread)
+          Broadcaster.prepend_to(
+            @plan,
+            target: "comment-threads",
+            partial: "coplan/comment_threads/thread",
+            locals: { thread: thread, plan: @plan }
+          )
+        end
+
+        def broadcast_thread_update(thread)
+          Broadcaster.replace_to(
+            @plan,
+            target: ActionView::RecordIdentifier.dom_id(thread),
+            partial: "coplan/comment_threads/thread",
+            locals: { thread: thread, plan: @plan }
+          )
+        end
+
+        def broadcast_new_comment(thread, comment)
+          Broadcaster.append_to(
+            @plan,
+            target: ActionView::RecordIdentifier.dom_id(thread, :comments),
+            partial: "coplan/comments/comment",
+            locals: { comment: comment }
+          )
+        end
+      end
+    end
+  end
+end

data/app/controllers/coplan/api/v1/leases_controller.rb

@@ -0,0 +1,62 @@
+module CoPlan
+  module Api
+    module V1
+      class LeasesController < BaseController
+        before_action :set_plan
+        before_action :authorize_plan_access!
+
+        def create
+          lease_token = params[:lease_token] || SecureRandom.hex(32)
+
+          lease = EditLease.acquire!(
+            plan: @plan,
+            holder_type: ApiToken::HOLDER_TYPE,
+            holder_id: api_actor_id,
+            lease_token: lease_token
+          )
+
+          render json: {
+            lease_token: lease_token,
+            expires_at: lease.expires_at,
+            plan_id: @plan.id
+          }, status: :created
+
+        rescue EditLease::Conflict => e
+          render json: { error: e.message }, status: :conflict
+        end
+
+        def update
+          lease = @plan.edit_lease
+          unless lease
+            render json: { error: "No active lease for this plan" }, status: :not_found
+            return
+          end
+
+          lease.renew!(lease_token: params[:lease_token])
+          render json: {
+            lease_token: params[:lease_token],
+            expires_at: lease.expires_at,
+            plan_id: @plan.id
+          }
+
+        rescue EditLease::Conflict => e
+          render json: { error: e.message }, status: :conflict
+        end
+
+        def destroy
+          lease = @plan.edit_lease
+          unless lease
+            render json: { error: "No active lease for this plan" }, status: :not_found
+            return
+          end
+
+          lease.release!(lease_token: params[:lease_token])
+          head :no_content
+
+        rescue EditLease::Conflict => e
+          render json: { error: e.message }, status: :conflict
+        end
+      end
+    end
+  end
+end

data/app/controllers/coplan/api/v1/operations_controller.rb

@@ -0,0 +1,298 @@
+module CoPlan
+  module Api
+    module V1
+      class OperationsController < BaseController
+        before_action :set_plan
+        before_action :authorize_plan_access!
+
+        def create
+          operations = params[:operations]
+          base_revision = params[:base_revision]&.to_i
+
+          unless base_revision.present?
+            render json: { error: "base_revision is required" }, status: :unprocessable_entity
+            return
+          end
+
+          unless operations.is_a?(Array) && operations.any?
+            render json: { error: "operations must be a non-empty array" }, status: :unprocessable_entity
+            return
+          end
+
+          if params[:session_id].present?
+            apply_with_session(operations, base_revision)
+          elsif params[:lease_token].present?
+            apply_with_lease(operations, base_revision)
+          else
+            apply_direct(operations, base_revision)
+          end
+        rescue Plans::OperationError => e
+          render json: { error: e.message }, status: :unprocessable_entity
+        end
+
+        private
+
+        def apply_with_session(operations, base_revision)
+          session = @plan.edit_sessions.find_by(id: params[:session_id], actor_id: api_actor_id)
+          unless session&.active?
+            render json: { error: "Edit session not found, expired, or not open" }, status: :not_found
+            return
+          end
+
+          applied_count = nil
+          ActiveRecord::Base.transaction do
+            session.lock!
+
+            unless session.active?
+              render json: { error: "Edit session is no longer active" }, status: :conflict
+              return
+            end
+
+            # Use draft_content if we've already applied ops, otherwise use the
+            # session's base revision snapshot so resolved ranges stay consistent
+            # with base_revision (not the potentially-advanced current content).
+            working_content = session.draft_content
+            unless working_content
+              base_version = @plan.plan_versions.find_by(revision: session.base_revision)
+              working_content = base_version&.content_markdown || @plan.current_content || ""
+            end
+            result = Plans::ApplyOperations.call(content: working_content, operations: operations)
+
+            session.update!(
+              operations_json: session.operations_json + result[:applied],
+              draft_content: result[:content]
+            )
+            applied_count = result[:applied].length
+          end
+
+          return if performed?
+
+          render json: {
+            session_id: session.id,
+            applied: applied_count,
+            operations_pending: session.reload.operations_json.length
+          }, status: :created
+        end
+
+        def apply_with_lease(operations, base_revision)
+          lease_token = params[:lease_token]
+
+          lease = @plan.edit_lease
+          unless lease&.held_by?(lease_token: lease_token)
+            render json: { error: "You do not hold a valid edit lease for this plan" }, status: :conflict
+            return
+          end
+
+          if @plan.current_revision != base_revision
+            render json: {
+              error: "Stale revision. Expected #{@plan.current_revision}, got #{base_revision}",
+              current_revision: @plan.current_revision
+            }, status: :conflict
+            return
+          end
+
+          create_version_from_operations(operations, base_revision: base_revision)
+        rescue EditLease::Conflict => e
+          render json: { error: e.message }, status: :conflict
+        end
+
+        def apply_direct(operations, base_revision)
+          ActiveRecord::Base.transaction do
+            @plan.lock!
+            @plan.reload
+
+            current_content = @plan.current_content || ""
+
+            final_ops = if @plan.current_revision != base_revision
+              rebase_and_resolve(operations, base_revision, current_content)
+            else
+              operations
+            end
+
+            return if performed? # rebase_and_resolve may have rendered a conflict
+
+            result = Plans::ApplyOperations.call(content: current_content, operations: final_ops)
+            commit_version(current_content, result)
+          end
+        end
+
+        # Rebase stale operations via OT: resolve each op to character ranges
+        # against the base_revision snapshot, transform those ranges through all
+        # intervening versions' positional metadata, verify the target text still
+        # matches at the transformed position, and return ops with pre-resolved
+        # ranges. All versions MUST have positional metadata in operations_json;
+        # TransformRange raises Conflict if any operation lacks it.
+        def rebase_and_resolve(operations, base_revision, current_content)
+          stale_gap = @plan.current_revision - base_revision
+          if stale_gap > 20
+            render json: {
+              error: "Too stale — #{stale_gap} revisions behind (max 20). Re-read the plan.",
+              current_revision: @plan.current_revision
+            }, status: :conflict
+            return
+          end
+
+          base_version = @plan.plan_versions.find_by(revision: base_revision)
+          unless base_version
+            render json: { error: "Base revision #{base_revision} not found" }, status: :conflict
+            return
+          end
+
+          intervening_versions = @plan.plan_versions
+            .where("revision > ? AND revision <= ?", base_revision, @plan.current_revision)
+            .order(revision: :asc)
+            .to_a
+
+          working_base = base_version.content_markdown
+          verification_content = current_content.dup
+          rebased_ops = []
+
+          operations.each do |op|
+            op = op.respond_to?(:to_unsafe_h) ? op.to_unsafe_h.transform_keys(&:to_s) : op.transform_keys(&:to_s)
+            begin
+              resolution = Plans::PositionResolver.call(content: working_base, operation: op)
+              transformed_ranges = resolution.ranges.map do |range|
+                Plans::TransformRange.transform_through_versions(range, intervening_versions)
+              end
+
+              verify_transformed_ranges!(op, transformed_ranges, verification_content)
+              return if performed?
+
+              # Advance the working base snapshot so the next op resolves
+              # against the result of this one (sequential semantics).
+              apply_result = Plans::ApplyOperations.call(content: working_base, operations: [op])
+              working_base = apply_result[:content]
+
+              rebased_op = op.dup
+              rebased_op["_pre_resolved_ranges"] = transformed_ranges
+              rebased_ops << rebased_op
+
+              # Advance verification content so the next op's conflict check
+              # runs against the incrementally updated snapshot.
+              verify_step = Plans::ApplyOperations.call(content: verification_content, operations: [rebased_op])
+              verification_content = verify_step[:content]
+            rescue Plans::TransformRange::Conflict => e
+              render json: {
+                error: "Conflict: #{e.message}",
+                current_revision: @plan.current_revision
+              }, status: :conflict
+              return
+            end
+          end
+
+          rebased_ops
+        end
+
+        def create_version_from_operations(operations, base_revision:)
+          ActiveRecord::Base.transaction do
+            @plan.lock!
+            @plan.reload
+
+            if @plan.current_revision != base_revision
+              render json: {
+                error: "Stale revision. Expected #{@plan.current_revision}, got #{base_revision}",
+                current_revision: @plan.current_revision
+              }, status: :conflict
+              return
+            end
+
+            current_content = @plan.current_content || ""
+            result = Plans::ApplyOperations.call(content: current_content, operations: operations)
+            commit_version(current_content, result)
+          end
+        end
+
+        def commit_version(current_content, result)
+          new_revision = @plan.current_revision + 1
+          diff = Diffy::Diff.new(current_content, result[:content]).to_s
+
+          version = PlanVersion.create!(
+            plan: @plan,
+            revision: new_revision,
+            content_markdown: result[:content],
+            actor_type: api_author_type,
+            actor_id: api_actor_id,
+            change_summary: params[:change_summary],
+            diff_unified: diff.presence,
+            operations_json: result[:applied],
+            base_revision: params[:base_revision]&.to_i,
+            reason: params[:reason]
+          )
+
+          @plan.update!(
+            current_plan_version: version,
+            current_revision: new_revision
+          )
+
+          @plan.comment_threads.mark_out_of_date_for_new_version!(version)
+
+          broadcast_plan_update
+
+          render json: {
+            revision: new_revision,
+            content_sha256: version.content_sha256,
+            applied: result[:applied].length,
+            version_id: version.id
+          }, status: :created
+        end
+
+        def verify_transformed_ranges!(op, transformed_ranges, content)
+          case op["op"]
+          when "replace_exact"
+            return unless op["old_text"]
+            transformed_ranges.each do |tr|
+              actual = content[tr[0]...tr[1]]
+              unless actual == op["old_text"]
+                render json: {
+                  error: "Conflict: text at target position has changed",
+                  current_revision: @plan.current_revision,
+                  expected: op["old_text"],
+                  found: actual
+                }, status: :conflict
+                return
+              end
+            end
+          when "insert_under_heading"
+            return unless op["heading"]
+            transformed_ranges.each do |tr|
+              line_start = tr[0] > 0 ? (content.rindex("\n", tr[0] - 1) || -1) + 1 : 0
+              line_text = content[line_start...tr[0]]
+              unless line_text&.match?(/\A#{Regexp.escape(op["heading"])}\s*\z/)
+                render json: {
+                  error: "Conflict: heading at target position has changed",
+                  current_revision: @plan.current_revision,
+                  expected: op["heading"],
+                  found: line_text
+                }, status: :conflict
+                return
+              end
+            end
+          when "delete_paragraph_containing"
+            return unless op["needle"]
+            transformed_ranges.each do |tr|
+              actual = content[tr[0]...tr[1]]
+              unless actual&.include?(op["needle"])
+                render json: {
+                  error: "Conflict: paragraph no longer contains the expected text",
+                  current_revision: @plan.current_revision,
+                  expected_needle: op["needle"],
+                  found: actual
+                }, status: :conflict
+                return
+              end
+            end
+          end
+        end
+
+        def broadcast_plan_update
+          Broadcaster.replace_to(
+            @plan,
+            target: "plan-header",
+            partial: "coplan/plans/header",
+            locals: { plan: @plan }
+          )
+        end
+      end
+    end
+  end
+end

data/app/controllers/coplan/api/v1/plans_controller.rb

@@ -0,0 +1,129 @@
+module CoPlan
+  module Api
+    module V1
+      class PlansController < BaseController
+        before_action :set_plan, only: [:show, :update, :versions, :comments]
+        before_action :authorize_plan_access!, only: [:show, :update, :versions, :comments]
+
+        def index
+          plans = Plan
+            .where.not(status: "brainstorm")
+            .or(Plan.where(created_by_user: current_user))
+            .order(updated_at: :desc)
+          plans = plans.where(status: params[:status]) if params[:status].present?
+          render json: plans.map { |p| plan_json(p) }
+        end
+
+        def show
+          render json: plan_json(@plan).merge(
+            current_content: @plan.current_content,
+            current_revision: @plan.current_revision
+          )
+        end
+
+        def create
+          plan = Plans::Create.call(
+            title: params[:title],
+            content: params[:content] || "",
+            user: current_user
+          )
+          render json: plan_json(plan).merge(
+            current_content: plan.current_content,
+            current_revision: plan.current_revision
+          ), status: :created
+        rescue ActiveRecord::RecordInvalid => e
+          render json: { error: e.message }, status: :unprocessable_entity
+        end
+
+        def update
+          policy = PlanPolicy.new(current_user, @plan)
+          unless policy.update?
+            return render json: { error: "Not authorized" }, status: :forbidden
+          end
+
+          permitted = {}
+          permitted[:title] = params[:title] if params.key?(:title)
+          permitted[:status] = params[:status] if params.key?(:status)
+          permitted[:tags] = params[:tags] if params.key?(:tags)
+
+          @plan.update!(permitted)
+
+          if @plan.saved_changes?
+            Broadcaster.replace_to(@plan, target: "plan-header", partial: "coplan/plans/header", locals: { plan: @plan })
+          end
+
+          if permitted.key?(:status) && @plan.saved_change_to_status?
+            Plans::TriggerAutomatedReviews.call(plan: @plan, new_status: permitted[:status], triggered_by: current_user)
+          end
+
+          render json: plan_json(@plan).merge(
+            current_content: @plan.current_content,
+            current_revision: @plan.current_revision
+          )
+        rescue ActiveRecord::RecordInvalid => e
+          render json: { error: e.record.errors.full_messages.join(", ") }, status: :unprocessable_entity
+        end
+
+        def versions
+          versions = @plan.plan_versions.order(revision: :desc)
+          render json: versions.map { |v| version_json(v) }
+        end
+
+        def comments
+          threads = @plan.comment_threads.includes(:comments, :created_by_user).order(created_at: :desc)
+          render json: threads.map { |t| thread_json(t) }
+        end
+
+        private
+
+        def plan_json(plan)
+          {
+            id: plan.id,
+            title: plan.title,
+            status: plan.status,
+            current_revision: plan.current_revision,
+            tags: plan.tags,
+            created_by: plan.created_by_user.name,
+            created_at: plan.created_at,
+            updated_at: plan.updated_at
+          }
+        end
+
+        def version_json(version)
+          {
+            id: version.id,
+            revision: version.revision,
+            content_sha256: version.content_sha256,
+            actor_type: version.actor_type,
+            change_summary: version.change_summary,
+            created_at: version.created_at
+          }
+        end
+
+        def thread_json(thread)
+          {
+            id: thread.id,
+            status: thread.status,
+            anchor_text: thread.anchor_text,
+            anchor_context: thread.anchor_context_with_highlight,
+            anchor_valid: thread.anchor_valid?,
+            start_line: thread.start_line,
+            end_line: thread.end_line,
+            out_of_date: thread.out_of_date,
+            created_by: thread.created_by_user.name,
+            created_at: thread.created_at,
+            comments: thread.comments.order(created_at: :asc).map { |c|
+              {
+                id: c.id,
+                author_type: c.author_type,
+                agent_name: c.agent_name,
+                body_markdown: c.body_markdown,
+                created_at: c.created_at
+              }
+            }
+          }
+        end
+      end
+    end
+  end
+end