cbc566

Author: davidk

.gitignore

@@ -17,3 +17,5 @@ system_audit.html
 
 # OS
 .DS_Store
+
+extras/

MANUAL.md

@@ -252,6 +252,47 @@ When reading `[install nginx]`, the dependency keyword should answer "what does
 
 `first [update cache]` reads as a natural instruction: "first, make sure the cache is updated." It's unambiguous about direction, and it matches how ops people actually talk: "first update the cache, then install the package."
 
+### File documentation headers
+
+A `.cgr` file can carry a documentation header that `cgr how FILE` renders for users and agents discovering the file for the first time. The header lives before any `set` or `target` declarations and consists of two optional parts:
+
+**Title line** — a `--- text ---` line on the very first content line:
+
+```
+--- deploy web application ---
+```
+
+**Comment block** — contiguous `#` lines immediately following the title (or at the top if there is no title):
+
+```
+--- authorize SSH key ---
+#
+# Copies your local public key to each host using ssh-copy-id.
+#
+# Usage:
+#   cgr apply authorize_ssh_key.cgr --set hosts="web01,web02,db01"
+#   cgr apply authorize_ssh_key.cgr --set hosts="host1" --set ssh_port=2222
+#
+# Variables:
+#   hosts     — comma-separated list of hostnames or IPs (required)
+#   ssh_user  — remote user (default: $USER from environment)
+#   ssh_port  — SSH port (default: 22)
+
+set hosts    = "192.168.1.10,192.168.1.11"
+set ssh_user = env("USER", "ubuntu")
+set ssh_port = "22"
+```
+
+`cgr how` renders the header and then a **Defaults** table showing each `set` declaration with its raw expression (`env("USER", "ubuntu")` rather than the evaluated value), so users can see exactly what to override.
+
+Conventions for the comment block:
+- Start with a one-line summary sentence.
+- Add a `Usage:` block with copy-pasteable `cgr apply` examples.
+- Add a `Variables:` block listing each user-facing `set` variable with a short description and whether it is required or has a default.
+- For graphs with manual resume steps, add a `Resuming after interruption:` block with `cgr state set` examples.
+
+The parser strips the header before building the AST; it has no effect on execution.
+
 ---
 
 ## Parallel constructs (.cgr format)
@@ -2024,6 +2065,7 @@ This makes the HTML file a self-contained pitch: send someone `webserver.html`,
 | `doctor` | Check environment: Python version, SSH client, sudo, template repo, Vault passphrase, graph files in CWD. |
 | `secrets` | Manage encrypted `.secrets` files for offline secret storage. |
 | `ping FILE` | Verify SSH connectivity to all targets defined in the graph. |
+| `how FILE` | Show the file's documentation header and a **Defaults** table of all `set` declarations with their raw expressions. Works without resolving the graph. |
 | `explain FILE STEP` | Show the full dependency chain for a step. |
 | `why FILE STEP` | Show what steps depend on a step (reverse of explain). |
 | `check FILE` | Re-run all check clauses against the live system and report drift. |
@@ -2256,7 +2298,7 @@ If you are an AI agent tasked with creating a CommandGraph dependency graph, fol
 
 3. **Identify the goal.** What end state must be true on which host(s)?
 
-4. **Check the repo.** Run or simulate `cgr repo index --repo ./repo`. Reuse existing templates wherever possible. Do not reinvent `apt-get install` — use `apt/install_package`.
+4. **Check the repo.** Run or simulate `cgr repo index --repo ./repo`. Reuse existing templates wherever possible. Do not reinvent `apt-get install` — use `apt/install_package`. To understand an existing `.cgr` file's interface before running it, use `cgr how FILE` — it prints the documentation header and a table of all `set` variables with their default expressions.
 
 5. **Decompose backwards.** Start from the end state and work backwards to roots. Draw the tree mentally or in comments.
 

cgr.py

@@ -474,6 +474,10 @@ def main():
     sub.add_parser("doctor",help="Check environment for common issues")
     sub.add_parser("version",help="Show version information")
 
+    # ── How ──────────────────────────────────────────────────────────
+    shw=sub.add_parser("how",help="Show documentation and variables for a graph file")
+    shw.add_argument("file",nargs="?",default=None,help="Graph file (.cgr or .cg)")
+
     # ── Shell completion generator ──────────────────────────────────────
     scmp=sub.add_parser("completion",help="Generate shell completion script")
     scmp.add_argument("shell",choices=["bash","zsh","fish"],help="Shell type")
@@ -497,7 +501,7 @@ def main():
         cmd_init(args.file); return
 
     # ── Auto-detect graph file if not provided ────────────────────────
-    if hasattr(args, "file") and args.file is None and args.command not in ("serve", "init", "repo", "completion", "version", "doctor", "test"):
+    if hasattr(args, "file") and args.file is None and args.command not in ("serve", "init", "repo", "completion", "version", "doctor", "test", "how"):
         args.file = _auto_detect_graph()
 
     if args.command=="convert":
@@ -516,6 +520,9 @@ def main():
     if args.command=="fmt":
         cmd_fmt(args.file); return
 
+    if args.command=="how":
+        cmd_how(args.file); return
+
     if args.command=="secrets":
         cmd_secrets(args.action, args.file, key=args.key, value=args.value, vault_args=args); return
 

cgr_src/cli.py

@@ -181,6 +181,97 @@ def _build_apply_report(graph: Graph, results: list[ExecResult], wall_ms: int,
     return report
 
 
+# ── How command ───────────────────────────────────────────────────────
+
+def _extract_file_header(source: str) -> tuple[str|None, str]:
+    """Return (title, doc_body) from the leading --- / # comment block."""
+    title = None
+    doc_lines: list[str] = []
+    for raw in source.splitlines():
+        stripped = raw.strip()
+        if not stripped:
+            if doc_lines or title:
+                doc_lines.append("")
+            continue
+        if stripped.startswith("---") and stripped.endswith("---") and title is None and not doc_lines:
+            title = stripped[3:-3].strip()
+            continue
+        if stripped.startswith("#"):
+            body = stripped[1:]
+            if body and body[0] in (" ", "\t"):
+                body = body[1:]
+            doc_lines.append(body)
+            continue
+        break  # first non-comment, non-blank line ends the header
+    while doc_lines and not doc_lines[-1]:
+        doc_lines.pop()
+    while doc_lines and not doc_lines[0]:
+        doc_lines.pop(0)
+    return title, "\n".join(doc_lines)
+
+
+def _extract_set_vars(source: str) -> list[tuple[str, str]]:
+    """Return [(name, raw_expr)] for top-level set declarations, preserving env() etc. un-evaluated."""
+    result: list[tuple[str, str]] = []
+    seen: set[str] = set()
+    for raw in source.splitlines():
+        stripped = raw.strip()
+        if stripped.startswith("#"):
+            continue
+        m = re.match(r'^set\s+(\w+)\s*=\s*(.+)', stripped)
+        if m:
+            name, expr = m.group(1), m.group(2).strip()
+            if name == "stateless" or name in seen:
+                continue
+            result.append((name, expr))
+            seen.add(name)
+    return result
+
+
+def cmd_how(filepath: str):
+    """Show header documentation and configurable variables for a graph file."""
+    path = Path(filepath)
+    if not path.exists():
+        print(red(f"error: file not found: {filepath}")); sys.exit(1)
+
+    source = path.read_text()
+    title, doc_body = _extract_file_header(source)
+    raw_vars = _extract_set_vars(source)
+
+    # Best-effort parse to flag secrets
+    secret_names: set[str] = set()
+    try:
+        ast = parse_cg(source, filepath) if filepath.endswith(".cg") else parse_cgr(source, filepath)
+        secret_names = {v.name for v in ast.variables if v.is_secret}
+    except Exception:
+        pass
+
+    print()
+
+    if title:
+        width = min(len(title), 60)
+        print(f"  {bold(title)}")
+        print(f"  {dim('─' * width)}")
+        print()
+
+    if doc_body:
+        for line in doc_body.splitlines():
+            print(f"  {line}" if line else "")
+        print()
+    elif not title:
+        print(f"  {dim('(no documentation header)')}")
+        print()
+
+    if raw_vars:
+        print(f"  {bold('Defaults')}  {dim('(override with --set NAME=VALUE)')}")
+        print()
+        max_len = max(len(n) for n, _ in raw_vars)
+        for name, expr in raw_vars:
+            secret_tag = f"  {dim('[secret]')}" if name in secret_names else ""
+            print(f"    {cyan(name.ljust(max_len))}  {dim('=')}  {expr}{secret_tag}")
+        print()
+
+
 # ── Check command (live drift detection without prior run) ─────────────
 
 def cmd_check(graph, *, max_parallel=4, verbose=False, json_output=False):
@@ -2075,7 +2166,7 @@ def cmd_doctor():
     # Python version
     ver = sys.version.split()[0]
     major, minor = sys.version_info[:2]
-    ok = major >= 3 and minor >= 9
+    ok = (major, minor) >= (3, 9)
     checks.append((ok, f"Python {ver}", "Requires 3.9+" if not ok else ""))
 
     # SSH client