anki_generator 1.1.0 → 1.4.0

data/lib/anki_generator/anki_connect_client.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'json'
+require_relative 'card'
+require_relative 'errors'
+
+module AnkiGenerator
+  # Talks to AnkiConnect (https://foosoft.net/projects/anki-connect), the
+  # add-on that exposes a local HTTP API inside a running Anki. Pushes cards
+  # straight into a deck — no .apkg import step.
+  class AnkiConnectClient
+    DEFAULT_URL = 'http://localhost:8765'
+    MODEL_NAME = 'Basic'
+
+    attr_reader :base_url
+
+    def initialize(base_url: DEFAULT_URL)
+      @base_url = base_url
+    end
+
+    # Creates the deck if needed and adds the cards. Returns
+    # { added:, duplicate: } counts. Raises ApiError when Anki is unreachable
+    # or AnkiConnect reports a failure.
+    def push_deck(deck_name:, cards:)
+      ensure_deck(deck_name)
+
+      payload = Array(cards).map do |card|
+        {
+          deckName: deck_name,
+          modelName: MODEL_NAME,
+          fields: { Front: card.front, Back: card.back },
+          tags: card.tags,
+          options: { allowDuplicate: false }
+        }
+      end
+
+      response = invoke('addNotes', notes: payload)
+      { added: response.compact.length, duplicate: response.count(nil) }
+    end
+
+    def deck_names
+      invoke('deckNames')
+    end
+
+    def create_deck(name)
+      invoke('createDeck', deck: name)
+    end
+
+    # AnkiConnect answers every action with {result, error}.
+    def invoke(action, **params)
+      response = connection.post do |request|
+        request.body = { action:, version: 6, params: }.to_json
+      end
+
+      unless response.success?
+        raise ApiError,
+              "AnkiConnect error #{response.status}: #{response.body} (is Anki running with AnkiConnect?)"
+      end
+
+      body = response.body
+      raise ApiError, "AnkiConnect error: #{body['error']}" if body.is_a?(Hash) && body['error']
+
+      body.is_a?(Hash) ? body['result'] : body
+    rescue Faraday::ConnectionFailed => e
+      raise ApiError, "Cannot reach AnkiConnect at #{@base_url}: #{e.message}"
+    end
+
+    private
+
+    def ensure_deck(deck_name)
+      create_deck(deck_name) unless deck_names.include?(deck_name)
+    end
+
+    def connection
+      @connection ||= Faraday.new(url: @base_url) do |conn|
+        conn.request :json
+        conn.response :json
+        conn.adapter Faraday.default_adapter
+        conn.options.open_timeout = 5
+        conn.options.timeout = 60
+      end
+    end
+  end
+end

data/lib/anki_generator/apkg_schema.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module AnkiGenerator
+  # Static Anki 2.1 collection definitions: the SQLite schema and the default
+  # conf/deck/model JSON blobs that populate the col table. Extracted from
+  # ApkgWriter so the writer deals only in rows and the archive.
+  module ApkgSchema
+    MODEL_ID = 1_609_739_310_911
+    MODEL_NAME = 'AnkiGenerator'
+    CLOZE_MODEL_ID = 1_609_739_310_912
+    CLOZE_MODEL_NAME = 'AnkiGenerator Cloze'
+    DECK_ID = 1
+    SCHEMA_VERSION = 11
+
+    CARD_CSS = <<~CSS
+      .card {
+        font-family: arial;
+        font-size: 20px;
+        text-align: center;
+        color: black;
+        background-color: white;
+      }
+    CSS
+
+    SQL = <<~SQL
+      CREATE TABLE col (
+        id integer primary key,
+        crt integer not null,
+        mod integer not null,
+        scm integer not null,
+        ver integer not null,
+        dty integer not null,
+        usn integer not null,
+        ls integer not null,
+        conf text not null,
+        models text not null,
+        decks text not null,
+        dconf text not null,
+        tags text not null
+      );
+      CREATE TABLE notes (
+        id integer primary key,
+        guid text not null,
+        mid integer not null,
+        mod integer not null,
+        usn integer not null,
+        tags text not null,
+        flds text not null,
+        sfld integer not null,
+        csum integer not null,
+        flags integer not null,
+        data text not null
+      );
+      CREATE TABLE cards (
+        id integer primary key,
+        nid integer not null,
+        did integer not null,
+        ord integer not null,
+        mod integer not null,
+        usn integer not null,
+        type integer not null,
+        queue integer not null,
+        due integer not null,
+        ivl integer not null,
+        factor integer not null,
+        reps integer not null,
+        lapses integer not null,
+        left integer not null,
+        odue integer not null,
+        odid integer not null,
+        flags integer not null,
+        data text not null
+      );
+      CREATE INDEX ix_cards_nid ON cards (nid);
+      CREATE INDEX ix_notes_csum ON notes (csum);
+    SQL
+
+    module_function
+
+    def conf_json
+      JSON.generate(
+        'nextPos' => 1,
+        'estTimes' => true,
+        'activeDecks' => [DECK_ID],
+        'sortType' => 'noteFld',
+        'timeLim' => 0,
+        'sortBackwards' => false,
+        'addToCur' => true,
+        'curDeck' => DECK_ID,
+        'newBury' => true,
+        'newSpread' => 0,
+        'dueDisplay' => 0,
+        'collapseTime' => 1200,
+        'curModel' => MODEL_ID.to_s
+      )
+    end
+
+    def decks_json(deck_name:, now_seconds:)
+      JSON.generate(
+        DECK_ID.to_s => {
+          'id' => DECK_ID,
+          'mod' => now_seconds,
+          'name' => deck_name,
+          'usn' => -1,
+          'lnewToday' => [0, 0],
+          'lrnToday' => [0, 0],
+          'revToday' => [0, 0],
+          'timeToday' => [0, 0],
+          'newToday' => [0, 0],
+          'conf' => 1,
+          'collapsed' => false,
+          'dyn' => 0,
+          'extendNew' => 0,
+          'extendRev' => 0,
+          'browserCollapsed' => true,
+          'desc' => ''
+        }
+      )
+    end
+
+    def dconf_json
+      JSON.generate(
+        '1' => {
+          'id' => 1,
+          'mod' => 0,
+          'name' => 'Default',
+          'usn' => 0,
+          'maxTaken' => 60,
+          'timer' => 0,
+          'autoplay' => true,
+          'replayq' => true,
+          'dyn' => false,
+          'newMix' => 0,
+          'newPer' => 0,
+          'resched' => true,
+          'new' => {
+            'delays' => [1, 10],
+            'ints' => [1, 4, 7],
+            'initialFactor' => 2500,
+            'separate' => true,
+            'order' => 1,
+            'perDay' => 20,
+            'bury' => false
+          },
+          'lapse' => {
+            'delays' => [10],
+            'mult' => 0,
+            'minInt' => 1,
+            'leechFails' => 8,
+            'leechAction' => 0
+          },
+          'rev' => {
+            'perDay' => 200,
+            'ease4' => 1.3,
+            'fuzz' => 0.05,
+            'minSpace' => 1,
+            'ivlFct' => 1,
+            'maxIvl' => 36_500
+          }
+        }
+      )
+    end
+
+    def models_json(now_seconds:)
+      JSON.generate(
+        MODEL_ID.to_s => basic_model(now_seconds),
+        CLOZE_MODEL_ID.to_s => cloze_model(now_seconds)
+      )
+    end
+
+    def basic_model(now_seconds)
+      {
+        'id' => MODEL_ID,
+        'name' => MODEL_NAME,
+        'mod' => now_seconds,
+        'usn' => -1,
+        'sortf' => 0,
+        'type' => 0,
+        'css' => CARD_CSS,
+        'tags' => [],
+        'flds' => [field('Front', 0), field('Back', 1)],
+        'tmpls' => [template],
+        'latexPre' => latex_pre,
+        'latexPost' => '\\end{document}',
+        'req' => [[0, 'any', [0]]]
+      }
+    end
+
+    def cloze_model(now_seconds)
+      {
+        'id' => CLOZE_MODEL_ID,
+        'name' => CLOZE_MODEL_NAME,
+        'mod' => now_seconds,
+        'usn' => -1,
+        'sortf' => 0,
+        'type' => 1,
+        'css' => CARD_CSS,
+        'tags' => [],
+        'flds' => [field('Text', 0)],
+        'tmpls' => [cloze_template],
+        'latexPre' => latex_pre,
+        'latexPost' => '\\end{document}',
+        'req' => [[0, 'all', [0]]]
+      }
+    end
+
+    def field(name, ord)
+      {
+        'name' => name,
+        'ord' => ord,
+        'sticky' => false,
+        'rtl' => false,
+        'font' => 'Arial',
+        'size' => 20,
+        'media' => []
+      }
+    end
+
+    def template
+      {
+        'name' => 'Card 1',
+        'ord' => 0,
+        'qfmt' => '{{Front}}',
+        'afmt' => "{{FrontSide}}\n\n<hr id=answer>\n\n{{Back}}",
+        'did' => nil,
+        'bqfmt' => '',
+        'bafmt' => ''
+      }
+    end
+
+    def cloze_template
+      {
+        'name' => 'Cloze',
+        'ord' => 0,
+        'qfmt' => '{{cloze:Text}}',
+        'afmt' => '{{cloze:Text}}',
+        'did' => nil,
+        'bqfmt' => '',
+        'bafmt' => ''
+      }
+    end
+
+    def latex_pre
+      <<~LATEX
+        \\documentclass[12pt]{article}
+        \\special{papersize=3in,5in}
+        \\usepackage[utf8]{inputenc}
+        \\usepackage{amssymb,amsmath}
+        \\pagestyle{empty}
+        \\setlength{\\parindent}{0in}
+        \\begin{document}
+      LATEX
+    end
+  end
+end

data/lib/anki_generator/apkg_writer.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'fileutils'
+require 'securerandom'
+require 'sqlite3'
+require 'tmpdir'
+require 'zip'
+require_relative 'apkg_schema'
+
+module AnkiGenerator
+  # Builds a valid Anki 2.1 .apkg file: a zip archive containing a SQLite
+  # collection database. Replaces the unmaintained `anki2` gem and gives us
+  # full control over the generated schema (see ApkgSchema for the definition).
+  class ApkgWriter
+    CardEntry = Struct.new(:front, :back, :tags, :cloze)
+
+    def initialize(name:, output_path:)
+      @name = name
+      @output_path = output_path
+      @cards = []
+      # Note and card ids must each be unique within their own table; simple
+      # monotonic sequences starting at the current millisecond timestamp work
+      # fine and keep cloze expansions collision-free.
+      @note_seq = (Time.now.to_f * 1000).to_i
+      @card_seq = @note_seq
+    end
+
+    # A basic card is a front/back pair; pass `cloze:` instead for an Anki
+    # cloze note (a single text with {{cN::...}} deletions). One card row is
+    # emitted per distinct cloze ordinal.
+    def add_card(front, back, tags: [], cloze: nil)
+      @cards << CardEntry.new(front.to_s, back.to_s, Array(tags).map(&:to_s), cloze&.to_s)
+    end
+
+    def save
+      Dir.mktmpdir('anki_generator') do |dir|
+        db_path = File.join(dir, 'collection.anki2')
+        build_database(db_path)
+        write_archive(db_path, File.join(dir, 'media'))
+      end
+      @output_path
+    end
+
+    private
+
+    def build_database(db_path)
+      SQLite3::Database.new(db_path) do |db|
+        # The insert helpers below all operate on this connection, which lives
+        # only for the duration of `save`; keeping it in an ivar keeps every
+        # insert signature at a readable arity.
+        @db = db
+        db.execute_batch(ApkgSchema::SQL)
+        insert_collection
+        @cards.each_with_index { |card, index| insert_note(card, index) }
+      end
+    end
+
+    def insert_collection
+      @db.execute(
+        'INSERT INTO col (id, crt, mod, scm, ver, dty, usn, ls, conf, models, decks, dconf, tags) ' \
+        'VALUES (1, ?, ?, ?, ?, 0, 0, 0, ?, ?, ?, ?, ?)',
+        [now_seconds, now_millis, now_millis, ApkgSchema::SCHEMA_VERSION,
+         ApkgSchema.conf_json,
+         ApkgSchema.models_json(now_seconds:),
+         ApkgSchema.decks_json(deck_name: @name, now_seconds:),
+         ApkgSchema.dconf_json, '{}']
+      )
+    end
+
+    def insert_note(card, index)
+      if card.cloze && !card.cloze.empty?
+        insert_cloze_note(card, index)
+      else
+        insert_basic_note(card, index)
+      end
+    end
+
+    def insert_basic_note(card, index)
+      note_id = next_note_id
+      fields = "#{card.front}\x1F#{card.back}"
+
+      insert_note_row(note_id, ApkgSchema::MODEL_ID, fields, card.front, card.tags)
+      insert_card_row(next_card_id, note_id, ord: 0, due: index)
+    end
+
+    def insert_cloze_note(card, index)
+      note_id = next_note_id
+      ords = cloze_ords(card.cloze)
+
+      insert_note_row(note_id, ApkgSchema::CLOZE_MODEL_ID, card.cloze, plain_text(card.cloze), card.tags)
+      ords.each_with_index do |ord, offset|
+        insert_card_row(next_card_id, note_id, ord:, due: index + offset)
+      end
+    end
+
+    def insert_note_row(note_id, model_id, fields, sort_field, tags)
+      checksum = Digest::SHA1.hexdigest(sort_field)[0, 8].to_i(16)
+
+      @db.execute(
+        'INSERT INTO notes (id, guid, mid, mod, usn, tags, flds, sfld, csum, flags, data) ' \
+        'VALUES (?, ?, ?, ?, -1, ?, ?, ?, ?, 0, ?)',
+        [note_id, SecureRandom.alphanumeric(10), model_id, now_seconds, tags.join(' '), fields, sort_field,
+         checksum, '']
+      )
+    end
+
+    def insert_card_row(card_id, note_id, ord:, due:)
+      @db.execute(
+        'INSERT INTO cards (id, nid, did, ord, mod, usn, type, queue, due, ivl, factor, reps, lapses, ' \
+        'left, odue, odid, flags, data) VALUES (?, ?, ?, ?, ?, -1, 0, 0, ?, 0, 0, 0, 0, 0, 0, 0, 0, ?)',
+        [card_id, note_id, ApkgSchema::DECK_ID, ord, now_seconds, due, '']
+      )
+    end
+
+    # Distinct 1-based cloze ordinals, e.g. "{{c1::a}} {{c2::b}}" → [0, 1]
+    # (card ord is zero-based; ordinal 1 → ord 0).
+    def cloze_ords(cloze_text)
+      cloze_text.scan(/\{\{c(\d+)::/).flatten.map(&:to_i).uniq.sort.map { |n| n - 1 }
+    end
+
+    def plain_text(cloze_text)
+      cloze_text.gsub(/\{\{c\d+::(.+?)\}\}/, '\1').gsub(/\{\{.+?\}\}/, '').strip
+    end
+
+    def next_note_id
+      @note_seq += 1
+    end
+
+    def next_card_id
+      @card_seq += 1
+    end
+
+    def write_archive(db_path, media_path)
+      File.write(media_path, '{}')
+      # Re-saving over an existing .apkg must replace it, not append duplicate
+      # zip entries.
+      FileUtils.rm_f(@output_path)
+
+      Zip::File.open(@output_path, Zip::File::CREATE) do |zip|
+        zip.add('collection.anki2', db_path)
+        zip.add('media', media_path)
+      end
+    end
+
+    def now_seconds = Time.now.to_i
+    def now_millis = (Time.now.to_f * 1000).to_i
+  end
+end

data/lib/anki_generator/card.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require_relative 'errors'
+
+module AnkiGenerator
+  # A single flashcard. Cards are value objects: immutable and compared by content.
+  #
+  # Two card types are supported:
+  # - basic: a front/back question-answer pair
+  # - cloze: a single sentence with {{cN::hidden text}} deletions (Anki cloze)
+  class Card
+    CLOZE_PATTERN = /\{\{c\d+::.+?\}\}/
+
+    attr_reader :front, :back, :tags
+
+    def initialize(front: nil, back: nil, tags: [], cloze: nil)
+      @tags = Array(tags).map { |tag| tag.to_s.strip }.reject(&:empty?)
+      @cloze = cloze&.to_s&.strip
+
+      if cloze?
+        @front = @cloze
+        @back = ''
+        validate_cloze!
+      else
+        @front = front.to_s.strip
+        @back = back.to_s.strip
+        validate!
+      end
+    end
+
+    def cloze?
+      !@cloze.nil? && !@cloze.empty?
+    end
+
+    # The distinct cloze ordinals (1-based) used by this card, e.g. [1, 2].
+    def cloze_indices
+      @cloze.to_s.scan(/\{\{c(\d+)::/).flatten.map(&:to_i).uniq.sort
+    end
+
+    # Plain-text version of the cloze text (markers stripped) — used for the
+    # note's sort field.
+    def plain_text
+      @cloze.to_s.gsub(/\{\{c\d+::(.+?)\}\}/, '\1').gsub(/\{\{.+?\}\}/, '').strip
+    end
+
+    def reversed
+      raise ValidationError, 'Cloze cards cannot be reversed' if cloze?
+
+      Card.new(front: back, back: front, tags:)
+    end
+
+    def to_h
+      hash = { 'front' => front, 'back' => back }
+      hash['tags'] = tags unless tags.empty?
+      hash['cloze'] = @cloze if cloze?
+      hash
+    end
+
+    def ==(other)
+      other.is_a?(Card) && front == other.front && back == other.back &&
+        tags == other.tags && @cloze == other.instance_variable_get(:@cloze)
+    end
+    alias eql? ==
+
+    def hash
+      [front, back, tags, @cloze].hash
+    end
+
+    private
+
+    def validate!
+      raise ValidationError, 'Flashcard front cannot be empty' if front.empty?
+      raise ValidationError, 'Flashcard back cannot be empty' if back.empty?
+    end
+
+    def validate_cloze!
+      raise ValidationError, 'Cloze text cannot be empty' if @cloze.empty?
+      return if CLOZE_PATTERN.match?(@cloze)
+
+      raise ValidationError, "Cloze text must contain at least one {{cN::...}} deletion, got: #{@cloze}"
+    end
+  end
+end