{"id":14955588,"url":"https://github.com/makandra/katapult","last_synced_at":"2025-10-01T18:31:47.224Z","repository":{"id":21712719,"uuid":"25034237","full_name":"makandra/katapult","owner":"makandra","description":"Kickstart Rails development!","archived":false,"fork":false,"pushed_at":"2019-06-19T07:54:54.000Z","size":692,"stargazers_count":22,"open_issues_count":0,"forks_count":2,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-01-14T11:21:37.941Z","etag":null,"topics":["code-generation","dsl","kickstart","rails5","ruby","ruby-gem","ruby-on-rails","template-engine"],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/makandra.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-10-10T12:21:15.000Z","updated_at":"2023-04-17T11:58:14.000Z","dependencies_parsed_at":"2022-08-17T18:40:50.644Z","dependency_job_id":null,"html_url":"https://github.com/makandra/katapult","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/makandra%2Fkatapult","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/makandra%2Fkatapult/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/makandra%2Fkatapult/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/makandra%2Fkatapult/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/makandra","download_url":"https://codeload.github.com/makandra/katapult/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234724650,"owners_count":18877239,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["code-generation","dsl","kickstart","rails5","ruby","ruby-gem","ruby-on-rails","template-engine"],"created_at":"2024-09-24T13:11:24.703Z","updated_at":"2025-10-01T18:31:41.796Z","avatar_url":"https://github.com/makandra.png","language":"Ruby","readme":"# Abandoned Project\n\nKatapult was an endeavor to dramatically speed up starting a new Rails\napplication. However, it turned out to save less time than expected, while\nrequiring more time for maintenance than anticipated. Since its benefits fell\ntoo low, we have decided to not continue developing Katapult.\n\nYou can still use Katapult for generating ready-to-run applications with model\nCRUD, authentication and all of Katapult's features, but the rapid development\nof the web will quickly render the generated code antiquated. Nevertheless, its\narchitecture may remain an inspiration on how to use the Rails generators\nprogrammatically.\n\n\nThat being sad, here's the latest version of its README:\n\n# Katapult 0.5.0\nGenerating a Rails 5.1.4 app on Ruby 2.5.0.\n\n\u003cimg src=\"katapult.png\" width=\"200px\" align=\"right\" /\u003e\n\n\nKatapult is a kickstart generator for Rails. It prepares a new\napplication with [lots of pre-configuration](https://github.com/makandra/katapult/blob/master/lib/generators/katapult/basics/basics_generator.rb)\nand offers [makandra-flavored](https://leanpub.com/growing-rails) code\ngeneration from an application model. This significantly speeds up the initial\nphase of Rails development by doing in minutes what would cost you weeks. When\nKatapult has finished, you can instantly start implementing the interesting\nparts of your application.\n\n\n## Prerequisites\n\nKatapult uses *PostgreSQL* as database, so you'll need to install that upfront.\nAlso, it drops the Rails asset pipeline in favor of *Webpacker*, so you'll need\n*Node* and *Yarn* (see \u003chttps://makandracards.com/makandra/47477\u003e).\n\nThe required *Ruby* version is 2.5.0. You'll need the *Bundler* and *Rake* gems,\nwhich are probably already installed on your system.\n\nWhen you're using the `katapult` binary (you should), you'll also need *Git*.\n\n\n## Installation\n\n    gem install katapult\n\n\n## Usage\n\nThere are two usage scenarios for Katapult:\n\n1. Starting a fresh Rails application\n2. Extending an existing Rails application\n\nChoose your use case and read on below.\n\n\n## Starting a fresh Rails application\n\nTo create a new Rails application with Katapult, run the following command:\n\n    katapult new $APPLICATION_NAME\n\nThis will create a new Rails application, prepared and configured: bundled,\ndatabase set up, RSpec, Cucumber and Capistrano installed and much more.\nPlease read the [BasicsGenerator](https://github.com/makandra/katapult/blob/master/lib/generators/katapult/basics/basics_generator.rb)\nfor details (its methods are executed one-by-one from top to bottom).\n\nWhen Katapult is done, you will find a default application model in\n`lib/katapult/application_model.rb`. It contains a full example of Katapult's\nDSL that you can use as an inspiration for creating your own application model.\n\nNext, check the templates in `lib/templates/katapult`. They will be used\nto generate the corresponding files, e.g. HAML views. Please modify the templates\nto match your requirements. (Actually, you can customize much more templates.\nEach template in Katapult's `lib/generators/katapult/\u003cgenerator\u003e/templates/` can\nbe overridden with a file at `lib/templates/katapult/\u003cgenerator\u003e/` in your\napplication.)\n\nWhen your application model and the templates are ready, let Katapult generate\nyour code:\n\n    katapult fire\n\nThis will create models, migrations, views, styles, controllers, routes,\nCucumber features, specs, factories and more. It will also commit the results\nand migrate the database.\n\nWhen this is done, your application is ready to use! Start a development\nserver and try it out.\n\n\n## Extending an existing Rails application\n\nYou can use Katapult for code generation in an existing application as well.\n\nFirst, add Katapult to the development group in your Gemfile:\n```\n  gem 'katapult'\n```\n\nNext, generate the default application model:\n\n```\nbundle exec rails generate katapult:app_model\n```\n\nYou'll find the application model at `lib/katapult/application_model.rb`. It\ncontains a full example of Katapult's features: Use it as an inspiration for\nmodeling your own application. (When you're used to the application model DSL,\nyou don't need to generate the default model. Just create a Ruby file and start\nmodeling.)\n\nNext, copy Katapult's template files to your application:\n\n```\nkatapult templates\n```\n\nThis will copy some of Katapult's file templates to `lib/templates/katapult`.\nModify them, especially the view templates, to match the current state of your\napplication. You can customize even more templates, see the \"Starting …\" section\nabove.\n\nWhen model and templates are ready, trigger code generation with:\n\n```\nkatapult fire path/to/your_model.rb\n```\n\n\n## DSL reference\n\nBelow you find an overview of the application model DSL. The respective sections\nhold examples of what options are available to each element. For details, dive\ninto the respective generator at `lib/generators/katapult/*/*_generator.rb`. The\nmethod names of a generator tell what it does.\n\n### Crud\nShortcut for creating a model together with a WebUI with CRUD actions. The block\nis passed the model instance.\n\n    crud 'Customer' do |customer|\n      # customer.attr :name\n    end\n\n\n### Model\nTakes a name and a block. Generates a Rails model, a migration, and a spec.\n\n    model 'Customer' do |customer|\n      # customer.attr :name etc, see Attribute element\n      # customer.belongs_to :group, see Association element\n    end\n\n\n#### Attribute\nDefined on Model; takes a name and options. Adds a database field in the model\nmigration, form fields in a WebUI, and configuration code in the model as\nneeded.\n\n    # Default type :string\n    model.attr :name\n    \n    # Inferred type :email (attribute name matches /email/)\n    model.attr :email\n\n    # Inferred type :password. Password fields are rendered as password_field in\n    # forms, but never rendered in show views.\n    model.attr :password\n    \n    # Specify assignable values. Available options: allow_blank, default\n    model.attr :age, type: :integer, assignable_values: 18..99, allow_blank: true\n    \n    # Will be rendered as number_field in forms, and with a € sign in show views\n    model.attr :income, type: :money\n    \n    # All attribute types take an optional default\n    model.attr :homepage, type: :url, default: 'http://www.makandra.de'\n    \n    # Boolean fields are modeled as flags. Default required!\n    model.attr :locked, type: :flag, default: false\n\n    # JSON fields are supported\n    model.attr :prefer, type: :json # PostgreSQL \"jsonb\"\n    model.attr :avoid, type: :plain_json # PostgreSQL \"json\"\n\n\n#### Association\nDefined on Model; takes the name of another model (just as you called it in the\napplication model). Adds a foreign key attribute to the model and `belongs_to`/`has_many`\ncalls to the respective models.\n\n    model 'Customer' do |customer|\n      customer.belongs_to 'Group'\n    end\n\n    model 'Group'\n\n\n### WebUI\nTakes a name, options and a block. Generates controller, routes, views, and a\npassing Cucumber feature.\n\n    web_ui 'Customer', model: 'User' do |web_ui|\n      web_ui.crud # Create all the standard rails actions\n      # web_ui.action :custom etc, see Action element\n    end\n\n    # Short syntax with inferred model name 'User'\n    web_ui 'User', \u0026:crud\n\n\n#### Action\nDefined on WebUI; takes a name and options. Adds an action to the controller,\nand a route as needed.\n\n    # Select single Rails actions\n    web_ui.action :index\n    web_ui.action :show\n    web_ui.action :create # also creates :new\n    web_ui.action :update # also creates :edit\n    web_ui.action :destroy\n    \n    # Add custom actions\n    web_ui.action :custom_action, method: :post, scope: :member\n    web_ui.action :other_action, method: :get, scope: :collection\n    \n\n### Navigation\nGenerates a main menu with links to the index pages of all WebUIs.\n\n    navigation\n\n\n### Authenticate\nTakes the name of the user model (currently only `User` is supported) and an\nemail address. Generates authentication with [Clearance](https://github.com/thoughtbot/clearance).\n\n    authenticate 'User', system_email: 'system@example.com'\n\nThe given email address will be configured as the sender for all mails sent by\nRails, including Clearance mails like password reset requests.\n\n\n## Development\n\n### Getting started\n`Katapult` is tested with [RSpec](http://rspec.info/) and\n[Cucumber](https://cucumber.io/) + [Aruba](https://github.com/cucumber/aruba)\n([API documentation](http://www.rubydoc.info/github/cucumber/aruba/master/)).\n\nFor its full-stack integration tests, Katapult requires a PostgreSQL account.\nCreate a dedicated account on your local PostgreSQL server:\n\n    $\u003e sudo -u postgres psql\n    postgres=# CREATE ROLE katapult WITH createdb LOGIN;\n\n\n### Continuing Development\nWhenever you start working on Katapult, you should run `script/update`, which\nwill guide you through a quick update process.\n\n### Architecture\nKatapult's code is roughly split into three parts: the `katapult` binary in bin/,\nthe model in lib/katapult/ and the generators in lib/generators. Also, there\nis a script/ directory that holds some scripts to simplify development. It is not\nincluded in the `katapult` gem.\n\nThe generators of Katapult extend the `rails/generators` you probably know\nfrom generating migration files or scaffolds. However, Katapult lifts them on a\nhigher level by passing them a model object instead\nof plain text arguments. This way, the Katapult generators can explore the whole\napplication model and are not restricted to a few strings they've been given.\n\nThere are a few \"public\" Rails generators. They can be considered the next API\nlevel after the `katapult` binary:\n\n- `katapult:basics`: Enhances a pristine Rails app with all of the\n  basic configuration.\n- `katapult:app_model`: Installs a boilerplate application model that\n  serves as a starting point for modeling an application.\n- `katapult:templates`: Copies some generator templates to the target\n  application.\n- `katapult:transform`: Parses the application model into an internal\n  representation, which will be turned into code by all the other generators.\n\nNote that the `katapult` binary is the only Rails-independent part of Katapult.\nEverything else runs in the context of the Rails application.\n\n### Suggested workflow\nWhen adding a feature to Katapult, it will usually take you some time to\nfigure out how exactly the generated code should look like. You'll be switching\nbetween Katapult's tests, its generators and the generated code.\n\nHere's a process for building larger code generation features:\n\n1) **Start with a test:** Create a Cucumber scenario that creates and transforms\n   an application model. Also, write a first draft of the code that generates\n   what you expect.\n2) Run your scenario. This will transform your test application model.\n3) Make a commit inside the generated test application, so you'll have a clean\n   working directory: `script/kta git add --all \u0026\u0026 script/kta git commit -m 'x'`\n4) **Modify the generated code** inside the generated test application until it\n   meets your expectations. If you like, boot a development server with\n   `script/kta rails s`.\n5) **Finish your test:** Once you've figured how the generated code should look\n   like, it's time to write steps that test it. For this purpose, tag your\n   scenario with @no-clobber and comment out the model transformation step. This\n   will leave the generated test app untouched in subsequent test runs, so you\n   will be able to run your scenario repeatedly, without losing what you've\n   built, until you have covered every change. Use `git diff` in the test app to\n   see your changes.\n6) **Write code:** When you've completed your scenario, write the code that\n   generates what is needed to satisfy the test.\n7) Remove the @no-clobber tag and uncomment the transformation step. Stop the\n   development server if you've started one.\n8) Run your scenario normally and iterate over your code generation code until\n   your scenario is green.\n\n### Guidelines\nPlease respect the following guidelines during development:\n\n- The application model should be order-agnostic. There is a #prepare_render\n  method in `ApplicationModel` for things that need to happen between parsing\n  and rendering the application model.\n- Transformation should be idempotent: it should be possible to generate the\n  application model over and over again without crashing or breaking things.\n\n### Debugging\nAdd the `@announce-output` tag to Katapult scenarios in order to have output\nlogged to your terminal. Note that each step will print all output to date, so\nyou will see things multiple times.\n\nTo precisely debug errors occurring _inside_ the generated application, use\n`script/kta`. It is a helper script that will execute whatever command you pass\nit, but in the directory of the generated application. While you could cd to the\ntest app and run your command there, you'd need to `cd ../../aruba/katapult_test_app`\nbetween test runs, because the tmp/aruba directory gets wiped before each test.\n\nWhen fixing issues in the generated app, make a commit in the app first. When\nyou've fixed it, the diff will show you what you need to port back to katapult.\n\n#### Typical issues\nBe sure to check this list when you encounter strange issues during development.\n\n- Spring was running in a directory that does not exist any more. This will\n  screw subsequent spring invocations. Run `ps aux | grep spring` and `kill`\n  suspect processes.\n- An outdated Rails application in `tmp/cached_*`\n- Timeout error because of a script waiting for user input\n\n#### Fast tests\nGenerating basics and transforming the application model take quite some time\n(about 20s), because it boots the Rails application, resolves Yarn dependencies\nand migrates databases. To speed that up, Katapult tests cache prepared Rails\napplications in tmp/.\n\nWhen debugging test suite speed, `bundle exec cucumber --format usage` is your\nfriend.\n\n\n## Credits\n\nDevelopment: Dominik Schöler from [makandra](makandra.com)\u003cbr /\u003e\nKatapult image: [Nemo](http://pixabay.com/de/katapult-30061)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmakandra%2Fkatapult","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmakandra%2Fkatapult","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmakandra%2Fkatapult/lists"}