Skip to content

Environment and Project Wiring

The environment helpers in stackops now live across stackops.utils.cloud.defaults. They answer two practical questions:

  • which virtualenv should this project use?
  • what cloud-transfer defaults should commands start from?

What this layer provides

API Responsibility
find_virtualenv_root(init_path) Walks upward from a path and resolves the first project-local .venv
build_virtualenv_activation_line(virtualenv_root) Builds the platform-specific shell line that activates a virtualenv
CloudConfig Typed cloud metadata for keys such as cloud, root, rel2home, pwd, encrypt, encryption, os_specific, zip, share, and overwrite
read_default_cloud_config() Returns the default CloudConfig payload used by callers as a baseline

Discovery model

find_virtualenv_root(init_path) treats init_path as a file-or-directory input, normalizes file paths to their parent directory, then walks upward through that path and its parents.

At each directory it:

  1. Checks for a sibling .venv directory.
  2. Returns the first match immediately.
  3. Continues through parent directories if no .venv is present.

The function returns a Path when it finds a project-local virtualenv and None otherwise. It also prints the resolved path, or that no environment was discovered.

Default cloud payload

read_default_cloud_config() returns:

  • cloud: mycloud101
  • root: myhome
  • rel2home, encrypt, os_specific, zip, share, overwrite: False
  • pwd, encryption: None

Activation lines

build_virtualenv_activation_line(virtualenv_root) returns:

  • . {virtualenv_root}/bin/activate on Linux and macOS
  • . $HOME/<relative-path>/Scripts/activate.ps1 on Windows

The Windows branch rewrites the expanded virtualenv path to a $HOME/.../Scripts/activate.ps1 PowerShell source line. The Windows path must be under the user's home directory because the implementation rewrites it relative to $HOME.

Example usage

from pathlib import Path

from stackops.utils.cloud.defaults import read_default_cloud_config

cloud_defaults = read_default_cloud_config()

print(cloud_defaults["root"])

Profile helpers

Use stackops.profile.create_helper.copy_assets_to_machine(...) when a script needs to install the packaged shell/script assets into the StackOps config root. Use stackops.profile.dotfiles_mapper for typed dotfile mapper reads and writes. The profile modules that parse CLI options or apply machine-local symlink changes are command implementation modules, not general-purpose public APIs.

API reference

defaults

Package logger

logger

get_logger 

get_logger(name: str | None = None) -> Logger

Return a child logger of the package root.

Inputs: - name: Optional dotted logger name; when None, returns the package root.

Returns: - logging.Logger configured under the 'stackops' hierarchy.

Profile creation helpers

create_helper

Dotfiles mapper

dotfiles_mapper

Secrets API

secrets

OneDrive auth

auth

OneDrive file operations

file_ops

Rclone helpers

rclone

Rclone wrapper

rclone_wrapper

StackOps repository helpers

stackops_paths

StackOps config schema

config_types

Fire agent input schema

fire_agents_input

TypedDict definitions for fire_agents.py inputs.

This module defines the structured input types for the fire_agents main function, capturing all user inputs collected during interactive execution.

FilePathSearchInput

Bases: TypedDict

Input for file_path search strategy.

KeywordSearchInput

Bases: TypedDict

Input for keyword_search strategy.

FilenamePatternSearchInput

Bases: TypedDict

Input for filename_pattern search strategy.

TasksPerPromptSplittingInput

Bases: TypedDict

Input for tasks_per_prompt splitting strategy.

FireAgentsMainInput

Bases: TypedDict

Complete input structure for fire_agents main function.

FireAgentsRuntimeData

Bases: TypedDict

Runtime data derived from inputs during execution.

Repository schema

repos_types