Transactions and file tools

autosave(doc_name: str | None = None, fallback_dir: str | None = None) -> list[TextContent]

Save Parashell documents to disk.

Saves the active document, a named document, or all open documents. Documents
that already have a file path are saved in place. Documents without a stored
path are written as <Name>.FCStd into fallback_dir, or into your home
directory (e.g. C:\Users\<you> on Windows) when fallback_dir is omitted.
Runs automatically before every execute_code call.

Args:
    doc_name: Name of a specific document to save. If omitted, all open
        documents are saved.
    fallback_dir: Directory used to save documents that have no FileName
        yet. If omitted, the user's home directory is used.

execute_code(code: str, reason: str, expected_action: str, transaction_id: str) -> list[TextContent | ImageContent]

Execute arbitrary Python code in Parashell.

Parashell exposes a FreeCAD-compatible Python API. Import the API
under its original module names inside the snippet - use 'import FreeCAD' and
'import FreeCADGui' with the FreeCAD-compatible API. Object TypeIds (e.g.
'Part::Box', 'PartDesign::Body') are FreeCAD-compatible.

Every model edit must run inside an open transaction. Open one with
transaction_create, pass its id here, then transaction_apply to persist the
changes or transaction_cancel to roll them back.

Args:
    code: The Python code to execute inside Parashell's interpreter.
    reason: A non-technical, straight-to-the-point explanation of why you
        are running this code. Must be between 10 and 25 words.
    expected_action: A non-technical, straight-to-the-point description of
        the expected output and logic. Must be between 5 and 15 words.
    transaction_id: Id of the open transaction returned by transaction_create.

is_file_saved(doc_name: str | None = None) -> list[TextContent]

Report whether a document is saved to a file on disk.

Args:
    doc_name: Document to check. If omitted, the active document is used.

request_file_save(doc_name: str | None = None, suggested_name: str | None = None) -> list[TextContent]

Ask the user where to save a model via a save-location prompt.

Opens a dialog letting the user pick a folder and a file name (the .FCStd
extension is fixed), then saves the document there. Use this when a model has
no save location yet so applied changes persist where the user wants. Returns
where the model was saved, or that the user cancelled.

Args:
    doc_name: Document to save. If omitted, the active document is used.
    suggested_name: Optional default file name to pre-fill (without extension).

rollback_to_transaction(transaction_id: str) -> list[TextContent | ImageContent]

Hard-reset a document to the exact state before an applied transaction.

Like reverting a commit and every commit above it: restores the pre-change
checkpoint captured before the given transaction opened, discarding the target
transaction's edits and every later change. Transactions newer than the target
are marked cancelled. Restoration verifies document identity and the checkpoint
object set before autosave. This destroys applied work - confirm with the user
before using it when changes would be lost.

Args:
    transaction_id: Id of the applied transaction whose changes should be removed.

transaction_apply(transaction_id: str) -> list[TextContent | ImageContent]

Apply an open transaction: commit its changes, recompute, and save.

Finalizes every edit made under the transaction as a single atomic change,
recomputes the document, and autosaves it (to its existing path, or to your
home directory as <Name>.FCStd if it has none). The transaction becomes
'applied'.

Args:
    transaction_id: Id of the open transaction to apply.

transaction_cancel(transaction_id: str) -> list[TextContent | ImageContent]

Cancel a transaction and roll back its changes.

For an open transaction this aborts and undoes every change made under it.
For an already-applied transaction it undoes the committed change (only
possible if no newer transaction sits on top of it). The transaction becomes
'cancelled' and can then be removed with transaction_delete.

Args:
    transaction_id: Id of the transaction to cancel.

transaction_create(doc_name: str, label: str | None = None, reason: str | None = None) -> list[TextContent]

Open a new transaction against a document and get its id.

Transactions work like Terraform: open one here, route every edit
(create_object, edit_object, delete_object, insert_part_from_library,
execute_code, and any other model change) through its id while it is open,
review the pending changes with transaction_plan, then transaction_apply to
persist and save them or transaction_cancel to roll everything back. Creation
writes a pre-change file checkpoint before opening the native transaction and
fails safely if that checkpoint cannot be created. Only one transaction can be
open per document at a time.

Args:
    doc_name: Document to open the transaction on.
    label: Optional human label for the transaction.
    reason: Optional explanation of what this transaction is for.

transaction_delete(transaction_id: str) -> list[TextContent]

Permanently remove a transaction record.

Only cancelled transactions can be deleted; cancel an open or applied
transaction first. This purges the bookkeeping record only - the document is
not modified.

Args:
    transaction_id: Id of the cancelled transaction to delete.

transaction_get(transaction_id: str) -> list[TextContent]

Get the full record of a single transaction, including its operation log.

Args:
    transaction_id: Id of the transaction to inspect.

transaction_list(doc_name: str | None = None) -> list[TextContent]

List tracked transactions and their status.

Args:
    doc_name: Optional document to filter by. If omitted, lists all
        transactions across every document.

transaction_plan(transaction_id: str) -> list[TextContent]

Preview the pending changes of a transaction without persisting them.

Returns a Terraform-style plan of what would change on apply: objects to add,
change, and destroy, plus the recorded operation log. Safe to call repeatedly.

Args:
    transaction_id: Id of the transaction returned by transaction_create.