tactus 0.29.4__tar.gz → 0.30.0__tar.gz

{tactus-0.29.4 → tactus-0.30.0}/AGENTS.md

@@ -376,6 +376,10 @@ Tactus has two distinct testing mechanisms that serve different purposes:
 
 The Tactus CLI provides powerful tools for developing and debugging agents.
 
+### Formatting `.tac` Files
+
+Use `tactus format` to automatically reindent and normalize whitespace in `.tac` files.
+
 ### Running and Debugging Procedures
 
 When you run a procedure with `tactus run`, you get real-time visibility into what's happening:

{tactus-0.29.4 → tactus-0.30.0}/CHANGELOG.md

@@ -2,6 +2,9 @@
 
 <!-- version list -->
 
+## v0.30.0 (2026-01-15)
+
+
 ## v0.29.4 (2026-01-15)
 
 ### Bug Fixes

{tactus-0.29.4 → tactus-0.30.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tactus
-Version: 0.29.4
+Version: 0.30.0
 Summary: Tactus: Lua-based DSL for agentic workflows
 Project-URL: Homepage, https://github.com/AnthusAI/Tactus
 Project-URL: Documentation, https://github.com/AnthusAI/Tactus/tree/main/docs
@@ -1665,6 +1665,12 @@ Agents:
 # Validate syntax and structure
 tactus validate workflow.tac
 
+# Format a workflow file (2-space indentation + normalized spacing)
+tactus format workflow.tac
+
+# Check formatting without rewriting (exit 1 if changes needed)
+tactus format workflow.tac --check
+
 # Run BDD specifications
 tactus test workflow.tac
 
@@ -1675,6 +1681,8 @@ tactus test workflow.tac --runs 10
 tactus eval workflow.tac --runs 10
 ```
 
+The `format` command uses Tactus's Lua parser to reindent and normalize whitespace while preserving the structure of the code.
+
 ### Understanding Output
 
 The CLI displays several types of events:

{tactus-0.29.4 → tactus-0.30.0}/README.md

@@ -1614,6 +1614,12 @@ Agents:
 # Validate syntax and structure
 tactus validate workflow.tac
 
+# Format a workflow file (2-space indentation + normalized spacing)
+tactus format workflow.tac
+
+# Check formatting without rewriting (exit 1 if changes needed)
+tactus format workflow.tac --check
+
 # Run BDD specifications
 tactus test workflow.tac
 
@@ -1624,6 +1630,8 @@ tactus test workflow.tac --runs 10
 tactus eval workflow.tac --runs 10
 ```
 
+The `format` command uses Tactus's Lua parser to reindent and normalize whitespace while preserving the structure of the code.
+
 ### Understanding Output
 
 The CLI displays several types of events:

{tactus-0.29.4 → tactus-0.30.0}/examples/02-basics-simple-logic.tac

@@ -6,36 +6,36 @@ Stages({"start", "middle", "end"})
 
 -- Procedure with input, output, and state defined inline
 Procedure {
-    input = {
-        target_count = field.number{required = false, description = "Target counter value", default = 5},
-    },
-    output = {
-        final_count = field.number{required = true, description = "Final counter value"},
-        message = field.string{required = true, description = "Status message"},
-    },
-    function(input)
-        -- Initialize
-        Stage.set("start")
+  input = {
+    target_count = field.number{required = false, description = "Target counter value", default = 5},
+  },
+  output = {
+    final_count = field.number{required = true, description = "Final counter value"},
+    message = field.string{required = true, description = "Status message"},
+  },
+  function(input)
+    -- Initialize
+    Stage.set("start")
 
-        -- Do work
-        local target = input.target_count or 5
-        for i = 1, target do
-            state.counter = i
-        end
+    -- Do work
+    local target = input.target_count or 5
+    for i = 1, target do
+      state.counter = i
+    end
 
-        -- Transition to middle
-        Stage.set("middle")
-        state.message = "halfway"
+    -- Transition to middle
+    Stage.set("middle")
+    state.message = "halfway"
 
-        -- Complete
-        Stage.set("end")
-        state.message = "complete"
+    -- Complete
+    Stage.set("end")
+    state.message = "complete"
 
-        return {
-            final_count = state.counter,
-            message = state.message
-        }
-    end
+    return {
+      final_count = state.counter,
+      message = state.message
+    }
+  end
 }
 
 -- BDD Specifications

tactus-0.30.0/features/60_formatting.feature

@@ -0,0 +1,37 @@
+Feature: Formatting
+  Formatting produces stable, canonical Lua DSL text.
+
+  Scenario: Formatting enforces 2-space semantic indentation
+    Given a formatting environment
+    And a Lua DSL file with formatting issues
+    When I run "tactus format" on the file
+    Then the format command should succeed
+    And the file should be formatted with 2-space indentation
+
+  Scenario: Formatting is idempotent
+    Given a formatting environment
+    And a Lua DSL file with formatting issues
+    When I run "tactus format" on the file
+    And I run "tactus format" on the file
+    Then the format command should succeed
+    And the file should be unchanged by the second run
+
+  Scenario: Check mode detects required changes
+    Given a formatting environment
+    And a Lua DSL file with formatting issues
+    When I run "tactus format --check" on the file
+    Then the format command should fail
+
+  Scenario: Check mode passes when formatted
+    Given a formatting environment
+    And a Lua DSL file with formatting issues
+    When I run "tactus format" on the file
+    And I run "tactus format --check" on the file
+    Then the format command should succeed
+
+  Scenario: Formatting indents Specifications content
+    Given a formatting environment
+    And a Lua DSL file with Specifications content needing indentation
+    When I run "tactus format" on the file
+    Then the format command should succeed
+    And the Specifications content should be indented by 2 spaces

tactus-0.30.0/features/steps/formatting_steps.py

@@ -0,0 +1,153 @@
+"""
+Step definitions for formatting feature.
+"""
+
+import subprocess
+import tempfile
+from pathlib import Path
+
+from behave import given, then, when
+
+
+@given("a formatting environment")
+def step_impl(context):
+    context.last_cli = None
+    context.last_formatted_content = None
+
+
+@given("a Lua DSL file with formatting issues")
+def step_impl(context):
+    # Intentionally inconsistent indentation (tabs + wrong nesting).
+    context.lua_content = """-- formatting test
+
+Procedure {
+\toutput = {
+\tgreeting=field.string{required=true},
+\tcompleted=field.boolean{required=true},
+\t},
+\tfunction(input)
+\tif 1<2 and 3>4 then
+\treturn {greeting="hi",completed=true}
+\tend
+\tend
+}
+"""
+
+    context.temp_file = tempfile.NamedTemporaryFile(mode="w", suffix=".tac", delete=False)
+    context.temp_file.write(context.lua_content)
+    context.temp_file.close()
+    context.lua_file = Path(context.temp_file.name)
+    context.expected_formatted = """-- formatting test
+
+Procedure {
+  output = {
+    greeting = field.string{required = true},
+    completed = field.boolean{required = true}
+  },
+  function(input)
+    if 1 < 2 and 3 > 4 then
+      return {greeting = "hi", completed = true}
+    end
+  end
+}
+"""
+
+
+@given("a Lua DSL file with Specifications content needing indentation")
+def step_impl(context):
+    context.lua_content = """Specifications([[
+Feature: Simple State Management
+  Test basic state and stage functionality without agents
+]])\n"""
+
+    context.temp_file = tempfile.NamedTemporaryFile(mode="w", suffix=".tac", delete=False)
+    context.temp_file.write(context.lua_content)
+    context.temp_file.close()
+    context.lua_file = Path(context.temp_file.name)
+
+    context.expected_specifications_formatted = """Specifications([[
+  Feature: Simple State Management
+    Test basic state and stage functionality without agents
+]])\n"""
+
+
+@when('I run "tactus format" on the file')
+def step_impl(context):
+    import sys
+
+    before = context.lua_file.read_text()
+    result = subprocess.run(
+        [sys.executable, "-m", "tactus.cli.app", "format", str(context.lua_file)],
+        capture_output=True,
+        text=True,
+    )
+    after = context.lua_file.read_text()
+
+    context.last_cli = result
+    context.last_formatted_content = after
+    context._before_after = (before, after)
+
+
+@when('I run "tactus format --check" on the file')
+def step_impl(context):
+    import sys
+
+    result = subprocess.run(
+        [
+            sys.executable,
+            "-m",
+            "tactus.cli.app",
+            "format",
+            "--check",
+            str(context.lua_file),
+        ],
+        capture_output=True,
+        text=True,
+    )
+    context.last_cli = result
+
+
+@then("the format command should succeed")
+def step_impl(context):
+    assert context.last_cli is not None, "No command was run"
+    assert (
+        context.last_cli.returncode == 0
+    ), f"Command failed: {context.last_cli.returncode}\nSTDOUT:\n{context.last_cli.stdout}\nSTDERR:\n{context.last_cli.stderr}"
+
+
+@then("the format command should fail")
+def step_impl(context):
+    assert context.last_cli is not None, "No command was run"
+    assert context.last_cli.returncode != 0, "Command unexpectedly succeeded"
+
+
+@then("the file should be formatted with 2-space indentation")
+def step_impl(context):
+    content = context.lua_file.read_text().splitlines()
+    # Ensure no tabs remain at line starts and indentation uses multiples of 2.
+    for line in content:
+        stripped = line.lstrip(" \t")
+        if stripped == "":
+            continue
+        leading = line[: len(line) - len(stripped)]
+        assert "\t" not in leading, f"Found tab indentation: {line!r}"
+        assert len(leading) % 2 == 0, f"Indentation is not a multiple of 2 spaces: {line!r}"
+
+    assert (
+        context.lua_file.read_text() == context.expected_formatted
+    ), "Formatted output did not match expected canonical indentation"
+
+
+@then("the file should be unchanged by the second run")
+def step_impl(context):
+    before, after = context._before_after
+    assert (
+        before == after
+    ), "Second formatting run changed file content (formatter is not idempotent)"
+
+
+@then("the Specifications content should be indented by 2 spaces")
+def step_impl(context):
+    assert (
+        context.lua_file.read_text() == context.expected_specifications_formatted
+    ), "Specifications content did not match expected indentation"

tactus-0.30.0/planning/FORMATTER.md

@@ -0,0 +1,48 @@
+# Formatter Roadmap (Lua DSL)
+
+## Goal
+
+Provide a stable formatter for `.tac` / `.lua` that preserves meaning, keeps comments, and converges to a single canonical style. This should be developed BDD-first with idempotence guarantees from the start.
+
+## Milestones
+
+### Milestone A: Semantic Indentation Formatter
+
+Primary requirement:
+- Enforce 2-space indentation based on syntactic structure (not lexical heuristics).
+
+Scope:
+- Reindent lines using the ANTLR token stream / parse result.
+- Preserve existing line breaks and token spelling.
+- Preserve comments and avoid rewriting inside multi-line comments/strings.
+- Idempotent output (formatting twice yields the same file).
+
+Non-goals:
+- Line wrapping, alignment, or spacing normalization beyond indentation.
+
+### Milestone B: Canonical Pretty Printer
+
+Primary requirement:
+- Black-like canonical formatting beyond indentation.
+
+Scope (incremental):
+- Normalize spaces around operators, commas, braces/parens.
+- Canonical table formatting (inline vs multiline decisions).
+- Stable line breaking within a configured line length.
+- Robust comment attachment and placement.
+- Preserve (or consistently normalize) string literal forms where safe.
+
+Non-goals:
+- Formatting arbitrary Lua “perfectly” in the first iteration; prioritize the Tactus DSL subset and expand.
+
+## Test Strategy (BDD + Pytest)
+
+- Behave scenarios:
+  - `tactus format` rewrites indentation to 2 spaces.
+  - `tactus format --check` fails when changes are needed.
+  - Idempotence: running `tactus format` twice does not change output.
+- Pytest unit tests:
+  - Idempotence at the formatter API level.
+  - Representative fixtures for nested blocks and tables.
+  - Negative tests (invalid input should not be formatted).
+

{tactus-0.29.4 → tactus-0.30.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "tactus"
-version = "0.29.4"
+version = "0.30.0"
 description = "Tactus: Lua-based DSL for agentic workflows"
 readme = "README.md"
 requires-python = ">=3.11"

{tactus-0.29.4 → tactus-0.30.0}/tactus/__init__.py

@@ -5,7 +5,7 @@ Tactus provides a declarative workflow engine for AI agents with pluggable
 backends for storage, HITL, and chat recording.
 """
 
-__version__ = "0.29.4"
+__version__ = "0.30.0"
 
 # Core exports
 from tactus.core.runtime import TactusRuntime