gooseloop 0.1.0__py3-none-any.whl

gooseloop/context_prepend.py

@@ -0,0 +1,316 @@
+"""Pre-render recipe `context:` blocks into the prompt before goose sees it.
+
+Per PROTOCOL.md §7. Recipes declare load-bearing inputs under a top-level
+`context:` block. Each entry is {label, source, optional?}. Before invoking
+goose, the looper resolves each source to literal text and prepends a
+fenced block to the recipe's `prompt`. The model cannot skip the step
+because the text is in the prompt, not behind a bash call.
+
+Sources:
+    env_file:VAR     read the file whose path is in env var VAR
+    file:PATH        read PATH directly (env-substituted)
+    glob:PATTERN     glob (env-substituted), concat sorted matches
+    env_method:NAME  call environment.NAME() and paste its return value
+
+Failure is loud by default. `optional: true` softens to a sentinel
+placeholder when a source is unresolvable.
+
+If GOOSER_KEEP_RENDERED=1 the rendered recipe is left on disk for
+inspection. Default is delete-after-run (cleanup is the caller's
+responsibility).
+"""
+
+import glob as _glob
+import os
+import re
+import tempfile
+from pathlib import Path
+from typing import Any, Optional
+
+import yaml
+
+from .toolkit import ZWSP as _ZWSP
+
+
+_BLOCK_OPEN = "<<<CONTEXT: {label}>>>"
+_BLOCK_CLOSE = "<<<END CONTEXT>>>"
+
+_PREAMBLE = (
+    "# Pre-loaded input\n"
+    "#\n"
+    "# The looper has already resolved the input files this recipe\n"
+    "# requires and pasted their contents below. You do NOT need to\n"
+    "# `cat` any of these paths yourself - the literal contents are\n"
+    "# already in your context. Read the block, then follow the\n"
+    "# instructions that come after it.\n"
+)
+
+
+_ENV_VAR_RE = re.compile(r"\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)")
+
+# A MiniJinja raw-block control token in any accepted spelling: {% raw %} /
+# {% endraw %}, with optional `-` trim markers and arbitrary inner whitespace
+# ({%- endraw -%}, {%raw%}, {%  endraw  %}). These are the ONE thing a raw
+# block can't safely contain, so _raw_wrap defuses them.
+_RAW_CTRL_RE = re.compile(r"\{%-?\s*(?:end)?raw\s*-?%\}")
+
+# _ZWSP (imported from toolkit, the one home for the zero-width-space trick)
+# is inserted between the `{` and `%` of a raw-control token so MiniJinja no
+# longer sees a `{%` tag opener. The character is invisible, so the model
+# reading the pasted text sees essentially the original; only the ephemeral
+# rendered prompt is touched (the on-disk recap is never modified).
+
+
+def _raw_wrap(text: str) -> str:
+    """Wrap arbitrary text so goose's MiniJinja templater treats it as literal.
+
+    Goose renders each recipe `prompt` through MiniJinja (to resolve its own
+    `{{ param }}` placeholders) AFTER the looper has pasted context into the
+    prompt. Any `{{`, `{%`, or `{#` sitting in the pasted data is then parsed
+    as a Jinja tag: a recap that mentioned a Svelte `{#if}` opened a comment
+    that never closed and goose died with "unexpected end of comment". Wrapping
+    the data in {% raw %}…{% endraw %} neutralises every delimiter at once.
+
+    The one sequence a raw block cannot itself contain is a raw-control token
+    (`{% raw %}` / `{% endraw %}`) — a recap *of this very function* carries
+    them in its prose. Rather than try to re-emit those tokens (which needs a
+    `{{ "…" }}` expression whose safety depends on the exact MiniJinja version
+    goose ships — and goose's build rejects it), we break the `{%` opener with
+    a zero-width space so goose never recognises a tag. The result is exactly
+    one clean raw block per body: no nesting, no stray `{% endraw %}`, valid in
+    any MiniJinja that supports raw at all. Empty text is returned unwrapped."""
+    if not text:
+        return text
+    defused = _RAW_CTRL_RE.sub(lambda m: "{" + _ZWSP + m.group(0)[1:], text)
+    return "{% raw %}" + defused + "{% endraw %}"
+
+
+def _prompt_needs_substitution(prompt: str) -> bool:
+    return isinstance(prompt, str) and bool(_ENV_VAR_RE.search(prompt))
+
+
+def _substitute_env(template: str, env: dict[str, str]) -> str:
+    def repl(m: re.Match) -> str:
+        name = m.group(1) or m.group(2)
+        return env.get(name, "")
+    return _ENV_VAR_RE.sub(repl, template)
+
+
+def _resolve_env_file(arg: str, env: dict[str, str], *, optional: bool) -> str:
+    var_name = arg.strip()
+    path_str = env.get(var_name)
+    if not path_str:
+        if optional:
+            return f"(env var {var_name} is unset; skipped)"
+        raise RuntimeError(
+            f"context source 'env_file:{var_name}' failed: "
+            f"env var {var_name} is unset or empty"
+        )
+    path = Path(path_str)
+    if not path.exists():
+        if optional:
+            return f"(file not present: {path})"
+        raise RuntimeError(
+            f"context source 'env_file:{var_name}' failed: "
+            f"file does not exist: {path}"
+        )
+    return path.read_text()
+
+
+def _resolve_file(arg: str, env: dict[str, str], *, optional: bool) -> str:
+    path_str = _substitute_env(arg.strip(), env)
+    if not path_str:
+        if optional:
+            return f"(file path resolved empty for '{arg}'; skipped)"
+        raise RuntimeError(
+            f"context source 'file:{arg}' resolved to an empty path"
+        )
+    path = Path(path_str)
+    if not path.exists():
+        if optional:
+            return f"(file not present: {path})"
+        raise RuntimeError(
+            f"context source 'file:{arg}' failed: file does not exist: {path}"
+        )
+    return path.read_text()
+
+
+def _resolve_glob(arg: str, env: dict[str, str], *, optional: bool) -> str:
+    pattern = _substitute_env(arg.strip(), env)
+    if not pattern:
+        if optional:
+            return f"(glob pattern resolved empty for '{arg}'; skipped)"
+        raise RuntimeError(
+            f"context source 'glob:{arg}' resolved to an empty pattern"
+        )
+    matches = sorted(_glob.glob(pattern))
+    if not matches:
+        if optional:
+            return f"(no files matched pattern: {pattern})"
+        raise RuntimeError(
+            f"context source 'glob:{arg}' matched no files (pattern: {pattern})"
+        )
+    chunks = []
+    for path_str in matches:
+        path = Path(path_str)
+        chunks.append(f"=== {path.name} ===\n{path.read_text()}")
+    return "\n\n".join(chunks)
+
+
+def _resolve_env_method(arg: str, environment: Any) -> str:
+    method_name = arg.strip()
+    if environment is None:
+        raise RuntimeError(
+            f"context source 'env_method:{method_name}' requires an "
+            f"Environment instance; the Looper was constructed without one"
+        )
+    method = getattr(environment, method_name, None)
+    if method is None or not callable(method):
+        raise RuntimeError(
+            f"context source 'env_method:{method_name}' failed: "
+            f"{type(environment).__name__} has no callable named {method_name!r}"
+        )
+    result = method()
+    if not isinstance(result, str):
+        raise RuntimeError(
+            f"context source 'env_method:{method_name}' must return str, "
+            f"got {type(result).__name__}"
+        )
+    return result
+
+
+def substitute_env_in_prompt(doc: dict, env: dict[str, str]) -> dict:
+    """Return a copy of `doc` with `${VAR}` / `$VAR` substituted in the prompt.
+
+    Goose itself does NOT shell-expand env vars inside recipe prompt prose
+    (its own templating uses `{{ name }}` parameters declared at the top
+    of the recipe). The looper substitutes here so recipes can reference
+    ${POTENTIAL_DIR}, ${NAME}, etc. uniformly with the env vars the
+    Environment / engine inject. Substitution is non-destructive: an
+    unknown variable becomes an empty string and the next step (file read,
+    glob, etc.) raises a clear error there.
+    """
+    prompt = doc.get("prompt")
+    if not isinstance(prompt, str) or not prompt:
+        return doc
+    return {**doc, "prompt": _substitute_env(prompt, env)}
+
+
+def _resolve_source(source: str, env: dict[str, str], environment: Any, *,
+                    optional: bool) -> str:
+    if ":" not in source:
+        raise RuntimeError(
+            f"context source {source!r} missing 'kind:' prefix "
+            f"(expected one of env_file, file, glob, env_method)"
+        )
+    kind, _, arg = source.partition(":")
+    kind = kind.strip()
+    if kind == "env_file":
+        return _resolve_env_file(arg, env, optional=optional)
+    if kind == "file":
+        return _resolve_file(arg, env, optional=optional)
+    if kind == "glob":
+        return _resolve_glob(arg, env, optional=optional)
+    if kind == "env_method":
+        return _resolve_env_method(arg, environment)
+    raise RuntimeError(
+        f"context source kind {kind!r} is not supported "
+        f"(expected env_file, file, glob, env_method)"
+    )
+
+
+class _BlockStyleDumper(yaml.SafeDumper):
+    """SafeDumper that emits multi-line strings as literal block scalars (`|`).
+
+    The default double-quoted folding splits long scalars at ~80 columns,
+    which can land a break in the middle of a goose template tag
+    (`{% raw %}` / `{% endraw %}`). goose's YAML parser reconstructs that
+    fold in a way that mangles the tag, so MiniJinja never sees the raw-block
+    terminator and fails with "unexpected end of raw block". A literal block
+    scalar preserves the prompt verbatim with no folding.
+
+    But literal style is not always available: PyYAML silently falls back to
+    double-quoted (and folds again) when a scalar has a line with trailing
+    whitespace, which pasted context routinely does (a config line like
+    `location_constraint = `). So the literal representer is only half the fix;
+    the guarantee is `width` on the dump call below set high enough that no
+    scalar folds in EITHER style. Both are applied together.
+    """
+
+
+# Effectively disable PyYAML's column-based line folding. Folding (not style)
+# is what splits the template tags; a huge width keeps every scalar on one line
+# even when literal-block style is unavailable.
+_NO_FOLD_WIDTH = 1_000_000_000
+
+
+def _literal_str_representer(dumper: yaml.Dumper, data: str):
+    style = "|" if "\n" in data else None
+    return dumper.represent_scalar("tag:yaml.org,2002:str", data, style=style)
+
+
+_BlockStyleDumper.add_representer(str, _literal_str_representer)
+
+
+def render_recipe_with_context(
+    recipe: dict | str | Path,
+    extra_env: dict[str, str],
+    *,
+    environment: Any = None,
+) -> Optional[str]:
+    """Resolve a recipe's context: block; write a rendered temp file.
+
+    Returns the path to the temp file (str) if a context: block was
+    present and rendered, or None if the recipe has no context: block
+    (caller can use the original recipe path unchanged).
+
+    `recipe` may be a parsed dict (e.g. the merged result of recipe_merge),
+    a path to a yaml file, or a Path object.
+    """
+    if isinstance(recipe, (str, Path)):
+        path = Path(recipe)
+        with open(path, "r") as f:
+            doc = yaml.safe_load(f) or {}
+    else:
+        doc = recipe
+
+    env = {**os.environ, **(extra_env or {})}
+    context_block = doc.get("context")
+
+    if context_block:
+        rendered_chunks: list[str] = [_PREAMBLE]
+        for entry in context_block:
+            label = entry.get("label", "(unnamed)")
+            source = entry.get("source", "")
+            optional = bool(entry.get("optional", False))
+            body = _resolve_source(source, env, environment, optional=optional)
+            rendered_chunks.append(
+                _BLOCK_OPEN.format(label=label) + "\n"
+                + _raw_wrap(body.rstrip()) + "\n"
+                + _BLOCK_CLOSE
+            )
+        block_text = "\n\n".join(rendered_chunks)
+        # Env-substitute the recipe's OWN prompt prose, but never the pasted
+        # context: that text is data, and `${VAR}`/`$VAR` sequences in it must
+        # survive verbatim (a recap can legitimately mention $HOME or
+        # ${WINDOW_DAYS}). The context is also already raw-wrapped, so goose's
+        # own templater leaves it alone.
+        substituted_prompt = _substitute_env(doc.get("prompt", ""), env)
+        doc = {**doc, "prompt": block_text + "\n\n" + substituted_prompt}
+        doc.pop("context", None)  # consumed; goose doesn't need to see it
+    else:
+        if not _prompt_needs_substitution(doc.get("prompt", "")):
+            # Nothing to render, nothing to substitute — caller can use the
+            # original recipe file unchanged.
+            return None
+        doc = substitute_env_in_prompt(doc, env)
+
+    tmp = tempfile.NamedTemporaryFile(
+        mode="w",
+        suffix=".rendered.yaml",
+        delete=False,
+    )
+    yaml.dump(doc, tmp, Dumper=_BlockStyleDumper, sort_keys=False,
+              default_flow_style=False, allow_unicode=True, width=_NO_FOLD_WIDTH)
+    tmp.close()
+    return tmp.name

gooseloop/contrib/__init__.py

@@ -0,0 +1,18 @@
+"""Shape-specific Environment contracts.
+
+Per ADR 0005 the framework Environment ABC has one abstract method
+(env_vars). Shape-specific contracts live here as separate ABCs that
+inherit from Environment and add their domain vocabulary:
+
+    CustomerPipelineEnvironment - for customer-acquisition pipelines.
+    ClaudeHandoffEnvironment    - for Claude design-handoff engines.
+
+A concrete environment subclasses whichever mixin matches its domain
+(or bare Environment if no mixin fits). Recipes call env_method:<name>
+against the live instance regardless of mixin lineage.
+"""
+
+from .claude_handoff import ClaudeHandoffEnvironment
+from .customer_pipeline import CustomerPipelineEnvironment
+
+__all__ = ["ClaudeHandoffEnvironment", "CustomerPipelineEnvironment"]

gooseloop/contrib/claude_handoff.py

@@ -0,0 +1,74 @@
+"""ClaudeHandoffEnvironment — shape contract for Claude design-handoff engines.
+
+Domain vocabulary: handoff folder, target repo, dev-up probe, panel
+inventory, screenshot baseline. A handoff engine receives a
+claude-handoff.toml in the target repo, drives Claude through a
+survey → implement-panel → screenshot-verify → status loop, and never
+provisions the target's dev environment itself.
+
+Per the feedback memory `feedback-handoff-engine-provisioning-contract`:
+the engine NEVER auto-provisions the target's dev stack. `dev_up_probe()`
+checks dev is up; if not, the engine fails loud and the operator owns
+the lifecycle.
+"""
+
+from abc import abstractmethod
+from pathlib import Path
+
+from ..environment import Environment
+
+
+class ClaudeHandoffEnvironment(Environment):
+    """Environment contract for Claude design-handoff engines.
+
+    Required:
+        env_vars()         - inherited from Environment.
+        handoff_dir()      - directory of handoff specs the engine consumes.
+        target_repo()      - root of the repo the handoff applies to.
+        dev_up_probe()     - shell command (str) checking dev is reachable.
+
+    Optional:
+        panel_inventory(), screenshot_baseline_dir(), handoff_toml_path().
+    """
+
+    @abstractmethod
+    def handoff_dir(self) -> Path:
+        """Directory containing handoff specs (markdown or toml) to consume."""
+
+    @abstractmethod
+    def target_repo(self) -> Path:
+        """Root of the repository this handoff applies to."""
+
+    @abstractmethod
+    def dev_up_probe(self) -> str:
+        """Shell command whose zero exit code means dev is reachable.
+
+        Example: 'curl -sf http://localhost:8000/healthz'. The engine
+        runs this in precheck; non-zero aborts with operator-action
+        instructing dev to be brought up.
+        """
+
+    def panel_inventory(self) -> str:
+        """Plain-text inventory of panels / UI components in scope.
+
+        Default returns "" (no inventory enforced). Override to scope
+        the engine to a specific subset of the target.
+        """
+        return ""
+
+    def screenshot_baseline_dir(self) -> Path | None:
+        """Directory of pre-handoff baseline screenshots for verification.
+
+        Default None (no baseline; verifier runs without diffs). Override
+        to enable visual-regression checks.
+        """
+        return None
+
+    def handoff_toml_path(self) -> Path | None:
+        """Path to the target repo's claude-handoff.toml, if any.
+
+        Default None (the engine works from `handoff_dir()` alone).
+        Override when the target codebase carries its own per-target
+        config.
+        """
+        return None

gooseloop/contrib/customer_pipeline.py

@@ -0,0 +1,98 @@
+"""CustomerPipelineEnvironment — shape contract for customer-acquisition pipelines.
+
+Domain vocabulary: prospects, lifecycles, outreach, research, broadcast,
+discovery questions, founder journal. Concrete environments (Storm's
+StormEnvironment, future BetaCo-style users) subclass this to inherit
+the contract and implement each abstractmethod.
+
+Recipes call these by name via env_method:<name> in their context:
+blocks.
+"""
+
+from abc import abstractmethod
+from pathlib import Path
+
+from ..environment import Environment
+
+
+class CustomerPipelineEnvironment(Environment):
+    """Environment contract for customer-acquisition engines.
+
+    Required:
+        env_vars()           - inherited from Environment.
+        core_dir()           - root of project's non-runtime data.
+        lifecycle_dirs()     - canonical ordered list of (name, path) pairs.
+        lifecycle_dir(name)  - one lifecycle dir by name.
+        output_dir(name)     - one output dir by name (outreach, research, broadcast).
+        build_digest()       - compact text summary of every routable prospect.
+        journal_text()       - operator's working journal, or "" if absent.
+        manifest_text()      - project-level static context (brand voice etc.).
+
+    Optional:
+        questions_dir(), insight_dir(), repo_activity(), questions_listing().
+        Default to empty / not-found sentinels; recipes that need them
+        should declare the source non-optional so a missing implementation
+        fails the run loud.
+    """
+
+    # ---- paths -------------------------------------------------------
+
+    @abstractmethod
+    def core_dir(self) -> Path:
+        """Root of the project's non-runtime data (foundation docs, journal, inputs)."""
+
+    @abstractmethod
+    def lifecycle_dirs(self) -> list[tuple[str, Path]]:
+        """All lifecycle dirs in canonical order, including non-routable ones."""
+
+    @abstractmethod
+    def lifecycle_dir(self, name: str) -> Path:
+        """One lifecycle dir by canonical name (e.g. 'potential', 'active')."""
+
+    @abstractmethod
+    def output_dir(self, name: str) -> Path:
+        """One output dir by canonical name (outreach, research, broadcast)."""
+
+    # ---- content loaders --------------------------------------------
+
+    @abstractmethod
+    def build_digest(self) -> str:
+        """Compact text summary of every routable prospect.
+
+        The pre-computed form that recipes paste in via env_method:.
+        Schema is environment-defined; engines treat the result as opaque text.
+        """
+
+    @abstractmethod
+    def journal_text(self) -> str:
+        """Operator's working journal as text, or "" if the file is missing."""
+
+    @abstractmethod
+    def manifest_text(self) -> str:
+        """Project-level static context (brand voice, framing, posture)."""
+
+    # ---- optional ---------------------------------------------------
+
+    def questions_dir(self) -> Path | None:
+        """Living-doc workspace for discovery question files. None = unused."""
+        return None
+
+    def insight_dir(self) -> Path | None:
+        """Workspace for cadence-triggered watcher outputs. None = unused."""
+        return None
+
+    def repo_activity(self) -> str:
+        """Recent commit activity across the project's tracked repos.
+
+        Default returns "" (no repo activity tracked). Override to wire
+        the activity-watch recipe to your repos.
+        """
+        return ""
+
+    def questions_listing(self) -> str:
+        """Plain-text listing of the discovery questions workspace.
+
+        Default returns "" (workspace absent). Override to enumerate
+        files for the questions-due recipe.
+        """
+        return ""

gooseloop/engine.py

@@ -0,0 +1,68 @@
+"""Engine abstract base class.
+
+Per ADRs 0001 (engine returns Pipeline), 0006 (named-slot Pipeline), 0007
+(BranchPolicy registry). The framework runs the Pipeline; the engine owns
+what's inside it.
+
+There is no decorator-based engine registry in v1.0. The CLI imports the
+engine module declared in gooseloop.toml and reads the engine class from
+that module's `engine` attribute (set by the engine's __init__.py). This
+keeps gooseloop.toml as the single source of truth for "which engine"
+without runtime registration side effects.
+"""
+
+from abc import ABC, abstractmethod
+
+from .branch_policy import BranchPolicy
+from .phase import Context, Pipeline
+
+
+class Engine(ABC):
+    """Implement this to plug into GooseLooper.
+
+    Required:
+        name        — short slug for logs, footers, config.
+        pipeline()  — returns the Pipeline (review + body + summary).
+
+    Optional:
+        branch_policies — dict of recipe-name → BranchPolicy for routing[].
+            May be overridden at the class level (static policies) or as
+            an instance attribute / @property (policies that close over
+            engine state like an output directory).
+        base_env()      — env vars injected into every recipe call.
+        precheck()      — run before the pipeline; raise to abort.
+        recipes_dir()   — where engine-bundled recipes live.
+        default_model() — engine-recommended model.
+    """
+
+    branch_policies: dict[str, BranchPolicy] = {}
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Short slug. Conventionally lowercase, hyphenated."""
+
+    @abstractmethod
+    def pipeline(self, ctx: Context) -> Pipeline:
+        """The Pipeline for one begin_loop() pass.
+
+        Free to do pre-pipeline work (snapshot state, build a digest) and
+        bake the results into the first Phase's build_env or ctx.artifacts.
+        Must return a Pipeline with review and summary phases set; body
+        may be empty.
+        """
+
+    def base_env(self) -> dict[str, str]:
+        """Engine-only env additions. Environment.env_vars() covers paths."""
+        return {}
+
+    def precheck(self, ctx: Context) -> None:
+        """Run once before the pipeline. Raise to abort the pass."""
+
+    def recipes_dir(self) -> str:
+        """Engine-bundled recipes location, relative to the engine module."""
+        return "recipes"
+
+    def default_model(self) -> str | None:
+        """Engine-suggested default model. None = use whatever the Looper has."""
+        return None

gooseloop/environment.py

@@ -0,0 +1,31 @@
+"""Environment abstract base class.
+
+Per ADR 0005 the framework ABC has exactly one abstract method: env_vars().
+Shape-specific contracts (Storm's customer pipeline, Claude design-handoff,
+future domains) live as separate ABCs under gooseloop.contrib.* and inherit
+from this base.
+
+Engines pull paths and project-data via ctx.environment, calling whatever
+methods the concrete instance exposes. Recipes paste content via the
+env_method:<name> source kind in their context: block.
+"""
+
+from abc import ABC, abstractmethod
+
+
+class Environment(ABC):
+    """Minimum the framework requires from an Environment.
+
+    A concrete environment must return the env vars the looper should merge
+    into every recipe call. Everything else (paths, loaders, project data)
+    is shape-specific and lives on a contrib mixin or the concrete class.
+    """
+
+    @abstractmethod
+    def env_vars(self) -> dict[str, str]:
+        """Env vars merged into every recipe call.
+
+        Conventionally includes ${VAR} interpolations the engine's recipes
+        reference (e.g. POTENTIAL_DIR, OUTREACH_DIR, CORE_DIR for a customer
+        pipeline; HANDOFF_DIR, TARGET_REPO for a handoff engine).
+        """