starbash 0.1.35__tar.gz → 0.2.3__tar.gz

{starbash-0.1.35 → starbash-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: starbash
-Version: 0.1.35
+Version: 0.2.3
 Summary: A tool for automating/standardizing/sharing astrophotography workflows.
 License-File: LICENSE
 Author: Kevin Hester
@@ -19,6 +19,7 @@ Requires-Dist: requests-cache (>=1.2.1,<2.0.0)
 Requires-Dist: restrictedpython (>=8.1,<9.0)
 Requires-Dist: rich (>=14.2.0,<15.0.0)
 Requires-Dist: sentry-sdk (>=2.42.1,<3.0.0)
+Requires-Dist: textual (>=6.8.0,<7.0.0)
 Requires-Dist: tomlkit (>=0.13.3,<0.14.0)
 Requires-Dist: typer (>=0.20.0,<0.21.0)
 Requires-Dist: update-checker (>=0.18.0,<0.19.0)
@@ -29,16 +30,18 @@ Description-Content-Type: text/markdown
 
 # [Starbash](https://github.com/geeksville/starbash)
 
-<img src="https://raw.githubusercontent.com/geeksville/starbash/refs/heads/main/doc/img/icon.jpg" alt="Starbash: Astrophotography workflows simplified" width="30%" align="right" style="margin-bottom: 20px;">
-
 [![PyPI - Version](https://img.shields.io/pypi/v/starbash)](https://pypi.org/project/starbash/)
 [![Continuous Integration](https://github.com/geeksville/starbash/actions/workflows/ci.yml/badge.svg)](https://github.com/geeksville/starbash/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/github/geeksville/starbash/graph/badge.svg?token=47RE10I7O1)](https://codecov.io/github/geeksville/starbash)
 
 A tool for automating/standardizing/sharing astrophotography workflows.
 
-* Automatic - with sensible defaults that you can change as needed.
-* Easy - provides a 'seestar-like' autoprocessing all your sessions (by default).  You can optionally do manual postprocessing with all this 'grunt work' preprocessing.
+## What is starbash?
+
+<img src="https://raw.githubusercontent.com/geeksville/starbash/refs/heads/main/doc/img/icon.jpg" alt="Starbash: Astrophotography workflows simplified" width="30%" align="right" style="margin-bottom: 20px;">
+
+* Automatic - with sensible defaults that you can change as needed.  Just a few keystrokes to preprocess an entire repo of raw images.
+* Easy - provides a 'seestar-like' autoprocessing all your sessions (by default).  You can optionally do manual postprocessing with all this 'grunt work' preprocessing automated.
 * Fast<sup>1</sup> - even with large image repositories.  Automatic master bias and flat generation.  Automatic preprocessing/ stacking/background-elimination with reasonable defaults.
 * Multi-session - by default.  So your workflows can stack from multiple nights (and still use the correct flats etc...).
 * Shareable - you can share/use recipes for image preprocessing flows.  The eventual goal is a transition away from opaque burried scripts.  Recipes can come from multiple repos and you or other orgs can host recipes.
@@ -49,7 +52,22 @@ A tool for automating/standardizing/sharing astrophotography workflows.
 <sub>**Caveats:**
 1. 'Fast' in terms of you 'just need to click run and magically (ahem) everything just happens.'  But if you ask it to process many images it can take hours - just come back when it is done.</sub>
 
-<br clear="right">
+## What is starbash NOT
+
+### Not a new image processing tool (like Siril)
+It is important to understand that Starbash is primarily a tool for **repeatable**, **sharable**, **semi-automated** workflows.  It is tool agnostic and really just focuses on the relationship between tools, images and sessions.  It builds upon the great work of existing tools (currently mainly Siril and Graxpert) so we can grow an ecosystem of recipes.
+
+### Not a set of scripts
+
+It is more a tool for moving away from (sometimes long and complex) opaque scripts.  "Recipes" are kinda like scripts except they are small and atomic and use dependencies to be automatically installed at the appropriate stage of workflows.  But the actual operations performed by a recipe can be for any of the supported tools.
+
+For instance: if you don't like a particular "stack" stage recipe you can swap out just that portion of the workflow for an alternate implementation.  Or make your own and share it with others.  (With full automatic versioning so that workflows hopefully always keep working/evolving)
+
+Starbash understands FITS metadata and how to run tools based on that metadata, but the actual image transformations are entirely up to you and anyone who writes a recipe.
+
+We provide a few example recipes to enable auto-selection of common workflows (see below for example links).  But hopefully others will either add to these recipes or host their own recipe repos.
+
+If you are familar with the software enginering tools "npm, make and git", the goal of this project is to provide an analogous sharable workflows for astrophotography.
 
 # Current status
 
@@ -68,21 +86,28 @@ If you are interested in alpha-testing we ❤️ you.  This README should have e
 * Automatically performs **complete** preprocessing on OSC (broadband, narrowband, or dual Duo filter).  i.e., gives you 'seestar-level' auto-preprocessing, so you only need to do the (optional) custom post-processing.
 * Uses Siril recipes for its pre-processing operations (support for Pixinsight-based recipes will probably be coming at some point...).
 
-### From the alpha 2 (0.2.0) release (2025/12/12 ish)
-* Include a stretched 'thumbnail'(FIXME - link example thumbnail) jpg proof-of-concept render in the output directories
-* Generates a per-target [report/config file](FIXME - link example processed toml) which can be customized if the detected defaults or preprocessing are not what you want.
+### From the alpha 2 (0.2.0) release (2025/12/12)
+* Include a stretched 'thumbnail'(FIXME/link/example/thumbnail) jpg proof-of-concept render in the output directories
+* Generates a per-target [report/config file](doc/toml/example/processed-repo/example-m20.toml) which can be customized if the detected defaults or preprocessing are not what you want.
 * '[Recipes](https://github.com/geeksville/starbash-recipes)' are now user-editable - provides repeatable/human-[readable](doc/toml/example/processed-repo/example-m20.toml)/shareable descriptions of all processing steps. [example Siril OSC stacking](https://github.com/geeksville/starbash-recipes/blob/6d255f48591c4991ddc1168ffa5c38050a500771/osc/osc_simple.toml), [example Graxpert BGE](https://github.com/geeksville/starbash-recipes/blob/6d255f48591c4991ddc1168ffa5c38050a500771/graxpert/background.toml), [example thumbnail generation](https://github.com/geeksville/starbash-recipes/blob/6d255f48591c4991ddc1168ffa5c38050a500771/common/thumbnail.toml)...
 * Repos can be on the local disk or shared via HTTPS/GitHub/etc.  This is particularly useful for recipe repos.
 * [Graxpert](https://graxpert.com/) based [recipe stages](https://github.com/geeksville/starbash-recipes/tree/main/graxpert) added (support for Pixinsight-based recipes will probably be coming at some point...).
 
 ## Features coming soon
 
-* Better recipe 'writers guide' documentation.
-* Support for mono-camera workflows (the alpha only has osc recipes).
+* Recipe 'writers guide' documentation.  Currently iterating based on usage reports 😄
+* Support for mono-camera workflows (the alpha only includes osc recipes).
 * The target report can be used to auto-generate a human-friendly 'postable/shareable' report about that image.
 * Target reports are shareable so that you can request comments from others and others can rerender with different settings.
 * Namespaces for recipes are disambiguated to be globally unique
 
+## Features (possibly) coming eventually
+
+* [IPFS](https://ipfs.tech/) based sharing of images and the workflows used to build those images (if you wish)
+* Nice graph view of raw images, recipes and operations that contributed to a final image.  Also possibly exposed via IPFS.
+* Pixinsight?
+* Autostakkert?
+
 See the [TODO](TODO.md) file for work items and approximate schedule.
 
 ## Support
@@ -206,8 +231,6 @@ If you don't want the automated processing you can still ask Starbash to prepare
 
 ## Supported telescope software
 
-FIXME explain FITS and directory paths
-
 * N.I.N.A. - tested, seems fairly okay.
 * Asiair - tested, seems fairly okay.
 * Seestar - tested, seems fairly okay.
@@ -221,27 +244,12 @@ Starbash is a tool agnostic workflow manager.  But it wouldn't be possible witho
 * [Graxpert](https://graxpert.com/) - for background and noise elimination
 * [Python](https://www.python.org/) (you can add Python code to recipes if necessary)
 
-## Supported tools (future?)
-
-* Pixinsight?
-* Autostakkert?
-
 ## Credits
 * Various reddit users who submitted anonymous crash reports from alpha 1
 * [@codegistics](https://github.com/codegistics) for kindly donating Dwarf3 test data and invaluable debugging assistance.
 * The developers of Siril and Graxpert - which are wonderful tools.
-* The [doit](https://pydoit.org/) automation building tool, which substantially simiplified this tool's development.
-
-## Design
-
-FIXME - write this
-
-FIXME - what this tool is
-a way to avoid opaque script blobs that are tied to a particular tool.
-instead a way to make sharable/extendable workflows from atomic mini-tools
-A way to capture preprocessing steps used to create an image
-FIXME - what this tool isn't
-Influences from make, npm, github.
+* The [doit](https://pydoit.org/) an **amazing** automation building tool, which substantially simiplified this tool's development.
+* Any parts of the user interface that look good are probably due to the awesome [rich](https://github.com/Textualize/rich) library.
 
 ## Development
 

{starbash-0.1.35 → starbash-0.2.3}/README.md

@@ -1,15 +1,17 @@
 # [Starbash](https://github.com/geeksville/starbash)
 
-<img src="https://raw.githubusercontent.com/geeksville/starbash/refs/heads/main/doc/img/icon.jpg" alt="Starbash: Astrophotography workflows simplified" width="30%" align="right" style="margin-bottom: 20px;">
-
 [![PyPI - Version](https://img.shields.io/pypi/v/starbash)](https://pypi.org/project/starbash/)
 [![Continuous Integration](https://github.com/geeksville/starbash/actions/workflows/ci.yml/badge.svg)](https://github.com/geeksville/starbash/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/github/geeksville/starbash/graph/badge.svg?token=47RE10I7O1)](https://codecov.io/github/geeksville/starbash)
 
 A tool for automating/standardizing/sharing astrophotography workflows.
 
-* Automatic - with sensible defaults that you can change as needed.
-* Easy - provides a 'seestar-like' autoprocessing all your sessions (by default).  You can optionally do manual postprocessing with all this 'grunt work' preprocessing.
+## What is starbash?
+
+<img src="https://raw.githubusercontent.com/geeksville/starbash/refs/heads/main/doc/img/icon.jpg" alt="Starbash: Astrophotography workflows simplified" width="30%" align="right" style="margin-bottom: 20px;">
+
+* Automatic - with sensible defaults that you can change as needed.  Just a few keystrokes to preprocess an entire repo of raw images.
+* Easy - provides a 'seestar-like' autoprocessing all your sessions (by default).  You can optionally do manual postprocessing with all this 'grunt work' preprocessing automated.
 * Fast<sup>1</sup> - even with large image repositories.  Automatic master bias and flat generation.  Automatic preprocessing/ stacking/background-elimination with reasonable defaults.
 * Multi-session - by default.  So your workflows can stack from multiple nights (and still use the correct flats etc...).
 * Shareable - you can share/use recipes for image preprocessing flows.  The eventual goal is a transition away from opaque burried scripts.  Recipes can come from multiple repos and you or other orgs can host recipes.
@@ -20,7 +22,22 @@ A tool for automating/standardizing/sharing astrophotography workflows.
 <sub>**Caveats:**
 1. 'Fast' in terms of you 'just need to click run and magically (ahem) everything just happens.'  But if you ask it to process many images it can take hours - just come back when it is done.</sub>
 
-<br clear="right">
+## What is starbash NOT
+
+### Not a new image processing tool (like Siril)
+It is important to understand that Starbash is primarily a tool for **repeatable**, **sharable**, **semi-automated** workflows.  It is tool agnostic and really just focuses on the relationship between tools, images and sessions.  It builds upon the great work of existing tools (currently mainly Siril and Graxpert) so we can grow an ecosystem of recipes.
+
+### Not a set of scripts
+
+It is more a tool for moving away from (sometimes long and complex) opaque scripts.  "Recipes" are kinda like scripts except they are small and atomic and use dependencies to be automatically installed at the appropriate stage of workflows.  But the actual operations performed by a recipe can be for any of the supported tools.
+
+For instance: if you don't like a particular "stack" stage recipe you can swap out just that portion of the workflow for an alternate implementation.  Or make your own and share it with others.  (With full automatic versioning so that workflows hopefully always keep working/evolving)
+
+Starbash understands FITS metadata and how to run tools based on that metadata, but the actual image transformations are entirely up to you and anyone who writes a recipe.
+
+We provide a few example recipes to enable auto-selection of common workflows (see below for example links).  But hopefully others will either add to these recipes or host their own recipe repos.
+
+If you are familar with the software enginering tools "npm, make and git", the goal of this project is to provide an analogous sharable workflows for astrophotography.
 
 # Current status
 
@@ -39,21 +56,28 @@ If you are interested in alpha-testing we ❤️ you.  This README should have e
 * Automatically performs **complete** preprocessing on OSC (broadband, narrowband, or dual Duo filter).  i.e., gives you 'seestar-level' auto-preprocessing, so you only need to do the (optional) custom post-processing.
 * Uses Siril recipes for its pre-processing operations (support for Pixinsight-based recipes will probably be coming at some point...).
 
-### From the alpha 2 (0.2.0) release (2025/12/12 ish)
-* Include a stretched 'thumbnail'(FIXME - link example thumbnail) jpg proof-of-concept render in the output directories
-* Generates a per-target [report/config file](FIXME - link example processed toml) which can be customized if the detected defaults or preprocessing are not what you want.
+### From the alpha 2 (0.2.0) release (2025/12/12)
+* Include a stretched 'thumbnail'(FIXME/link/example/thumbnail) jpg proof-of-concept render in the output directories
+* Generates a per-target [report/config file](doc/toml/example/processed-repo/example-m20.toml) which can be customized if the detected defaults or preprocessing are not what you want.
 * '[Recipes](https://github.com/geeksville/starbash-recipes)' are now user-editable - provides repeatable/human-[readable](doc/toml/example/processed-repo/example-m20.toml)/shareable descriptions of all processing steps. [example Siril OSC stacking](https://github.com/geeksville/starbash-recipes/blob/6d255f48591c4991ddc1168ffa5c38050a500771/osc/osc_simple.toml), [example Graxpert BGE](https://github.com/geeksville/starbash-recipes/blob/6d255f48591c4991ddc1168ffa5c38050a500771/graxpert/background.toml), [example thumbnail generation](https://github.com/geeksville/starbash-recipes/blob/6d255f48591c4991ddc1168ffa5c38050a500771/common/thumbnail.toml)...
 * Repos can be on the local disk or shared via HTTPS/GitHub/etc.  This is particularly useful for recipe repos.
 * [Graxpert](https://graxpert.com/) based [recipe stages](https://github.com/geeksville/starbash-recipes/tree/main/graxpert) added (support for Pixinsight-based recipes will probably be coming at some point...).
 
 ## Features coming soon
 
-* Better recipe 'writers guide' documentation.
-* Support for mono-camera workflows (the alpha only has osc recipes).
+* Recipe 'writers guide' documentation.  Currently iterating based on usage reports 😄
+* Support for mono-camera workflows (the alpha only includes osc recipes).
 * The target report can be used to auto-generate a human-friendly 'postable/shareable' report about that image.
 * Target reports are shareable so that you can request comments from others and others can rerender with different settings.
 * Namespaces for recipes are disambiguated to be globally unique
 
+## Features (possibly) coming eventually
+
+* [IPFS](https://ipfs.tech/) based sharing of images and the workflows used to build those images (if you wish)
+* Nice graph view of raw images, recipes and operations that contributed to a final image.  Also possibly exposed via IPFS.
+* Pixinsight?
+* Autostakkert?
+
 See the [TODO](TODO.md) file for work items and approximate schedule.
 
 ## Support
@@ -177,8 +201,6 @@ If you don't want the automated processing you can still ask Starbash to prepare
 
 ## Supported telescope software
 
-FIXME explain FITS and directory paths
-
 * N.I.N.A. - tested, seems fairly okay.
 * Asiair - tested, seems fairly okay.
 * Seestar - tested, seems fairly okay.
@@ -192,27 +214,12 @@ Starbash is a tool agnostic workflow manager.  But it wouldn't be possible witho
 * [Graxpert](https://graxpert.com/) - for background and noise elimination
 * [Python](https://www.python.org/) (you can add Python code to recipes if necessary)
 
-## Supported tools (future?)
-
-* Pixinsight?
-* Autostakkert?
-
 ## Credits
 * Various reddit users who submitted anonymous crash reports from alpha 1
 * [@codegistics](https://github.com/codegistics) for kindly donating Dwarf3 test data and invaluable debugging assistance.
 * The developers of Siril and Graxpert - which are wonderful tools.
-* The [doit](https://pydoit.org/) automation building tool, which substantially simiplified this tool's development.
-
-## Design
-
-FIXME - write this
-
-FIXME - what this tool is
-a way to avoid opaque script blobs that are tied to a particular tool.
-instead a way to make sharable/extendable workflows from atomic mini-tools
-A way to capture preprocessing steps used to create an image
-FIXME - what this tool isn't
-Influences from make, npm, github.
+* The [doit](https://pydoit.org/) an **amazing** automation building tool, which substantially simiplified this tool's development.
+* Any parts of the user interface that look good are probably due to the awesome [rich](https://github.com/Textualize/rich) library.
 
 ## Development
 

{starbash-0.1.35 → starbash-0.2.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "starbash"
-version = "0.1.35"
+version = "0.2.3"
 description = "A tool for automating/standardizing/sharing astrophotography workflows."
 authors = ["Kevin Hester <kevinh@geeksville.com>"]
 readme = "README.md"
@@ -25,11 +25,17 @@ sentry-sdk = "^2.42.1"
 update-checker = "^0.18.0"
 requests-cache = "^1.2.1"
 doit = "^0.36.0"
+textual = "^6.8.0"
 
 # Note: to use graxpert from the local tree rather than pypi use:
 # graxpert = {path = "GraXpert", extras = ["cpuonly"], develop = true}
 graxpert = {version = "^3.2.0a1", extras = ["cpuonly"]}
 
+# The following two libs are only needed for the experiment of running siril scripts directly...
+# experimenting with siril-scripts/processing/VeraLux_HyperMetric_Stretch.py
+#numpy = "2.2.6"
+#pyqt6 = "^6.10.1"
+
 [tool.poetry.group.dev.dependencies]
 pytest = ">=8.4.2,<9.0.0"
 pytest-cov = "^6.0.0"
@@ -37,6 +43,7 @@ pytest-xdist = "^3.8.0"
 pre-commit = "^4.3.0"
 ruff = "^0.14.4"
 basedpyright = "^1.33.0"
+textual-dev = "^1.8.0"
 
 # We don't currently use this text based sql client
 # harlequin = "^2.4.1"
@@ -56,7 +63,7 @@ markers = [
 # --tb=short shows shorter tracebacks
 # -rA shows summary of all test outcomes at end
 # --ignore excludes third-party test directories
-addopts = "-m 'not slow and not integration' -n auto --tb=short -rA --ignore=GraXpert"
+addopts = "-m 'not slow and not integration' -n auto --tb=short -rA --ignore=GraXpert --ignore=textual --ignore=starbash-recipes"
 
 # Note: To limit captured output further, you can:
 # 1. Use --tb=line for minimal tracebacks
@@ -88,7 +95,24 @@ line-length = 100
 target-version = "py312"
 
 # Exclude a variety of commonly ignored directories
-exclude = [".git", ".venv", "__pycache__", "build", "dist"]
+exclude = [".git", ".venv", "__pycache__", "build", "dist", "reference", "siril-scripts"]
+
+[tool.ruff.format]
+# Only format files in src/ and tests/ - exclude everything else
+exclude = [
+    "doc/**",
+    "examples/**",
+    "siril-scripts/**",
+    "htmlcov/**",
+    "images/**",
+    "reference/**",
+    "starbash-recipes/**",
+    "test-data/**",
+    "GraXpert/**",
+    "textual/**",
+    "bin/**",
+    "*.py"  # Exclude root-level Python files
+]
 
 [tool.ruff.lint]
 # Enable these rule sets

{starbash-0.1.35 → starbash-0.2.3}/src/repo/repo.py

@@ -505,7 +505,12 @@ class Repo:
         """
         # Construct the full URL by joining the base URL with the filepath
         if filepath:
-            url = self.url.rstrip("/") + "/" + filepath.lstrip("/")
+            # If the URL points to a .toml file, strip the filename to get the directory
+            base_url = self.url
+            if self._is_direct_toml_file():
+                # Strip the .toml filename to get the parent directory URL
+                base_url = base_url.rsplit("/", 1)[0]
+            url = base_url.rstrip("/") + "/" + filepath.lstrip("/")
         else:
             url = self.url
 

{starbash-0.1.35 → starbash-0.2.3}/src/starbash/__init__.py

@@ -7,7 +7,7 @@ from rich.console import Console
 
 # Common type aliases for clarity
 type StageDict = dict[str, Any]  # a processing stage definition from our toml
-type InputDef = dict[str, Any]  # an input definition within a stage
+type InputDef = dict[Any, Any]  # an input definition within a stage
 type OutputDef = dict[str, Any]  # an output definition within a stage
 type RequireDef = dict[str, Any]  # a requires definition within an input
 type Metadata = dict[str, Any]  # image metadata dictionary

{starbash-0.1.35 → starbash-0.2.3}/src/starbash/analytics.py

@@ -47,9 +47,9 @@ def analytics_setup(allowed: bool = False, user_email: str | None = None) -> Non
             ],  # This line removes the aggressive unhandled exception catcher
             integrations=[
                 LoggingIntegration(
-                    level=starbash.log_filter_level,  # Capture INFO and above as breadcrumbs
+                    level=starbash.log_filter_level,  # Capture INFO and above as breadcrumbs (used for exception reports)
                     event_level=None,  # Don't automatically convert error messages to sentry events
-                    sentry_logs_level=starbash.log_filter_level,  # Capture INFO and above as logs
+                    sentry_logs_level=logging.INFO,  # Capture INFO and above as logs (general usage)
                 ),
             ],
         )
@@ -85,7 +85,7 @@ def is_development_environment() -> bool:
     return False
 
 
-def analytics_exception(exc: Exception) -> bool:
+def analytics_exception(exc: BaseException) -> bool:
     """Report an exception to the analytics service, if enabled.
     return True to suppress exception propagation/log messages"""
 

{starbash-0.1.35 → starbash-0.2.3}/src/starbash/app.py

@@ -3,6 +3,7 @@ import logging
 import sys
 from importlib.metadata import version
 from pathlib import Path
+from sqlite3 import OperationalError
 from string import Template
 from typing import Any
 
@@ -36,7 +37,7 @@ from starbash.database import (
     get_column_name,
 )
 from starbash.dwarf3 import extend_dwarf3_headers
-from starbash.exception import UserHandledError, raise_missing_repo
+from starbash.exception import NonSoftwareError, UserHandledError, raise_missing_repo
 from starbash.linux import linux_init
 from starbash.os import symlink_or_copy
 from starbash.paths import get_user_config_dir, get_user_config_path
@@ -121,6 +122,28 @@ def copy_images_to_dir(images: list[ImageRow], output_dir: Path) -> None:
         console.print(f"  [red]Errors: {error_count} files[/red]")
 
 
+def remap_expected_errors(exc: BaseException | None) -> BaseException | None:
+    """Remap certain expected exceptions to UserHandledError for consistent handling."""
+
+    if exc is None:
+        return None
+
+    # Some OSErrors definitely don't indicate a code level bug...
+    expected_errors = [ "Read-only file system" ]
+
+    if isinstance(exc, OperationalError):
+        return NonSoftwareError(f"[red]Database IO error:[/red] {exc}")
+    elif isinstance(exc, FileNotFoundError):
+        return NonSoftwareError(f"[red]OS error:[/red] {exc}")
+    elif isinstance(exc, OSError):
+        exc_str = str(exc)
+        if any(err in exc_str for err in expected_errors):
+            return NonSoftwareError(f"[red]OS error:[/red] {exc}")
+    # Add more remappings as needed
+
+    return exc
+
+
 class Starbash:
     """The main Starbash application class."""
 
@@ -161,7 +184,8 @@ class Starbash:
         self._init_repos()
         self._init_analytics(cmd)  # after init repos so we have user prefs
 
-        logging.info("Starbash starting")
+        app_version = version("starbash")
+        logging.info(f"🚀 Starbash {app_version} starting!")
 
         check_version()
         self._init_aliases()
@@ -271,20 +295,38 @@ class Starbash:
         return self
 
     def __exit__(self, exc_type, exc, tb) -> bool:
+        from starbash import _is_test_env
         from starbash.exception import UserHandledError
 
+        exc = remap_expected_errors(exc)
+
         handled = False
         # Don't suppress typer.Exit - it's used for controlled exit codes
         if exc and not isinstance(exc, typer.Exit) and not isinstance(exc, KeyboardInterrupt):
-            # For UserHandledError, call ask_user_handled() and don't suppress
-            if isinstance(exc, UserHandledError):
-                exc.ask_user_handled()
+            # For errors we expect, just print error message and exit cleanly
+            if isinstance(exc, NonSoftwareError):
+                # For UserHandledError, call ask_user_handled() and don't suppress
+                if isinstance(exc, UserHandledError):
+                    exc.ask_user_handled()
+                else:
+                    starbash.console.print(exc)
                 self.close()
                 # Raise typer.Exit to ensure proper exit code
                 raise typer.Exit(code=1)
             else:
                 handled = analytics_exception(exc)
-        self.close()
+                self.close()
+                if not handled:
+                    # Show the full exception for developers
+                    starbash.console.print_exception(show_locals=False) # Locals are too verbose
+
+                # In test environments, let exceptions propagate naturally for better test diagnostics
+                if not _is_test_env:
+                    # But in any case, make our app exit with an error code
+                    raise typer.Exit(code=1)
+        else:
+            self.close()
+
         return handled
 
     def _add_session(self, header: dict) -> None:
@@ -439,7 +481,7 @@ class Starbash:
                 absolute_path = repo.resolve_path(relative_path)
                 image["abspath"] = str(absolute_path)
             else:
-                logging.error(f"Repo not found for URL: {repo_url}, skipping image...")
+                raise UserHandledError(f"Repo not found for URL: {repo_url}, session skipped.")
 
         return image
 

{starbash-0.1.35 → starbash-0.2.3}/src/starbash/commands/process.py

@@ -14,6 +14,7 @@ from starbash.commands.__init__ import (
 from starbash.commands.select import selection_by_number
 from starbash.database import SessionRow
 from starbash.doit import FileInfo
+from starbash.paths import get_user_config_path
 from starbash.processed_target import ProcessedTarget
 from starbash.processing import Processing, ProcessingResult
 from starbash.rich import to_rich_link
@@ -110,7 +111,9 @@ def print_results(
     from rich.table import Table
 
     if not results:
-        console.print(f"[yellow]{title}: No results, do you have a target selected?[/yellow]")
+        console.print(
+            f"[yellow]{title}: No results, do you have a target selected?  If this is your first time here run 'sb user setup'[/yellow]"
+        )
         return
 
     table = Table(title=title, show_header=True, header_style=TABLE_HEADER_STYLE)
@@ -212,18 +215,25 @@ def auto(
         import starbash
 
         starbash.process_masters = False
+
+    # Users might run "process auto" as their first command without reading any docs...
+    if not get_user_config_path().exists():
+        from starbash import console
+
+        console.print("[red]No app setup found.[/red]  Please run 'sb user setup'.")
+        raise typer.Exit(1)
+
     with Starbash("process.auto") as sb:
         with Processing(sb) as proc:
             from starbash import console
 
             if session_num is not None:
                 console.print(
-                    f"[read]Session number base filtering not yet implemented: {session_num}...[/red]"
+                    f"[red]Session number base filtering not yet implemented: {session_num}...[/red]"
                 )
             else:
                 console.print("[yellow]Auto-processing all selected sessions...[/yellow]")
 
-            try:
                 results = proc.run_all_stages()
 
                 title = "Autoprocessed"
@@ -237,10 +247,6 @@ def auto(
 
                 print_results(title, results, console)
 
-            except Exception:
-                console.print_exception(show_locals=True)
-                raise typer.Exit(code=1)
-
 
 @app.command(
     context_settings={"allow_extra_args": True, "ignore_unknown_options": True},

{starbash-0.1.35 → starbash-0.2.3}/src/starbash/commands/user.py

@@ -152,6 +152,7 @@ def _ask_user_config(sb: Starbash) -> None:
 
 
 def do_reinit(sb: Starbash) -> None:
+    """Do guided 1st time setup for starbash."""
     from starbash import console
 
     console.print()
@@ -177,11 +178,9 @@ def do_reinit(sb: Starbash) -> None:
             Recommended next steps (to get your first auto-generated images):
             1. Add your source raw image repositories (starbash will only READ from these):
                [cyan]sb repo add /path/to/your/raw_images[/cyan]
-            2. Ask starbash to auto-generate 'master' darks, biases and flats:
-                [cyan]sb process masters[/cyan]
-            3. Process your images using automated workflows:
+            2. Process your images using automated workflows:
                 [cyan]sb process auto[/cyan]
-            4. (Highly recommended) Tell your shell to auto-complete starbash commands:
+            3. (Highly recommended) Tell your shell to auto-complete starbash commands:
                 [cyan]sb shell-complete --install-completion[/cyan]
 
             This project is currently very 'alpha' but we are eager to have it work for you.

{starbash-0.1.35 → starbash-0.2.3}/src/starbash/doit.py

@@ -252,11 +252,10 @@ class ToolAction(BaseAction):
                 self.result = self.tool.run(
                     self.commands, context=context, cwd=self.cwd, log_out=logfile, **self.parameters
                 )
-        except ValueError as e:
+        except Exception as e:
             # We pass back any exceptions in task.meta - so that our ConsoleReporter can pick them up (doit normally strips exceptions)
             self.task.meta["exception"] = e
             return TaskFailed("tool failed")
-            # raise e  # Let doit do its normal exception handling though
 
         self.values = {}  # doit requires this attribute to be set
 

{starbash-0.1.35 → starbash-0.2.3}/src/starbash/exception.py

@@ -1,7 +1,17 @@
 from typing import Any, NoReturn
 
 
-class UserHandledError(ValueError):
+class NonSoftwareError(Exception):
+    """An error outside the control of the software, exit the app with an error code, but no need to
+    report it as a software bug.
+
+    Used for OS errors etc after we've determined we can't do anything more useful."""
+
+    def __rich__(self) -> Any:
+        return self.__str__()  # At least this is something readable...
+
+
+class UserHandledError(NonSoftwareError):
     """An exception that terminates processing of the current file, but we want to help the user fix the problem."""
 
     def ask_user_handled(self) -> bool:
@@ -14,9 +24,6 @@ class UserHandledError(ValueError):
         console.print(f"Error: {self}")
         return False
 
-    def __rich__(self) -> Any:
-        return self.__str__()  # At least this is something readable...
-
 
 def raise_missing_repo(kind: str) -> NoReturn:
     """Raise a UserHandledError indicating that a repository of the given kind is missing."""

{starbash-0.1.35 → starbash-0.2.3}/src/starbash/paths.py

@@ -64,8 +64,13 @@ def get_user_data_dir() -> Path:
 
 
 def get_user_cache_dir() -> Path:
-    """Get the user cache directory. Returns test override if set, otherwise the real user directory."""
-    dir_to_use = _override_cache_dir if _override_cache_dir is not None else cache_dir
+    """Get the user cache directory. Returns test override if set, otherwise checks STARBASH_CACHE_DIR env var, otherwise the real user directory."""
+    if _override_cache_dir is not None:
+        dir_to_use = _override_cache_dir
+    elif env_cache_dir := os.getenv("STARBASH_CACHE_DIR"):
+        dir_to_use = Path(env_cache_dir)
+    else:
+        dir_to_use = cache_dir
     os.makedirs(dir_to_use, exist_ok=True)
     return dir_to_use