Merge pull request #3 from dstackai/feat/program-variables-support

Add program variable support with preview diffs and docs

Author: peterschmidt85

README.md

@@ -82,12 +82,22 @@ CLAUDEFORM_VERSION=v0.0.2 curl -fsSL https://raw.githubusercontent.com/dstackai/
 cf apply -f examples/smoke.md
 ```
 
+Override a program variable for one run:
+
+```bash
+cf apply -f examples/smoke.md --var SMOKE_VALUE=YU
+```
+
+The confirmation preview includes a variables summary, for example: `variables: 1 value changed, 0 added, 0 removed`.
+
+Program variables are defined in frontmatter under `variables` (`NAME: {}` for required, `NAME: { default: "..." }` for optional defaults) and referenced as `${{ var.NAME }}`.
+
 Example output (will vary by session/model):
 
 ```text
 cf apply -f examples/smoke.md
 Last session: 019d5843-eb2d-70b1-b49a-343033117944 (success, 43m ago)
-  program diff: examples/smoke.md unchanged
+  program: examples/smoke.md unchanged
   changes: 0 files
 Proceed? [y/N] y
 session 019d586b-aa65-78b2-8a0d-27b5543c59bb

contrib/ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # Claudeform Architecture
 
-Last updated: 2026-04-04  
+Last updated: 2026-04-06  
 Status: v0 (implemented baseline)
 
 ## 1) Product Goal
@@ -9,7 +9,7 @@ Claudeform runs agent work from markdown files instead of chat windows.
 
 A **program** is one markdown file (`*.md`) representing one task.
 
-- frontmatter is tool-owned and strict (`id`, `model`)
+- frontmatter is tool-owned and strict (`id`, `model`, `variables`)
 - markdown body is agent-facing and free-form
 
 ## 2) Implemented v0 Scope
@@ -57,6 +57,11 @@ Frontmatter (strict):
 
 - `id` (optional)
 - `model` (optional override)
+- `variables` (optional map)
+  - key: variable name (`[A-Za-z_][A-Za-z0-9_]*`)
+  - value:
+    - required (no default): `NAME: {}`
+    - optional default: `NAME: { default: "value" }`
 
 Program key resolution:
 
@@ -65,19 +70,30 @@ Program key resolution:
 
 Markdown body remains untyped in v0 and is interpreted by the agent.
 
+Variable rules:
+
+1. markdown may reference variables as `${{ var.NAME }}`
+2. referenced variables must be defined in frontmatter
+3. apply-time `--var NAME=VALUE` overrides frontmatter default
+4. variables without default are required at apply time
+
 ## 4) Apply Session Flow (Current Behavior)
 
 1. Load program + config and resolve model.
-2. Build preview from last session context:
+2. Resolve program variables (frontmatter defaults + CLI `--var` overrides).
+3. Validate variable definitions and `${{ var.NAME }}` references.
+4. Build preview from last session context:
    - last session status/summary (if exists)
    - program diff vs last session snapshot (if available)
-3. Ask for confirmation (interactive default; skipped by `--yes`).
-4. Run provider in the current workspace (no temp workspace copy).
-5. Stream provider events to terminal and persist artifacts.
-6. Read agent status from `.claudeform/agent_result.json` (required).
-7. Collect reported changed files (events-first, manifest fallback).
-8. Persist session artifacts + history record.
-9. Persist program snapshot (`program.md`) on success.
+   - variable diff vs last session variable snapshot (if available)
+5. Ask for confirmation (interactive default; skipped by `--yes`).
+6. Write runtime variables file (`.claudeform/agent_variables.json`) when variables are present.
+7. Run provider in the current workspace (no temp workspace copy).
+8. Stream provider events to terminal and persist artifacts.
+9. Read agent status from `.claudeform/agent_result.json` (required).
+10. Collect reported changed files (events-first, manifest fallback).
+11. Persist session artifacts + history record.
+12. Persist program snapshot (`program.md`) and variable snapshot (`variables.json`) on success.
 
 ## 5) State and Storage Layout
 
@@ -93,6 +109,7 @@ Per program/session:
 - `<cwd>/.claudeform/programs/<program_id>/sessions/<session_id>/outcome.json`
 - `<cwd>/.claudeform/programs/<program_id>/sessions/<session_id>/output.md` (Claudeform summary)
 - `<cwd>/.claudeform/programs/<program_id>/sessions/<session_id>/program.md` (success snapshot)
+- `<cwd>/.claudeform/programs/<program_id>/sessions/<session_id>/variables.json` (success snapshot)
 - `<cwd>/.claudeform/programs/<program_id>/sessions/<session_id>/commands/*` (captured command outputs)
 - `<cwd>/.claudeform/programs/<program_id>/sessions/<session_id>/messages/*` (captured message outputs)
 
@@ -109,6 +126,7 @@ Agent may write:
 - `<cwd>/.claudeform/agent_result.json` (required)
 - `<cwd>/.claudeform/agent_output.md` (optional human summary)
 - `<cwd>/.claudeform/agent_outputs.json` (optional fallback list of changed files)
+- `<cwd>/.claudeform/agent_variables.json` (runtime resolved variable values provided by Claudeform)
 
 These files are execution protocol files, not user deliverables.
 
@@ -134,23 +152,21 @@ Actual:
 
 These items are intentionally deferred. Each item describes desired product capability, not implementation.
 
-1. Program variables support  
-   Goal: allow programs to define reusable runtime inputs with clear behavior.
-2. Memory support  
+1. Memory support  
    Goal: support durable context across sessions with predictable usage rules.
-3. Plan support  
+2. Plan support  
    Goal: support planning as a first-class workflow, separate from execution.
-4. Interrupted/canceled session handling  
+3. Interrupted/canceled session handling  
    Goal: represent and communicate non-completed runs clearly to users.
-5. Changes/diff reliability and consistency  
+4. Changes/diff reliability and consistency  
    Goal: for the same session, preview, apply output, debug output, and history should report the same changed-file set and line counts, with generated/noise files handled consistently.
-6. Agent-reported changes as single source of truth  
+5. Agent-reported changes as single source of truth  
    Goal: remove legacy local diff-based change reporting and use agent-reported change data consistently across apply, debug, and history.
-7. MCP and broader tool integration model  
+6. MCP and broader tool integration model  
    Goal: support richer external tool and integration patterns.
-8. Multi-agent orchestration model  
+7. Multi-agent orchestration model  
    Goal: support coordinated workflows that involve more than one agent.
-9. Additional providers beyond Codex  
+8. Additional providers beyond Codex  
    Goal: support multiple model providers in a consistent user experience.
-10. Improved session storage and retrieval performance  
+9. Improved session storage and retrieval performance  
    Goal: keep history/state operations fast and scalable as usage grows.

contrib/DEVELOPMENT.md

@@ -155,6 +155,27 @@ Skip confirmation prompt:
 cargo run -p claudeform -- apply -f examples/smoke.md --yes
 ```
 
+Pass program variables at apply time (repeat `--var` as needed):
+
+```bash
+# uses smoke frontmatter default (SMOKE_OK)
+cargo run -p claudeform -- apply -f examples/smoke.md --yes
+
+# smoke has default SMOKE_OK, and this overrides it for one run
+cargo run -p claudeform -- apply -f examples/smoke.md --var SMOKE_VALUE=YU --yes
+```
+
+Notes:
+
+- Variables are defined in program frontmatter under `variables`.
+- Required variable syntax (no default): `NAME: {}`.
+- Optional variable syntax with default: `NAME: { default: "value" }`.
+- Program body references variables via `${{ var.NAME }}`.
+- Confirmation preview includes a variable-diff summary against last session when available.
+- Runtime resolved values are written to `.claudeform/agent_variables.json` for the agent.
+- Successful sessions persist a snapshot at `.claudeform/programs/<program_id>/sessions/<session_id>/variables.json`.
+- If a required variable is missing at apply time, apply fails before provider execution.
+
 Reset session history:
 
 ```bash

crates/claudeform-cli/src/lib.rs

@@ -54,6 +54,10 @@ enum Commands {
         #[arg(short = 'f', long = "file")]
         file: PathBuf,
 
+        /// Program variable value (`NAME=VALUE`). Repeatable.
+        #[arg(long = "var", value_name = "NAME=VALUE", action = ArgAction::Append)]
+        vars: Vec<String>,
+
         /// Auto-approve apply without interactive confirmation prompt.
         #[arg(short = 'y', long)]
         yes: bool,
@@ -139,6 +143,7 @@ fn real_main() -> Result<()> {
     match cli.command {
         Commands::Apply {
             file,
+            vars,
             yes,
             debug,
             progress_mode,
@@ -167,6 +172,7 @@ fn real_main() -> Result<()> {
             };
             let confirm = interactive_shell && !yes;
             let sandbox_mode: SandboxMode = sandbox_mode.into();
+            let program_variables = parse_apply_variables(&vars)?;
 
             if debug {
                 let caps = runner.capabilities();
@@ -196,6 +202,7 @@ fn real_main() -> Result<()> {
                 &ApplyRequest {
                     workspace_root,
                     program_path: file,
+                    program_variables,
                     confirm,
                     debug,
                     progress: true,
@@ -331,6 +338,44 @@ fn confirm_history_reset_interactive(target: &str) -> Result<bool> {
     Ok(matches!(line.trim(), "y" | "Y" | "yes" | "YES"))
 }
 
+fn parse_apply_variables(entries: &[String]) -> Result<BTreeMap<String, String>> {
+    let mut out = BTreeMap::new();
+    for raw in entries {
+        let Some((name_raw, value_raw)) = raw.split_once('=') else {
+            return Err(anyhow!("invalid --var '{}': expected NAME=VALUE", raw));
+        };
+        let name = name_raw.trim();
+        if name.is_empty() {
+            return Err(anyhow!(
+                "invalid --var '{}': variable name cannot be empty",
+                raw
+            ));
+        }
+        if !is_valid_variable_name(name) {
+            return Err(anyhow!(
+                "invalid --var '{}': NAME must match [A-Za-z_][A-Za-z0-9_]*",
+                raw
+            ));
+        }
+        if out.contains_key(name) {
+            return Err(anyhow!("duplicate --var for '{}'", name));
+        }
+        out.insert(name.to_string(), value_raw.to_string());
+    }
+    Ok(out)
+}
+
+fn is_valid_variable_name(name: &str) -> bool {
+    let mut chars = name.chars();
+    let Some(first) = chars.next() else {
+        return false;
+    };
+    if !(first.is_ascii_alphabetic() || first == '_') {
+        return false;
+    }
+    chars.all(|ch| ch.is_ascii_alphanumeric() || ch == '_')
+}
+
 fn yes_no(v: bool) -> &'static str {
     if v {
         "yes"
@@ -737,4 +782,19 @@ mod tests {
             ]
         );
     }
+
+    #[test]
+    fn parse_apply_variables_parses_name_value_pairs() {
+        let vars =
+            parse_apply_variables(&["APP_NAME=calc".to_string(), "APP_PORT=8080".to_string()])
+                .expect("must parse");
+        assert_eq!(vars.get("APP_NAME").map(String::as_str), Some("calc"));
+        assert_eq!(vars.get("APP_PORT").map(String::as_str), Some("8080"));
+    }
+
+    #[test]
+    fn parse_apply_variables_rejects_invalid_name() {
+        let err = parse_apply_variables(&["BAD-NAME=x".to_string()]).expect_err("must fail");
+        assert!(format!("{:#}", err).contains("NAME must match"));
+    }
 }