magik 0.0.1

data/lib/magik/pwa.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Magik
+  # Installable progressive web app metadata. Explicitly no offline caching: the server
+  # is the single source of truth.
+  #
+  # Implements: **Phase 8 — i18n, PWA, Notifications** of `docs/idea/00-build-spec.md`.
+  #
+  # Planned DSL surface, copied from the spec:
+  #
+  #   * `pwa do name/icon/display 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 PWA
+    # 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 = [
+      "pwa do name/icon/display end"
+    ].freeze
+
+    # Implementation status of this subsystem.
+    # @return [String]
+    STATUS = "Not implemented — spec only"
+
+    # Entry point for the PWA 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::PWA is spec-only; see docs/idea/00-build-spec.md"
+    end
+  end
+end

data/lib/magik/realtime.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Magik
+  # Opt-in realtime. Default is plain request/response; nothing costs anything until a
+  # screen declares `live` or a `channel` exists.
+  #
+  # Implements: **Phase 3 — Realtime (opt-in)** of `docs/idea/00-build-spec.md`.
+  #
+  # Planned DSL surface, copied from the spec:
+  #
+  #   * `live :state_var, on: "channel:name"`
+  #   * `channel :name do subscribe_to/on_create/on_update end`
+  #   * `broadcast "channel", :event, payload`
+  #   * `presence for online/cursor tracking`
+  #   * `backend: Postgres LISTEN/NOTIFY (default) → Redis pub/sub (swap via config)`
+  #
+  # 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 Realtime
+    # The build-spec phase this subsystem implements.
+    # @return [String]
+    SPEC_PHASE = "Phase 3 — Realtime (opt-in)"
+
+    # The DSL this subsystem will expose, verbatim from the spec.
+    # @return [Array<String>]
+    DSL_SURFACE = [
+      "live :state_var, on: \"channel:name\"",
+      "channel :name do subscribe_to/on_create/on_update end",
+      "broadcast \"channel\", :event, payload",
+      "presence for online/cursor tracking",
+      "backend: Postgres LISTEN/NOTIFY (default) → Redis pub/sub (swap via config)"
+    ].freeze
+
+    # Implementation status of this subsystem.
+    # @return [String]
+    STATUS = "Not implemented — spec only"
+
+    # Entry point for the Realtime DSL.
+    #
+    # @param _args [Array] ignored
+    # @param _options [Hash] ignored
+    # @return [void] never returns
+    # @raise [NotImplementedError] always, until Phase 3 lands
+    def self.define(*_args, **_options)
+      raise NotImplementedError, "Magik::Realtime is spec-only; see docs/idea/00-build-spec.md"
+    end
+  end
+end

data/lib/magik/render.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Magik
+  # The UI DSL. Compiles components and screens to server-rendered HTML plus htmx
+  # attributes. There is no SPA framework and there never will be.
+  #
+  # Implements: **Phase 2 — Rendering & Actions** of `docs/idea/00-build-spec.md`.
+  #
+  # Planned DSL surface, copied from the spec:
+  #
+  #   * `component :Name do prop; body do ... end end`
+  #   * `screen :Name do state/body end`
+  #   * `kit: button, form, field, data_table, modal, toast, card, list, grid, tabs, stat, chart`
+  #   * `theme system: design tokens, light/dark mode via CSS vars`
+  #
+  # 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 Render
+    # The build-spec phase this subsystem implements.
+    # @return [String]
+    SPEC_PHASE = "Phase 2 — Rendering & Actions"
+
+    # The DSL this subsystem will expose, verbatim from the spec.
+    # @return [Array<String>]
+    DSL_SURFACE = [
+      "component :Name do prop; body do ... end end",
+      "screen :Name do state/body end",
+      "kit: button, form, field, data_table, modal, toast, card, list, grid, tabs, stat, chart",
+      "theme system: design tokens, light/dark mode via CSS vars"
+    ].freeze
+
+    # Implementation status of this subsystem.
+    # @return [String]
+    STATUS = "Not implemented — spec only"
+
+    # Entry point for the Render DSL.
+    #
+    # @param _args [Array] ignored
+    # @param _options [Hash] ignored
+    # @return [void] never returns
+    # @raise [NotImplementedError] always, until Phase 2 lands
+    def self.define(*_args, **_options)
+      raise NotImplementedError, "Magik::Render is spec-only; see docs/idea/00-build-spec.md"
+    end
+  end
+end

data/lib/magik/router.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Magik
+  # Convention-driven routing: an action name becomes a path, a screen auto-routes. Also
+  # the dev server and hot reload entry point.
+  #
+  # Implements: **Phase 2 — Rendering & Actions (build order step 4)** of `docs/idea/00-build-spec.md`.
+  #
+  # Planned DSL surface, copied from the spec:
+  #
+  #   * `convention: action name → path`
+  #   * `screens are auto-routed by name`
+  #
+  # 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 Router
+    # The build-spec phase this subsystem implements.
+    # @return [String]
+    SPEC_PHASE = "Phase 2 — Rendering & Actions (build order step 4)"
+
+    # The DSL this subsystem will expose, verbatim from the spec.
+    # @return [Array<String>]
+    DSL_SURFACE = [
+      "convention: action name → path",
+      "screens are auto-routed by name"
+    ].freeze
+
+    # Implementation status of this subsystem.
+    # @return [String]
+    STATUS = "Not implemented — spec only"
+
+    # Entry point for the Router DSL.
+    #
+    # @param _args [Array] ignored
+    # @param _options [Hash] ignored
+    # @return [void] never returns
+    # @raise [NotImplementedError] always, until Phase 2 lands
+    def self.define(*_args, **_options)
+      raise NotImplementedError, "Magik::Router is spec-only; see docs/idea/00-build-spec.md"
+    end
+  end
+end

data/lib/magik/schema.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Magik
+  # The migration DSL over Sequel migrations.
+  #
+  # Implements: **Phase 1 — Foundation** of `docs/idea/00-build-spec.md`.
+  #
+  # Planned DSL surface, copied from the spec:
+  #
+  #   * `migrate :Name do up/down 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 Schema
+    # 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 = [
+      "migrate :Name do up/down end"
+    ].freeze
+
+    # Implementation status of this subsystem.
+    # @return [String]
+    STATUS = "Not implemented — spec only"
+
+    # Entry point for the Schema 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::Schema is spec-only; see docs/idea/00-build-spec.md"
+    end
+  end
+end

data/lib/magik/testing.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Magik
+  # The test DSL, compiling to Minitest (never RSpec), with auto-inferred factories and
+  # a parallel runner.
+  #
+  # Implements: **Phase 9 — Testing** of `docs/idea/00-build-spec.md`.
+  #
+  # Planned DSL surface, copied from the spec:
+  #
+  #   * `test :Name do it "..." do expect(...) end end`
+  #   * `helpers: perform_action, render_screen, concurrently(n), travel_to`
+  #   * `helpers: assert_enqueued, assert_broadcast, assert_notified`
+  #   * `parallel: one Ractor per test file group, workers: :auto, transactional rollback per test`
+  #   * `magik test, magik test --watch, magik test --changed`
+  #
+  # 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 Testing
+    # The build-spec phase this subsystem implements.
+    # @return [String]
+    SPEC_PHASE = "Phase 9 — Testing"
+
+    # The DSL this subsystem will expose, verbatim from the spec.
+    # @return [Array<String>]
+    DSL_SURFACE = [
+      "test :Name do it \"...\" do expect(...) end end",
+      "helpers: perform_action, render_screen, concurrently(n), travel_to",
+      "helpers: assert_enqueued, assert_broadcast, assert_notified",
+      "parallel: one Ractor per test file group, workers: :auto, transactional rollback per test",
+      "magik test, magik test --watch, magik test --changed"
+    ].freeze
+
+    # Implementation status of this subsystem.
+    # @return [String]
+    STATUS = "Not implemented — spec only"
+
+    # Entry point for the Testing DSL.
+    #
+    # @param _args [Array] ignored
+    # @param _options [Hash] ignored
+    # @return [void] never returns
+    # @raise [NotImplementedError] always, until Phase 9 lands
+    def self.define(*_args, **_options)
+      raise NotImplementedError, "Magik::Testing is spec-only; see docs/idea/00-build-spec.md"
+    end
+  end
+end

data/lib/magik/version.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Magik
+  # The released version of the `magik` gem.
+  #
+  # `0.0.1` is a **name-reservation release**: the gem name is claimed on
+  # RubyGems, the public surface is a CLI shim plus documented, spec-only
+  # subsystem stubs. No framework behaviour from `docs/idea/00-build-spec.md`
+  # is implemented.
+  #
+  # The value follows [Semantic Versioning](https://semver.org). While the
+  # major version is `0`, minor bumps may break the public API.
+  #
+  # @return [String] a frozen `MAJOR.MINOR.PATCH` string
+  # @example Read the version at runtime
+  #   require "magik"
+  #   Magik::VERSION # => "0.0.1"
+  VERSION = "0.0.1"
+end

data/lib/magik.rb

@@ -0,0 +1,258 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+require_relative "magik/version"
+
+# Magik is an opinionated, full-stack Ruby framework targeting TruffleRuby:
+# one DSL for models, screens, actions, realtime channels, background jobs,
+# ledgers, APIs and admin panels, rendered server-side as HTML + htmx.
+#
+# **Status as of 2026-08-26: spec only.** The product specification lives in
+# `docs/idea/00-build-spec.md` and is entirely unimplemented. What ships in
+# this gem today is:
+#
+# * {Magik::VERSION} — the name-reservation version string.
+# * {Magik::Error} — the stable `MAGIK_*` error-code convention.
+# * {Magik::CLI} — a working `magik version` / `magik help` command line.
+# * One documented, spec-only stub module per planned subsystem
+#   (see {Magik::SUBSYSTEMS}); every entry point raises {NotImplementedError}.
+#
+# Nothing in this gem renders a page, talks to a database, or runs a job.
+#
+# @see https://github.com/developerz-ai/magik
+module Magik
+  # Every planned subsystem, mapped from its file basename under `lib/magik/`
+  # to the constant it defines. Each entry mirrors one area of the build spec.
+  #
+  # The map drives {https://ruby-doc.org/core/Module.html#method-i-autoload
+  # autoload} registration below, so requiring `magik` is cheap: a subsystem
+  # file is only read when its constant is first referenced.
+  #
+  # @return [Hash{Symbol => Symbol}] file basename => constant name
+  # @example List the planned subsystems
+  #   Magik::SUBSYSTEMS.keys # => [:core, :cli, :model, ...]
+  SUBSYSTEMS = {
+    core: :Core,
+    cli: :CLI,
+    model: :Model,
+    schema: :Schema,
+    render: :Render,
+    action: :Action,
+    router: :Router,
+    realtime: :Realtime,
+    jobs: :Jobs,
+    ledger: :Ledger,
+    api: :API,
+    auth: :Auth,
+    billing: :Billing,
+    admin: :Admin,
+    i18n: :I18n,
+    pwa: :PWA,
+    notify: :Notify,
+    testing: :Testing,
+    domains: :Domains,
+    check: :Check
+  }.freeze
+
+  # The subsystems that are documentation-only: their modules load and carry
+  # their spec metadata, but every entry point raises {NotImplementedError}.
+  #
+  # {Magik::CLI} is deliberately absent — it is the one subsystem with real,
+  # useful behaviour today.
+  #
+  # @return [Array<Symbol>] file basenames, a subset of {SUBSYSTEMS} keys
+  SPEC_ONLY_SUBSYSTEMS = (SUBSYSTEMS.keys - [:cli]).freeze
+
+  SUBSYSTEMS.each { |file, const| autoload const, "magik/#{file}" }
+
+  # Base class for every error Magik raises.
+  #
+  # Magik errors are not free-form strings. Each one carries three things, and
+  # all three are required:
+  #
+  # 1. a **stable code** matching {CODE_FORMAT} (`MAGIK_SOMETHING`) that is
+  #    safe to grep for, link to, and match on in tests and CI;
+  # 2. a **cause** — one sentence saying what actually went wrong;
+  # 3. a **fix** — a runnable command or a concrete edit, never "check your
+  #    configuration".
+  #
+  # The rendered message is deterministic:
+  #
+  # ```text
+  # MAGIK_LEDGER_UNBALANCED: entries for :Payouts do not balance (debits 1200, credits 900).
+  #   fix: run `magik check --ledger Payouts`
+  # ```
+  #
+  # Subclasses declare their defaults with the {code} and {fix} class-level
+  # DSL, so a raise site only has to supply the cause.
+  #
+  # @example Raise a one-off error
+  #   raise Magik::Error.new(
+  #     "the app has no `App.define` block",
+  #     code: "MAGIK_NO_APP",
+  #     fix: "run `magik new myapp` to generate one"
+  #   )
+  # @example Declare a reusable error class
+  #   class MissingTenant < Magik::Error
+  #     code "MAGIK_MISSING_TENANT"
+  #     fix  "add `tenant_by :subdomain` to your App.define block"
+  #   end
+  #   raise MissingTenant, "query on :Invoice has no tenant_id in WHERE"
+  class Error < StandardError
+    # The shape every Magik error code must take: `MAGIK_` followed by
+    # underscore-separated uppercase words.
+    #
+    # @return [Regexp]
+    CODE_FORMAT = /\AMAGIK_[A-Z0-9]+(?:_[A-Z0-9]+)*\z/
+
+    # Fallback code for {Magik::Error} itself.
+    # @return [String]
+    DEFAULT_CODE = "MAGIK_ERROR"
+
+    # Fallback fix for {Magik::Error} itself.
+    # @return [String]
+    DEFAULT_FIX = "read the raised cause above, then see docs/idea/00-build-spec.md"
+
+    class << self
+      # Get or set the default error code for this class and its subclasses.
+      #
+      # Called with an argument it is a writer; called without, a reader that
+      # walks up the superclass chain.
+      #
+      # @param value [String, nil] a code matching {CODE_FORMAT}, or nil to read
+      # @return [String] the effective code for this class
+      # @raise [ArgumentError] if `value` does not match {CODE_FORMAT}
+      def code(value = nil)
+        return @code = Error.validate_code!(value) unless value.nil?
+
+        @code || (superclass.respond_to?(:code) ? superclass.code : DEFAULT_CODE)
+      end
+
+      # Get or set the default fix line for this class and its subclasses.
+      #
+      # @param value [String, nil] an actionable fix, or nil to read
+      # @return [String] the effective fix for this class
+      # @raise [ArgumentError] if `value` is blank
+      def fix(value = nil)
+        return @fix = Error.validate_fix!(value) unless value.nil?
+
+        @fix || (superclass.respond_to?(:fix) ? superclass.fix : DEFAULT_FIX)
+      end
+
+      # @api private
+      # @param value [String] candidate error code
+      # @return [String] the frozen, validated code
+      # @raise [ArgumentError] if the code is malformed
+      def validate_code!(value)
+        string = value.to_s
+        return string.freeze if CODE_FORMAT.match?(string)
+
+        raise ArgumentError, "error code #{string.inspect} must match #{CODE_FORMAT.source}"
+      end
+
+      # @api private
+      # @param value [String, nil] candidate cause text
+      # @param klass [Class] the error class, used as the fallback cause
+      # @return [String] a frozen, non-empty cause
+      def normalize_cause(value, klass)
+        string = value.to_s
+        (string.strip.empty? ? klass.name.to_s : string).freeze
+      end
+
+      # @api private
+      # @param value [String] candidate fix line
+      # @return [String] the frozen, validated fix
+      # @raise [ArgumentError] if the fix is blank
+      def validate_fix!(value)
+        string = value.to_s
+        return string.freeze unless string.strip.empty?
+
+        raise ArgumentError, "a Magik error needs a non-empty fix: line"
+      end
+    end
+
+    # The stable, greppable error code.
+    # @return [String] e.g. `"MAGIK_UNKNOWN_COMMAND"`
+    attr_reader :code
+
+    # What went wrong, in one sentence.
+    #
+    # Named `cause_text` because `Exception#cause` is reserved by Ruby for the
+    # exception that was in flight when this one was raised.
+    #
+    # @return [String]
+    attr_reader :cause_text
+
+    # How to make it stop — a runnable command or a concrete edit.
+    # @return [String]
+    attr_reader :fix
+
+    # @param cause_text [String] what went wrong, one sentence
+    # @param code [String] a code matching {CODE_FORMAT}; defaults to the
+    #   class-level {Error.code}
+    # @param fix [String] an actionable fix; defaults to the class-level
+    #   {Error.fix}
+    # @raise [ArgumentError] if the code is malformed or the fix is blank
+    def initialize(cause_text = nil, code: self.class.code, fix: self.class.fix)
+      @code = Error.validate_code!(code)
+      @cause_text = Error.normalize_cause(cause_text, self.class)
+      @fix = Error.validate_fix!(fix)
+      super(self.class.render(@code, @cause_text, @fix))
+    end
+
+    # Render the canonical two-line message for an error triple.
+    #
+    # @param code [String] the error code
+    # @param cause_text [String] what went wrong
+    # @param fix [String] how to fix it
+    # @return [String] `"CODE: cause\n  fix: fix"`
+    def self.render(code, cause_text, fix)
+      "#{code}: #{cause_text}\n  fix: #{fix}"
+    end
+
+    # The error as plain data, ready for `--json` output or a log line.
+    #
+    # @return [Hash{Symbol => String}] with keys `:code`, `:cause`, `:fix`
+    def to_h
+      { code: code, cause: cause_text, fix: fix }
+    end
+  end
+
+  # Raised when a CLI command is named in the spec but not implemented yet.
+  #
+  # @see Magik::CLI
+  class CommandNotImplementedError < Error
+    code "MAGIK_COMMAND_NOT_IMPLEMENTED"
+    fix "run `magik help` for the commands that work today; " \
+        "track the rest in docs/idea/00-build-spec.md"
+  end
+
+  # Raised when a CLI command is not a Magik command at all.
+  #
+  # @see Magik::CLI
+  class UnknownCommandError < Error
+    code "MAGIK_UNKNOWN_COMMAND"
+    fix "run `magik help` to list every command"
+  end
+
+  # Raised when the command line carries a flag Magik does not understand.
+  #
+  # @see Magik::CLI
+  class InvalidOptionError < Error
+    code "MAGIK_INVALID_OPTION"
+    fix "run `magik help` to list the supported options"
+  end
+
+  # The installed gem's root directory — the parent of `lib/`.
+  #
+  # Useful for locating packaged assets and the specification itself, e.g.
+  # `Magik.root.join("docs/idea/00-build-spec.md")`.
+  #
+  # @return [Pathname] an absolute, resolved path
+  # @example
+  #   Magik.root.join("lib", "magik.rb").exist? # => true
+  def self.root
+    @root ||= Pathname.new(File.expand_path("..", __dir__))
+  end
+end

metadata

@@ -0,0 +1,87 @@
+--- !ruby/object:Gem::Specification
+name: magik
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- developerz.ai
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-08-26 00:00:00.000000000 Z
+dependencies: []
+description: |
+  Magik is a full-stack Ruby framework designed for TruffleRuby: one DSL for models,
+  screens, actions, realtime channels, background jobs, ledgers, APIs and admin panels.
+  The server renders HTML and htmx handles interactivity — there is no separate frontend
+  framework, no offline mode, and no heavy client-side compute.
+
+  Status as of 2026-08-26: this is a name-reservation release. The specification lives in
+  docs/idea/00-build-spec.md and is entirely unimplemented. What ships today is the gem
+  skeleton, the MAGIK_* error-code convention, a `magik version` / `magik help` CLI, and
+  one documented, spec-only stub module per planned subsystem. Nothing renders a page,
+  connects to a database, or runs a job yet.
+email:
+- admin@developerz.ai
+executables:
+- magik
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- exe/magik
+- lib/magik.rb
+- lib/magik/action.rb
+- lib/magik/admin.rb
+- lib/magik/api.rb
+- lib/magik/auth.rb
+- lib/magik/billing.rb
+- lib/magik/check.rb
+- lib/magik/cli.rb
+- lib/magik/core.rb
+- lib/magik/domains.rb
+- lib/magik/i18n.rb
+- lib/magik/jobs.rb
+- lib/magik/ledger.rb
+- lib/magik/model.rb
+- lib/magik/notify.rb
+- lib/magik/pwa.rb
+- lib/magik/realtime.rb
+- lib/magik/render.rb
+- lib/magik/router.rb
+- lib/magik/schema.rb
+- lib/magik/testing.rb
+- lib/magik/version.rb
+homepage: https://github.com/developerz-ai/magik
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/developerz-ai/magik
+  source_code_uri: https://github.com/developerz-ai/magik
+  changelog_uri: https://github.com/developerz-ai/magik/blob/main/CHANGELOG.md
+  documentation_uri: https://developerz-ai.github.io/magik/api/
+  bug_tracker_uri: https://github.com/developerz-ai/magik/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.20
+signing_key:
+specification_version: 4
+summary: An opinionated, full-stack Ruby framework for TruffleRuby — one DSL for the
+  whole app.
+test_files: []