ssmforge 0.2.1__tar.gz → 0.2.2__tar.gz

{ssmforge-0.2.1/src/ssmforge.egg-info → ssmforge-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ssmforge
-Version: 0.2.1
+Version: 0.2.2
 Summary: Standalone HF architecture analyzer (`ssmforge arch`). Inspects any HuggingFace model and reports architectural quirks — attention biases, fused QKV/gate-up, tied embeddings, GQA, MQA, MoE, sliding window, LayerScale, soft-capping, partial RoPE, MLP type, norm type. Outputs structured JSON + human-readable summary.
 Author: SSMForge Contributors
 License-Expression: Apache-2.0
@@ -82,6 +82,14 @@ visible *before* you spend the next hour finding out the hard way.
 It does **not** modify the model. It does **not** run inference. It only
 inspects.
 
+### What's new in 0.2.2
+
+| Fix | What was broken |
+|-----|-----------------|
+| `--output PATH` with bad parent dir | Previously got a generic `bash: Permission denied` (when redirecting) or a Python traceback (when using `--output`). Now pre-flight checks the parent directory, prints a clear hint pointing at writable locations like `./` and `~/`, then exits 1. |
+
+Plus 6 new tests (162 total). Tiny release — main bug fix only.
+
 ### What's new in 0.2.1
 
 | Feature | Why it matters |
@@ -1392,7 +1400,44 @@ install.
 
 ## 16. Update log
 
-### v0.2.1 (current) — 2026-09-23
+### v0.2.2 (current) — 2026-09-23
+
+**Bug fix: `--output PATH` directory validation**
+
+When `--output PATH` points to a non-writable location, users were getting
+either a generic shell `Permission denied` (when using shell redirection)
+or an opaque Python `OSError` (when using `--output` directly). Now
+ssmforge pre-flight checks the parent directory and prints a friendly
+hint pointing at writable alternatives.
+
+**Before:**
+```
+$ python -m ssmforge.cli arch X --graph --format markdown > q.md
+bash: q.md: Permission denied
+
+$ python -m ssmforge.cli arch X --graph --format markdown --output C:\q.md
+Error: cannot write to 'C:\\q.md': [Errno 13] Permission denied: 'C:\\q.md'
+```
+
+**After:**
+```
+$ python -m ssmforge.cli arch X --graph --format markdown > q.md
+# (still works in any shell that allows the redirect)
+
+$ python -m ssmforge.cli arch X --graph --format markdown --output C:\q.md
+Error: cannot write to directory: C:\
+  Permission denied.
+  Try a writable location like:
+    --output ./report.md        (current directory)
+    --output ~/report.md        (your home directory)
+    --output $TMPDIR/report.md  (system temp)
+```
+
+Tests: 162 passed (was 156). 6 new tests for `_check_output_path`
+(returns (None, None) for None / '-' paths, validates writability,
+emits helpful hints for missing or read-only parents).
+
+### v0.2.1 — 2026-09-23
 
 **New feature: `doctor --check-install`**
 

{ssmforge-0.2.1 → ssmforge-0.2.2}/README.md

@@ -59,6 +59,14 @@ visible *before* you spend the next hour finding out the hard way.
 It does **not** modify the model. It does **not** run inference. It only
 inspects.
 
+### What's new in 0.2.2
+
+| Fix | What was broken |
+|-----|-----------------|
+| `--output PATH` with bad parent dir | Previously got a generic `bash: Permission denied` (when redirecting) or a Python traceback (when using `--output`). Now pre-flight checks the parent directory, prints a clear hint pointing at writable locations like `./` and `~/`, then exits 1. |
+
+Plus 6 new tests (162 total). Tiny release — main bug fix only.
+
 ### What's new in 0.2.1
 
 | Feature | Why it matters |
@@ -1369,7 +1377,44 @@ install.
 
 ## 16. Update log
 
-### v0.2.1 (current) — 2026-09-23
+### v0.2.2 (current) — 2026-09-23
+
+**Bug fix: `--output PATH` directory validation**
+
+When `--output PATH` points to a non-writable location, users were getting
+either a generic shell `Permission denied` (when using shell redirection)
+or an opaque Python `OSError` (when using `--output` directly). Now
+ssmforge pre-flight checks the parent directory and prints a friendly
+hint pointing at writable alternatives.
+
+**Before:**
+```
+$ python -m ssmforge.cli arch X --graph --format markdown > q.md
+bash: q.md: Permission denied
+
+$ python -m ssmforge.cli arch X --graph --format markdown --output C:\q.md
+Error: cannot write to 'C:\\q.md': [Errno 13] Permission denied: 'C:\\q.md'
+```
+
+**After:**
+```
+$ python -m ssmforge.cli arch X --graph --format markdown > q.md
+# (still works in any shell that allows the redirect)
+
+$ python -m ssmforge.cli arch X --graph --format markdown --output C:\q.md
+Error: cannot write to directory: C:\
+  Permission denied.
+  Try a writable location like:
+    --output ./report.md        (current directory)
+    --output ~/report.md        (your home directory)
+    --output $TMPDIR/report.md  (system temp)
+```
+
+Tests: 162 passed (was 156). 6 new tests for `_check_output_path`
+(returns (None, None) for None / '-' paths, validates writability,
+emits helpful hints for missing or read-only parents).
+
+### v0.2.1 — 2026-09-23
 
 **New feature: `doctor --check-install`**
 

{ssmforge-0.2.1 → ssmforge-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ssmforge"
-version = "0.2.1"
+version = "0.2.2"
 description = "Standalone HF architecture analyzer (`ssmforge arch`). Inspects any HuggingFace model and reports architectural quirks — attention biases, fused QKV/gate-up, tied embeddings, GQA, MQA, MoE, sliding window, LayerScale, soft-capping, partial RoPE, MLP type, norm type. Outputs structured JSON + human-readable summary."
 readme = "README.md"
 license = "Apache-2.0"

{ssmforge-0.2.1 → ssmforge-0.2.2}/src/ssmforge/__init__.py

@@ -1,3 +1,3 @@
 """SSMForge — architecture analyzer for HuggingFace models."""
 
-__version__ = "0.2.1"
+__version__ = "0.2.2"

{ssmforge-0.2.1 → ssmforge-0.2.2}/src/ssmforge/cli.py

@@ -282,16 +282,70 @@ def _format_dry_run_summary(report: dict) -> str:
     return "\n".join(lines)
 
 
+def _check_output_path(output_path: str | None) -> tuple[Path | None, str | None]:
+    """Pre-flight check on an --output target before writing.
+
+    Returns ``(parent_dir_or_None, error_message_or_None)``:
+    - ``(None, None)`` when output_path is None or '-' (stdout).
+    - ``(parent_dir, None)`` when the directory exists and is writable.
+    - ``(parent_dir, error_message)`` when the path can't be written.
+
+    The error_message is a user-friendly hint that names the actual problem
+    (missing parent dir, not a directory, permission denied) and suggests
+    writable alternatives when appropriate.
+    """
+    if not output_path or output_path == "-":
+        return None, None
+    p = Path(output_path)
+    parent = p.parent if str(p.parent) else Path(".")
+    # Catch a bare filename like 'report.md' (parent is '.') which DOES work
+    parent = parent.resolve()
+    # Case 1: parent doesn't exist
+    if not parent.exists():
+        return parent, (
+            f"Error: output directory does not exist: {parent}\n"
+            f"  Hint: create the directory first, or use a writable location.\n"
+            f"  Try: --output ./report.md  (current working directory)"
+        )
+    # Case 2: parent exists but is a file (not a dir)
+    if parent.is_file():
+        return parent, (
+            f"Error: output path's parent is a file, not a directory: {parent}"
+        )
+    # Case 3: parent is not writable
+    if not os.access(parent, os.W_OK):
+        return parent, (
+            f"Error: cannot write to directory: {parent}\n"
+            f"  Permission denied.\n"
+            f"  Try a writable location like:\n"
+            f"    --output ./report.md        (current directory)\n"
+            f"    --output ~/report.md        (your home directory)\n"
+            f"    --output $TMPDIR/report.md  (system temp)"
+        )
+    return parent, None
+
+
 def _write_or_print(text: str, output_path: str | None) -> None:
     """Write text to a file if path given, else print to stdout.
 
     Special-case: if output_path is '-', print to stdout (Unix convention).
+    Pre-flight checks the parent directory exists and is writable; on
+    failure prints a friendly hint and exits 1.
     """
     if output_path and output_path != "-":
+        parent, err = _check_output_path(output_path)
+        if err is not None:
+            print(err, file=sys.stderr)
+            sys.exit(1)
         try:
-            Path(output_path).write_text(text, encoding="utf-8")
+            p = Path(output_path)
+            p.write_text(text, encoding="utf-8")
         except (PermissionError, FileNotFoundError, IsADirectoryError, OSError) as e:
-            print(f"Error: cannot write to {output_path!r}: {e}", file=sys.stderr)
+            print(
+                f"Error: cannot write to {output_path!r}: {e}\n"
+                f"  Hint: try --output ./report.md for the current directory",
+                file=sys.stderr,
+            )
             sys.exit(1)
         print(f"Report written to {output_path}", file=sys.stderr)
     else:

{ssmforge-0.2.1 → ssmforge-0.2.2/src/ssmforge.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ssmforge
-Version: 0.2.1
+Version: 0.2.2
 Summary: Standalone HF architecture analyzer (`ssmforge arch`). Inspects any HuggingFace model and reports architectural quirks — attention biases, fused QKV/gate-up, tied embeddings, GQA, MQA, MoE, sliding window, LayerScale, soft-capping, partial RoPE, MLP type, norm type. Outputs structured JSON + human-readable summary.
 Author: SSMForge Contributors
 License-Expression: Apache-2.0
@@ -82,6 +82,14 @@ visible *before* you spend the next hour finding out the hard way.
 It does **not** modify the model. It does **not** run inference. It only
 inspects.
 
+### What's new in 0.2.2
+
+| Fix | What was broken |
+|-----|-----------------|
+| `--output PATH` with bad parent dir | Previously got a generic `bash: Permission denied` (when redirecting) or a Python traceback (when using `--output`). Now pre-flight checks the parent directory, prints a clear hint pointing at writable locations like `./` and `~/`, then exits 1. |
+
+Plus 6 new tests (162 total). Tiny release — main bug fix only.
+
 ### What's new in 0.2.1
 
 | Feature | Why it matters |
@@ -1392,7 +1400,44 @@ install.
 
 ## 16. Update log
 
-### v0.2.1 (current) — 2026-09-23
+### v0.2.2 (current) — 2026-09-23
+
+**Bug fix: `--output PATH` directory validation**
+
+When `--output PATH` points to a non-writable location, users were getting
+either a generic shell `Permission denied` (when using shell redirection)
+or an opaque Python `OSError` (when using `--output` directly). Now
+ssmforge pre-flight checks the parent directory and prints a friendly
+hint pointing at writable alternatives.
+
+**Before:**
+```
+$ python -m ssmforge.cli arch X --graph --format markdown > q.md
+bash: q.md: Permission denied
+
+$ python -m ssmforge.cli arch X --graph --format markdown --output C:\q.md
+Error: cannot write to 'C:\\q.md': [Errno 13] Permission denied: 'C:\\q.md'
+```
+
+**After:**
+```
+$ python -m ssmforge.cli arch X --graph --format markdown > q.md
+# (still works in any shell that allows the redirect)
+
+$ python -m ssmforge.cli arch X --graph --format markdown --output C:\q.md
+Error: cannot write to directory: C:\
+  Permission denied.
+  Try a writable location like:
+    --output ./report.md        (current directory)
+    --output ~/report.md        (your home directory)
+    --output $TMPDIR/report.md  (system temp)
+```
+
+Tests: 162 passed (was 156). 6 new tests for `_check_output_path`
+(returns (None, None) for None / '-' paths, validates writability,
+emits helpful hints for missing or read-only parents).
+
+### v0.2.1 — 2026-09-23
 
 **New feature: `doctor --check-install`**