krnl-code 1.0.4__py3-none-any.whl

krnl_agent/context.py

@@ -0,0 +1,352 @@
+"""Context-window management and @file mention expansion.
+
+- `estimate_tokens` — a cheap, dependency-free token estimate (~4 chars/token).
+- `expand_mentions` — turns `@path/to/file` in a task into inlined file content.
+- `compact_history` — when the conversation gets too big, trims the oldest tool
+  outputs (safe: it never breaks the assistant→tool message pairing) so the
+  request stays under the model's budget.
+
+Phase 2 additions:
+- `get_graph_aware_context` — uses the code knowledge graph to pull in relevant
+  code (callers, callees, parent classes) up to a configurable hop limit.
+- `DifferentialContextTracker` — tracks what's been sent to the model this session
+  and sends only diffs on subsequent turns.
+- `compact_with_summarization` — improves compaction by summarizing dropped content.
+"""
+from __future__ import annotations
+
+import hashlib
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:
+    from .tools import ToolContext
+
+_MENTION_RE = re.compile(r"(?<!\w)@([A-Za-z0-9_./\\\-]+)")
+_TRIM_NOTE = "[older tool output trimmed to save context]"
+
+
+def estimate_tokens(messages: list[dict]) -> int:
+    chars = 0
+    for m in messages:
+        c = m.get("content")
+        if isinstance(c, str):
+            chars += len(c)
+        for tc in m.get("tool_calls") or []:
+            chars += len(str(tc.get("function", {}).get("arguments", "")))
+    return chars // 4
+
+
+def expand_mentions(task: str, ctx: "ToolContext") -> str:
+    """Inline the contents of any @-mentioned files that exist in the workspace."""
+    seen: set[str] = set()
+    blocks: list[str] = []
+    for match in _MENTION_RE.finditer(task):
+        rel = match.group(1).strip(".,;:)")
+        if rel in seen:
+            continue
+        seen.add(rel)
+        try:
+            if ctx.is_ignored(rel):
+                continue
+            full = ctx.resolve(rel)
+            if not full.is_file():
+                continue
+            if full.stat().st_size > ctx.cfg.max_file_bytes:
+                blocks.append(f"--- @{rel} (too large to inline) ---")
+                continue
+            text = full.read_text(encoding="utf-8", errors="replace")
+            blocks.append(f"--- @{rel} ---\n{text}")
+        except Exception:
+            continue
+    if not blocks:
+        return task
+    return task + "\n\nReferenced files:\n" + "\n\n".join(blocks)
+
+
+def compact_history(messages: list[dict], max_tokens: int, keep_recent: int = 6):
+    """Return (messages, changed). Trims oldest tool outputs when over budget."""
+    if estimate_tokens(messages) <= max_tokens:
+        return messages, False
+    out = [dict(m) for m in messages]
+    # never touch the system message (0) or the most recent `keep_recent`
+    end = max(1, len(out) - keep_recent)
+    changed = False
+    for i in range(1, end):
+        if estimate_tokens(out) <= max_tokens:
+            break
+        m = out[i]
+        if m.get("role") == "tool" and m.get("content") != _TRIM_NOTE:
+            m["content"] = _TRIM_NOTE
+            changed = True
+    return out, changed
+
+
+_SUMMARY_SYS = (
+    "Summarize this coding-session transcript into a concise brief a developer "
+    "needs to continue: decisions made, files changed, current state, and what's "
+    "left. Be factual and specific; no fluff."
+)
+
+
+def summarize_history(client, messages: list[dict], keep_recent: int = 4):
+    """Replace the middle of the conversation with an LLM-written summary.
+    Returns (new_messages, changed). Preserves assistant→tool message pairing.
+    """
+    if len(messages) <= keep_recent + 2:
+        return messages, False
+    system = messages[0]
+    cut = len(messages) - keep_recent
+    while cut > 1 and messages[cut].get("role") == "tool":
+        cut -= 1
+    middle = messages[1:cut]
+    recent = messages[cut:]
+    if not middle:
+        return messages, False
+
+    lines = []
+    for m in middle:
+        role = m.get("role", "?")
+        content = m.get("content") or ""
+        if m.get("tool_calls"):
+            names = ", ".join(tc["function"]["name"] for tc in m["tool_calls"])
+            content = (content + f" [called: {names}]").strip()
+        lines.append(f"{role}: {content}")
+    transcript = "\n".join(lines)[:12000]
+
+    try:
+        resp = client.chat(
+            [
+                {"role": "system", "content": _SUMMARY_SYS},
+                {"role": "user", "content": transcript},
+            ],
+            None,
+            None,
+            False,
+        )
+        summary = resp.content
+    except Exception:
+        return messages, False
+
+    new = [system, {"role": "user", "content": "[Summary of earlier conversation]\n" + summary}]
+    new += recent
+    return new, True
+
+
+# --------------------------------------------------------------------------- #
+# Phase 2: Graph-Aware Context Selection
+# --------------------------------------------------------------------------- #
+@dataclass
+class DifferentialContextTracker:
+    """Tracks what content has been sent to the model to enable differential updates."""
+    sent_files: dict[str, str] = field(default_factory=dict)  # file_path -> content_hash
+    sent_graph_nodes: set[str] = field(default_factory=set)  # node_ids that have been sent
+
+    def _hash_content(self, content: str) -> str:
+        """Create a hash of content for change detection."""
+        return hashlib.md5(content.encode("utf-8")).hexdigest()
+
+    def update_file(self, file_path: str, content: str) -> bool:
+        """Update tracking for a file. Returns True if content changed."""
+        content_hash = self._hash_content(content)
+        if file_path in self.sent_files:
+            if self.sent_files[file_path] == content_hash:
+                return False  # No change
+        self.sent_files[file_path] = content_hash
+        return True
+
+    def add_graph_nodes(self, node_ids: list[str]) -> None:
+        """Mark graph nodes as sent."""
+        self.sent_graph_nodes.update(node_ids)
+
+    def get_file_diff(self, file_path: str, content: str) -> Optional[str]:
+        """Return content if file changed, None if unchanged."""
+        content_hash = self._hash_content(content)
+        if file_path in self.sent_files and self.sent_files[file_path] == content_hash:
+            return None  # Unchanged
+        return content
+
+    def get_new_graph_nodes(self, node_ids: list[str]) -> list[str]:
+        """Return node IDs that haven't been sent yet."""
+        return [nid for nid in node_ids if nid not in self.sent_graph_nodes]
+
+
+def get_graph_aware_context(
+    task: str,
+    ctx: "ToolContext",
+    graph_manager,
+    hop_limit: int = 1,
+    tracker: Optional[DifferentialContextTracker] = None,
+) -> str:
+    """Use the code knowledge graph to pull in relevant code.
+
+    Given the current task/files-in-focus, use the Phase 1 graph to pull in
+    directly connected nodes (callers, callees, parent classes) up to a
+    configurable hop limit.
+
+    If tracker is provided, only returns new/changed content.
+    """
+    if not graph_manager or not graph_manager.graph.node_by_id:
+        return ""  # Graph not available or empty
+
+    # Extract @file mentions from task to find focus files
+    focus_files = set()
+    for match in _MENTION_RE.finditer(task):
+        rel = match.group(1).strip(".,;:)")
+        try:
+            if not ctx.is_ignored(rel):
+                full = ctx.resolve(rel)
+                if full.is_file():
+                    focus_files.add(str(full))
+        except Exception:
+            continue
+
+    if not focus_files:
+        return ""  # No focus files, no graph context needed
+
+    # Get graph nodes for focus files
+    focus_node_ids = set()
+    for file_path in focus_files:
+        nodes = graph_manager.graph.get_nodes_by_file(file_path)
+        focus_node_ids.update(n.id for n in nodes)
+
+    # Get neighbors within hop limit
+    relevant_node_ids = set(focus_node_ids)
+    current_level = set(focus_node_ids)
+
+    for _hop in range(hop_limit):
+        next_level = set()
+        for nid in current_level:
+            neighbors = graph_manager.graph.get_neighbors(nid, direction="out")
+            for neighbor in neighbors:
+                if neighbor.id not in relevant_node_ids:
+                    relevant_node_ids.add(neighbor.id)
+                    next_level.add(neighbor.id)
+        current_level = next_level
+        if not current_level:
+            break
+
+    # If using differential tracking, filter to new nodes
+    if tracker:
+        new_node_ids = tracker.get_new_graph_nodes(list(relevant_node_ids))
+        relevant_node_ids = set(new_node_ids)
+
+    # Collect file paths for relevant nodes
+    relevant_files = set()
+    for nid in relevant_node_ids:
+        node = graph_manager.graph.get_node(nid)
+        if node:
+            relevant_files.add(node.file_path)
+
+    # Read file contents (with differential tracking)
+    context_parts = []
+    for file_path in sorted(relevant_files):
+        try:
+            if ctx.is_ignored(file_path):
+                continue
+            full_path = Path(file_path)
+            if not full_path.is_file():
+                continue
+            if full_path.stat().st_size > ctx.cfg.max_file_bytes:
+                continue
+            content = full_path.read_text(encoding="utf-8", errors="replace")
+
+            # Differential tracking
+            if tracker:
+                diff_content = tracker.get_file_diff(file_path, content)
+                if diff_content is None:
+                    continue  # Unchanged, skip
+                content = diff_content
+                tracker.update_file(file_path, content)
+
+            context_parts.append(f"--- {file_path} ---\n{content}")
+        except Exception:
+            continue
+
+    # Mark nodes as sent
+    if tracker:
+        tracker.add_graph_nodes(list(relevant_node_ids))
+
+    if not context_parts:
+        return ""
+
+    return "\n\n".join(context_parts)
+
+
+def compact_with_summarization(
+    messages: list[dict],
+    max_tokens: int,
+    keep_recent: int = 6,
+    client=None,
+) -> tuple[list[dict], bool]:
+    """Compact history with LLM summarization of dropped content.
+
+    When compaction triggers, summarize dropped tool output/decisions rather
+    than naive oldest-first drop. This improves compaction quality at the
+    truncation boundary.
+    """
+    if estimate_tokens(messages) <= max_tokens:
+        return messages, False
+
+    if not client:
+        # Fall back to simple compaction if no client available
+        return compact_history(messages, max_tokens, keep_recent)
+
+    out = [dict(m) for m in messages]
+    changed = False
+
+    # Find content to drop
+    to_summarize = []
+    keep_indices = {0, len(out) - 1}  # Always keep system and last message
+    for i in range(len(out) - keep_recent, len(out)):
+        keep_indices.add(i)
+
+    for i in range(1, len(out) - 1):
+        if i in keep_indices:
+            continue
+        if estimate_tokens(out) <= max_tokens:
+            break
+        m = out[i]
+        if m.get("role") in ("user", "assistant"):
+            to_summarize.append((i, m))
+            out[i] = None  # Mark for removal
+            changed = True
+
+    # Remove marked messages
+    out = [m for m in out if m is not None]
+
+    # Generate summary if we dropped content
+    if to_summarize and client:
+        try:
+            summary_text = "\n".join(
+                f"{m.get('role', '?')}: {m.get('content', '')[:500]}"
+                for _, m in to_summarize
+            )
+            summary_text = summary_text[:8000]  # Limit summary input
+
+            resp = client.chat(
+                [
+                    {
+                        "role": "system",
+                        "content": "Summarize this conversation excerpt concisely. Focus on: decisions made, files changed, errors encountered, and current state.",
+                    },
+                    {"role": "user", "content": summary_text},
+                ],
+                None,
+                None,
+                False,
+            )
+
+            # Insert summary after system message
+            summary_msg = {
+                "role": "user",
+                "content": f"[Summary of earlier conversation]\n{resp.content}",
+            }
+            out.insert(1, summary_msg)
+        except Exception:
+            # If summarization fails, just use simple compaction
+            pass
+
+    return out, changed

krnl_agent/depaudit.py

@@ -0,0 +1,63 @@
+"""Dependency vulnerability audit.
+
+Detects the project's package ecosystem(s) and runs the matching audit tool if it
+is installed - `pip-audit` for Python, `npm audit` for Node, `cargo audit` for
+Rust, `govulncheck` for Go. Each is best-effort: if the tool is missing we say so
+and tell the agent how to install it, rather than failing. The agent can then act
+on the findings (pin/upgrade versions) or surface them to the user.
+"""
+from __future__ import annotations
+
+import shutil
+import subprocess
+
+# (manifest filename, tool exe, audit command, install hint)
+_ECOSYSTEMS = [
+    ("requirements.txt", "pip-audit", "pip-audit -r requirements.txt --progress-spinner off",
+     "pip install pip-audit"),
+    ("pyproject.toml", "pip-audit", "pip-audit --progress-spinner off", "pip install pip-audit"),
+    ("package.json", "npm", "npm audit --omit=dev", "install Node.js / npm"),
+    ("Cargo.toml", "cargo-audit", "cargo audit", "cargo install cargo-audit"),
+    ("go.mod", "govulncheck", "govulncheck ./...", "go install golang.org/x/vuln/cmd/govulncheck@latest"),
+]
+
+
+def audit(ctx, timeout: int = 180) -> tuple[bool, str]:
+    """Run dependency audits for every detected ecosystem. Returns (clean, report)."""
+    root = ctx.root
+    detected = [(mf, exe, cmd, hint) for (mf, exe, cmd, hint) in _ECOSYSTEMS
+                if (root / mf).exists()]
+    if not detected:
+        return True, ("No recognized dependency manifest found "
+                      "(requirements.txt, pyproject.toml, package.json, Cargo.toml, go.mod).")
+
+    blocks: list[str] = []
+    any_findings = False
+    seen_tools: set[str] = set()
+    for manifest, exe, cmd, hint in detected:
+        if exe in seen_tools:
+            continue
+        seen_tools.add(exe)
+        if not shutil.which(exe):
+            blocks.append(f"## {manifest}\n  ⚠ '{exe}' not installed — `{hint}` to enable this audit.")
+            continue
+        try:
+            res = subprocess.run(cmd, cwd=root, shell=True, capture_output=True,
+                                 text=True, timeout=timeout)
+        except subprocess.TimeoutExpired:
+            blocks.append(f"## {manifest}\n  ⚠ {exe} timed out after {timeout}s.")
+            continue
+        except Exception as e:  # noqa: BLE001
+            blocks.append(f"## {manifest}\n  ⚠ {exe} failed to run: {e}")
+            continue
+        out = (res.stdout + "\n" + res.stderr).strip()
+        if len(out) > 6000:
+            out = out[:6000] + "\n… (truncated)"
+        # Non-zero exit from these tools means vulnerabilities were found.
+        status = "VULNERABILITIES FOUND" if res.returncode != 0 else "clean"
+        if res.returncode != 0:
+            any_findings = True
+        blocks.append(f"## {manifest} ({exe}) — {status}\n{out or '(no output)'}")
+
+    report = "Dependency audit\n\n" + "\n\n".join(blocks)
+    return (not any_findings), report

krnl_agent/deploy.py

@@ -0,0 +1,245 @@
+"""Auto-deployment — one sentence to a live URL, across many providers.
+
+A registry of deploy *targets*, each described declaratively: the CLI it needs, the
+env var(s) that hold its credential, the headless deploy/rollback commands, the
+config file(s) it expects, and whether it has a real free tier. The agent (or the
+`deploy` / `ship` commands) uses this to:
+
+  * `readiness()`  — which targets are usable right now (CLI installed + token set),
+  * `suggest()`    — pick a sensible default target for a detected stack,
+  * `deploy_command()` / `rollback_command()` — build the exact shell command,
+  * `config_template()` — scaffold the platform config file.
+
+Nothing here runs a command itself — building the command is separated from running
+it so the loop can route execution through the normal approval + sandbox + audit
+gates. Credentials are referenced by env-var name only and never read into strings.
+"""
+from __future__ import annotations
+
+import os
+import shutil
+from dataclasses import dataclass, field
+
+# kinds: edge | static | paas | container | cloud | db
+@dataclass
+class Target:
+    name: str
+    kind: str
+    cli: str                      # executable that must be installed
+    token_envs: list[str]         # env vars holding the credential (any present = ok)
+    deploy_cmd: str               # headless, non-interactive
+    rollback_cmd: str = ""        # "" = no first-class rollback
+    config_files: list[str] = field(default_factory=list)
+    free_tier: bool = True
+    billable: bool = False        # may create billable infra even on free plans
+    note: str = ""
+    health_supported: bool = True
+
+
+# Ordered roughly by agent-friendliness (one-command source->URL first).
+TARGETS: dict[str, Target] = {
+    # --- Edge / serverless (true one-command, perpetual free tier) ----------- #
+    "cloudrun": Target(
+        "cloudrun", "cloud", "gcloud", ["GOOGLE_APPLICATION_CREDENTIALS"],
+        "gcloud run deploy {service} --source . --region {region} --quiet "
+        "--allow-unauthenticated --format json",
+        "gcloud run services update-traffic {service} --to-revisions {revision}=100 "
+        "--region {region} --quiet",
+        ["Dockerfile (optional — buildpacks used otherwise)"],
+        free_tier=True, note="Always-free 2M req/mo; source->URL in one command."),
+    "cloudflare": Target(
+        "cloudflare", "edge", "wrangler", ["CLOUDFLARE_API_TOKEN"],
+        "npx wrangler deploy",
+        "npx wrangler rollback",
+        ["wrangler.toml"],
+        free_tier=True, note="100k req/day free, no cold start, commercial OK."),
+    "cfpages": Target(
+        "cfpages", "static", "wrangler", ["CLOUDFLARE_API_TOKEN"],
+        "npx wrangler pages deploy {dist}",
+        "", ["wrangler.toml (optional)"],
+        free_tier=True, note="Static/JAMstack on Cloudflare Pages."),
+    # --- PaaS / static (low friction) --------------------------------------- #
+    "vercel": Target(
+        "vercel", "paas", "vercel", ["VERCEL_TOKEN"],
+        "vercel deploy --prod --yes --token $VERCEL_TOKEN",
+        "vercel rollback {deployment} --yes --token $VERCEL_TOKEN",
+        ["vercel.json"],
+        free_tier=True, note="Hobby tier is non-commercial; great for Next.js/front-end."),
+    "netlify": Target(
+        "netlify", "static", "netlify", ["NETLIFY_AUTH_TOKEN"],
+        "netlify deploy --prod --dir {dist}",
+        "", ["netlify.toml"],
+        free_tier=True, note="Generous free static hosting."),
+    "fly": Target(
+        "fly", "container", "fly", ["FLY_API_TOKEN"],
+        "fly deploy --remote-only",
+        "fly releases rollback {version}",
+        ["fly.toml"],
+        free_tier=False, billable=True, note="No free tier (trial only); needs a card."),
+    "railway": Target(
+        "railway", "paas", "railway", ["RAILWAY_TOKEN", "RAILWAY_API_TOKEN"],
+        "railway up --ci",
+        "", ["railway.json"],
+        free_tier=False, billable=True, note="Trial credit only (~$5)."),
+    "render": Target(
+        "render", "paas", "render", ["RENDER_API_KEY"],
+        "render deploys create {service} --confirm --wait --output json",
+        "render rollback {service} --confirm",
+        ["render.yaml"],
+        free_tier=True, note="Free web service spins down when idle. Deploy hooks also work."),
+    # --- Containers / orchestration ----------------------------------------- #
+    "docker": Target(
+        "docker", "container", "docker", ["DOCKER_TOKEN", "DOCKER_PASSWORD"],
+        "docker buildx build --platform linux/amd64 -t {image} --push .",
+        "", ["Dockerfile", ".dockerignore"],
+        free_tier=True, note="Builds & pushes an image to a registry; pair with a runtime."),
+    "helm": Target(
+        "helm", "container", "helm", ["KUBECONFIG"],
+        "helm upgrade --install {release} {chart} -f values.yaml --atomic --timeout 5m",
+        "helm rollback {release} {revision}",
+        ["Chart.yaml", "values.yaml"],
+        free_tier=True, billable=True,
+        note="--atomic auto-rolls-back on failed deploy (self-healing primitive)."),
+    "kubernetes": Target(
+        "kubernetes", "container", "kubectl", ["KUBECONFIG"],
+        "kubectl apply -f {manifest}",
+        "kubectl rollout undo deployment/{deployment}",
+        ["*.yaml"],
+        free_tier=True, billable=True, note="Cluster costs apply."),
+    # --- Big cloud ---------------------------------------------------------- #
+    "aws-sam": Target(
+        "aws-sam", "cloud", "sam", ["AWS_ACCESS_KEY_ID"],
+        "sam deploy --no-confirm-changeset --resolve-s3 --capabilities CAPABILITY_IAM",
+        "", ["template.yaml", "samconfig.toml"],
+        free_tier=True, billable=True, note="Smoothest AWS path after first --guided run."),
+    "aws-apprunner": Target(
+        "aws-apprunner", "cloud", "aws", ["AWS_ACCESS_KEY_ID"],
+        "aws apprunner create-service --cli-input-json file://apprunner.json",
+        "", ["apprunner.json"],
+        free_tier=False, billable=True, note="Consumption-billed container service."),
+    "azure-aca": Target(
+        "azure-aca", "cloud", "az", ["AZURE_CLIENT_ID"],
+        "az containerapp up --name {service} --source .",
+        "", ["app.yaml (optional)"],
+        free_tier=True, billable=True, note="Always-free 2M req/mo; source->URL."),
+    # --- Databases (provisioned before the app) ----------------------------- #
+    "neon": Target(
+        "neon", "db", "neonctl", ["NEON_API_KEY"],
+        "neonctl projects create --name {name} --output json",
+        "", [], free_tier=True,
+        note="Serverless Postgres, instant branches, generous free tier."),
+    "supabase": Target(
+        "supabase", "db", "supabase", ["SUPABASE_ACCESS_TOKEN"],
+        "supabase db push",
+        "", ["supabase/config.toml"], free_tier=True,
+        note="Full backend: Postgres + auth + storage + edge functions."),
+}
+
+# Default target preference order for an autodetected app (free + one-command first).
+_DEFAULT_ORDER = ["cloudrun", "cloudflare", "vercel", "netlify", "render", "fly",
+                  "railway", "azure-aca", "aws-sam", "helm"]
+
+
+def target(name: str) -> Target | None:
+    return TARGETS.get(name)
+
+
+def has_token(t: Target) -> bool:
+    return any(os.getenv(e) for e in t.token_envs)
+
+
+def cli_installed(t: Target) -> bool:
+    return shutil.which(t.cli) is not None
+
+
+def readiness() -> list[dict]:
+    """One row per target: is the CLI installed, is a token set, is it usable now."""
+    rows = []
+    for t in TARGETS.values():
+        rows.append({
+            "name": t.name, "kind": t.kind, "cli": t.cli,
+            "cli_ok": cli_installed(t),
+            "token_env": " or ".join(t.token_envs),
+            "token_ok": has_token(t),
+            "ready": cli_installed(t) and has_token(t),
+            "free_tier": t.free_tier, "billable": t.billable, "note": t.note,
+        })
+    return rows
+
+
+def suggest(detected_stack: str = "", prefer_ready: bool = True) -> str | None:
+    """Pick a default deploy target. Prefer one that's ready (CLI+token), else the
+    most agent-friendly free option for the order list."""
+    order = list(_DEFAULT_ORDER)
+    s = (detected_stack or "").lower()
+    if any(k in s for k in ("next", "react", "vite", "static", "astro", "vue")):
+        order = ["vercel", "netlify", "cloudflare", "cfpages"] + order
+    if prefer_ready:
+        for name in order:
+            t = TARGETS.get(name)
+            if t and cli_installed(t) and has_token(t):
+                return name
+    for name in order:
+        if name in TARGETS:
+            return name
+    return None
+
+
+def _fill(cmd: str, params: dict) -> str:
+    out = cmd
+    for k, v in (params or {}).items():
+        out = out.replace("{" + k + "}", str(v))
+    return out
+
+
+def deploy_command(name: str, params: dict | None = None) -> tuple[bool, str]:
+    """Return (ok, command-or-error). Does NOT run it."""
+    t = TARGETS.get(name)
+    if not t:
+        return False, f"Unknown deploy target '{name}'. Known: {', '.join(TARGETS)}"
+    if not cli_installed(t):
+        return False, f"'{t.cli}' CLI not installed for target {name}."
+    if not has_token(t):
+        return False, (f"No credential for {name}: set one of "
+                       f"{', '.join(t.token_envs)} in the environment.")
+    return True, _fill(t.deploy_cmd, params or {})
+
+
+def rollback_command(name: str, params: dict | None = None) -> tuple[bool, str]:
+    t = TARGETS.get(name)
+    if not t:
+        return False, f"Unknown target '{name}'."
+    if not t.rollback_cmd:
+        return False, f"{name} has no first-class rollback command."
+    return True, _fill(t.rollback_cmd, params or {})
+
+
+# ---- config-file scaffolds (minimal, safe starting points) ----------------- #
+_CONFIGS = {
+    "fly.toml": (
+        'app = "{app}"\nprimary_region = "{region}"\n\n'
+        '[build]\n\n[http_service]\n  internal_port = {port}\n  force_https = true\n'
+        '  auto_stop_machines = true\n  auto_start_machines = true\n  min_machines_running = 0\n'),
+    "render.yaml": (
+        "services:\n  - type: web\n    name: {app}\n    runtime: docker\n"
+        "    plan: free\n    healthCheckPath: /health\n"),
+    "vercel.json": '{\n  "version": 2\n}\n',
+    "wrangler.toml": (
+        'name = "{app}"\nmain = "{entry}"\ncompatibility_date = "2024-01-01"\n'),
+    "Dockerfile.python": (
+        "FROM python:3.12-slim\nWORKDIR /app\nCOPY requirements.txt .\n"
+        "RUN pip install --no-cache-dir -r requirements.txt\nCOPY . .\n"
+        "EXPOSE {port}\nCMD [\"python\", \"{entry}\"]\n"),
+    "Dockerfile.node": (
+        "FROM node:20-slim\nWORKDIR /app\nCOPY package*.json ./\nRUN npm ci --omit=dev\n"
+        "COPY . .\nEXPOSE {port}\nCMD [\"node\", \"{entry}\"]\n"),
+}
+
+
+def config_template(kind: str, params: dict | None = None) -> str | None:
+    tpl = _CONFIGS.get(kind)
+    if tpl is None:
+        return None
+    p = {"app": "my-app", "region": "iad", "port": 8080, "entry": "main.py"}
+    p.update(params or {})
+    return _fill(tpl, p)