flashdrive-cli 1.0.0__py3-none-macosx_11_0_arm64.whl

flashdrive_cli/__init__.py

@@ -0,0 +1,5 @@
+"""FlashDrive command-line client."""
+
+from ._version import __version__
+
+__all__ = ["__version__"]

flashdrive_cli/__main__.py

@@ -0,0 +1,3 @@
+from .main import main
+
+raise SystemExit(main())

flashdrive_cli/_api.py

@@ -0,0 +1,3 @@
+"""The API major this CLI speaks."""
+
+API_MAJOR = 1

flashdrive_cli/_channel.py

@@ -0,0 +1,6 @@
+"""Explicit configuration for this client build."""
+
+CHANNEL = 'production'
+DEFAULT_BASE_URL = 'https://api.flashdrive.space'
+CONFIG_DIR_NAME = 'flashdrive'
+PACKAGE_INDEX_URL = 'https://pypi.org/simple/'

flashdrive_cli/_exit_codes.py

@@ -0,0 +1,17 @@
+# Generated by backend/scripts/errors.mjs from backend/src/error-catalogue.json. Do not edit.
+"""Process exit statuses by error type. 1 is any other failure and 2 a usage error; 130 is an interrupt."""
+
+TYPE_EXITS: dict[str, int] = {
+    "auth": 3,
+    "permission": 4,
+    "not_found": 5,
+    "invalid": 2,
+    "conflict": 6,
+    "precondition": 6,
+    "rate_limit": 7,
+    "payment_required": 8,
+    "quota": 9,
+    "too_large": 2,
+    "unavailable": 10,
+    "upgrade": 11,
+}

flashdrive_cli/_legacy.py

@@ -0,0 +1,13 @@
+"""Read-only identifiers for retained state from earlier private clients.
+
+New state uses FlashDrive identifiers. These sets only admit existing records
+so an upgrade does not discard pending work. They do not enable old commands,
+imports, credential namespaces or default hosts.
+"""
+
+GIT_SCOPE_SCHEMAS = ("flashdrive-mount-git-sync-scope.v1", "baseseat-mount-git-sync-scope.v1")
+# The service validates this issued wire format. Renaming it requires an API
+# migration, independently of the Python package and local recovery filenames.
+GIT_CHECKPOINT_WIRE_SCHEMA = "baseseat.git-checkpoint.v1"
+GIT_CHECKPOINT_SCHEMAS = (GIT_CHECKPOINT_WIRE_SCHEMA,)
+WORKCOPY_METADATA = (".flashdrive", ".baseseat", ".wondersearch")

flashdrive_cli/_messages.py

@@ -0,0 +1,239 @@
+"""Local error messages. Backend response messages are preserved verbatim."""
+
+MESSAGES = {
+    "mount_credential_origin_mismatch": "The mount belongs to a different API origin. Select its original profile or set credentials and their matching API base URL before restarting it.",
+    "expected_revision_must_be_a_document_revision": "--expected-revision is required from your original document read (a positive decimal integer through 9223372036854775807)",
+    "expected_revision_requires_replace": "--expected-revision requires --replace",
+    "file_revision_is_required": "--revision is required from your original file read (a positive decimal integer through 9223372036854775807)",
+    "folder_move_needs_a_target": "Give --to PARENT (or --to root for the top level), --name, or both.",
+    "folder_deletion_progress": "Deleted {} of {} files...",
+    "folder_sync_retired": "FlashDrive uses mounted drives for filesystem access. Folder synchronization commands are unavailable. Existing folders, drafts and recovery data remain intact. Stop old synchronization processes, manually review selected drafts, then copy the selected files into a mounted drive. This command does not read, upload, move or delete those files.",
+    "mount_unsupported": "Mounting needs macOS, or Linux with FUSE, and this machine has no /dev/fuse. Read and write single files with flashdrive file cat|get|patch, and flashdrive file link for a URL a program can stream.",
+    "mount_needs_fusermount": "Mounting as a user other than root needs fusermount3 (Debian and Ubuntu: apt-get install fuse3). Use a machine with FUSE support, or read and write files through the CLI file commands or SDK.",
+    "state_too_new": "{} was written by a newer FlashDrive CLI (state version {}). Update the CLI to use it.",
+    "file_edit_pairs": "Give each edit as --old TEXT --new TEXT (old text not empty), or a list with --edits.",
+    "file_edit_one_source": "Give the edits either as --old/--new pairs or with --edits, not both.",
+    "file_edit_bad_list": "--edits needs a JSON list of objects, each with old and new text.",
+    "delete_many_pairs": "Give each file as DOCUMENT_ID:REVISION, with the revision from your original document read (a positive decimal integer through 9223372036854775807), or a list with --documents.",
+    "delete_many_one_source": "Give the files either as DOCUMENT_ID:REVISION arguments or with --documents, not both.",
+    "delete_many_bad_list": "--documents needs a JSON list of objects, each with id and expected_revision text.",
+    "delete_many_count": "Name from 1 through {} files. One request deletes all of them or none; split a larger delete into several.",
+    "delete_many_duplicate": "Name each file once.",
+    "delete_many_idempotency_key": "Delete idempotency key: {} (pass it with --idempotency-key to retry this same delete)",
+    "mount_journal_newer": "This drive was last used with a newer FlashDrive. Update FlashDrive, then mount again; your pending changes are kept.",
+    "mount_helper_version": "The mount helper wd-fs (version {}, protocol {}) does not match this CLI. Install the wd-fs that came with it, or update both.",
+    "mount_busy": "The drive is in use by {}, so it stays mounted. Close them (or their windows on the drive), then unmount again.",
+    "mount_busy_unknown": "The drive is in use, and which programs hold it could not be told, so it stays mounted. Close the programs using it, then unmount again.",
+    "mount_helper_override_missing": "FLASHDRIVE_WD_FS is set to {}, which is not an executable file. Point it at the wd-fs mount helper, or unset it to use the one installed with the CLI.",
+    "mount_helper_missing": "This install has no mount helper (wd-fs): it came from a package without one. Install the CLI again with the uv, pipx or pip command for macOS or Linux at {}, adding its reinstall option (uv tool install --reinstall, pipx install --force, pip install --force-reinstall); those packages include wd-fs. Or set FLASHDRIVE_WD_FS to the path of a wd-fs you have.",
+    "mount_folder_not_empty": "{} is not empty. Mount into an empty folder, or choose one with --at.",
+    "mount_already_running": "{} is already mounted. Run flashdrive unmount first.",
+    "mount_failed": "The drive could not be mounted: {}",
+    "mount_not_found": "No mount found there. flashdrive mounts lists them.",
+    "mount_which": "Several drives are mounted. Name the folder: flashdrive unmount <folder>.",
+    "workcopy_bad_path": "Refused the path {}: it is not a plain path inside the folder.",
+    "workcopy_other_drive": "{} is a working copy of another drive.",
+    "workcopy_no_manifest": "{} has no legacy working-copy manifest. Keep existing drafts intact and manually review selected files before copying them into a mounted drive.",
+    "conflicts_wait": "{} conflict(s) wait for a merge. Each entry under conflicts lists next_steps: merge the two versions, then save the file in the mounted drive.",
+    "workcopy_confirm_deletes": "This legacy operation would delete {0} drive files. Folder synchronization is unavailable. Preserve local files and manually review any intended changes in a mounted drive.",
+    "mount_unsaved_read_only": "This folder's last mount left changes the drive does not have yet. Mount it again without --read-only to save them.",
+    "unmount_unsaved": "Some changes are not saved to the drive yet, so the folder stays mounted: {} Fix them, or unmount with --force to keep them on this machine only.",
+    "unmount_failed": "Could not unmount: {} (leave the folder and close files in it, then try again).",
+    "file_range_modes_conflict": "Read by lines (--start-line, --line-count) or by bytes (--offset, --length), not both.",
+    "file_option_out_of_range": "{} must be a whole number from {} through {}.",
+    "file_download_unexpected_answer": "The service did not answer with the requested byte range. Try the download again.",
+    "file_bytes_range_invalid": "--bytes takes A-B (inclusive), A- or -N, in bytes.",
+    "file_text_required": "Provide nonempty text of at most {} characters for {}.",
+    "file_pages_exceeded": "Stopped after {} pages. Continue with --cursor {}.",
+    "upload_metadata_exceeds_batch_limit": "Upload metadata exceeds the drive's {} byte request limit. Reduce the metadata before retrying.",
+    "upload_capacity_pending_resume": "Unresolved uploads fill this run's pending window. Resume the saved run to reconcile them before adding more files.",
+    "upload_recovery_quarantined": "This saved upload cannot safely submit mutations. Its original recovery record and source paths are unchanged. Keep the source as a draft and reconcile any upload or operation receipt before starting a new edit; do not assign the draft today's revision. Receipt checks here are read-only and do not prove the file is still current.",
+    "upload_exceeds_drive_limits": "This upload has {} files and {} bytes, but a drive holds at most {} documents and {} bytes. Split it across drives.",
+    "unreadable_file": "Cannot read file or directory.",
+    "invalid_signin_callback": "Invalid sign-in callback. Return to your terminal.",
+    "api_url_must_be_a_string": "API URL must be a string.",
+    "api_url_must_be_an_https_origin_http": "API URL must be an HTTPS origin (HTTP is permitted only on loopback).",
+    "configuration_recovery_paths_must_not_contain_symlinks": "Configuration/recovery paths must not contain symlinks.",
+    "invalid_profile_name": "Invalid profile name.",
+    "configuration_profiles_must_be_an_object": "Configuration profiles must be an object.",
+    "profile_settings_must_contain_string_values": "Profile settings must contain string values.",
+    "private_configuration_recovery_file_must_have_mode_0600": "Private configuration/recovery file must have mode 0600.",
+    "set_only_one_of_flashdrive_api_key_and": "Set only one of FLASHDRIVE_API_KEY and FLASHDRIVE_ACCESS_TOKEN.",
+    "invalid_saved_credential_record_log_in_again": "Invalid saved credential record. Log in again.",
+    "log_in_or_provide_credentials_for_this_api": "Log in or provide credentials for this API origin.",
+    "cannot_read_private_configuration_recovery_file": "Cannot read private configuration/recovery file.",
+    "saved_credential_belongs_to_a_different_api_origin": "Saved credential belongs to a different API origin. Log in for this origin first.",
+    "unlock_or_configure_your_operating_system_credential_store": "Unlock or configure your operating system credential store, then run flashdrive login again. For automation, use FLASHDRIVE_API_KEY.",
+    "the_saved_session_is_invalid_run_flashdrive_login": "The saved session is invalid. Run flashdrive login again.",
+    "credential_paths_must_not_contain_symlinks": "Credential paths must not contain symlinks.",
+    "the_server_returned_an_invalid_sign_in_address": "The server returned an invalid sign-in address.",
+    "sign_in_timed_out_run_flashdrive_login_again": "Sign-in timed out. Run flashdrive login again.",
+    "sign_in_cancelled": "Sign-in cancelled.",
+    "your_session_has_expired_run_flashdrive_login_to": "Your session has expired. Run flashdrive login to sign in again.",
+    "browser_sign_in_is_unavailable_on_this_server": "Browser sign-in is unavailable on this server. Try again shortly, or use flashdrive login --api-key.",
+    "could_not_complete_sign_in_check_your_connection": "Could not complete sign-in. Check your connection and try again.",
+    "could_not_save_your_session_in_the_operating": "Could not save your session in the operating system credential store.",
+    "run_flashdrive_login_to_sign_in": "Run flashdrive login to sign in.",
+    "could_not_read_your_saved_session_unlock_your": "Could not read your saved session. Unlock your operating system credential store and try again.",
+    "the_session_was_revoked_but_local_cleanup_failed": "The session was revoked, but local cleanup failed. Unlock your credential store and run flashdrive logout again.",
+    "this_server_requires_a_different_cli_api_major": "This server requires a different CLI API major.",
+    "upgrade_flashdrive_cli_to_at_least_0": "Upgrade flashdrive-cli to at least {0}. Run flashdrive update.",
+    "cli_upgrade_available": "flashdrive-cli {} is available. Run flashdrive update to upgrade.",
+    "cli_version_deprecated": "flashdrive-cli {} will stop being supported. Run flashdrive update to install {} or later.",
+    "api_feature_deprecated": "This request uses a deprecated API feature.",
+    "api_feature_sunset": "It stops working on {}.",
+    "api_feature_replacement": "Use {} instead.",
+    "api_feature_docs": "See {}.",
+    "api_version_retired": "This API version or feature has been retired.",
+    "client_upgrade_required": "This version of flashdrive-cli is no longer supported.",
+    "run_flashdrive_update": "Run flashdrive update.",
+    "minimum_cli_version_is": "The minimum supported version is {}.",
+    "update_source_install": "This CLI was installed from a local checkout or file. Update it from that source.",
+    "update_installer_missing": "This CLI was installed with {}, which is not on PATH. Run its upgrade command yourself.",
+    "update_unknown_installer": "Cannot tell how this CLI was installed (installer: {}). Upgrade it with the tool you used to install it.",
+    "update_uv_upgrade_yourself": "This CLI is a uv tool installed with its own sources or settings, which an update here would not keep. Run: uv tool upgrade flashdrive-cli",
+    "update_no_manifest": "The service did not report a current CLI release. Try again later.",
+    "update_busy": "Another updater is using this CLI environment, or its update lock is unavailable. Try again after it finishes.",
+    "update_version_conflict": "The installed CLI version could not be verified or is newer than the update target. Restart the CLI and check again.",
+    "update_verification_failed": "The upgrade did not produce a working CLI at the exact requested version {}. Inspect the installation before retrying.",
+    "update_api_incompatible": "This release targets an incompatible API major. Select the correct API instance before updating.",
+    "update_channel_incompatible": "Automatic and in-place updates require a stable release channel and version.",
+    "update_origin_incompatible": "This staging build accepts release updates only from its configured staging API.",
+    "update_staging_manual": "Manual staging update required. Install {} from {} with the tool that owns this environment. Preserve its settings and staging access credentials.",
+    "update_manual_command": "Run: {}",
+    "upload_file_exceeds_limit": "Provide a file no larger than {} bytes.",
+    "upload_expected_regular_file": "Expected a regular file.",
+    "update_major_metadata": "This API instance has not advertised compatibility for a new CLI major. Keep this client until compatible release metadata is available.",
+    "update_major_required": "CLI {} is a new major version. Review its migration guide, then run flashdrive update --allow-major.",
+    "update_installing": "Updating flashdrive-cli to {}.",
+    "update_installing_newest": "Updating flashdrive-cli to its newest release.",
+    "update_failed": "The {} upgrade did not finish. Its output is shown above.",
+    "update_rerun": "flashdrive-cli was updated. Running the command again.",
+    "cli_release_available": "flashdrive-cli {} is available (installed {}). Run: flashdrive update",
+    "cli_below_minimum": "flashdrive-cli {1} is the minimum supported version (installed {0}). Run: flashdrive update",
+    "cli_moved": "The FlashDrive CLI is now published as {} (command {}). It is not installed automatically.",
+    "cli_moved_install": "Install it with: {}.",
+    "update_no_workdir": "Cannot prepare the private update directory in the CLI configuration directory.",
+    "update_continues": "flashdrive-cli was updated; this command runs on the version that was already running.",
+    "update_rerun_failed": "flashdrive-cli was updated, but the command could not be run again. Run it again yourself.",
+    "update_unchanged": "The {} upgrade finished, but the installed version did not change. Upgrade with the tool you used to install the CLI.",
+    "update_timed_out": "The upgrade did not finish in time. Run it yourself: {}",
+    "server_response_is_missing_required_fields_or_has": "Server response is missing required fields or has invalid field types.",
+    "operation_timed_out_accepted_server_work_continues": "Operation timed out; accepted server work continues.",
+    "expected_a_resource_uuid": "Expected a resource UUID.",
+    "complete_account_setup_in_the_console_first": "Complete account setup in the Console first.",
+    "sign_in_with_a_user_session_to_run": "Sign in with a user session to run this command. API keys cannot be used here.",
+    "api_request_failed": "API request failed.",
+    "unsafe_transfer_destination": "Unsafe transfer destination.",
+    "invalid_api_path": "Invalid API path.",
+    "server_returned_an_invalid_response": "Server returned an invalid response.",
+    "server_returned_invalid_pagination_data": "Server returned invalid pagination data.",
+    "repeated_pagination_cursor": "Repeated pagination cursor.",
+    "resource_is_missing_its_concurrency_etag": "Resource is missing its concurrency ETag.",
+    "server_returned_a_non_json_response": "Server returned a non-JSON response.",
+    "network_request_failed": "Network request failed.",
+    "processing_failed": "Processing failed.",
+    "replace_requires_exactly_one_file_and_no_recursive": "--replace requires exactly one file and no --recursive.",
+    "directories_require_recursive": "Directories require --recursive.",
+    "recovery_record_does_not_match_this_profile_origin": "Recovery record does not match this profile, origin, identity, workspace, and drive.",
+    "invalid_upload_recovery_record_restore_the_original_record": "Invalid upload recovery record. Restore the original record before resuming.",
+    "expected_a_supported_regular_file_of_1_through": "Expected a regular file of at most 1,000,000,000 bytes.",
+    "upload_bytes_are_incomplete_use_upload_resume_with": "Upload bytes are incomplete. Use upload resume with the original run ID.",
+    "source_changed_since_reservation_cannot_resume_this_upload": "Source changed since reservation; cannot resume this upload.",
+    "ambiguous_destination_folder": "Ambiguous destination folder: ",
+    "destination_folder_could_not_be_created_or_resolved": "Destination folder could not be created or resolved.",
+    "transfer_headers_must_be_strings": "Transfer headers must be strings.",
+    "unknown_transfer_transport": "Unknown transfer transport.",
+    "cannot_read_source_file": "Cannot read source file.",
+    "unsupported_command": "Unsupported command.",
+    "incorrect_number_of_command_arguments_see_help": "Incorrect number of command arguments. See --help.",
+    "use_either_a_positional_drive_or_drive_not": "Use either a positional drive or --drive, not both.",
+    "use_either_a_positional_workspace_or_workspace_not": "Use either a positional workspace or --workspace, not both.",
+    "deletion_revocation_requires_confirmation_use_yes_in_scripts": "Deletion/revocation requires confirmation; use --yes in scripts.",
+    "deletion_revocation_was_not_confirmed": "Deletion/revocation was not confirmed.",
+    "allowed_config_keys": "Allowed config keys: ",
+    "": ", ",
+    "provide_a_configuration_value": "Provide a configuration value.",
+    "list_limit_must_be_between_1_and_100": "List limit must be between 1 and 100.",
+    "missing_command_argument_see_help": "Missing command argument. See --help.",
+    "processing_timeout_requires_wait": "--processing-timeout requires --wait.",
+    "dry_run_cannot_be_combined_with_wait": "--dry-run cannot be combined with --wait.",
+    "0_is_not_supported_for_this_command": "--{0} is not supported for this command.",
+    "select_an_organization_with_organization_or_config_set": "Select an organization with --organization or config set organization.",
+    "drive_is_not_accessible_in_the_selected_workspace": "Drive is not accessible in the selected workspace.",
+    "operation_is_looked_up_in_one_drive": "An operation is looked up in the drive it was made in. This one was looked for in the default drive ({}). If it was made in another drive, name it with --drive.",
+    "full_text_must_be_on_or_off": "Full-text search must be on or off.",
+    "mode_must_be_drive_or_search": "Mode must be drive or search.",
+    "this_token_is_limited_to_another_drive": "This sandbox token is limited to another drive. Omit --drive or mint a token for this drive.",
+    "token_not_saved": "The token was created but could not be saved. Revoke it: flashdrive sandbox-token revoke {0} --yes",
+    "token_file_exists": "The --out file already exists. Choose a new path; the token is written only to a new private file.",
+    "choose_out_or_print": "Choose --out FILE to save the token to a private file, or --print to show it once.",
+    "profile_names_must_contain_1_through_120_characters": "Profile names must contain 1 through 120 characters.",
+    "unknown_profile_create_it_with_login_profile_name": "Unknown profile. Create it with login --profile NAME or config set KEY VALUE --profile NAME.",
+    "waiting_interrupted_drive_0_continues_provisioning_check_it": "Waiting interrupted; drive {0} continues provisioning. Check it with drive get {1}.",
+    "idempotency_key_must_be_1_128_visible_ascii": "Idempotency key must be 1-128 visible ASCII characters.",
+    "input_ended_before_a_credential_was_provided": "Input ended before a credential was provided.",
+    "cannot_read_write_a_local_file_or_parse": "Cannot read/write a local file or parse its contents. Check paths, permissions, and encoding.",
+    "timeout_applies_only_to_browser_login": "--timeout applies only to browser login.",
+    "timeout_requires_wait": "--timeout requires --wait.",
+    "0_name_must_match_exactly_one_accessible_resource": "{0} name must match exactly one accessible resource; use its UUID.",
+    "this_api_key_is_scoped_to_a_different": "This API key is scoped to a different workspace.",
+    "drive_provisioning_failed": "Drive provisioning failed.",
+    "unknown_drive_provisioning_status": "Unknown drive provisioning status.",
+    "use_workspace_default_drive_get_or_set_drive": "Use workspace default-drive get or set <drive>.",
+    "use_upload_status_upload_id": "Use upload status <upload-id>.",
+    "use_upload_resume_run_id_wait": "Use upload resume <run-id> [--wait].",
+    "document_text_exceeds_2_000_000_bytes": "Document text exceeds 2,000,000 bytes.",
+    "timeouts_must_be_finite_and_positive": "Timeouts must be finite and positive.",
+    "select_a_workspace_with_workspace_or_workspace_use": "Select a workspace with --workspace or workspace use.",
+    "select_the_profile_for_this_api_origin_before": "Select the profile for this API origin before signing out.",
+    "choose_browser_sign_in_or_one_credential_type": "Choose browser sign-in or one credential type. Browser timeout must be at most 300 seconds.",
+    "provide_a_nonempty_credential_without_whitespace": "Provide a nonempty credential without whitespace.",
+    "import_exceeds_drive_limits": "This import has {} documents and {} bytes, but a drive holds at most {} documents and {} bytes. Split it across drives.",
+    "import_exceeds_service_limits": "This import has {} documents, {} bytes and {} chunks, but one import holds at most {} documents, {} bytes and {} chunks. Split it into several imports.",
+    "import_has_nothing_to_send": "No importable files found. Imports accept nonempty UTF-8 .txt and .md files.",
+    "import_unfinished_exists": "An unfinished import of these paths to this drive exists. Continue it with flashdrive import PATHS --drive DRIVE --resume.",
+    "import_no_unfinished_run": "No unfinished import of these paths to this drive was found. Run the command without --resume to start one.",
+    "import_record_mismatch": "The saved import does not match this profile, origin, identity, workspace, and drive.",
+    "import_record_invalid": "The saved import record is invalid. Restore the original record, or start a new import.",
+    "import_option_conflicts_with_saved_run": "--{0} differs from the value saved with this import. Resume without it.",
+    "import_source_changed": "Files changed since this import started. Restore them, or start a new import.",
+    "import_rejected_content": "The service rejected part of this import. Check that every file is UTF-8 text, then start a new import.",
+    "import_conflict": "This import no longer matches its declared files. Start a new import.",
+    "import_closed": "This import is closed or has expired. Start a new import for any files that are not yet searchable.",
+    "import_not_found": "The import could not be found on this drive. Start a new import.",
+    "import_busy": "The import is busy. Run the same command with --resume to continue.",
+    "import_failed_documents": "{} documents could not be imported. Their files are listed in the error details; import them again in a new import.",
+    "import_failed_operations": "Some documents could not be made searchable. Run the same command with --resume --retry-failed to try them again.",
+    "import_interrupted": "Interrupted; the service keeps the accepted work. Run the same command with --resume to continue.",
+    "import_timed_out": "Waiting reached its time limit; the service keeps the accepted work. Run the same command with --resume to continue.",
+    "import_invalid_combine_bytes": "--combine-bytes must be between 0 and 1,000,000.",
+    "import_resume_or_dry_run": "Use --dry-run or --resume, not both.",
+    "import_retry_requires_resume": "--retry-failed requires --resume.",
+    "import_file_too_large": "This file is larger than one import chunk allows. Use flashdrive upload for it.",
+    "import_invalid_text": "Imports accept nonempty UTF-8 text only.",
+    "import_operations_not_retryable": "Some documents could not be made searchable and cannot be retried. The import is closed; import the listed files again in a new import.",
+    "import_scan_timed_out": "Reading the files reached the time limit; nothing was sent. Run the command again with a longer --timeout.",
+    "import_sealed_follow": "The import is sealed; its documents become searchable over time. Follow it with: {}",
+    "import_service_unavailable": "The service is temporarily unavailable. Run the same command with --resume to continue.",
+    "import_duplicate_paths": "Two files would become the same document ({}). Import paths with the same name separately, or rename one.",
+}
+
+
+def local_message(code: str, *values: object) -> str:
+    return MESSAGES[code].format(*values)
+
+
+# 429s that are capacity or a daily quota, not pacing: their own messages say what to do.
+QUOTA_CODES = {"upload_limit", "agent_quota_exhausted"}
+
+
+def throttle_line(retry_after=None, now=None) -> str:
+    """The one line for any rate throttle: the next whole minute after the wait asked for."""
+    import math
+    import time
+
+    wait = float(retry_after) if isinstance(retry_after, (int, float)) and math.isfinite(retry_after) else 60.0
+    moment = math.ceil(((time.time() if now is None else now) + max(wait, 1.0)) / 60) * 60
+    stamp = time.gmtime(moment)
+    return f"Too many requests. Try again after {stamp.tm_hour:02d}:{stamp.tm_min:02d} UTC."

flashdrive_cli/_time_scale.py

@@ -0,0 +1,29 @@
+"""One factor for the mount's waits, read once when the process starts.
+
+Test-only: FLASHDRIVE_TEST_TIME_SCALE (a float from 0.01 to 1) shortens the
+waits that bound how long a queued change takes to end (retry backoff, the
+limit, permission and held waits, the offline probe and the status journal
+grace), so a real-mount test grid runs in minutes. Unset or invalid, SCALE is
+exactly 1.0 and every wait is its production value. Never documented for
+customers. HTTP timeouts and the mount lease are never scaled.
+"""
+from __future__ import annotations
+import math
+import os
+
+VARIABLE = "FLASHDRIVE_TEST_TIME_SCALE"
+
+
+def read_scale(value: str | None) -> float:
+    try:
+        scale = float(value) if value is not None else 1.0
+    except ValueError:
+        return 1.0
+    return scale if math.isfinite(scale) and 0.01 <= scale <= 1.0 else 1.0
+
+
+SCALE = read_scale(os.environ.get(VARIABLE))
+
+
+def scaled(seconds: float) -> float:
+    return seconds if SCALE == 1.0 else seconds * SCALE

flashdrive_cli/_version.py

@@ -0,0 +1 @@
+__version__ = '1.0.0'