moku6 0.1.0

data/lib/moku6/generators/bigquery_generator.rb

@@ -0,0 +1,29 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Moku6
+  module Generators
+    # Emits BigQuery DDL for the shared envelope (design section 12.5).
+    # Fields live in the `metadata JSON` column, consistent with section 8.
+    class BigQueryGenerator < BaseGenerator
+      #: () -> String
+      def render
+        <<~SQL
+          -- #{AUTOGEN_NOTE}
+          CREATE TABLE audit_events (
+            event_id    STRING    NOT NULL,
+            action      STRING    NOT NULL,
+            occurred_at TIMESTAMP NOT NULL,
+            actor       JSON,
+            target      JSON,
+            metadata    JSON,
+            privacy     JSON,
+            created_at  TIMESTAMP NOT NULL
+          )
+          PARTITION BY DATE(occurred_at)
+          CLUSTER BY action;
+        SQL
+      end
+    end
+  end
+end

data/lib/moku6/generators/cloud_events_generator.rb

@@ -0,0 +1,47 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+
+module Moku6
+  module Generators
+    # Emits a CloudEvents (v1.0, structured JSON mode) validation JSON Schema per
+    # action. The CloudEvents `type` maps to the action and `data` carries the
+    # definition's metadata (design section 13: CloudEvents conversion).
+    class CloudEventsGenerator < BaseGenerator
+      SPEC_VERSION = "1.0" #: String
+
+      #: (String dir) -> String
+      def write(dir)
+        FileUtils.mkdir_p(dir)
+        @catalog.sorted.each do |e|
+          File.write(File.join(dir, "#{e.action}.json"),
+            JSON.pretty_generate(schema_for(e)) + "\n")
+        end
+        dir
+      end
+
+      private
+
+      def schema_for(e)
+        {
+          "$schema" => "https://json-schema.org/draft/2020-12/schema",
+          "title" => "#{e.action} (CloudEvents)",
+          "type" => "object",
+          "required" => %w[specversion id source type data],
+          "properties" => {
+            "specversion" => {"const" => SPEC_VERSION},
+            "id" => {"type" => "string"},
+            "source" => {"type" => "string"},
+            "type" => {"const" => e.action},
+            "subject" => {"type" => "string"},
+            "time" => {"type" => "string", "format" => "date-time"},
+            "datacontenttype" => {"const" => "application/json"},
+            "data" => EnvelopeSchema.metadata_schema(e)
+          }
+        }
+      end
+    end
+  end
+end

data/lib/moku6/generators/docs_generator.rb

@@ -0,0 +1,49 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Moku6
+  module Generators
+    class DocsGenerator < BaseGenerator
+      #: () -> String
+      def render
+        lines = ["# Audit Events", "", summary_table, ""]
+        @catalog.sorted.each { |e| lines.concat(detail(e)) }
+        lines.join("\n")
+      end
+
+      private
+
+      def summary_table
+        rows = @catalog.sorted.map do |e|
+          [
+            "`#{e.action}`", e.label,
+            yn(e.required?),
+            yn(e.visibility&.dig("customer_visible")),
+            (e.privacy&.dig("contains_personal_data") ? "Yes" : "No"),
+            "#{e.retention&.dig("years")} years"
+          ]
+        end
+        header = "| Event | Label | Required | Customer visible | Personal data | Retention |"
+        sep = "|---|---|---|---|---|---|"
+        ([header, sep] + rows.map { |r| "| #{r.join(" | ")} |" }).join("\n")
+      end
+
+      def detail(e)
+        out = ["## #{e.action} — #{e.label}", "", e.description.to_s, ""]
+        unless e.fields.empty?
+          out << "| Field | Type | Required | Description |"
+          out << "|---|---|---|---|"
+          e.fields.each do |name, f|
+            out << "| #{name} | #{f["type"]} | #{yn(f["required"])} | #{f["description"]} |"
+          end
+          out << ""
+        end
+        out
+      end
+
+      def yn(v) = v ? "Yes" : "No"
+    end
+  end
+end

data/lib/moku6/generators/event_catalog_generator.rb

@@ -0,0 +1,57 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Moku6
+  module Generators
+    # Emits EventCatalog (eventcatalog.dev) compatible event documents, one per
+    # action at <action>/index.md (design section 13: EventCatalog integration).
+    class EventCatalogGenerator < BaseGenerator
+      #: (String dir) -> String
+      def write(dir)
+        FileUtils.mkdir_p(dir)
+        @catalog.sorted.each do |e|
+          event_dir = File.join(dir, e.action.to_s)
+          FileUtils.mkdir_p(event_dir)
+          File.write(File.join(event_dir, "index.md"), document(e))
+        end
+        dir
+      end
+
+      private
+
+      def document(e)
+        out = []
+        out << "---"
+        out << "id: #{e.action}"
+        out << "name: #{e.label}"
+        out << "version: #{Moku6::VERSION}"
+        out << "summary: #{e.description.to_s.inspect}"
+        out << "badges:"
+        out << "  - content: #{e.category}"
+        out << "    textColor: blue"
+        out << "    backgroundColor: blue"
+        out << "---"
+        out << ""
+        out << "<!-- #{AUTOGEN_NOTE} -->"
+        out << ""
+        out << "## Overview"
+        out << ""
+        out << e.description.to_s
+        out << ""
+        unless e.fields.empty?
+          out << "## Schema"
+          out << ""
+          out << "| Field | Type | Required | Description |"
+          out << "|---|---|---|---|"
+          e.fields.each do |name, f|
+            out << "| #{name} | #{f["type"]} | #{f["required"] ? "Yes" : "No"} | #{f["description"]} |"
+          end
+          out << ""
+        end
+        out.join("\n")
+      end
+    end
+  end
+end

data/lib/moku6/generators/example_generator.rb

@@ -0,0 +1,66 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+
+module Moku6
+  module Generators
+    # Generates a minimal sample event (envelope) satisfying required fields per definition.
+    class ExampleGenerator < BaseGenerator
+      #: (String dir) -> String
+      def write(dir)
+        FileUtils.mkdir_p(dir)
+        @catalog.sorted.each do |e|
+          File.write(File.join(dir, "#{e.action}.json"),
+            JSON.pretty_generate(example_for(e)) + "\n")
+        end
+        dir
+      end
+
+      private
+
+      def example_for(e)
+        {
+          "event_id" => "00000000-0000-0000-0000-000000000000",
+          "action" => e.action,
+          "occurred_at" => "2026-01-01T00:00:00Z",
+          "actor" => actor_sample(e),
+          "target" => target_sample(e),
+          "metadata" => metadata_sample(e),
+          "privacy" => {"masked_fields" => e.privacy&.dig("masked_fields") || []},
+          "created_at" => "2026-01-01T00:00:00Z"
+        }
+      end
+
+      def actor_sample(e)
+        type = (e.actor.is_a?(Hash) && e.actor["type"]) || "user"
+        {"type" => type, "id" => "actor_1"}
+      end
+
+      def target_sample(e)
+        type = (e.target.is_a?(Hash) && e.target["type"]) || "target"
+        {"type" => type, "id" => "target_1"}
+      end
+
+      def metadata_sample(e)
+        e.fields.each_with_object({}) do |(name, f), h|
+          next unless f["required"]
+
+          h[name] = sample_value(f["type"])
+        end
+      end
+
+      def sample_value(type)
+        case type
+        when "integer", "number" then 0
+        when "boolean" then false
+        when "array" then []
+        when "object" then {}
+        when "timestamp" then "2026-01-01T00:00:00Z"
+        else "example"
+        end
+      end
+    end
+  end
+end

data/lib/moku6/generators/json_schema_generator.rb

@@ -0,0 +1,23 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+
+module Moku6
+  module Generators
+    # Emits a runtime event (envelope) validation JSON Schema per action.
+    # write(dir) takes a directory and writes multiple files.
+    class JsonSchemaGenerator < BaseGenerator
+      #: (String dir) -> String
+      def write(dir)
+        FileUtils.mkdir_p(dir)
+        @catalog.sorted.each do |e|
+          File.write(File.join(dir, "#{e.action}.json"),
+            JSON.pretty_generate(EnvelopeSchema.for(e)) + "\n")
+        end
+        dir
+      end
+    end
+  end
+end

data/lib/moku6/generators/open_api_generator.rb

@@ -0,0 +1,60 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+require "yaml"
+
+module Moku6
+  module Generators
+    # Emits a single OpenAPI 3.1 document describing audit events as webhooks,
+    # with one component schema per action (design section 13: OpenAPI output).
+    class OpenApiGenerator < BaseGenerator
+      #: () -> String
+      def render
+        "# #{AUTOGEN_NOTE}\n" + YAML.dump(document)
+      end
+
+      private
+
+      def document
+        {
+          "openapi" => "3.1.0",
+          "info" => {
+            "title" => "Audit Events",
+            "version" => Moku6::VERSION,
+            "description" => "Audit event webhooks generated by moku6."
+          },
+          "webhooks" => webhooks,
+          "components" => {"schemas" => schemas}
+        }
+      end
+
+      def webhooks
+        @catalog.sorted.each_with_object({}) do |e, h|
+          h[e.action] = {
+            "post" => {
+              "summary" => e.label.to_s,
+              "description" => e.description.to_s,
+              "requestBody" => {
+                "required" => true,
+                "content" => {
+                  "application/json" => {
+                    "schema" => {"$ref" => "#/components/schemas/#{e.action}"}
+                  }
+                }
+              },
+              "responses" => {"200" => {"description" => "Event accepted"}}
+            }
+          }
+        end
+      end
+
+      def schemas
+        @catalog.sorted.each_with_object({}) do |e, h|
+          schema = EnvelopeSchema.for(e)
+          schema.delete("$schema")
+          h[e.action] = schema
+        end
+      end
+    end
+  end
+end

data/lib/moku6/generators/outbox_generator.rb

@@ -0,0 +1,96 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Moku6
+  module Generators
+    # Emits a sample Rails transactional outbox for audit events: a migration,
+    # an ActiveRecord model, and a dispatcher (design section 13: Outbox sample).
+    # The files are a starting point and are meant to be edited.
+    class OutboxGenerator < BaseGenerator
+      FILES = {
+        "db/migrate/0001_create_audit_event_outbox.rb" => :migration,
+        "app/models/audit_event_outbox.rb" => :model,
+        "app/services/audit_event_dispatcher.rb" => :dispatcher
+      }.freeze #: Hash[String, Symbol]
+
+      #: (String dir) -> String
+      def write(dir)
+        FILES.each do |rel, kind|
+          path = File.join(dir, rel)
+          FileUtils.mkdir_p(File.dirname(path))
+          File.write(path, send(kind))
+        end
+        dir
+      end
+
+      private
+
+      def migration
+        <<~RUBY
+          # #{AUTOGEN_NOTE}
+          class CreateAuditEventOutbox < ActiveRecord::Migration[7.1]
+            def change
+              create_table :audit_event_outbox do |t|
+                t.string :event_id, null: false
+                t.string :action, null: false
+                t.jsonb :payload, null: false
+                t.datetime :occurred_at, null: false
+                t.datetime :dispatched_at
+                t.timestamps
+              end
+
+              add_index :audit_event_outbox, :event_id, unique: true
+              add_index :audit_event_outbox, :dispatched_at
+            end
+          end
+        RUBY
+      end
+
+      def model
+        <<~RUBY
+          # frozen_string_literal: true
+          # #{AUTOGEN_NOTE}
+          class AuditEventOutbox < ApplicationRecord
+            self.table_name = "audit_event_outbox"
+
+            scope :pending, -> { where(dispatched_at: nil) }
+
+            # Wire this as the AuditEvents sink:
+            #   AuditEvents.sink = ->(event) { AuditEventOutbox.enqueue(event) }
+            def self.enqueue(event)
+              create!(
+                event_id: event.fetch("event_id"),
+                action: event.fetch("action"),
+                payload: event,
+                occurred_at: event.fetch("occurred_at")
+              )
+            end
+          end
+        RUBY
+      end
+
+      def dispatcher
+        <<~RUBY
+          # frozen_string_literal: true
+          # #{AUTOGEN_NOTE}
+          # Drains the outbox and forwards each event to a delivery backend
+          # (HTTP endpoint, Pub/Sub, Kafka, BigQuery, ...). Run it periodically.
+          class AuditEventDispatcher
+            def initialize(delivery:)
+              @delivery = delivery
+            end
+
+            def run(batch_size: 100)
+              AuditEventOutbox.pending.order(:id).limit(batch_size).each do |record|
+                @delivery.call(record.payload)
+                record.update!(dispatched_at: Time.current)
+              end
+            end
+          end
+        RUBY
+      end
+    end
+  end
+end

data/lib/moku6/generators/rails_generator.rb

@@ -0,0 +1,84 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Moku6
+  module Generators
+    # Emits a Ruby SDK with one typed emitter method per action. Each method
+    # builds the canonical envelope and hands it to a configurable sink, so a
+    # Rails app can wire it to an outbox (design section 13: Rails SDK).
+    class RailsGenerator < BaseGenerator
+      #: () -> String
+      def render
+        out = ["# frozen_string_literal: true", "# #{AUTOGEN_NOTE}", ""]
+        out << 'require "securerandom"'
+        out << 'require "time"'
+        out << ""
+        out << "module AuditEvents"
+        out.concat(sink_block)
+        out << ""
+        out << "  module Emitter"
+        out << "    module_function"
+        @catalog.sorted.each do |e|
+          out << ""
+          out.concat(emitter_method(e))
+        end
+        out << "  end"
+        out << "end"
+        out << ""
+        out.join("\n")
+      end
+
+      private
+
+      def sink_block
+        [
+          "  # Assign AuditEvents.sink to an object responding to #call(event_hash),",
+          "  # e.g. an outbox writer. Defaults to returning the event unchanged.",
+          "  class << self",
+          "    attr_writer :sink",
+          "",
+          "    def sink",
+          "      @sink ||= ->(event) { event }",
+          "    end",
+          "  end"
+        ]
+      end
+
+      def emitter_method(e)
+        required = e.fields.select { |_, f| f["required"] }.keys
+        optional = e.fields.reject { |_, f| f["required"] }.keys
+        params = ["actor:", "target:"]
+        params.concat(required.map { |k| "#{k}:" })
+        params.concat(optional.map { |k| "#{k}: nil" })
+        params << "occurred_at: Time.now.utc"
+
+        lines = ["    def #{method_name(e)}(#{params.join(", ")})"]
+        lines << "      metadata = {#{required.map { |k| "#{k.inspect} => #{k}" }.join(", ")}}"
+        optional.each do |k|
+          lines << "      metadata[#{k.inspect}] = #{k} unless #{k}.nil?"
+        end
+        lines << "      event = {"
+        lines << '        "event_id" => SecureRandom.uuid,'
+        lines << "        \"action\" => #{e.action.inspect},"
+        lines << '        "occurred_at" => occurred_at.iso8601,'
+        lines << '        "actor" => actor,'
+        lines << '        "target" => target,'
+        lines << '        "metadata" => metadata,'
+        lines << "        \"privacy\" => {\"masked_fields\" => #{masked_fields(e).inspect}},"
+        lines << '        "created_at" => Time.now.utc.iso8601'
+        lines << "      }"
+        lines << "      AuditEvents.sink.call(event)"
+        lines << "    end"
+        lines
+      end
+
+      def method_name(e)
+        e.action.split(/[._]/).join("_")
+      end
+
+      def masked_fields(e)
+        (e.privacy.is_a?(Hash) && e.privacy["masked_fields"]) || []
+      end
+    end
+  end
+end

data/lib/moku6/generators/ruby_generator.rb

@@ -0,0 +1,27 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Moku6
+  module Generators
+    # Emits Ruby constants for every action (design section 12.4).
+    class RubyGenerator < BaseGenerator
+      #: () -> String
+      def render
+        consts = @catalog.sorted.map { |e| [const_name(e), e.action] }
+        out = ["# frozen_string_literal: true", "# #{AUTOGEN_NOTE}", "module AuditEvents"]
+        consts.each { |name, action| out << "  #{name} = #{action.inspect}" }
+        out << ""
+        out << "  ALL = [#{consts.map(&:first).join(", ")}].freeze"
+        out << "end"
+        out << ""
+        out.join("\n")
+      end
+
+      private
+
+      def const_name(e)
+        e.action.split(/[._]/).join("_").upcase
+      end
+    end
+  end
+end

data/lib/moku6/generators/typescript_generator.rb

@@ -0,0 +1,59 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Moku6
+  module Generators
+    class TypeScriptGenerator < BaseGenerator
+      #: () -> String
+      def render
+        events = @catalog.sorted
+        out = ["// #{AUTOGEN_NOTE}", ""]
+        out.concat(union_type(events))
+        out << ""
+        events.each { |e| out.concat(interface(e)) }
+        out << "export interface AuditEventMetadataMap {"
+        events.each { |e| out << "  \"#{e.action}\": #{iface_name(e)};" }
+        out << "}"
+        out << ""
+        out.join("\n")
+      end
+
+      private
+
+      def union_type(events)
+        return ["export type AuditAction = never;"] if events.empty?
+
+        lines = ["export type AuditAction ="]
+        events.each_with_index do |e, i|
+          suffix = (i == events.size - 1) ? ";" : ""
+          lines << "  | \"#{e.action}\"#{suffix}"
+        end
+        lines
+      end
+
+      def interface(e)
+        lines = ["export interface #{iface_name(e)} {"]
+        e.fields.each do |name, f|
+          opt = f["required"] ? "" : "?"
+          lines << "  #{name}#{opt}: #{ts(f)};"
+        end
+        lines << "}" << ""
+        lines
+      end
+
+      def iface_name(e)
+        e.action.split(/[._]/).map(&:capitalize).join + "Metadata"
+      end
+
+      def ts(f)
+        case f["type"]
+        when "integer", "number" then "number"
+        when "boolean" then "boolean"
+        when "array" then "unknown[]"
+        when "object" then "Record<string, unknown>"
+        else "string"
+        end
+      end
+    end
+  end
+end

data/lib/moku6/generators.rb

@@ -0,0 +1,29 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Moku6
+  module Generators
+    REGISTRY = {
+      docs: DocsGenerator,
+      json_schema: JsonSchemaGenerator,
+      typescript: TypeScriptGenerator,
+      ruby: RubyGenerator,
+      bigquery: BigQueryGenerator,
+      cloudevents: CloudEventsGenerator,
+      eventcatalog: EventCatalogGenerator,
+      openapi: OpenApiGenerator,
+      rails: RailsGenerator,
+      outbox: OutboxGenerator,
+      example: ExampleGenerator
+    } #: Hash[Symbol, untyped]
+
+    #: (String | Symbol name, untyped klass) -> untyped
+    def self.register(name, klass) = REGISTRY[name.to_sym] = klass
+
+    #: (String | Symbol name, Catalog catalog, Config config) -> untyped
+    def self.build(name, catalog, config)
+      klass = REGISTRY.fetch(name.to_sym) { raise UsageError, "unknown generator: #{name}" }
+      klass.new(catalog, config)
+    end
+  end
+end

data/lib/moku6/initializer.rb

@@ -0,0 +1,44 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Moku6
+  # Backs `moku6 init`. Copies templates/init into ./ (never overwrites existing files).
+  class Initializer
+    TEMPLATE_DIR = File.expand_path("../../templates/init", __dir__.to_s) #: String
+
+    # @rbs @options: Hash[Symbol, untyped]
+    # @rbs @dest_root: String
+
+    #: (?Hash[Symbol, untyped] options) -> void
+    def initialize(options = {})
+      @options = options
+      @dest_root = Dir.pwd
+    end
+
+    #: () -> void
+    def run
+      entries.each do |src|
+        rel = src.delete_prefix("#{TEMPLATE_DIR}/")
+        dest = File.join(@dest_root, rel)
+        if File.exist?(dest)
+          puts "skip (exists): #{rel}"
+          next
+        end
+        FileUtils.mkdir_p(File.dirname(dest))
+        FileUtils.cp(src, dest)
+        puts "create: #{rel}"
+      end
+    end
+
+    private
+
+    #: () -> Array[String]
+    def entries
+      Dir.glob(File.join(TEMPLATE_DIR, "**", "*"), File::FNM_DOTMATCH)
+        .reject { |p| File.directory?(p) }
+        .sort
+    end
+  end
+end