magik 0.0.1

data/lib/magik/auth.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Magik
+  # Generated authentication flows, Rodauth-backed.
+  #
+  # Implements: **Phase 7 — Auth, Billing, Admin** of `docs/idea/00-build-spec.md`.
+  #
+  # Planned DSL surface, copied from the spec:
+  #
+  #   * `auth do strategy; oauth_providers; two_factor end`
+  #
+  # Status: **Not implemented — spec only.** Every entry point below raises
+  # {NotImplementedError}. Nothing here reads config, touches a database or
+  # emits a byte of HTML.
+  #
+  # @see Magik::SUBSYSTEMS
+  module Auth
+    # The build-spec phase this subsystem implements.
+    # @return [String]
+    SPEC_PHASE = "Phase 7 — Auth, Billing, Admin"
+
+    # The DSL this subsystem will expose, verbatim from the spec.
+    # @return [Array<String>]
+    DSL_SURFACE = [
+      "auth do strategy; oauth_providers; two_factor end"
+    ].freeze
+
+    # Implementation status of this subsystem.
+    # @return [String]
+    STATUS = "Not implemented — spec only"
+
+    # Entry point for the Auth DSL.
+    #
+    # @param _args [Array] ignored
+    # @param _options [Hash] ignored
+    # @return [void] never returns
+    # @raise [NotImplementedError] always, until Phase 7 lands
+    def self.define(*_args, **_options)
+      raise NotImplementedError, "Magik::Auth is spec-only; see docs/idea/00-build-spec.md"
+    end
+  end
+end

data/lib/magik/billing.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Magik
+  # Subscriptions, trials and metered billing over the Stripe/Paddle SDKs.
+  #
+  # Implements: **Phase 7 — Auth, Billing, Admin** of `docs/idea/00-build-spec.md`.
+  #
+  # Planned DSL surface, copied from the spec:
+  #
+  #   * `billing provider: :stripe do plans end`
+  #
+  # Status: **Not implemented — spec only.** Every entry point below raises
+  # {NotImplementedError}. Nothing here reads config, touches a database or
+  # emits a byte of HTML.
+  #
+  # @see Magik::SUBSYSTEMS
+  module Billing
+    # The build-spec phase this subsystem implements.
+    # @return [String]
+    SPEC_PHASE = "Phase 7 — Auth, Billing, Admin"
+
+    # The DSL this subsystem will expose, verbatim from the spec.
+    # @return [Array<String>]
+    DSL_SURFACE = [
+      "billing provider: :stripe do plans end"
+    ].freeze
+
+    # Implementation status of this subsystem.
+    # @return [String]
+    STATUS = "Not implemented — spec only"
+
+    # Entry point for the Billing DSL.
+    #
+    # @param _args [Array] ignored
+    # @param _options [Hash] ignored
+    # @return [void] never returns
+    # @raise [NotImplementedError] always, until Phase 7 lands
+    def self.define(*_args, **_options)
+      raise NotImplementedError, "Magik::Billing is spec-only; see docs/idea/00-build-spec.md"
+    end
+  end
+end

data/lib/magik/check.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Magik
+  # The guardrail linter. The guardrails are the product: ledgers must balance, `field
+  # :card_number` is refused, domain boundaries hold, screens and actions hold no
+  # in-process state, timestamps carry a timezone.
+  #
+  # Implements: **Build order step 12 — `magik check` linter** of `docs/idea/00-build-spec.md`.
+  #
+  # Planned DSL surface, copied from the spec:
+  #
+  #   * `magik check --scale — warns on queries missing tenant_id in WHERE`
+  #   * `boot guardrails enforced as a standalone lint pass`
+  #
+  # Status: **Not implemented — spec only.** Every entry point below raises
+  # {NotImplementedError}. Nothing here reads config, touches a database or
+  # emits a byte of HTML.
+  #
+  # @see Magik::SUBSYSTEMS
+  module Check
+    # The build-spec phase this subsystem implements.
+    # @return [String]
+    SPEC_PHASE = "Build order step 12 — `magik check` linter"
+
+    # The DSL this subsystem will expose, verbatim from the spec.
+    # @return [Array<String>]
+    DSL_SURFACE = [
+      "magik check --scale — warns on queries missing tenant_id in WHERE",
+      "boot guardrails enforced as a standalone lint pass"
+    ].freeze
+
+    # Implementation status of this subsystem.
+    # @return [String]
+    STATUS = "Not implemented — spec only"
+
+    # Entry point for the Check DSL.
+    #
+    # @param _args [Array] ignored
+    # @param _options [Hash] ignored
+    # @return [void] never returns
+    # @raise [NotImplementedError] always, until Build order step 12 lands
+    def self.define(*_args, **_options)
+      raise NotImplementedError, "Magik::Check is spec-only; see docs/idea/00-build-spec.md"
+    end
+  end
+end

data/lib/magik/cli.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+
+module Magik
+  # The `magik` command line.
+  #
+  # Two commands work today — {version} and {help}. Every other command named
+  # in `docs/idea/00-build-spec.md` is listed by `magik help` with status
+  # `planned` and exits non-zero with `MAGIK_COMMAND_NOT_IMPLEMENTED` if you
+  # run it. That is deliberate: the CLI tells you the truth about what exists.
+  #
+  # Both working commands support `--json`, so scripts and CI can consume the
+  # output without parsing prose. Errors are emitted as JSON too when `--json`
+  # is set, using {Magik::Error#to_h}.
+  #
+  # Implemented with the stdlib `OptionParser`; Magik takes no third-party CLI
+  # dependency.
+  #
+  # @example Human output
+  #   $ magik version
+  #   magik 0.0.1 (spec only)
+  # @example Machine output
+  #   $ magik version --json
+  #   {"name":"magik","version":"0.0.1","status":"spec only",...}
+  module CLI
+    # Exit status for a command that did what it said.
+    # @return [Integer]
+    EXIT_SUCCESS = 0
+
+    # Exit status for any {Magik::Error} — unknown command, planned command,
+    # bad option.
+    # @return [Integer]
+    EXIT_ERROR = 1
+
+    # Short status label reused in every output format.
+    # @return [String]
+    STATUS = "spec only"
+
+    # Every command the spec calls for, in the order `magik help` prints them.
+    #
+    # `:status` is `"ready"` for commands that work today and `"planned"` for
+    # commands that only exist in `docs/idea/00-build-spec.md`.
+    #
+    # @return [Hash{String => Hash{Symbol => String}}]
+    COMMANDS = {
+      "new" => { summary: "Generate a new Magik application", status: "planned" },
+      "generate" => { summary: "Generate a model, screen, action or job", status: "planned" },
+      "console" => { summary: "Open an application console", status: "planned" },
+      "server" => { summary: "Run the Falcon-backed application server", status: "planned" },
+      "worker" => { summary: "Run the background job worker", status: "planned" },
+      "test" => { summary: "Run the application test suite", status: "planned" },
+      "check" => { summary: "Lint an application against Magik's boot guardrails", status: "planned" },
+      "version" => { summary: "Print the magik gem version", status: "ready" },
+      "help" => { summary: "List every magik command and its status", status: "ready" }
+    }.freeze
+
+    class << self
+      # Run the CLI.
+      #
+      # Never raises for user error: a {Magik::Error} is rendered to `err` (or
+      # to `out` as JSON when `--json` is set) and reported as {EXIT_ERROR}.
+      #
+      # @param argv [Array<String>] the raw command line, usually `ARGV`
+      # @param out [IO] stream for command output
+      # @param err [IO] stream for error output
+      # @return [Integer] a process exit status: {EXIT_SUCCESS} or {EXIT_ERROR}
+      # @example
+      #   Magik::CLI.start(["version", "--json"]) # => 0
+      def start(argv = [], out: $stdout, err: $stderr)
+        options = { json: false }
+        args = parse_options(Array(argv), options)
+        dispatch(args, options, out)
+        EXIT_SUCCESS
+      rescue Magik::Error => e
+        report_error(e, options[:json], out, err)
+        EXIT_ERROR
+      end
+
+      # Print the gem version.
+      #
+      # @param out [IO] stream to write to
+      # @param json [Boolean] emit JSON instead of prose
+      # @return [void]
+      def version(out: $stdout, json: false)
+        if json
+          out.puts JSON.generate(
+            name: "magik",
+            version: Magik::VERSION,
+            status: STATUS,
+            ruby: RUBY_VERSION,
+            ruby_engine: RUBY_ENGINE
+          )
+        else
+          out.puts "magik #{Magik::VERSION} (#{STATUS})"
+        end
+      end
+
+      # Print usage and every command in {COMMANDS} with its status.
+      #
+      # @param out [IO] stream to write to
+      # @param json [Boolean] emit JSON instead of prose
+      # @return [void]
+      def help(out: $stdout, json: false)
+        return out.puts(JSON.generate(usage: usage, status: STATUS, commands: commands_as_data)) if json
+
+        out.puts usage
+        out.puts
+        out.puts "Commands:"
+        width = COMMANDS.keys.map(&:length).max
+        COMMANDS.each do |name, meta|
+          out.puts format("  %-#{width}s  %-8s  %s", name, meta[:status], meta[:summary])
+        end
+        out.puts
+        out.puts "Global options:"
+        out.puts "      --json               Emit machine-readable JSON"
+        out.puts "  -v, --version            Print the magik gem version"
+        out.puts "  -h, --help               Show this message"
+        out.puts
+        out.puts "Magik is #{STATUS}: `planned` commands are specified in " \
+                 "docs/idea/00-build-spec.md and not implemented."
+      end
+
+      # The one-line usage banner.
+      # @return [String]
+      def usage
+        "Usage: magik <command> [options]"
+      end
+
+      # {COMMANDS} flattened into an array of plain hashes, for JSON output.
+      # @return [Array<Hash{Symbol => String}>]
+      def commands_as_data
+        COMMANDS.map { |name, meta| { name: name, summary: meta[:summary], status: meta[:status] } }
+      end
+
+      private
+
+      # @param argv [Array<String>] raw arguments
+      # @param options [Hash] mutated with parsed global options
+      # @return [Array<String>] the remaining positional arguments
+      # @raise [Magik::InvalidOptionError] on an unrecognised flag
+      def parse_options(argv, options)
+        rest = argv.dup
+        parser = OptionParser.new do |o|
+          o.banner = usage
+          o.on("--json", "Emit machine-readable JSON") { options[:json] = true }
+          o.on("-v", "--version", "Print the magik gem version") { options[:command] = "version" }
+          o.on("-h", "--help", "Show this message") { options[:command] = "help" }
+        end
+        parser.parse!(rest)
+        rest
+      rescue OptionParser::ParseError => e
+        raise InvalidOptionError, e.message
+      end
+
+      # @param args [Array<String>] positional arguments
+      # @param options [Hash] parsed global options
+      # @param out [IO] stream for command output
+      # @return [void]
+      # @raise [Magik::CommandNotImplementedError] for a `planned` command
+      # @raise [Magik::UnknownCommandError] for anything else
+      def dispatch(args, options, out)
+        command = options[:command] || args.first || "help"
+
+        case command
+        when "version" then version(out: out, json: options[:json])
+        when "help" then help(out: out, json: options[:json])
+        else unsupported!(command)
+        end
+      end
+
+      # @param command [String] the requested command
+      # @raise [Magik::CommandNotImplementedError, Magik::UnknownCommandError] always
+      # @return [void]
+      def unsupported!(command)
+        raise CommandNotImplementedError, "`magik #{command}` is planned but not implemented" if COMMANDS.key?(command)
+
+        raise UnknownCommandError, "`#{command}` is not a magik command"
+      end
+
+      # @param error [Magik::Error] the error to report
+      # @param json [Boolean] emit JSON instead of prose
+      # @param out [IO] stream used for JSON output
+      # @param err [IO] stream used for prose output
+      # @return [void]
+      def report_error(error, json, out, err)
+        if json
+          out.puts JSON.generate(error: error.to_h)
+        else
+          err.puts error.message
+        end
+      end
+    end
+  end
+end

data/lib/magik/core.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Magik
+  # Application composition root: the `App.define` boot process, the Sequel connection,
+  # and the config swap points every opinionated default must honour.
+  #
+  # Implements: **Phase 1 — Foundation** of `docs/idea/00-build-spec.md`.
+  #
+  # Planned DSL surface, copied from the spec:
+  #
+  #   * `App.define :Name do ... end`
+  #   * `tenant_by :subdomain`
+  #   * `swap points: db, cache, jobs, search, realtime backends`
+  #
+  # Status: **Not implemented — spec only.** Every entry point below raises
+  # {NotImplementedError}. Nothing here reads config, touches a database or
+  # emits a byte of HTML.
+  #
+  # @see Magik::SUBSYSTEMS
+  module Core
+    # The build-spec phase this subsystem implements.
+    # @return [String]
+    SPEC_PHASE = "Phase 1 — Foundation"
+
+    # The DSL this subsystem will expose, verbatim from the spec.
+    # @return [Array<String>]
+    DSL_SURFACE = [
+      "App.define :Name do ... end",
+      "tenant_by :subdomain",
+      "swap points: db, cache, jobs, search, realtime backends"
+    ].freeze
+
+    # Implementation status of this subsystem.
+    # @return [String]
+    STATUS = "Not implemented — spec only"
+
+    # Entry point for the Core DSL.
+    #
+    # @param _args [Array] ignored
+    # @param _options [Hash] ignored
+    # @return [void] never returns
+    # @raise [NotImplementedError] always, until Phase 1 lands
+    def self.define(*_args, **_options)
+      raise NotImplementedError, "Magik::Core is spec-only; see docs/idea/00-build-spec.md"
+    end
+  end
+end

data/lib/magik/domains.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Magik
+  # The domain module system for large apps, with boot-time boundary enforcement: a
+  # domain reaches another domain only through its published interface or events.
+  #
+  # Implements: **Build order step 12 — Domain module system** of `docs/idea/00-build-spec.md`.
+  #
+  # Planned DSL surface, copied from the spec:
+  #
+  #   * `domains/<name>/domain.rb declares depends_on, exposes, publishes_events`
+  #   * `boot-time enforcement of cross-domain access`
+  #
+  # Status: **Not implemented — spec only.** Every entry point below raises
+  # {NotImplementedError}. Nothing here reads config, touches a database or
+  # emits a byte of HTML.
+  #
+  # @see Magik::SUBSYSTEMS
+  module Domains
+    # The build-spec phase this subsystem implements.
+    # @return [String]
+    SPEC_PHASE = "Build order step 12 — Domain module system"
+
+    # The DSL this subsystem will expose, verbatim from the spec.
+    # @return [Array<String>]
+    DSL_SURFACE = [
+      "domains/<name>/domain.rb declares depends_on, exposes, publishes_events",
+      "boot-time enforcement of cross-domain access"
+    ].freeze
+
+    # Implementation status of this subsystem.
+    # @return [String]
+    STATUS = "Not implemented — spec only"
+
+    # Entry point for the Domains DSL.
+    #
+    # @param _args [Array] ignored
+    # @param _options [Hash] ignored
+    # @return [void] never returns
+    # @raise [NotImplementedError] always, until Build order step 12 lands
+    def self.define(*_args, **_options)
+      raise NotImplementedError, "Magik::Domains is spec-only; see docs/idea/00-build-spec.md"
+    end
+  end
+end

data/lib/magik/i18n.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Magik
+  # Localisation and timezone-safe time handling. Timestamps cannot be rendered without
+  # explicit timezone conversion — that is a boot guardrail, not a lint.
+  #
+  # Implements: **Phase 8 — i18n, PWA, Notifications** of `docs/idea/00-build-spec.md`.
+  #
+  # Planned DSL surface, copied from the spec:
+  #
+  #   * `locales :en, :es, ...`
+  #   * `translatable: true fields`
+  #   * `timezone-safe :timestamp type`
+  #
+  # Status: **Not implemented — spec only.** Every entry point below raises
+  # {NotImplementedError}. Nothing here reads config, touches a database or
+  # emits a byte of HTML.
+  #
+  # @see Magik::SUBSYSTEMS
+  module I18n
+    # The build-spec phase this subsystem implements.
+    # @return [String]
+    SPEC_PHASE = "Phase 8 — i18n, PWA, Notifications"
+
+    # The DSL this subsystem will expose, verbatim from the spec.
+    # @return [Array<String>]
+    DSL_SURFACE = [
+      "locales :en, :es, ...",
+      "translatable: true fields",
+      "timezone-safe :timestamp type"
+    ].freeze
+
+    # Implementation status of this subsystem.
+    # @return [String]
+    STATUS = "Not implemented — spec only"
+
+    # Entry point for the I18n DSL.
+    #
+    # @param _args [Array] ignored
+    # @param _options [Hash] ignored
+    # @return [void] never returns
+    # @raise [NotImplementedError] always, until Phase 8 lands
+    def self.define(*_args, **_options)
+      raise NotImplementedError, "Magik::I18n is spec-only; see docs/idea/00-build-spec.md"
+    end
+  end
+end

data/lib/magik/jobs.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Magik
+  # Background jobs on a Postgres-backed transactional queue (Que-style) by default,
+  # swappable to Kafka.
+  #
+  # Implements: **Phase 4 — Jobs & Async** of `docs/idea/00-build-spec.md`.
+  #
+  # Planned DSL surface, copied from the spec:
+  #
+  #   * `job :Name do retry; schedule :cron/:every; perform do |args| end end`
+  #   * `magik worker — horizontally scalable worker process`
+  #
+  # Status: **Not implemented — spec only.** Every entry point below raises
+  # {NotImplementedError}. Nothing here reads config, touches a database or
+  # emits a byte of HTML.
+  #
+  # @see Magik::SUBSYSTEMS
+  module Jobs
+    # The build-spec phase this subsystem implements.
+    # @return [String]
+    SPEC_PHASE = "Phase 4 — Jobs & Async"
+
+    # The DSL this subsystem will expose, verbatim from the spec.
+    # @return [Array<String>]
+    DSL_SURFACE = [
+      "job :Name do retry; schedule :cron/:every; perform do |args| end end",
+      "magik worker — horizontally scalable worker process"
+    ].freeze
+
+    # Implementation status of this subsystem.
+    # @return [String]
+    STATUS = "Not implemented — spec only"
+
+    # Entry point for the Jobs DSL.
+    #
+    # @param _args [Array] ignored
+    # @param _options [Hash] ignored
+    # @return [void] never returns
+    # @raise [NotImplementedError] always, until Phase 4 lands
+    def self.define(*_args, **_options)
+      raise NotImplementedError, "Magik::Jobs is spec-only; see docs/idea/00-build-spec.md"
+    end
+  end
+end

data/lib/magik/ledger.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Magik
+  # Double-entry ledgers with boot-time balance validation and append-only entries, plus
+  # the audit and multi-step flow primitives that fintech work needs.
+  #
+  # Implements: **Phase 5 — Money & Compliance** of `docs/idea/00-build-spec.md`.
+  #
+  # Planned DSL surface, copied from the spec:
+  #
+  #   * `ledger :Name do account; entry do debit/credit/guard end end`
+  #   * `audited + immutable_after: model annotations`
+  #   * `flow :Name do step ... end — multi-step wizards`
+  #
+  # Status: **Not implemented — spec only.** Every entry point below raises
+  # {NotImplementedError}. Nothing here reads config, touches a database or
+  # emits a byte of HTML.
+  #
+  # @see Magik::SUBSYSTEMS
+  module Ledger
+    # The build-spec phase this subsystem implements.
+    # @return [String]
+    SPEC_PHASE = "Phase 5 — Money & Compliance"
+
+    # The DSL this subsystem will expose, verbatim from the spec.
+    # @return [Array<String>]
+    DSL_SURFACE = [
+      "ledger :Name do account; entry do debit/credit/guard end end",
+      "audited + immutable_after: model annotations",
+      "flow :Name do step ... end — multi-step wizards"
+    ].freeze
+
+    # Implementation status of this subsystem.
+    # @return [String]
+    STATUS = "Not implemented — spec only"
+
+    # Entry point for the Ledger DSL.
+    #
+    # @param _args [Array] ignored
+    # @param _options [Hash] ignored
+    # @return [void] never returns
+    # @raise [NotImplementedError] always, until Phase 5 lands
+    def self.define(*_args, **_options)
+      raise NotImplementedError, "Magik::Ledger is spec-only; see docs/idea/00-build-spec.md"
+    end
+  end
+end

data/lib/magik/model.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Magik
+  # The model DSL — a thin, explicit wrapper over Sequel. No lazy-loading magic, no
+  # implicit N+1.
+  #
+  # Implements: **Phase 1 — Foundation** of `docs/idea/00-build-spec.md`.
+  #
+  # Planned DSL surface, copied from the spec:
+  #
+  #   * `model :Name do field/belongs_to/has_many/validate/scope end`
+  #   * `:money field type, integer-cents backed (floats forbidden)`
+  #   * `UUIDv7 primary keys`
+  #   * `tenant_id auto-injection`
+  #
+  # Status: **Not implemented — spec only.** Every entry point below raises
+  # {NotImplementedError}. Nothing here reads config, touches a database or
+  # emits a byte of HTML.
+  #
+  # @see Magik::SUBSYSTEMS
+  module Model
+    # The build-spec phase this subsystem implements.
+    # @return [String]
+    SPEC_PHASE = "Phase 1 — Foundation"
+
+    # The DSL this subsystem will expose, verbatim from the spec.
+    # @return [Array<String>]
+    DSL_SURFACE = [
+      "model :Name do field/belongs_to/has_many/validate/scope end",
+      ":money field type, integer-cents backed (floats forbidden)",
+      "UUIDv7 primary keys",
+      "tenant_id auto-injection"
+    ].freeze
+
+    # Implementation status of this subsystem.
+    # @return [String]
+    STATUS = "Not implemented — spec only"
+
+    # Entry point for the Model DSL.
+    #
+    # @param _args [Array] ignored
+    # @param _options [Hash] ignored
+    # @return [void] never returns
+    # @raise [NotImplementedError] always, until Phase 1 lands
+    def self.define(*_args, **_options)
+      raise NotImplementedError, "Magik::Model is spec-only; see docs/idea/00-build-spec.md"
+    end
+  end
+end

data/lib/magik/notify.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Magik
+  # Multi-channel notifications from a single declaration.
+  #
+  # Implements: **Phase 8 — i18n, PWA, Notifications** of `docs/idea/00-build-spec.md`.
+  #
+  # Planned DSL surface, copied from the spec:
+  #
+  #   * `notification :name do channel :email, :in_app, :push end`
+  #
+  # Status: **Not implemented — spec only.** Every entry point below raises
+  # {NotImplementedError}. Nothing here reads config, touches a database or
+  # emits a byte of HTML.
+  #
+  # @see Magik::SUBSYSTEMS
+  module Notify
+    # The build-spec phase this subsystem implements.
+    # @return [String]
+    SPEC_PHASE = "Phase 8 — i18n, PWA, Notifications"
+
+    # The DSL this subsystem will expose, verbatim from the spec.
+    # @return [Array<String>]
+    DSL_SURFACE = [
+      "notification :name do channel :email, :in_app, :push end"
+    ].freeze
+
+    # Implementation status of this subsystem.
+    # @return [String]
+    STATUS = "Not implemented — spec only"
+
+    # Entry point for the Notify DSL.
+    #
+    # @param _args [Array] ignored
+    # @param _options [Hash] ignored
+    # @return [void] never returns
+    # @raise [NotImplementedError] always, until Phase 8 lands
+    def self.define(*_args, **_options)
+      raise NotImplementedError, "Magik::Notify is spec-only; see docs/idea/00-build-spec.md"
+    end
+  end
+end