cli¶

def upload_controller(
    ctx: typer.Context,
    file_path: UploadFilePathOpt = DEFAULT_PUBLISHED_FILE_PATH,
    target_folder: TargetFolderOpt = SHAREPOINT_REMOTE_OUTPUT_DIR,
    id_element: IdOpt = None,
) -> None:
    """
    Implements the `upload` CLI command: pushes the built load file to
    SharePoint for human review.

    Defaults `file_path` to the most-recently-modified file in `./output` if
    not given. If `id_element` is supplied, also writes the request's
    Workflow State to "Uploading" before the push (best-effort), and after a
    successful upload writes a sharing link to the "iMarina Excel output
    link" field (best-effort) — the trigger for the second Power Automate
    workflow that starts the Microsoft Approval requesting permission to
    publish (see CLAUDE.md's "Publish pipeline" section).

    Args:
        ctx (typer.Context): Typer's invocation context (unused directly;
            required so Typer's `--help` machinery can populate it).
        file_path (UploadFilePathOpt): The file to upload; autodetected from
            `./output` if not given.
        target_folder (TargetFolderOpt): SharePoint review folder to upload into.
        id_element (IdOpt): The request's Operation ID, if any, used to keep
            its Workflow State and output-link fields in sync.

    Raises:
        typer.Exit: With code 1 if the upload itself fails.
    """
    logger.info("Uploading the latest Excel file to SharePoint...")

    if file_path is None:
        file_path = select_file_to_upload(LOCAL_OUTPUT_DIR)

    logger.info(f"Local file detected: {file_path.name}")
    logger.info(f"Destination SharePoint: {target_folder}")

    if id_element is not None:
        try:
            update_list_item_fields(
                str(id_element), {FIELD_WORKFLOW_STATE: WorkflowState.UPLOADING}
            )
        except Exception:
            # Best-effort bookkeeping: must not block the actual upload below.
            logger.exception("Error updating Workflow State to Uploading")

    token_manager = get_token_manager()
    drive_id = read_secret(SecretName.DRIVE_ID)

    try:

        item_id = upload_file(
            token_manager=token_manager,
            local_file_path=file_path,
            target_folder=target_folder,
            drive_id=drive_id,
        )
        logger.info(f"Successfully uploaded {file_path.name}")

    # Broad on purpose: CLI boundary turns any failure into a clean exit(1).
    except Exception as e:
        logger.exception("Error uploading to SharePoint")
        raise typer.Exit(code=1) from e

    if id_element is not None:
        try:
            link = create_sharing_link(token_manager, drive_id, item_id)
            update_list_item_fields(
                str(id_element),
                {FIELD_IMARINA_EXCEL_OUTPUT_LINK: link},
            )
        except Exception:
            # Best-effort: the upload itself already succeeded above, a
            # metadata-write failure here must not turn that into exit(1).
            logger.exception(
                "Error writing back iMarina Excel output link / Workflow State"
            )