ArtCraft Desktop (fresh start)

This is a fresh start for the `artcraft` repo.

The old monorepo, which included our web API gateway, job services, SRE
tools, various frontends, and more has moved to `artcraft-services`

You can find the full git history here:

https://github.com/storytold/artcraft-services

This change was motivated by the fact that the entire git history was
hundreds of gigabytes in size, which is unwieldy for anyone not in the
core team that doesn't care about support services outside of the core
artcraft app.

We wanted to keep this repo in its well-known place since we already
have users and activity here.

Please update your remotes to either `artcraft-services` or make a fresh
clone of this repo.

History can be found at the artcraft-services repo.

.claude/rules/api-conventions.md

@@ -0,0 +1,56 @@
+# API Conventions
+
+## HTTP Handlers (Actix-Web)
+
+Handlers in `storyteller_web` follow this structure:
+
+1. **Request/Response types** with `#[derive(Deserialize/Serialize, ToSchema)]`
+2. **Error enum** implementing `ResponseError`, `Display`, `Serialize`, `ToSchema`
+3. **Handler function** annotated with `#[utoipa::path(...)]` for OpenAPI docs
+4. Handler returns `Result<Json<Response>, ErrorType>`. Only use `Result<HttpResponse, ErrorType>` when you need to set headers/cookies.
+
+### Error Types
+
+- Use `CommonWebError` for simple handlers that only need standard HTTP error codes
+- Use a custom error enum when you need endpoint-specific error variants (e.g. `LoginErrorType::InvalidCredentials`)
+- Custom error enums MUST implement `ResponseError` (actix), `Display`, and `Serialize`
+- When adding `From<RequireUserSessionError>` or similar conversions, implement them on `CommonWebError` in its own module (orphan rule)
+- Error response bodies include: `success: false`, `error_code`, `error_code_str`
+
+### Session/Auth
+
+Helpers live in `storyteller_web` under `http_server/web_utils/user_session/`. Each takes a
+generic `mysql_executor: E` (any `sqlx::Executor`), so whether it reuses a connection or acquires
+its own depends on the **argument you pass**:
+
+- `require_user_session(http_request, session_checker, mysql_executor)` — require a logged-in user.
+- `require_user_session_extended(...)` — same, with extra session detail.
+- `require_moderator(http_request, session_checker, mysql_executor)` — admin-only endpoints.
+
+PREFER passing an already-open connection (`&mut *conn`) so the helper reuses it. Passing
+`&server_state.mysql_pool` makes it acquire a fresh connection — avoid that when the handler
+already holds one (the double-acquire adds pool pressure; this crate has had pool-timeout
+incidents). There is no `*_using_connection` variant — the reuse/acquire choice is the argument.
+
+### API Type Definitions
+
+- Shared request/response types go in `artcraft_api_defs` crate (under `crates/api_clients/artcraft/artcraft_api_defs/`)
+- Types that need `ResponseError` impl must stay in `storyteller_web` (orphan rule)
+- New types must be added to `api_doc.rs` schemas (in storyteller-web) for Swagger generation
+
+## Enums (Database-backed)
+
+- Located in `crates/schema/public/enums/src/by_table/{table_name}/`
+- Require manual `to_str()` and `from_str()` implementations
+- Use `impl_enum_display_and_debug_using_to_str!` and `impl_mysql_enum_coders!` macros
+- Add comprehensive tests: serialization, round-trip, variant count
+- YOU CAN ADD NEW VALUES but DO NOT CHANGE EXISTING VALUES without a migration strategy
+- Note that adding new values can break older versions of the Tauri desktop app that read
+  responses over Rust - make sure it consumes variants with an "Unknown(String)" variant 
+  catch-all to future proof the APIs.
+
+## Tokens (Primary Keys)
+
+- Located in `crates/schema/public/tokens/src/tokens/`
+- Opaque `String` wrappers with Stripe-like prefixes (e.g. `user_`, `mf_`)
+- Use `impl_string_token!`, `impl_mysql_token_from_row!`, `impl_crockford_generator!` macros

.claude/rules/code-style.md

@@ -0,0 +1,92 @@
+# Code Style
+
+## Rust
+
+- Two spaces for indentation (not four)
+- No minimum supported Rust version; use latest stable features freely
+- `#[macro_use] extern crate serde_derive;` is used in binary crates; library crates use `use serde_derive::{Serialize, Deserialize};`
+- Never use `println!` or `eprintln!` outside of tests; use `log` crate macros (`info!`, `warn!`, `error!`, `debug!`, `trace!`) instead
+- Use `anyhow::Result` / `AnyhowResult` for fallible functions in application code; new database queries should use `Result<T, sqlx::Error>` instead
+- SQLx: MySQL queries belong in the `mysql_queries` crate. Do NOT write `sqlx::query!` /
+  `sqlx::query()` in application/service crates (e.g. `storyteller-web`, which has zero direct
+  SQLx queries) — add or reuse a function in `mysql_queries` and call it. The compile-time
+  `query!` / `query_as!` macro conventions for that crate are documented in
+  `crates/schema/database/mysql_queries/CLAUDE.md`.
+- Enum Display/Debug: use `impl_enum_display_and_debug_using_to_str!` macro, not `derive_more::Display` (CLion doesn't understand it)
+- Fields that are optional use the `maybe_` prefix: `maybe_creator_user_token`, `maybe_prompt_token`
+- When implementing `fmt::Display` for error types, use the pattern: `write!(f, "{:?}", self)`
+
+## File Layout (Top-to-Bottom Reading Order)
+
+Organize code so a human reading top-to-bottom encounters the most important things first and
+can drill down into details only when curious. Think of it like a newspaper: headline first,
+then the story, then the fine print.
+
+### Ordering within a file
+
+1. **Constants** at the top, right after imports.
+2. **The primary public type** (the main struct/enum the file is about) comes next.
+   A reader opening this file should immediately see what it defines.
+3. **Supporting/subordinate types** (sub-structs, helper enums, serialization DTOs) go
+   below the primary type, not above it. Ask: "Would a reader need to know this type
+   exists before seeing the main type?" — if no, push it down.
+4. **Type ordering for API types**: Request, then Response (success), then Error.
+5. **`impl` blocks** after their type definitions.
+
+### Ordering within an `impl` block
+
+1. **Constructors** (`new`, `from_*`, `builder`) at the top.
+2. **Public methods** next — these are the main entry points a reader cares about.
+3. **Private helper methods** below public methods.
+   - Among helpers: place "meaty" helpers (substantial logic, direct continuations of the
+     public entry point) above "leaf" helpers (small formatters, simple lookups).
+   - A method that calls another method in the same file should appear *above* the method
+     it calls. This lets readers follow the call chain downward.
+
+### Ordering within test modules
+
+Put test cases first, helpers last. A reader opening a test file should immediately see
+*what* is being tested before *how* the test machinery works.
+
+1. **Imports**
+2. **Constants** (test IDs, URLs, fixture data) — small context that tests reference
+3. **Test functions** or **sub-modules** grouped by category
+4. **Helper functions** (builders, pipeline runners, assertions)
+
+Group related tests into sub-modules (`mod pricing_tests { ... }`) when a category has 2+
+tests. Don't create a sub-module for a single test. Keep nesting to two levels max
+(`mod tests { mod category { ... } }`). Shared helpers go in the parent module so
+sub-modules can reach them via `use super::*`.
+
+## Naming
+
+- Handler functions: `{verb}_{noun}_handler` (e.g. `get_health_check_handler`, `login_handler`)
+- Error enums: `{Feature}Error` (e.g. `FalWebhookError`, `HealthCheckError`)
+- Request/response structs: `{Action}Request`, `{Action}Response`, `{Action}SuccessResponse`
+- Path params: `{Action}PathInfo`
+- Builder structs: `{Thing}Builder` with `set_` prefixed setters and a `build()` method
+
+## Imports
+
+- Group imports: std, external crates, internal workspace crates, `crate::` imports
+- Prefer `use` imports over inline fully-qualified paths. Inline qualification is acceptable
+  only for genuine one-off references where adding an import would be noise, or for types
+  that collide with std prelude names (`Result`, `Option`, `Error`). If you reference a symbol
+  more than once, always import it.
+- Prefer specific imports over wildcards, except in `api_doc.rs` and test modules
+- When two crates export a type with the same name, alias with a suffix describing the source crate:
+  `use enums::...::CommonResolution as CommonResolutionEnum;`
+  `use artcraft_router::...::CommonResolution as CommonResolutionRouter;`
+  This avoids long fully-qualified paths in function signatures and bodies.
+
+## MySQL 
+
+- MySQL tables: primary key `id` columns must be `BIGINT(20) UNSIGNED`. Do not use signed IDs. 
+- Always create tables with `ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin`.
+
+## TypeScript / Frontend
+
+- TypeScript with React, Vite, Zustand, Three.js
+- Nx monorepo under `crates/frontend/`
+- Two spaces for indentation
+

.claude/rules/testing.md

@@ -0,0 +1,73 @@
+# Testing
+
+## Database Fixture Tests
+
+- Live in-crate (e.g. `storyteller-web`'s omni_gen video pricing tests) and
+  use the `mysql_testing` crate (`crates/schema/database/mysql_testing`) for
+  guarded pools, schema setup, and account/session/wallet fixtures
+- They RUN BY DEFAULT with `cargo test -p storyteller-web` and from the IDE
+  (requires a local MySQL with an `artcraft_test` database). Machines/CI
+  without MySQL skip them via the off switch:
+  `SQLX_OFFLINE=true cargo test -p storyteller-web --features skip_database_tests`
+- They connect ONLY via `ARTCRAFT_TEST_DATABASE_URL` (default
+  `mysql://root:@localhost:3306/artcraft_test`); the guard panics on any
+  database whose name lacks "test", on `storyteller`/`artcraft`, and on
+  cloud hosts — see `mysql_testing/README.md`
+- Database tests run in PARALLEL: each test creates its own users, wallets,
+  and rows; schema setup single-flights via a MySQL named lock. Only tests
+  mutating shared/global state take
+  `mysql_testing::serial::acquire_serial_test_lock().await`
+- External providers must never be called: the harness stubs Kinovi with an
+  in-process HTTP server via `KINOVI_CUSTOM_API_HOST`/`KINOVI_CUSTOM_CDN_HOST`
+
+## Running Tests
+
+- Most crates: `cargo test -p {crate_name}`
+- Crates using SQLx offline mode: `SQLX_OFFLINE=true cargo test -p {crate_name}`
+- The `storyteller-web` and `mysql_queries` crates require `SQLX_OFFLINE=true` for compilation
+- Use `cargo check -p {crate_name}` for fast compilation checks without running tests
+
+## Test Patterns
+
+- Tests live in `#[cfg(test)] mod tests { ... }` at the bottom of each file
+- Group related tests into sub-modules by category (e.g. `mod pricing_tests`, `mod resolution_tests`)
+- Only create a sub-module when it has 2+ tests — don't wrap a single test in its own module
+- Keep nesting shallow: `mod tests { mod category { ... } }` is fine; a third level is rarely needed
+- Shared helpers used by multiple sub-modules belong in the parent `mod tests`, not duplicated in each sub-module
+- Enum tests should cover: serialization, deserialization, `to_str`/`from_str` round-trip, variant count
+- Password/crypto tests: be mindful of computation cost, don't add too many bcrypt test cases
+
+## Test File Layout
+
+Put test cases first, helpers last. Engineers should see the actual tests before scrolling
+to understand helper plumbing.
+
+Within a `mod tests { ... }` block:
+
+1. **Imports** at the top
+2. **Constants** (test data IDs, URLs, etc.) — small context that tests reference
+3. **Test functions** (`#[test]` / `#[tokio::test]`) grouped by category
+4. **Helper functions** (builders, pipeline runners, etc.) at the very bottom
+
+If tests are grouped into sub-modules, the same rule applies within each sub-module:
+constants first, then tests, then helpers at the end of that sub-module.
+
+## What to Test
+
+- New error types and their mappings
+- Enum variant serialization stability (these are stored in the database)
+- Hash/deduplication functions with known inputs
+- Edge cases in parsers (empty input, missing fields, malformed data)
+
+## Imports in Tests
+
+- Import test fixtures and constants with `use`, not inline fully-qualified paths.
+  Write `use test_data::web::image_urls::JUNO_AT_LAKE_IMAGE_URL;` at the top,
+  then reference `JUNO_AT_LAKE_IMAGE_URL` in test bodies.
+- Same rule applies to enum variants used in match arms — import them, don't write
+  `crate::some::deep::module::MyEnum::Variant` inline.
+
+## What Not to Test
+
+- Don't add integration tests that require a running database unless explicitly asked
+- Don't add tests for simple struct construction or trivial getters