gooseloop 0.1.0__py3-none-any.whl

gooseloop/toolkit.py

@@ -0,0 +1,243 @@
+"""Engine toolkit: the helpers every real engine ended up writing.
+
+Extracted from three independent copies (doc_drift, and the site-drift /
+pain-harvest / site-pitch engines) once the duplication proved the need.
+Everything here is stdlib-only and framework-agnostic: an engine can use any
+of it without buying into anything else.
+
+What lives here and why it earned the spot:
+
+    Source / parse_source(s)   a doc, feed, or reference is a file path or a
+                               live URL; every engine that reads inputs from
+                               config re-invented this two-arm shape.
+    FetchResult / fetch_url    hardened urllib fetch with HTML-to-text. The
+                               named-field result exists because doc_drift
+                               needed ETag/Last-Modified for revision probing
+                               and had to fork the (text, error) tuple.
+    html_to_text               minimal dependency-free HTML normalizer.
+    cap                        paste budget with a visible truncation marker.
+                               The marker is the load-bearing part: a silent
+                               cap reads as "pasted everything" when it didn't.
+    template_safe / ZWSP       goose renders assembled recipes through
+                               minijinja; any surviving delimiter in pasted
+                               reference text aborts the run. One ZWSP trick,
+                               one home (context_prepend shares this constant).
+    safe_filename/unique_slug  model-emitted routing params become file paths
+                               via BranchPolicy.output_path. The model is
+                               untrusted input: slashes and leading dots are
+                               stripped so a hallucinated slug can never
+                               resolve outside the output dir.
+    load_state / save_state    cross-run JSON state with corrupt-file recovery
+                               and defaults backfill.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from email.utils import parsedate_to_datetime
+from pathlib import Path
+from typing import Optional
+
+DEFAULT_PASTE_CAP = 60_000
+_HTTP_TIMEOUT = 15
+_HTTP_MAX_BYTES = 5_000_000
+_DEFAULT_USER_AGENT = "gooseloop/1.0 (+https://github.com/smattymatty/gooseloop)"
+_URL_RE = re.compile(r"^https?://", re.IGNORECASE)
+
+
+# ---- sources: a file path or a live URL --------------------------
+
+
+@dataclass(frozen=True)
+class Source:
+    kind: str   # "file" | "url"
+    value: str  # absolute path for files; the URL string for urls
+
+    @property
+    def is_url(self) -> bool:
+        return self.kind == "url"
+
+
+def parse_source(raw: str, base: Path) -> Source:
+    raw = raw.strip()
+    if _URL_RE.match(raw):
+        return Source("url", raw)
+    path = Path(raw).expanduser()
+    resolved = path if path.is_absolute() else (base / path).resolve()
+    return Source("file", str(resolved))
+
+
+def parse_sources(raw, base: Path) -> tuple[Source, ...]:
+    """A single source, a list of them, or None. Returns a tuple of Sources."""
+    if raw is None:
+        return ()
+    items = raw if isinstance(raw, list) else [raw]
+    return tuple(parse_source(str(x), base) for x in items if str(x).strip())
+
+
+# ---- http fetch + html->text (dependency-free) -------------------
+
+
+@dataclass(frozen=True)
+class FetchResult:
+    """Outcome of one fetch_url call. Exactly one of text/error is set.
+
+    etag and last_modified_unix carry the response headers when the server
+    sent them; revision-probing engines build change tokens from these.
+    """
+    text: Optional[str]
+    error: Optional[str]
+    etag: Optional[str] = None
+    last_modified_unix: Optional[int] = None
+
+    @property
+    def ok(self) -> bool:
+        return self.error is None
+
+
+def fetch_url(
+    url: str,
+    *,
+    strip: bool = True,
+    timeout: int = _HTTP_TIMEOUT,
+    max_bytes: int = _HTTP_MAX_BYTES,
+    user_agent: str = _DEFAULT_USER_AGENT,
+) -> FetchResult:
+    """Fetch a URL. strip=True normalizes HTML to visible text (stable for
+    hashing and readable for the model); strip=False returns the body as-is
+    (for JSON / sitemap XML / href scraping). Any network or HTTP error comes
+    back as FetchResult(error=reason), never an exception."""
+    req = urllib.request.Request(url, headers={"User-Agent": user_agent})
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            raw = resp.read(max_bytes)
+            ctype = resp.headers.get("Content-Type", "")
+            etag = resp.headers.get("ETag")
+            last_mod = resp.headers.get("Last-Modified")
+    except urllib.error.HTTPError as e:
+        return FetchResult(None, f"HTTP {e.code} fetching {url}")
+    except (urllib.error.URLError, OSError, ValueError) as e:
+        return FetchResult(None, f"could not fetch {url}: {e}")
+
+    text = raw.decode("utf-8", errors="replace")
+    if strip and ("html" in ctype.lower() or _looks_like_html(text)):
+        text = html_to_text(text)
+    return FetchResult(text, None, etag, _http_date_to_unix(last_mod))
+
+
+def url_resolves(url: str) -> bool:
+    """True if the URL fetches without a network/HTTP error."""
+    return fetch_url(url, strip=False).ok
+
+
+_SCRIPT_STYLE_RE = re.compile(r"<(script|style)\b[^>]*>.*?</\1>", re.IGNORECASE | re.DOTALL)
+_TAG_RE = re.compile(r"<[^>]+>")
+_WS_RE = re.compile(r"[ \t\f\v]+")
+_BLANKLINES_RE = re.compile(r"\n{3,}")
+
+
+def _looks_like_html(text: str) -> bool:
+    head = text[:512].lower()
+    return "<html" in head or "<!doctype html" in head
+
+
+def html_to_text(html: str) -> str:
+    """Minimal, dependency-free HTML->text: drop script/style, strip tags, tidy."""
+    import html as _html
+    text = _SCRIPT_STYLE_RE.sub(" ", html)
+    text = _TAG_RE.sub("\n", text)
+    text = _html.unescape(text)
+    text = _WS_RE.sub(" ", text)
+    text = "\n".join(line.strip() for line in text.splitlines())
+    return _BLANKLINES_RE.sub("\n\n", text).strip()
+
+
+def _http_date_to_unix(value: Optional[str]) -> Optional[int]:
+    if not value:
+        return None
+    try:
+        dt = parsedate_to_datetime(value)
+    except (TypeError, ValueError):
+        return None
+    return int(dt.timestamp()) if dt is not None else None
+
+
+def cap(text: str, limit: int = DEFAULT_PASTE_CAP) -> str:
+    """Bound pasted content. The truncation marker is deliberate: a capped
+    paste must say so, or the model (and the operator reading the session)
+    believes it saw everything."""
+    if len(text) > limit:
+        return f"{text[:limit]}\n\n(... truncated at {limit} chars ...)"
+    return text
+
+
+# ---- minijinja delimiter neutralizer -----------------------------
+
+# goose renders the whole assembled recipe through minijinja. Any delimiter
+# that survives in inlined reference text is parsed as a tag and aborts the
+# run. Splitting each delimiter with a zero-width space keeps the text
+# visually identical while goose no longer recognises a tag.
+ZWSP = "​"
+_TEMPLATE_DELIMS = ("{{", "}}", "{%", "%}", "{#", "#}")
+
+
+def template_safe(text: str) -> str:
+    for d in _TEMPLATE_DELIMS:
+        while d in text:
+            text = text.replace(d, d[0] + ZWSP + d[1])
+    return text
+
+
+# ---- filename + slug safety --------------------------------------
+
+_SAFE_RE = re.compile(r"[^a-zA-Z0-9._-]+")
+
+
+def safe_filename(text: str, fallback: str = "item") -> str:
+    """Reduce untrusted text (a model-emitted routing slug, a URL fragment) to
+    a single safe path component. Separators collapse to '-'; leading dots are
+    stripped so '..' and dotfiles cannot come back out. Never returns empty:
+    a fully-consumed input yields `fallback`."""
+    cleaned = _SAFE_RE.sub("-", text).strip("-").lstrip(".-")
+    return cleaned or fallback
+
+
+def unique_slug(raw: str, seen: set[str]) -> str:
+    slug = safe_filename(raw)
+    if slug not in seen:
+        return slug
+    i = 2
+    while f"{slug}-{i}" in seen:
+        i += 1
+    return f"{slug}-{i}"
+
+
+# ---- json state io -----------------------------------------------
+
+
+def load_state(path: Path, defaults: dict) -> dict:
+    """Read a JSON state file, falling back to a copy of `defaults` on a missing
+    or corrupt file. Missing keys in a present file are backfilled from defaults."""
+    if not path.exists():
+        return dict(defaults)
+    try:
+        with open(path, "rb") as f:
+            data = json.load(f)
+    except (json.JSONDecodeError, OSError):
+        return dict(defaults)
+    if not isinstance(data, dict):
+        return dict(defaults)
+    for k, v in defaults.items():
+        data.setdefault(k, v)
+    return data
+
+
+def save_state(path: Path, state: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(state, f, indent=2, sort_keys=True)
+        f.write("\n")

gooseloop-0.1.0.dist-info/METADATA

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: gooseloop
+Version: 0.1.0
+Summary: Execution shell for goose-recipe pipelines
+Author: Storm Developments
+License: MIT License
+        
+        Copyright (c) 2026 Storm Developments
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Source, https://gitforge.ca/storm/gooseloop
+Keywords: goose,llm,pipeline,agent,automation
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: minijinja>=2; extra == "dev"
+Dynamic: license-file
+
+# gooseloop
+
+An execution shell for [goose](https://block.github.io/goose/) recipe pipelines.
+
+`gooseloop` runs an **Engine** against an **Environment**, driving a `Pipeline`
+of `review -> body -> summary` through goose, with retry, rate-limit handling,
+session bookkeeping, recipe overlay merging, and a typed session ledger.
+
+It is generic. The framework knows nothing about your domain. Engines plug in.
+
+## Install
+
+```
+pip install gooseloop
+```
+
+Or, from a checkout:
+
+```
+pip install -e .
+```
+
+Requires Python 3.11+, the `goose` CLI on `$PATH`, and a YAML recipe directory.
+
+## The shape
+
+Three primitives:
+
+- **Engine** (verbs). Returns a `Pipeline(review, body, summary)`. Owns
+  branching, recipes, scoring, retry rules.
+- **Environment** (nouns). One abstract method (`env_vars()`). Subclasses or
+  contrib mixins (`gooseloop.contrib.CustomerPipelineEnvironment`,
+  `gooseloop.contrib.ClaudeHandoffEnvironment`) add shape-specific contracts.
+- **Pipeline** (the bookend). Review runs first and emits structured routing.
+  Body phases run in queue order (cadence phases + review-spawned branches).
+  Summary runs last and reads the final ledger.
+
+The contract is documented in [`PROTOCOL.md`](PROTOCOL.md).
+The design history lives in [`docs/adr/`](docs/adr/).
+
+## Five minute tour
+
+```python
+from gooseloop import GooseLooper, Engine, Environment, Phase, Pipeline
+
+class HelloEnvironment(Environment):
+    def env_vars(self) -> dict[str, str]:
+        return {"GREETING": "hello"}
+
+class HelloEngine(Engine):
+    name = "hello-world"
+
+    def pipeline(self, ctx) -> Pipeline:
+        return Pipeline(
+            review=Phase(name="review", recipe_path="recipes/review.yaml"),
+            body=[Phase(name="greet", recipe_path="recipes/greet.yaml")],
+            summary=Phase(name="summary", recipe_path="recipes/summary.yaml"),
+        )
+
+GooseLooper(engine=HelloEngine(), environment=HelloEnvironment()).begin_loop()
+```
+
+The framework ships a working version of this engine under `engines/hello_world/`.
+
+## Built-in engines
+
+Three reference engines ship in `engines/`. They live alongside the framework,
+not inside the installed wheel, so run them **from a checkout** (the repo root,
+where `engines/` is importable) and select one with `-e <module>`:
+
+| Engine | What it does | Run (from the repo root) |
+|--------|--------------|--------------------------|
+| `hello_world` | The minimal reference engine (the tour above). | `python3 -m gooseloop run -e engines.hello_world` |
+| `git_recap` | Summarises your recent commits across configured repos into a changelog. Configure `[git_recap]` in `gooseloop.toml`. | `python3 -m gooseloop run -e engines.git_recap` |
+| `doc_drift` | Finds derived docs/pages that fell behind their canonical source and drafts a patch to seal. Configure `[doc_drift]`, then `cp doc-map.example.toml doc-map.toml` and edit. | `python3 -m gooseloop run -e engines.doc_drift` |
+
+Drop `-e` to run whatever `[gooseloop] engine_module` points at (`hello_world`
+by default). The installed `gooseloop` console script is equivalent to
+`python3 -m gooseloop`, but the built-in engines above still need a checkout on
+the path. Add `--review-only` to any of them to stop after the review phase.
+
+## Recipe overlay merge
+
+Recipes compose docker-compose style. The looper resolves layers in this order:
+
+1. Base recipe (declared in `gooseloop.toml`).
+2. `<name>.local.yaml` (gitignored; per-machine).
+3. `--review-overlay X.yaml` / `--summary-overlay X.yaml` (ad-hoc).
+
+Inspect the merged result with `gooseloop recipe --resolve <name>`.
+
+Merge rules table is in [PROTOCOL.md §6](PROTOCOL.md).
+
+## Contrib mixins
+
+Domain-shaped Environment ABCs ship under `gooseloop.contrib`:
+
+- `CustomerPipelineEnvironment`: customer-acquisition pipelines
+  (`build_digest()`, `journal_text()`, `lifecycle_dirs()`, ...).
+- `ClaudeHandoffEnvironment`: Claude design-handoff engines
+  (`handoff_dir()`, `target_repo()`, `dev_up_probe()`, ...).
+
+An engine with no fit subclasses bare `Environment` and writes one method.
+
+## CLI
+
+```
+gooseloop run                      # run the configured engine, one pass
+gooseloop run --review-only        # stop after review
+gooseloop run --review-overlay x.yaml --summary-overlay y.yaml
+gooseloop recipe --resolve review  # print fully-merged recipe
+gooseloop engines                  # list known engines from gooseloop.toml
+```
+
+`gooseloop.toml` at the project root configures which engine, which recipes,
+retry tuning, sessions dir.
+
+## License
+
+MIT. See [`LICENSE`](LICENSE).
+
+## Provenance
+
+`gooseloop` was extracted from Storm Developments' customer-acquisition pipeline
+in June 2026. Storm's customer engine remains the reference consumer; the
+framework is independent and OSS-first.

gooseloop-0.1.0.dist-info/RECORD

@@ -0,0 +1,28 @@
+gooseloop/__init__.py,sha256=u48uVVU0YS94w-GmQrQn07bRriHqXD55mapB4LhnhMQ,1395
+gooseloop/__main__.py,sha256=TZx_k1Vf_Uaa1HzfHqmKNM8qdfZF49KKl-5gCzabUTU,7040
+gooseloop/artifact.py,sha256=8xKGkpR_wpQh76oUMjsqd4ePIRd_3dTe8HXLfm88_BA,3241
+gooseloop/branch_policy.py,sha256=NjIRYLNdEpWFicDP0LwgoYKXSrqZ8khQAxAc8xrMBUM,2058
+gooseloop/config.py,sha256=9VT7-tq0T8dN8DWef-JvvO9laCF4_mIbdv6tZs3korI,3532
+gooseloop/context_prepend.py,sha256=IG1lFFW6PffYbJpZRvttSpuku7EyqTw3I92dY1L9qio,12701
+gooseloop/engine.py,sha256=SYTGZ92eL5bg9s8paqc1Ue4Bx-W7TusPc9zkFsl-9EU,2519
+gooseloop/environment.py,sha256=hJ-UNaI1k9gEBAAMNM0mUx8wkhkHK1rmqaqxV2SYUho,1185
+gooseloop/extract.py,sha256=PLDcxP5Mf4GKBq3ACkbyZTcLnZ2NjBOWkpT1KY-0NXs,7310
+gooseloop/footer.py,sha256=aNqzlCdzeH1fKdaDyxTykIVioYS7Mpd4gIr13FZeHIY,2776
+gooseloop/goose.py,sha256=yEjB7ZIpfTxY53dhQa3wyvdUF8nml_Mcl1UyMCZ41c0,12101
+gooseloop/looper.py,sha256=LV8ywftiSzviJG4lYSsb9M5vi9YIeRS4uBlgUeohyrc,24432
+gooseloop/phase.py,sha256=UVdR2UOxt6IYX7TzSE9iGAz2z9xh4sgC1r4hQi7BlJU,5895
+gooseloop/predicates.py,sha256=t2WBlYJ5ok_ypdrf_AlaLDV4fBIhdN3D5ZpqkXEGnGw,2425
+gooseloop/protocol.py,sha256=E7qCjoO2indv6MSua_MbEeCnXTxWvmZLAxXq0mSZCys,6995
+gooseloop/recipe_merge.py,sha256=5cfcdIjJWpJTjsDzPs2GDgewnOU-198-MgExgas0c9o,4980
+gooseloop/session.py,sha256=jWfXeJGiILMvs380Oz502PtMrxaWn7NesUxGEkZvQwU,1339
+gooseloop/text.py,sha256=FcxGLSFJd5KlI1z99hLlDYhf4smSR_YJ1iE47ya2l4I,1633
+gooseloop/toolkit.py,sha256=tY_m2sPxJUjjAtovZh9IOZgbDgUAu2RIdOVA5gblDE8,8909
+gooseloop/contrib/__init__.py,sha256=KRoc5DkqtzNcu97BY4M3T6BcW_KL6CF02pL0rRATOi0,760
+gooseloop/contrib/claude_handoff.py,sha256=xz9rDgXqcNnBya8g-5gdaH9ZrSlcX6CXbRv3n6H1pz4,2653
+gooseloop/contrib/customer_pipeline.py,sha256=hzflDtdi2akHLba4745B3vE62nbSxiWGFOCgcWPQSLk,3670
+gooseloop-0.1.0.dist-info/licenses/LICENSE,sha256=c17jwlcrQHxqB8tXRgcHk9ek4J9Dm3m99lcsA_QK8yU,1075
+gooseloop-0.1.0.dist-info/METADATA,sha256=lbW3S3hDzbWsD1-jDQlt2rwUQzAa_6qc2lkiVcOO_WA,6715
+gooseloop-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+gooseloop-0.1.0.dist-info/entry_points.txt,sha256=it6aXQnfzwZSrBfA1DuMuk60Qr5a--F4B3yPzIf3bpM,54
+gooseloop-0.1.0.dist-info/top_level.txt,sha256=8RIsNdZaIfAQLi6nIlMWiYoKM4KDC74ZNIgCY94rGCA,10
+gooseloop-0.1.0.dist-info/RECORD,,

gooseloop-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

gooseloop-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+gooseloop = gooseloop.__main__:main

gooseloop-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Storm Developments
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gooseloop-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+gooseloop