mingle-link-fixer 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 3fbe569bf3bcac0083625a2c51097cd37d96f3fc
+  data.tar.gz: 9176dc5401d134f6000c1d99d3bb86339564ec04
+SHA512:
+  metadata.gz: d127e2b6d7de385d1ba32eede46b059361d240faae99d9eeee88f02b352ad1fd04f5099d11400283b026b746145a35b5d6fe318e222f8a40c12922dc123529b1
+  data.tar.gz: ccf029ae581e2a83c4f19d99ca5f3fc898d60d93250eddceeb101cfa78c71efddb69cce0201d5f275753ff3d935a4b2491a94a1d732c9cae5dced75367e30195

data/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2014 ThoughtWorks Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

data/README.md

@@ -0,0 +1,33 @@
+Mingle Attachment Link Fixer
+============================
+
+If you're like many [Mingle](http://getmingle.io) users and you wanted to add link to an attachment, then you probably just right-clicked the attachment at the bottom of the card and pasted that into the link box.
+
+Which is all fine and dandy, until you move Mingle servers, move from on-premise to Mingle SaaS, or recover your project from a data backup.  In this case, the attachment IDs will be different.  All the links will be broken!!
+
+This script is designed to fix this problem.  If you have your export file with valid attachments inside, then this tool can go through your cards and magically restore your links. It will use the archaic (but correct and guaranteed not to break) syntax:
+
+[[Your link text|#123/my-file.ext]]
+
+What's that, you say?  That's wiki markup?  Well, yes, it is.  We chose to stick with the format our users were used to rather than invent a way to put that into HTML links.
+
+Usage
+-----
+
+You'll need Ruby 2.0+
+
+  > gem install mingle-link-fixer
+
+  > mingle-link-fixer http://mingle.your.org/projects/iphone_app /path/containing/extracted/good/export
+
+You can set the environment variables VERBOSE and DRY_RUN to true if you want more information or want to see what will happen when it runs, respectively.
+
+
+Contributors / Bugs / &c.
+-------------------------
+
+Please open a GitHub issue and we'll get in touch.
+
+Snap CI build status:
+
+[![Build Status](https://snap-ci.com/ThoughtWorksStudios/mingle-link-fixer/branch/master/build_image)](https://snap-ci.com/ThoughtWorksStudios/mingle-link-fixer/branch/master)

data/bin/mingle-link-fixer

@@ -0,0 +1,38 @@
+#!/usr/bin/env ruby
+require 'highline/import'
+require 'uri'
+require_relative '../lib/mingle_link_fixer'
+
+def my_simple_name
+  $0.split('/')[-1]
+end
+
+def die_with_usage
+  puts(<<-USAGE.strip)
+  usage: #{my_simple_name} PROJECT_URL OLD_PROJECT_EXPORT
+      example: #{my_simple_name} http://mingle.your.org/projects/plan_a /path/to/extracted/proj/export
+USAGE
+  exit -1
+end
+
+die_with_usage if ARGV[0].nil? || ARGV[0].empty?
+project_uri = URI.parse(ARGV[0])
+
+old_project_export_folder = if ARGV[1].nil? || ARGV[1].empty?
+  die_with_usage
+elsif Dir[File.join(ARGV[1], "*.yml")].count > 0
+  ARGV[1]
+else
+  puts "Could find attachments yml files in #{ARGV[1]}"
+  exit -1
+end
+
+username = ENV['MINGLE_USERNAME'] || ask("enter username for #{project_uri.hostname}")
+password = ENV['MINGLE_PASSWORD'] || ask("enter password for #{username}: ") { |prompt| prompt.echo = false }
+
+fixer = Mingle::LinkFixer.new(project_url: project_uri.to_s,
+                              historical_attachments_folder: old_project_export_folder,
+                              username: username,
+                              password: password)
+
+fixer.fix(dry_run: ENV['DRY_RUN'] == 'true', starting_card: ENV['STARTING_CARD'], limit: ENV['LIMIT'])

data/lib/mingle/api.rb

@@ -0,0 +1,44 @@
+require 'nokogiri'
+require 'cgi'
+
+require_relative 'logging'
+
+module Mingle
+
+  class API
+    include Logging
+
+    def initialize(http_client)
+      @http_client = http_client
+    end
+
+    def get_card(number)
+      @http_client.get("/cards/#{number}.xml").body
+    end
+
+    def get_attachments_on(card_number)
+      @http_client.get("/cards/#{card_number}/attachments.xml").body
+    end
+
+    def save_card(card)
+      @http_client.put("/cards/#{card.number}.xml", body: card.to_xml, 'Content-Type' => 'text/xml')
+    end
+
+    def execute_mql(mql)
+      response = @http_client.get('/cards/execute_mql.xml', mql: mql)
+      logger.debug(response.body)
+      Nokogiri::XML.parse(response.body).search('result').inject([]) do |results, result|
+        result_hash = result.children.inject({}) do |hash, child|
+          unless Nokogiri::XML::Text === child
+            hash[child.name] = child.text
+          end
+          hash
+        end
+        results << result_hash
+      end
+    end
+
+
+  end
+
+end

data/lib/mingle/attachment.rb

@@ -0,0 +1,27 @@
+require 'nokogiri'
+
+module Mingle
+  class Attachment
+
+    attr_reader :filename
+
+    def initialize(filename)
+      @filename = filename
+    end
+
+    def self.api=(api)
+      @@api = api
+    end
+
+    def self.find_all_by_card_number(number)
+      [].tap do |attachments|
+        xml = @@api.get_attachments_on(number)
+        document = Nokogiri::XML.parse(xml)
+        document.xpath('./attachments/attachment').each do |element|
+          filename = element.xpath('./file_name').text
+          attachments << Attachment.new(filename)
+        end
+      end
+    end
+  end
+end

data/lib/mingle/attachment_link.rb

@@ -0,0 +1,43 @@
+require_relative 'logging'
+require_relative 'card'
+require_relative 'historical_attachments'
+require_relative 'attachment'
+
+module Mingle
+  class AttachmentLink
+    include Logging
+
+    def initialize(element)
+      @element = element
+    end
+
+    def rewrite(card, historical_attachments)
+      href = @element['href']
+      old_attachment_id = if href =~ /projects.*\/attachments\/(\d+)/
+        $1
+      elsif href =~ /attachments\/[0-9a-f]+\/(\d+)/
+        $1
+      end
+      old_attachment = historical_attachments.find_by_id(old_attachment_id)
+      raise "Could not find historical attachment based on #{old_attachment_id}" unless old_attachment
+      new_attachment = card.attachments.find { |attachment| attachment.filename == old_attachment.filename }
+      if new_attachment
+        "[[#{@element.text}|##{card.number}/#{new_attachment.filename}]]"
+      else
+        raise "Could not find matching attachmen for #{old_attachment.filename} in #{card.attachments.map(&:filename)}"
+      end
+
+    end
+
+    def rewrite!(card, historical_attachments)
+      new_content = rewrite(card, historical_attachments)
+      logger.debug "replacing #{@element.to_html} with #{new_content}"
+      @element.replace(Nokogiri::XML::Text.new(new_content, @element.document))
+      nil
+    rescue => e
+      raise "Could not replace #{@element} because: #{e.message}"
+    end
+
+
+  end
+end

data/lib/mingle/attachment_link_finder.rb

@@ -0,0 +1,27 @@
+require 'nokogiri'
+require_relative 'attachment_link'
+
+module Mingle
+  class AttachmentLinkFinder
+
+    attr_reader :attachment_links, :card_description_document
+
+    def initialize(description)
+      @attachment_links = find_links(description)
+    end
+
+    private
+
+    def find_links(html)
+      @card_description_document = Nokogiri::HTML.parse(html)
+      @card_description_document.search('a').inject([]) do |memo, anchor|
+        href = anchor['href']
+        if href =~ /attachments/
+          memo << AttachmentLink.new(anchor)
+        end
+        memo
+      end
+    end
+
+  end
+end

data/lib/mingle/card.rb

@@ -0,0 +1,82 @@
+require 'nokogiri'
+require_relative 'api'
+
+module Mingle
+  class Card
+
+    def self.all(options={})
+      options = {starting_from: '1'}.merge(options)
+      Logging.debug "Mingle API => #{@@api.inspect}"
+      starting_card_number = options[:starting_with].to_i
+      max_card_number = unless options[:limit]
+        mql = "SELECT MAX(number)"
+        results = @@api.execute_mql(mql)
+        Logging.debug "#{mql}: #{results.inspect}"
+         results[0]['max_number'].to_i
+       else
+         starting_card_number + options[:limit].to_i
+       end
+      Enumerator.new do |yielder|
+        (starting_card_number..max_card_number).to_a.each do |number|
+          begin
+            yielder.yield Card.find_by_number(number)
+          rescue => e
+            Logging.error "Unable to fetch card ##{number} due to #{e.message}"
+          end
+        end
+      end
+    end
+
+    def self.find_by_number(number)
+      Logging.debug("fetching card ##{number}")
+      card_xml = @@api.get_card(number)
+      Card.new(card_xml)
+    end
+
+    def self.api=(api)
+      @@api = api
+    end
+
+    attr_accessor :description, :number, :name
+
+    def initialize(xml)
+      document = Nokogiri::XML.parse(xml)
+      @description = document.xpath('./card/description').text
+      @number = document.xpath('./card/number').text.to_i
+      @name = document.xpath('./card/name').text
+    end
+
+    def description=(desc)
+      @description = remove_enclosing_html_doc_and_body(desc)
+    end
+
+    def attachments
+      @attachments ||= Attachment.find_all_by_card_number(number)
+    end
+
+    def save!
+      @@api.save_card(self)
+    end
+
+    def to_xml
+      Nokogiri::XML::Builder.new { |xml|
+        xml.card {
+          xml.description(@description)
+        }
+      }.to_xml
+    end
+
+    private
+
+    DOCTYPE_REGEX = /^<!DOCTYPE html PUBLIC "-\/\/W3C\/\/DTD HTML 4.0 Transitional\/\/EN" "http:\/\/www.w3.org\/TR\/REC-html40\/loose.dtd\">/
+
+    def remove_enclosing_html_doc_and_body(html)
+      html.gsub(DOCTYPE_REGEX, '').strip
+        .gsub(/<html>/, '').strip
+        .gsub(/<body>/, '').strip
+        .gsub(/<\/html>$/, '').strip
+        .gsub(/<\/body>$/, '').strip
+    end
+
+  end
+end

data/lib/mingle/historical_attachments.rb

@@ -0,0 +1,25 @@
+require 'yaml'
+require_relative 'attachment'
+
+module Mingle
+  class HistoricalAttachments
+
+    def initialize(path)
+      @path = path
+      @attachments = []
+      Dir[File.join(@path, 'attachments_*.yml')].each do |file|
+        @attachments += YAML.load_file(file)
+      end
+    end
+
+    def size
+      @attachments.size
+    end
+
+    def find_by_id(id)
+      attachment = @attachments.find { |attachment| attachment['id'].to_s == id.to_s }
+      Attachment.new(attachment['file']) if attachment
+    end
+
+  end
+end

data/lib/mingle/http_client.rb

@@ -0,0 +1,58 @@
+require 'net/http'
+require 'cgi'
+
+module Mingle
+  class HttpClient
+    include Logging
+
+    attr_accessor :base_url
+
+    def initialize(username, password)
+      @username = username
+      @password = password
+    end
+
+    def get(path, params={})
+      url = File.join(base_url, path + to_url(params))
+      logger.debug "HTTP GET #{url}"
+      process(Net::HTTP::Get, url)
+    end
+
+    def put(path, params={})
+      url = url = File.join(base_url, path)
+      body = params.delete :body
+      process(Net::HTTP::Put, url, params, body)
+    end
+
+    private
+
+    def to_url(params)
+      params.inject([]) do |memo, pair|
+        memo.tap do |memo|
+          key, value = *pair
+          memo << "#{CGI.escape(key.to_s)}=#{CGI.escape(value.to_s)}"
+        end
+      end.join("&").tap { |params| return "?#{params}" unless params.empty? }
+    end
+
+    def process(request_class, url, headers={}, body=nil)
+      uri = URI.parse(url)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true if uri.scheme == 'https'
+
+      request = request_class.new(uri.request_uri)
+      request.basic_auth @username, @password
+      request.body = body if body.tap { logger.debug("HTTP body: #{body}") if body }
+      headers.each do |key, value|
+        request[key] = value
+      end
+
+      response = http.request(request)
+
+      response.tap do
+        raise "Unexpected response of #{response.code} to #{url}" unless response.code.to_i >= 200 && response.code.to_i < 400
+      end
+    end
+
+  end
+end

data/lib/mingle/logging.rb

@@ -0,0 +1,26 @@
+require 'logger'
+
+module Mingle
+  module Logging
+
+    VERBOSE = (ENV['VERBOSE'] == 'true')
+    LOGGER = Logger.new(STDOUT).tap { |l| l.level = VERBOSE ? Logger::DEBUG : Logger::INFO }
+
+    def self.info(msg)
+      LOGGER.info(msg)
+    end
+
+    def self.debug(msg)
+      LOGGER.debug(msg)
+    end
+
+    def self.error(msg)
+      LOGGER.error(msg)
+    end
+
+    def logger
+      LOGGER
+    end
+
+  end
+end

data/lib/mingle/stats.rb

@@ -0,0 +1,42 @@
+module Mingle
+  class Stats
+
+    attr_accessor :total_cards_checked, :cards_without_attachments, :cards_without_links,
+                  :cards_fixed, :problematic_cards
+
+    def initialize
+      @total_cards_checked = 0
+      @cards_without_attachments = 0
+      @cards_without_links = 0
+      @problematic_cards = {}
+      @cards_fixed = 0
+      @start = Time.now
+    end
+
+    def duration_in_seconds
+      Time.now - @start
+    end
+
+    SPACER = "=" * 80
+
+    def to_pretty_string
+      %{
+        #{SPACER}
+        SUMMARY
+
+        Completed in #{duration_in_seconds} sec
+
+        Total Cards Checked:         #{total_cards_checked}
+        Cards Without Attachments:   #{cards_without_attachments}
+        Cards Without Fixable Links: #{cards_without_links}
+
+        Problematic Cards:           #{problematic_cards.size}
+        #{'(specific errors can be seen if you set VERBOSE environment variable)' if problematic_cards.any?}
+
+        Fixed Cards:                 #{cards_fixed}
+        #{SPACER}
+      }
+    end
+
+  end
+end

data/lib/mingle_link_fixer.rb

@@ -0,0 +1,70 @@
+require 'logger'
+
+require_relative 'mingle/logging'
+require_relative 'mingle/stats'
+require_relative 'mingle/http_client'
+require_relative 'mingle/api'
+require_relative 'mingle/card'
+require_relative 'mingle/historical_attachments'
+require_relative 'mingle/attachment_link_finder'
+
+module Mingle
+  class LinkFixer
+    include Logging
+
+    def initialize(options)
+      @http_client = HttpClient.new(options[:username], options[:password])
+      @http_client.base_url = options[:project_url].gsub('/projects/', '/api/v2/projects/')
+      @api = API.new(@http_client)
+      @historical_attachments = HistoricalAttachments.new(options[:historical_attachments_folder])
+      Card.api = Attachment.api = @api
+    end
+
+    def fix(options={})
+      stats = Stats.new
+      options = {dry_run: false, starting_card: '1'}.merge(options)
+      logger.info "running #{self.class} (dry_run: #{options[:dry_run]}, verbose_logging: #{VERBOSE})"
+      Card.all(starting_with: options[:starting_card], limit: options[:limit]).each do |card|
+        stats.total_cards_checked += 1
+        begin
+          if card.attachments.empty?
+            logger.debug "skipping Card ##{card.number} because it has no attachments."
+            stats.cards_without_attachments += 1
+            next
+          end
+          finder = AttachmentLinkFinder.new(card.description)
+
+          if finder.attachment_links.empty?
+            logger.info "no attachment links present"
+            stats.cards_without_links += 1
+            next
+          end
+
+          logger.info "fixing #{finder.attachment_links.size} links"
+
+          finder.attachment_links.each do |attachment_link|
+            attachment_link.rewrite!(card, @historical_attachments)
+          end
+
+          html_document = finder.card_description_document
+          card.description = html_document.to_html
+
+          if options[:dry_run]
+              logger.info("(skipped saving card because dry_run is enabled)")
+          else
+              card.save!
+              stats.cards_fixed += 1
+          end
+
+        rescue => e
+          logger.error "Unable to fix Card ##{card.number} because of error: #{e.message}"
+          stats.cards_with_problematic_links[card.number] = e.message
+          logger.debug e.backtrace.join("\n")
+        end
+      end
+
+      logger.info stats.to_pretty_string
+    end
+
+  end
+end

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification
+name: mingle-link-fixer
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Bill DePhillips
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-10-01 00:00:00.000000000 Z
+dependencies: []
+description: fixes inline attachment links when a project is relocated
+email:
+- bill.dephillips@gmail.com
+executables:
+- mingle-link-fixer
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/mingle_link_fixer.rb
+- lib/mingle/logging.rb
+- lib/mingle/http_client.rb
+- lib/mingle/api.rb
+- lib/mingle/attachment.rb
+- lib/mingle/historical_attachments.rb
+- lib/mingle/attachment_link.rb
+- lib/mingle/attachment_link_finder.rb
+- lib/mingle/card.rb
+- lib/mingle/stats.rb
+- LICENSE
+- README.md
+- bin/mingle-link-fixer
+homepage: https://github.com/thoughtworksstudios/mingle-link-fixer
+licenses:
+- Apache
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.14
+signing_key: 
+specification_version: 4
+summary: fixes attachment links if you relocate a project
+test_files: []