appstruct-cli 0.1.0

Command-line compiler and development workflow for AppStruct applications
appstruct-cli-0.1.0 is not a library.

AppStruct

English | 简体中文

AppStruct is a configuration-driven Rust full-stack application generator. It compiles a multi-file YAML App Spec into a typed IR, PostgreSQL migrations, an Axum/SeaORM backend, OpenAPI, a TypeScript client, and a React/Vite application.

The repository is currently a technical preview. It is distributed from a source checkout for now; there is no crates.io package or binary installer yet. M0-M6 are complete, including production builds, the coordinated development server, Tenant/Audit/Mail/Jobs/File modules, the locked appstruct/saas@1 preset, transactional project updates, and a runnable SaaS template and example. The SaaS preset includes an Admin operations overview and guarded Jobs retry/replay controls; Billing remains out of scope for preset version 1.

Quick Start

The workspace pins Rust 1.98.0. Install the CLI from this checkout:

rustup toolchain install 1.98.0 --component clippy,rustfmt
cargo build --release --locked -p appstruct-cli
export PATH="$PWD/target/release:$PATH"
appstruct --version

Create a minimal project backed by an existing PostgreSQL database:

appstruct new notes --template minimal
cd notes
cp .env.example .env
export DATABASE_URL=postgresql://appstruct:appstruct-dev@127.0.0.1:5432/appstruct
appstruct migrate dev --accept
appstruct doctor
appstruct dev

Update DATABASE_URL in .env before running doctor. For a Docker-managed PostgreSQL development database, use --template dashboard or --template saas and ensure Docker Compose is available.

appstruct dev starts the generated API and Vite, watches App Spec and user Rust inputs, and stops its child processes on Ctrl-C. Managed databases default to prompting only when migrations are required; external databases default to leaving migrations entirely to the operator. The default URLs are http://127.0.0.1:3000 and http://127.0.0.1:5173.

Generated Web applications use a pinned modern baseline: React 19, TypeScript, and Vite with TanStack Query, TanStack Router, TanStack Table, and TanStack Form plus Zod validation. The generated dependency lockfile is part of the project output, so installs and builds remain repeatable across machines.

Configure development migration ownership explicitly when needed:

database:
  provider: postgres
  dev:
    mode: managed
    migration: prompt # auto | prompt | never | unmanaged

auto creates and applies safe migrations, prompt asks only when work is pending, never performs read-only compatibility checks and blocks stale schemas, and unmanaged skips all AppStruct migration checks before starting. Production backend startup never runs migrations; use a dedicated migrate status / migrate apply release step.

Create a review-only App Spec draft from an existing PostgreSQL schema:

appstruct db pull --schema public --output spec/imported.yaml

The command reads DATABASE_URL, never changes the database or root includes, and refuses to overwrite the output. Review unsupported-shape warnings and add explicit entity access rules before including the draft in appstruct.yaml.

Generated list endpoints offer offset pagination with totals and primary-key cursor pagination for large result sets. A filterable relation can traverse one hop to target fields that are also marked filterable, while retaining target access and tenant scopes. Each resource also exposes bounded count/sum/average/min/max and group-by queries over filterable fields. See Generated resource queries for request, response, OpenAPI, and TypeScript client contracts. Fields can additionally declare independent read/write access rules; unauthorized response fields are omitted and unauthorized submitted fields are rejected by the backend.

Composite and partial indexes are declared per entity with indexes; see Schema indexes.

Named entity seed rows are declared with seeds and included in reviewable migrations; see Seed data.

Enable tenant isolation together with Auth and mark each tenant-owned entity explicitly:

modules:
  auth:
    enabled: true
    user_entity: User
  tenant:
    enabled: true

entities:
  Project:
    tenant: true

The generated Web application provides organization onboarding and switching. Generated clients send X-AppStruct-Tenant; the backend validates membership and injects tenant_id into every tenant-scoped CRUD query and write.

Enable Audit with Auth, choose the reader roles, and opt entities into transactional snapshots:

modules:
  audit:
    enabled: true
    reader_roles: [admin]

entities:
  Project:
    audit: true

Create, update, and delete snapshots are committed in the same PostgreSQL transaction as the business write. The generated Audit page and read-only API enforce reader roles and current-tenant isolation.

Mail supports compile-time validated templates and capture, SMTP, or Resend providers. Provider credentials remain in server environment variables, and business handlers can call the generated RequestContext::send_mail capability. Capture is development-only and rejected in production.

Select the official SaaS preset to enable the implemented modules with one versioned contract:

preset:
  name: appstruct/saas
  version: 1

The project must commit an appstruct.lock containing the preset digest and exact module versions. User modules mappings override defaults recursively; scalar and list values replace their defaults. Inspect the locked contract with appstruct preset show or print the effective module configuration after project overrides with appstruct preset show --expanded. Admin is available as an operations preview with Jobs recovery controls; Billing is not part of preset version 1.

Commands

appstruct new <name> --template minimal|dashboard|saas
appstruct schema
appstruct check [--deny-warnings] [--format text|json]
appstruct generate [--check]
appstruct migrate plan|dev|lint|apply|status
appstruct dev [--api-port <port>] [--web-port <port>]
appstruct build
appstruct doctor [--format text|json]
appstruct db pull [--schema <name>] [--output <project-relative-path>]
appstruct auth bootstrap-admin --email <address>
appstruct preset show [--expanded]
appstruct update

migrate plan is read-only. migrate dev --accept creates and optionally applies only non-destructive online migrations. Production deployment uses migrate status followed by the explicit migrate apply command. migrate lint reports destructive, locking, and unsafe non-null changes without writing files; use --deny-warnings in CI to enforce operational review.

Documentation

The references/ directory contains local research material and is intentionally excluded from version control and product commits.

Development

Run the repository quality gates with the pinned local toolchain:

cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace

Run the PostgreSQL browser gate against a dedicated test database:

APPSTRUCT_E2E_DATABASE_URL='postgresql://user:password@127.0.0.1/appstruct_e2e' \
  scripts/run-m5-browser-e2e.sh

APPSTRUCT_E2E_DATABASE_URL='postgresql://user:password@127.0.0.1/appstruct_tenant_e2e' \
  scripts/run-m6-tenant-e2e.sh

APPSTRUCT_E2E_DATABASE_URL='postgresql://user:password@127.0.0.1/appstruct_audit_e2e' \
  scripts/run-m6-audit-e2e.sh

APPSTRUCT_E2E_DATABASE_URL='postgresql://user:password@127.0.0.1/appstruct_mail_e2e' \
  scripts/run-m6-mail-e2e.sh

APPSTRUCT_E2E_DATABASE_URL='postgresql://user:password@127.0.0.1/appstruct_jobs_e2e' \
  scripts/run-m6-jobs-e2e.sh

APPSTRUCT_E2E_DATABASE_URL='postgresql://user:password@127.0.0.1/appstruct_file_e2e' \
  scripts/run-m6-file-e2e.sh

APPSTRUCT_E2E_DATABASE_URL='postgresql://user:password@127.0.0.1/appstruct_saas_e2e' \
  scripts/run-m6-saas-e2e.sh

Rust source files are limited to 400 lines by a repository test. Generated projects also pin their Rust and pnpm dependency graphs so repeated generation and production builds remain reviewable and reproducible.

Before committing or pushing a change, inspect the worktree and run the checks that match the files you changed:

git status --short --branch
git status --short --ignored
git diff --check
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace

Do not commit local secrets or generated machine state. In particular, keep .env files (except intentional .env.example templates), private keys and certificates, node_modules/, target/, references/, Playwright reports, and test-results/ out of Git. The repository .gitignore already excludes these paths; verify tracked, untracked, and ignored state before the first push.

License

Workspace crates are licensed under MIT OR Apache-2.0.