rails_ai_admin 0.1.0

data/README.md

@@ -0,0 +1,292 @@
+# Rails AI Admin
+
+A self-hosted Rails admin engine with explicitly registered resources and one
+policy-checked, audited execution boundary for conventional CRUD.
+
+**0.1.0 Public Preview.** Current code supplies conventional CRUD with everyday
+field types (text, numbers, dates, times, email, URL, JSON, write-only passwords,
+Active Storage files and Action Text rich text), `belongs_to` references,
+many-to-many `references` lists, readonly `has_many`/`has_one` panels, registered
+field types and partials, CSV export and import, record history, the audit log,
+dashboard metrics and trends, bulk delete, a search across resources, synchronous member operations, fixed Selection previews, bounded
+asynchronous collection operations, opt-in admin review Surfaces and a durable
+outbox for one declared post-commit effect. Opt-in admin Chat streams replies and
+turns proposals into review Surfaces. An optional MCP endpoint exposes the same
+grant-filtered tools. Native-provider verification, token and cost budgets,
+nested and polymorphic association writes and broader job-center workflows
+remain open. The
+[development plan](docs/development-plan.md) describes the target product, not the
+supported feature set.
+
+The engine supports custom policy adapters and an optional Pundit adapter with
+explicit policy mappings per resource. The host owns authentication, tenants,
+policies and domain data. Missing context or policy grants deny access. Generic writes require a record version
+(`lock_version`, or else `updated_at`) and the same Active Record connection pool for domain records,
+operation receipts, audit and Work items. Resources with irreversible callback
+effects should remain readonly until their host boundary is redesigned and tested.
+
+See [Field Types](docs/site/_core_features/field-types.md) for custom normalization,
+validation, fixed Select labels and authorized form/index/show partials. Plugins
+refine a core scalar; they do not grant access. [Computed Fields](docs/site/_core_features/computed-fields.md)
+derive readonly values from declared, currently readable scalar dependencies.
+Neither API exposes arbitrary model methods.
+
+Use [Template Overrides](docs/site/_advanced/template-overrides.md) to copy one
+public presentation template and review source/context drift with doctor. Host
+overrides remain trusted Rails code and must preserve the execution boundary.
+
+Build ordinary host-owned Rails pages with the public
+[Custom Controller and Status API](docs/site/_advanced/custom-controllers.md).
+Scoped Access and the shared Runner preserve the execution boundary; host routes,
+layouts and partials remain ordinary Rails. The native-session packaged consumer
+includes an Order review workbench that shares its operation with native pages.
+
+Link records with [Associations](docs/site/_core_features/associations.md):
+references and child lists resolve through each target resource's own grants,
+so an association never shows or attaches a record its policy hides.
+
+Group, label, order or hide sidebar and Overview entries with
+[Resource Navigation](docs/site/_core_features/resource-navigation.md). The menu
+follows current index grants; hiding an entry changes no direct authorization.
+
+## Develop
+
+To see the admin before installing it anywhere, run the demo. It copies the
+packaged session/SQLite host to `tmp/demo`, seeds sample data and serves it on
+127.0.0.1 only; Ctrl-C stops it:
+
+```sh
+bin/demo --assistant   # everything, incl. admin Chat and MCP against an offline fake model (no key)
+bin/demo               # everything except admin Chat and MCP
+# then open http://127.0.0.1:3917/login and click "Sign in as Admin"
+# Open Assistant → New conversation and send: search articles for upgrading
+```
+
+Follow the [demo walkthrough](docs/site/_getting_started/demo.md#ai-chat-and-mcp)
+to try streamed replies, record links and a change that you review in Chat.
+
+```sh
+bundle install
+bundle exec rake test
+bundle exec rake build
+```
+
+The build creates `pkg/rails_ai_admin-<version>.gem` (currently `0.1.0`); it
+does not publish. `bundle exec rake release:check` reports release readiness, and
+[RELEASING.md](RELEASING.md) lists the next release's open gates and procedure. The
+[ten-minute quickstart](docs/site/_getting_started/quickstart.md) goes from an app
+with Rails 8 sign-in to a working, policy-checked Users admin. The
+[installation guide](docs/site/_getting_started/getting-started.md) covers other
+hosts and adding a local build or development checkout. Then run:
+
+```sh
+bin/rails generate rails_ai_admin:install
+bin/rails db:migrate
+bin/rails generate rails_ai_admin:resource Customer
+bin/rails rails_ai_admin:doctor
+```
+
+Installation stays closed: the generated `AdminContext` returns nil and the
+`AdminPolicyAdapter` stub denies all actions/fields. The install generator also
+provides an unregistered `ExampleAdmin` and an anonymous HTTP test at
+`test/rails_ai_admin/access_test.rb`. These are starting points, not a working
+authentication integration.
+
+The resource generator keeps only a readonly ID enabled and leaves the resource
+unregistered. When model schema is available, it adds commented scalar field
+suggestions for review. It does not sample records; sensitive/encrypted fields,
+foreign keys and polymorphic type columns, STI inheritance columns,
+`lock_version`, authority-like names such as role/permission/security_version,
+and unsupported types are excluded from suggestions. A declared non-polymorphic
+`belongs_to` is suggested as a commented `belongs_to` field.
+Missing models or unavailable table metadata still leave the safe readonly scaffold.
+Implement host authentication and explicit policies, then review fields and
+register class-name strings in the initializer.
+
+```ruby
+RailsAiAdmin.configure do |config|
+  config.context_adapter = "AdminContext"
+  config.authorization_adapter = "AdminPolicyAdapter"
+  config.resources = ["CustomerAdmin"]
+end
+```
+
+```ruby
+class CustomerAdmin < RailsAiAdmin::Resource
+  model "Customer"
+  key :customers
+  title :name
+
+  fields do
+    id :id
+    text :name, required: true, nullable: false,
+      searchable: :prefix, sortable: true
+  end
+end
+```
+
+Run the generated anonymous request test before and after adapting the host:
+
+```sh
+bin/rails test test/rails_ai_admin/access_test.rb
+```
+
+Doctor reports obviously incompatible public zero-argument constructors/signatures, schema,
+field-type review hints, sortable-index and sensitive-declaration findings,
+and default autoload-path diagnostics. Its metadata cannot prove authentication
+or authorization. `TestKit` provides separate anonymous-context, action, tenant
+and exact field-grant assertions; field-grant snapshots are not an AI exposure
+report. See the [host verification guide](docs/site/_advanced/host-verification.md).
+
+Resources can also declare named index tabs with `scopes`. Each tab needs its own
+default-deny `named_scopes` grant and can only narrow the policy relation; see
+the [Named Scopes guide](docs/site/_core_features/named-scopes.md). Fields can opt
+into typed exact/range filters with `filterable:`, behind a separate default-deny
+`:filter` field grant; see the [Typed Filters guide](docs/site/_core_features/typed-filters.md).
+An `index` block chooses columns, a default sort, page size and an optional
+bounded count; see the [Index Tables guide](docs/site/_core_features/index-tables.md).
+
+The resource declaration grants no permission. See the runnable host contract
+examples in the [configuration guide](docs/site/_getting_started/configuration.md).
+Use one static-path engine mount whose final helper name is `rails_ai_admin`,
+with no HTTP-verb restriction. Run installation inside the target Rails app; its
+loaded routes are checked before writing, including drawn files and namespace
+prefixes. Other helper names, dynamic path parameters and multiple mounts are
+rejected. Admin CSS/ESM are
+prebuilt in the gem, so a host does not need Node to compile them. No provider key,
+AI table or provider call is required for conventional mode.
+
+## Custom Operations and Follow-Up Delivery
+
+Register a `RailsAiAdmin::Operation` on a resource for a synchronous member command.
+Its native input form leads to input-bound preflight and a separate human
+confirmation, using the same Runner/receipt/audit transaction as CRUD. Operation
+inputs, committed-receipt reads and follow-up delivery have independent grants;
+ordinary editable-field permissions do not grant them. Successful custom receipt
+replay compares its already bound schema/input digest, not current input grants;
+failed or changed replay input returns a generic conflict without field errors.
+See the
+[Operation guide](docs/site/_core_features/operations.md).
+
+`RailsAiAdmin::Work` reuses the input DSL for post-commit delivery. Registered
+`config.work_handlers` persist bounded payload/digest intent through
+`context.outbox.enqueue`. Work performs one declared `context.effect(request:)`
+using a stable downstream delivery key and a dedicated digest of its plain JSON
+wire request. Typed values must be serialized first; normalized key collisions,
+nonfinite floats and unsupported objects are rejected. Ordinary Active Record
+writes in Work/effect execution are guarded, while trusted Ruby remains outside
+a sandbox. A successful business result does not
+mean the effect finished. Outbox auto-dispatch defaults to false; the host must
+schedule `rails_ai_admin:work:scan` or bounded `work:drain` recovery. Optional
+after-commit enqueue is only an accelerator.
+
+The default exact record-version policy stops delivery after later record edits.
+Unknown non-idempotent effects require reconciliation rather than automatic
+retry. Leases/fencing and persistent payloads do not establish downstream
+exactly-once execution. Read the [Durable Outbox guide](docs/site/_advanced/durable-outbox.md)
+before enabling a real transport. Preflight's Active Record write guard is not a
+trusted-Ruby sandbox, and operation duration checks do not hard-interrupt Ruby/SQL.
+Global operations, CRUD handler replacement and AI/Surface dispatch remain
+unavailable; complete release Gates remain open.
+
+## Review Surfaces
+
+Hosts that already use rails_tool_views can set `config.surfaces = true` and mark
+member operations `surface: true`. A native review can then be saved as a
+persistent Surface that confirms the same intent once, through admin-owned
+endpoints that leave the host's rails_tool_views settings untouched. Operations
+marked `assistant: true` can also be proposed by an assistant through the
+on-demand `raa_propose_operation` RubyLLM tool; only the user's Surface
+confirmation executes them. See the
+[Review Surfaces guide](docs/site/_advanced/review-surfaces.md).
+
+## Admin Assistant
+
+Hosts that load ruby_llm can run `bin/rails generate rails_ai_admin:assistant`
+and set `config.assistant = true`. The assistant reads records through each
+admin's current grants plus a default-deny `assistant?` grant, reads audited
+record history, and answers questions asked from a record or list page. It
+cannot change data: a suggested create, update, delete (for resources that
+declare `assistant_changes`) or business operation opens a review Surface with
+before → after values, and only the person's confirmation writes it, once, as
+that person, with a version check and an audit event. Creates are reviewed too.
+Replies stream as they are written. With `config.mcp = true`, outside agents
+(Claude Code, Cursor) use the same tools through an MCP endpoint under personal
+access tokens, and their proposals wait for confirmation in the admin. Turns run in jobs through a leased inbox that
+recovers after crashes without repeating messages. Provider settings come from
+your own adapter, never from global RubyLLM configuration. See the
+[Admin Assistant guide](docs/site/_advanced/admin-assistant.md).
+
+## Fixed Selection Previews
+
+A default-deny `export_records?` grant adds an Export CSV button for the current list
+(same rows, columns and values as the pages; audited and bounded by `export_limit`).
+A default-deny `view_history?` grant adds a record History page listing its audited
+changes (fields named only when currently readable or writable).
+
+A separate default-deny `select_records?` grant enables native index checkboxes
+and a no-JavaScript preview of up to 100 explicit targets. `Selections::Builder`
+captures exact canonical IDs/versions and revalidates ownership, security version,
+expiry, resource contract and current record/field grants. Newly matching records
+or same-count replacements cannot expand a captured manifest. Labels are freshly
+projected; only IDs/versions/positions and parent binding metadata are persisted.
+
+Capture is not operation approval and creates no OperationRun, business audit,
+Work item or job. See [Fixed Selections](docs/site/_core_features/selections.md).
+
+## Asynchronous Collection Operations
+
+Register an `Operation` with `scope: :collection` to apply its per-record handler
+to a fixed Selection of at most 100 targets. Native input, pure review and explicit
+**Confirm and queue** create one approved parent with durable child intents/items;
+admission performs no domain mutation. Each worker attempt rebuilds current host
+authority and commits a target change, audit, receipt, optional outbox and item
+completion in one transaction. Public member execution cannot execute child intents.
+
+Items commit independently. Cancellation stops remaining uncommitted items and
+preserves committed changes and their Work. Approval expiry controls admission;
+a separate execution deadline bounds the admitted run. Job receipts use separate
+current receipt grants; cancellation needs its own `cancel_operation?` grant.
+The parent stores bounded typed input once, so exclude credentials and secrets.
+
+`collection_auto_dispatch` defaults to false. The host supplies `resolve_job`, a
+persistent queue and recurring `rails_ai_admin:collections:scan` (or bounded
+`collections:drain`); after-commit enqueue only accelerates recovery. Read
+[Collection Operations](docs/site/_core_features/collection-operations.md) before
+enabling workers. All-filtered/10,000-target manifests, global operations, a full
+job center and retention remain planned; this bounded slice does not close the
+full roadmap or release Gates.
+
+## Read the Contracts
+
+- [Architecture](ARCHITECTURE.md), [public contract](docs/reference/public-contract.md)
+  and [operation semantics](docs/reference/operations.md).
+- [Resources and fields](docs/site/_core_features/resources-and-fields.md),
+  [host verification](docs/site/_advanced/host-verification.md) and
+  [data/security boundaries](docs/site/_advanced/data-and-security.md).
+- [Compatibility evidence](COMPATIBILITY.md), [roadmap](ROADMAP.md) and
+  [dependency integration constraints](docs/reference/dependency-contracts.md).
+
+An independent [Devise/Pundit/PostgreSQL consumer](spec_hosts/devise_postgres)
+exercises UUID tickets, verified tenant memberships, development reload and
+fresh-process crash/replay using the built gem. Its Propshaft/jsbundling and
+Sprockets/jsbundling modes are asset variants of one consumer. See the
+[Pundit/Devise guide](docs/site/_advanced/pundit-and-devise.md) and
+[host verification guide](docs/site/_advanced/host-verification.md). The engine
+does not provide accounts or login routes. The fixture's separate product Chat
+and Surface remain host-owned, beside its opt-in admin Chat.
+
+Changing a resource's policy mapping changes its operation fingerprint. Reopen
+existing development forms if their old intents are invalidated.
+
+The Jekyll/RDoc site lives under `docs/site/`. Install its separate bundle, then
+run `docs/site/bin/build.sh`. See [Releasing](RELEASING.md) for the Pages setup
+and versioned builds.
+
+Local automated checks and internal review do not establish production readiness,
+independent security review, real-provider behavior or user acceptance. Release
+gates remain in the plan; publishing requires explicit maintainer approval.
+
+Licensed under [MIT](LICENSE). Dependencies retain their own licenses in
+[third-party notices](THIRD_PARTY_NOTICES.md). Read [SECURITY.md](SECURITY.md) before
+reporting a vulnerability and [CONTRIBUTING.md](CONTRIBUTING.md) before contributing.

data/SECURITY.md

@@ -0,0 +1,14 @@
+# Security policy
+
+0.1.0 is a Public Preview. Review the limitations in CHANGELOG.md and deploy
+behind your host application's authentication and network controls. Verify
+tenant scopes and action and field grants before granting access.
+
+Report suspected vulnerabilities privately to wangyaodi@gmail.com. Include the
+affected version, minimal synthetic reproduction, impact and suggested fix.
+Do not open a public issue containing exploit details or sensitive data. Reports
+are reviewed by the maintainer; no response-time SLA is currently offered.
+
+Authentication and policies belong to the host. A logged-in actor alone grants
+no resource access. Trusted Ruby extensions are not sandboxed. See the threat
+model and public contract for the supported transaction and privacy boundaries.

data/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,19 @@
+# Third-party notices
+
+Original project code is MIT licensed. No competitor source or assets are copied.
+Runtime dependencies retain their own notices in their distributed packages:
+
+| Dependency | License | Source |
+| --- | --- | --- |
+| Rails | MIT | https://github.com/rails/rails |
+| rails_tool_views | MIT | https://github.com/yorzi/rails_tool_views |
+| RubyLLM | MIT | https://github.com/crmne/ruby_llm |
+| Turbo / turbo-rails | MIT | https://github.com/hotwired/turbo-rails |
+| Stimulus / stimulus-rails | MIT | https://github.com/hotwired/stimulus-rails |
+
+The prebuilt ESM contains Turbo 8.0.23, Stimulus 3.2.2 and the rails_tool_views 1.0.2
+Stimulus controller. Their complete notices
+ship in `app/assets/builds/rails_ai_admin.LICENSE.txt`, generated from the sources
+recorded in `frontend/licenses/README.md`. The host needs no Node build for these
+assets. Dependency installation and license declarations do not prove a security
+audit or grant rights to third-party trademarks.

data/app/assets/builds/rails_ai_admin.LICENSE.txt

@@ -0,0 +1,55 @@
+Turbo 8.0.23
+Copyright (c) 37signals
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+Stimulus 3.2.2
+# MIT License
+
+Copyright © 2021 Basecamp, LLC.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+The Software is provided "as is," without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the Software or the use or other dealings in the Software.
+
+rails_tool_views 1.0.2 (Stimulus controller)
+MIT License
+
+Copyright (c) 2026 Andy Wang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.