Files
craft-anything/docs/tools.md
Herwin bd405ceeb5 Study websites behind a login: save a sign-in you make in a browser window and reuse it (R2.9) (#1459)
Addresses #1178 (which also consolidates #1277).

## The problem

The website study a build starts with opens a fresh private browser, so a web app behind a login is studied as its sign-in or landing page, and the builder then builds a sign-in page.

## What this adds

- **`web_site_sign_in { url }`** opens a visible browser window on the site. The person signs in there themselves and closes the window. The browser's profile is then saved in Craft Anything's own folder, keyed by the site's host and port. Craft Anything never sees or stores a password and still never reads cookie or storage values.
- **`web_site_open`** uses a saved sign-in for that exact host and port when there is one, by copying it into the usual temporary profile (headless as before, deleted afterwards). `signed_in: false` forces the private profile; `signed_in: true` with nothing saved is a clear error naming the sign-in tool. Nothing else about the private path changes.
- **`web_site_sign_out { url }`** forgets a saved sign-in.
- **A check right after saving.** The sign-in tool reopens the site headless exactly as a later study will, and reports whether it still looks like a sign-in page, plus a screenshot kept in the site's owner-only folder (path, hash and size are returned, not the picture, so the person's account screen is not sent to an agent).
- **Typed facts through to the builder.** `signed_in`, `signed_in_site` and `sign_in_page` are in the open result, the capture result and `capture.json`. The website briefs tell the builder the capture is the signed-in view only when it is signed in and does not look like a sign-in page. A not-signed-in capture with a password field says how to sign in; a signed-in one says the sign-in may have ended.
- The check phase opens the built site with `signed_in: false`.

Because a study already starts with `web_site_open`, a normal build of that site is signed in after one `web_site_sign_in`, with no new build option.

## Decisions for maintainers

These are policy calls I made so the change is usable; each is small to reverse.

1. **Clean room allows the two tools** (two lines in `clean_room.rs`). Reasoning: the person signing in as themselves and looking at pages is watching from outside, as a user would; `visitor_view()` strips exactly what it did before.
2. **A saved sign-in is used by default** for later opens of that site, until `web_site_sign_out`. Saving it is treated as the consent, and the tool text and evidence say so. The alternative is opt-in per study, which needs an option in the Make screen and `rebuild`.
3. **Restricted MCP mode refuses both tools even with `--allow-web`**, since sign-in opens a window on the person's desktop.
4. The saved profile sits on disk (owner-only on Unix; on Windows it relies on the per-user config folder). On Linux it is launched with the basic password store so the visible and headless launches can read the same cookies. The tool text says that anyone who can open the person's files could use the sign-in.

## Trade-offs and limits

- Needs a desktop: on a computer with no display the tool refuses at once with what to do instead.
- Sites that tie a sign-in to the browser, or expire it quickly, will capture signed out; the check after saving and the `sign_in_page` field say so.
- Session-only cookies are kept by setting the profile to continue where it left off; restored tabs are not copied.
- The saved profile can also hold single sign-on providers' sign-ins made in that window. It is used only when that exact host and port is opened.
- Screenshots and page text of a signed-in study contain the person's own account data; the evidence says so. Result URLs drop the query and fragment when a sign-in is used.
- Not in this PR (roadmap lines added under R2.9): a Make-screen button, showing the person the study's first screenshots to confirm before the builder starts, attaching to the person's running browser, refreshing a saved sign-in from a capture, and a live run on a real site and with the Snap browser.

## What was verified

Run locally on Linux (x86-64), on the branch before its final rebase onto `main` (the rebase was clean; after it: `cargo fmt --all --check`, `cargo xtask layers`, `locks`, `secrets`, `tools --check`, `i18n-coverage` pass):

- `cargo test -p craft-anything-engine` (583 passed, 12 ignored), `-p craft-anything-mcp` (22), `-p craft-anything-ai` (580, 3 ignored).
- `cargo clippy -p <crate> --all-targets -- -D warnings` for engine, mcp and ai.
- **Live, with Chromium 157 under a virtual display against a local test site** (the new `#[ignore]` tests in `site_sign_in/tests.rs`; a helper plays the person over the browser's own debugging port and closes the window):
  - a sign-in made in the visible window is seen by a later headless open and capture, including an HttpOnly cookie and a session-only cookie (removing the continue-where-you-left-off setting makes that assertion fail, so the setting is what keeps it);
  - `signed_in: false` and a signed-out site show the signed-out page with the private-profile limitation;
  - a site that forgets the cookie is reported as still a sign-in page by the check after saving;
  - two overlapping signed-in opens both work and leave the saved sign-in byte-identical;
  - the timeout path stops the browser, keeps what was saved and leaves no process behind;
  - with no display the tool refuses immediately.
  - The two existing live website tests still pass.

**Not verified:** a real third-party site; a confined Snap or Flatpak browser (reasoned from the existing profile-location code, not run); Windows and macOS behaviour, including the browser-exit signal (the profile lock going away) and cookie decryption there; the workspace-wide `cargo xtask ci` steps and `--features wasm-plugins` (not enough disk locally, so CI is the first run of those); how the egui app shows the new tools.

An independent review pass was done before opening; its findings (copying only after the browser has exited, not treating one slow probe as a closed window, a whole-or-nothing replacement of the saved profile, reserved Windows names in site keys, owner-only permissions) are fixed in the later commits.
2026-11-15 17:28:04 +01:00

363 lines
15 KiB
Markdown

# Tools
Generated by `cargo xtask tools`. Do not edit by hand.
**305 engine tools** in 17 toolsets. Each is an MCP tool, a CLI command (`craft-anything-cli <id with dashes>`) and a tool the agent can call. The AI and setup layers add their own on top (`rebuild_*`, `assets_key_*`, `ai_models_list`, `ai_model_set`, `setup_*`); `craft-anything-cli commands` lists them all. [OpenCode model and thinking selection](opencode.md) describes the AI model tools.
## Essentials (`core`, 36)
- `core_target_open`: Open
- `core_target_close`: Close
- `core_session_show`: Session status
- `core_targets_list`: List open targets
- `core_target_select`: Switch target
- `core_evidence_show`: Evidence so far
- `core_evidence_export`: Export evidence
- `core_evidence_import`: Import evidence
- `core_unknowns_show`: Open questions
- `core_unknown_add`: Record an open question
- `core_unknown_edit`: Update an open question
- `core_unknown_verify`: Check an answer
- `core_archive_show`: Inventory an archive or app bundle
- `core_archive_extract`: Extract an archive
- `core_archives_compare`: Compare two artifacts
- `core_person_ask`: Ask the person
- `core_action_approve`: Approve an agent action
- `assets_image_generate`: Generate a picture
- `assets_model_generate`: Generate a 3D model
- `core_investigation_show`: Investigation so far
- `core_brief_write`: Write the brief
- `core_plan_update`: Update the plan
- `core_hypothesis_record`: Record a hypothesis
- `core_hypothesis_update`: Update a hypothesis
- `core_finding_record`: Record a finding
- `core_finding_edit`: Update a finding
- `core_handoff_write`: Write the handoff
- `core_journal_read`: Read the journal
- `core_report_save`: Save a report
- `core_report_write`: Write a readable report
- `core_overview_show`: Overview
- `native_function_study`: Function dossier
- `core_feature_find`: Trace a feature
- `core_target_triage`: What is this?
- `core_evidence_browse`: Page through evidence
- `core_text_read`: Read a text file
## Programs (native code) (`native`, 55)
- `native_cursor_show`: Where am I
- `native_functions_list`: List functions
- `native_sections_list`: List segments
- `native_strings_browse`: List strings
- `native_named_addresses_list`: List names
- `native_open_documents_list`: List documents
- `native_bookmarks_show`: List bookmarks
- `native_functions_search`: Search functions
- `native_strings_find`: Search strings
- `native_bytes_show`: Read bytes
- `native_address_offset_show`: Address to file offset
- `native_xrefs_list`: Cross-references
- `native_name_show`: Name at address
- `native_comment_read`: Read comment
- `native_inline_comment_read`: Read inline comment
- `native_function_show`: Function info
- `native_function_disassemble`: Function assembly
- `native_function_callees_list`: What it calls
- `native_function_callers_list`: Who calls it
- `native_function_references_list`: Function references
- `native_function_pseudocode`: Decompile
- `native_function_address_show`: Function address
- `native_function_instructions_list`: Function instructions
- `native_function_find`: Which function is this in
- `native_instruction_show`: Inspect instruction
- `native_call_site_resolve`: Resolve a call
- `native_data_show`: Inspect data
- `native_name_set`: Name an address
- `native_names_set`: Name many addresses
- `native_comment_write`: Write comment
- `native_inline_comment_write`: Write inline comment
- `native_bookmark_add`: Bookmark
- `native_bookmark_remove`: Remove bookmark
- `native_function_label`: Annotate function
- `native_cursor_address_show`: Cursor address
- `native_cursor_function_show`: Cursor function
- `native_document_show`: Current document
- `native_cursor_goto`: Go to address
- `native_cursor_forward`: Next address
- `native_cursor_back`: Previous address
- `native_call_graph_show`: Call graph
- `native_call_path_find`: Call path
- `native_functions_decompile`: Decompile many
- `native_name_xrefs_list`: References to a name
- `native_api_show`: API boundary
- `native_value_flow_show`: Value flow
- `native_dos_image_show`: DOS load image
- `native_address_show`: What's at this address
- `native_bytes_find`: Search for bytes
- `app_builds_line_up`: Match functions between two builds
- `native_source_folder_write`: Write pseudo-C to a folder
- `native_objdump_run`: objdump output
- `native_rizin_command_run`: Rizin command
- `native_cutter_sessions_list`: List shared Cutter sessions
- `native_cutter_command_run`: Cutter command
## Apple apps (`apple`, 14)
- `apple_objc_classes_list`: Objective-C classes
- `apple_objc_protocols_list`: Objective-C protocols
- `apple_swift_types_list`: Swift types
- `apple_dispatch_show`: Dispatch metadata
- `apple_ui_action_trace`: Trace a UI action
- `apple_macho_show`: Mach-O structure
- `apple_signature_show`: Code signature
- `apple_plist_show`: Property list
- `apple_slices_list`: Architectures
- `apple_swift_symbols_demangle`: Demangle Swift symbols
- `apple_nib_decode`: Interface Builder documents
- `apple_archive_decode`: Keyed archive
- `apple_assets_list`: Asset catalog
- `apple_dylibs_resolve`: Library resolution
## File formats (`formats`, 36)
- `web_recording_show`: Inspect a network recording
- `native_pe_resources_list`: Windows resources
- `native_layout_show`: Binary layout
- `native_crash_show`: Crash dump
- `native_go_binary_show`: Go program details
- `formats_wasm_module_show`: WebAssembly module
- `formats_evm_interface_show`: Smart contract interface
- `formats_sbpf_show`: Solana program (sBPF)
- `formats_sbpf_disassemble`: Disassemble sBPF code
- `firmware_regions_list`: Firmware regions
- `firmware_image_extract`: Extract firmware
- `core_packed_files_list`: Files packed inside a file
- `core_packed_files_unpack`: Take out packed files
- `formats_bytecode_show`: Compiled Python file
- `game_archives_list`: List a game's archives
- `game_pak_list`: List an Unreal pak
- `game_iostore_list`: List an Unreal IoStore container
- `game_unity_list`: List a Unity assets file
- `game_unity_bundle_list`: List a Unity bundle
- `game_unity_asset_export`: Take an asset out of a Unity game
- `game_unreal_texture_export`: Take a texture out of an Unreal game
- `game_pak_extract`: Take files out of an Unreal pak
- `game_unity_code_names_show`: Read a Unity game's IL2CPP metadata
- `app_folder_explain`: Work out what an installed app is built on
- `native_rust_binary_show`: Rust program details
- `native_library_calls_list`: What a program imports
- `native_offered_symbols_list`: What a program exports
- `native_publisher_show`: Who signed this Windows program
- `formats_ai_weights_show`: AI model file
- `formats_wasm_compare`: Compare WebAssembly interfaces
- `packets_capture_show`: Packet capture overview
- `packets_fields_show`: Packet fields
- `engines_tshark_check`: Wireshark tools check
- `packets_inventory_show`: Capture inventories
- `radio_recording_decode`: Decode a radio recording
- `radio_decoders_list`: List radio decoders
## .NET apps (`managed`, 8)
- `managed_assembly_show`: .NET assembly overview
- `managed_members_list`: .NET types and methods
- `managed_native_calls_list`: .NET native calls
- `managed_assemblies_compare`: Compare two .NET builds
- `managed_native_calls_verify`: Check .NET native calls
- `managed_reconstruction_check`: Check decompiled C#
- `managed_app_graph_build`: .NET application graph
- `managed_ilspy_decompile`: ILSpy decompile
## Android apps (`android`, 14)
- `android_package_show`: Android app package
- `android_classes_find`: Find Android classes
- `android_class_show`: Android class
- `android_method_show`: Android method bytecode
- `android_class_users_find`: Who uses this Android class?
- `android_resources_read`: Android resources
- `android_components_list`: Android app components
- `engines_apktool_check`: Is Apktool available?
- `android_flutter_identify`: Identify a Flutter build
- `android_dart_snapshot_show`: Inspect a Dart AOT snapshot
- `engines_jeb_check`: Check the JEB connection
- `android_jeb_open`: Open a file in JEB
- `android_jeb_units_browse`: List JEB units
- `android_jeb_decompile`: Decompile with JEB
## Java programs (`java`, 6)
- `java_archive_show`: Java archive overview
- `java_classes_find`: Find Java classes
- `java_class_show`: Java class
- `java_method_show`: Java method bytecode and pseudo-Java
- `java_class_users_find`: Who uses this Java class?
- `java_vineflower_decompile`: Decompile Java with Vineflower
## Connected phone (`adb`, 24)
- `engines_adb_check`: Is adb available?
- `adb_devices_find`: Connected devices
- `adb_device_show`: Device details
- `adb_apps_list`: Installed apps
- `adb_log_read`: Device log
- `adb_app_show`: App details on device
- `adb_running_processes_list`: Running processes
- `adb_folder_list`: Device folder
- `adb_device_features_list`: Device features
- `adb_system_services_list`: System services
- `adb_display_show`: Display info
- `adb_window_show`: Window / focus info
- `adb_setting_get`: Read a setting
- `adb_apps_find`: Find an app
- `adb_app_download`: Copy an app off the phone
- `adb_file_download`: Copy a file off the phone
- `adb_screenshot_take`: Screenshot
- `adb_bugreport_save`: Bug report
- `adb_file_upload`: Copy a file to the phone
- `adb_app_install`: Install an app
- `adb_app_remove`: Remove an app
- `adb_app_launch`: Launch an app
- `adb_activity_open`: Start an activity
- `adb_app_force_stop`: Force-stop an app
## Websites (`browser`, 24)
- `web_browser_connect`: Connect to a browser
- `web_pages_list`: List browser pages
- `web_page_show`: Inspect a web page
- `web_page_js_analyze`: Analyse a page's JavaScript
- `web_page_watch`: Watch a page over time
- `web_mcp_tools_list`: Find in-page MCP tools
- `web_page_screenshot_take`: Screenshot a page
- `web_snapshots_compare`: Compare two page captures
- `web_pixels_compare`: Compare two screenshots
- `web_walkthrough_record`: Run a scripted web session
- `web_walkthrough_check`: Check a scripted web session
- `web_site_open`: Open a website
- `web_site_capture`: Capture a website for rebuilding
- `web_page_states_capture`: Capture menus, dialogs and tabs
- `web_site_close`: Close the website
- `web_site_sign_in`: Sign in to a website
- `web_site_sign_out`: Forget a website sign-in
- `web_standin_build`: Build a stand-in backend
- `web_standin_start`: Start a stand-in backend
- `web_standin_stop`: Stop a stand-in backend
- `web_standin_show`: See what a stand-in was asked
- `web_coverage_measure`: Measure which code ran
- `web_listeners_list`: List a node's event listeners
- `web_modules_trace`: Map a page's module graph
## Electron and JavaScript (`javascript`, 11)
- `js_app_map`: Analyse a JavaScript app
- `js_runtime_code_match`: Match static code to what ran
- `web_scripts_save`: Export captured scripts
- `js_source_locate`: Find the original source line
- `js_sources_restore`: Recover readable sources
- `js_electron_pages_list`: List Electron pages
- `js_electron_page_show`: Inspect an Electron page
- `js_electron_walkthrough_record`: Run a scripted Electron session
- `js_runtimes_list`: List JS runtime targets
- `js_runtime_watch`: Observe a JS runtime
- `js_electron_fuses_show`: Electron fuses
## Running programs (`runtime`, 14)
- `native_window_capture`: Picture a program's window
- `runtime_walkthrough_record`: Run and watch a program
- `runtime_captures_compare`: Compare two runs
- `runtime_ui_read`: Read an app's screen
- `runtime_ui_walkthrough_record`: Drive an app's screen
- `apple_calls_observe`: Watch a Mac app's calls
- `native_gdb_session_begin`: Start a GDB session
- `native_gdb_command_run`: GDB command
- `native_gdb_session_show`: GDB session status
- `native_gdb_session_end`: Close a GDB session
- `native_rizin_session_begin`: Start a Rizin debug session
- `native_rizin_session_command_run`: Rizin debug command
- `native_rizin_session_show`: Rizin debug session status
- `native_rizin_session_end`: Close a Rizin debug session
## Frida instrumentation (`frida`, 9)
- `frida_devices_find`: Frida devices
- `frida_targets_list`: Frida processes
- `frida_session_begin`: Start a Frida session
- `frida_script_run`: Run a Frida script
- `frida_session_continue`: Resume a Frida session
- `frida_script_forget`: Unload a Frida script
- `frida_session_show`: Frida session status
- `frida_session_end`: Close a Frida session
- `frida_instrument_run`: One-shot instrumentation
## Comparing and rebuilding (`application`, 17)
- `app_feature_follow`: Trace a feature
- `js_function_explain`: Explain a function
- `app_graphs_compare`: Compare two app versions
- `js_exports_compare`: Compare module exports
- `app_source_import`: Import a source folder
- `js_source_bundle_compare`: Line up source with the bundle
- `app_ledger_build`: Build a rebuild ledger
- `app_coverage_evaluate`: How complete is the rebuild
- `android_app_graph_build`: Map an Android app
- `apple_app_graph_build`: Map an Apple app
- `harmony_app_graph_build`: Map a HarmonyOS app
- `app_function_versions_compare`: Compare two functions
- `core_evidence_exports_compare`: Compare two evidence bundles
- `app_changes_summarize`: Summarise what changed
- `app_call_path_find`: Find a call path
- `app_runtime_correlate`: Line up code and behaviour
- `app_rebuild_claim_check`: Check a rebuild claim
## Databases (`database`, 1)
- `db_sqlite_show`: SQLite database contents
## Projects (`projects`, 21)
- `project_list`: List projects
- `project_show`: Show a project
- `project_inbox_answer`: Answer a project's question
- `project_play`: Play a project's result
- `project_preview`: Preview a project's website
- `project_open_folder`: Open a project's folder
- `project_rename`: Rename a project
- `project_plan_fold`: Fold a project's plan
- `project_duplicate`: Duplicate a project
- `project_delete`: Delete a project
- `project_questions_set`: Choose what the builder's questions get
- `project_approvals_set`: Choose what the builder's approvals get
- `project_build_finish`: Call the build done
- `project_assets_budget`: Set a project's asset budget
- `project_assets_allow`: Let a project generate assets
- `project_pin_create`: Pin a project's build
- `project_pins_list`: List pinned builds
- `project_pin_open`: Open a pinned build
- `project_pin_stop`: Stop a pinned build
- `project_pin_rename`: Rename a pinned build
- `project_pin_delete`: Remove a pinned build
## Engines and settings (`setup`, 9)
- `engines_list`: List engines
- `engines_install`: Install an engine
- `settings_show`: Show settings
- `settings_set`: Change a setting
- `plugins_list`: List plugins
- `plugins_refresh`: Refresh plugins
- `plugins_add`: Add a plugin
- `plugins_remove`: Remove a plugin
- `engines_app_open`: Open an engine's app
## Building (`build`, 6)
- `build_files_list`: List project files
- `build_file_read`: Read a project file
- `build_file_write`: Write a project file
- `build_file_edit`: Edit a project file
- `build_checklist`: Update the checklist
- `build_command_run`: Run a build command