@kindgi/cli 0.1.4 → 0.1.5

package/dist/templates/java/mvnw

@@ -0,0 +1,295 @@
+#!/bin/sh
+# ----------------------------------------------------------------------------
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+# ----------------------------------------------------------------------------
+
+# ----------------------------------------------------------------------------
+# Apache Maven Wrapper startup batch script, version 3.3.4
+#
+# Optional ENV vars
+# -----------------
+#   JAVA_HOME - location of a JDK home dir, required when download maven via java source
+#   MVNW_REPOURL - repo url base for downloading maven distribution
+#   MVNW_USERNAME/MVNW_PASSWORD - user and password for downloading maven
+#   MVNW_VERBOSE - true: enable verbose log; debug: trace the mvnw script; others: silence the output
+# ----------------------------------------------------------------------------
+
+set -euf
+[ "${MVNW_VERBOSE-}" != debug ] || set -x
+
+# OS specific support.
+native_path() { printf %s\\n "$1"; }
+case "$(uname)" in
+CYGWIN* | MINGW*)
+  [ -z "${JAVA_HOME-}" ] || JAVA_HOME="$(cygpath --unix "$JAVA_HOME")"
+  native_path() { cygpath --path --windows "$1"; }
+  ;;
+esac
+
+# set JAVACMD and JAVACCMD
+set_java_home() {
+  # For Cygwin and MinGW, ensure paths are in Unix format before anything is touched
+  if [ -n "${JAVA_HOME-}" ]; then
+    if [ -x "$JAVA_HOME/jre/sh/java" ]; then
+      # IBM's JDK on AIX uses strange locations for the executables
+      JAVACMD="$JAVA_HOME/jre/sh/java"
+      JAVACCMD="$JAVA_HOME/jre/sh/javac"
+    else
+      JAVACMD="$JAVA_HOME/bin/java"
+      JAVACCMD="$JAVA_HOME/bin/javac"
+
+      if [ ! -x "$JAVACMD" ] || [ ! -x "$JAVACCMD" ]; then
+        echo "The JAVA_HOME environment variable is not defined correctly, so mvnw cannot run." >&2
+        echo "JAVA_HOME is set to \"$JAVA_HOME\", but \"\$JAVA_HOME/bin/java\" or \"\$JAVA_HOME/bin/javac\" does not exist." >&2
+        return 1
+      fi
+    fi
+  else
+    JAVACMD="$(
+      'set' +e
+      'unset' -f command 2>/dev/null
+      'command' -v java
+    )" || :
+    JAVACCMD="$(
+      'set' +e
+      'unset' -f command 2>/dev/null
+      'command' -v javac
+    )" || :
+
+    if [ ! -x "${JAVACMD-}" ] || [ ! -x "${JAVACCMD-}" ]; then
+      echo "The java/javac command does not exist in PATH nor is JAVA_HOME set, so mvnw cannot run." >&2
+      return 1
+    fi
+  fi
+}
+
+# hash string like Java String::hashCode
+hash_string() {
+  str="${1:-}" h=0
+  while [ -n "$str" ]; do
+    char="${str%"${str#?}"}"
+    h=$(((h * 31 + $(LC_CTYPE=C printf %d "'$char")) % 4294967296))
+    str="${str#?}"
+  done
+  printf %x\\n $h
+}
+
+verbose() { :; }
+[ "${MVNW_VERBOSE-}" != true ] || verbose() { printf %s\\n "${1-}"; }
+
+die() {
+  printf %s\\n "$1" >&2
+  exit 1
+}
+
+trim() {
+  # MWRAPPER-139:
+  #   Trims trailing and leading whitespace, carriage returns, tabs, and linefeeds.
+  #   Needed for removing poorly interpreted newline sequences when running in more
+  #   exotic environments such as mingw bash on Windows.
+  printf "%s" "${1}" | tr -d '[:space:]'
+}
+
+scriptDir="$(dirname "$0")"
+scriptName="$(basename "$0")"
+
+# parse distributionUrl and optional distributionSha256Sum, requires .mvn/wrapper/maven-wrapper.properties
+while IFS="=" read -r key value; do
+  case "${key-}" in
+  distributionUrl) distributionUrl=$(trim "${value-}") ;;
+  distributionSha256Sum) distributionSha256Sum=$(trim "${value-}") ;;
+  esac
+done <"$scriptDir/.mvn/wrapper/maven-wrapper.properties"
+[ -n "${distributionUrl-}" ] || die "cannot read distributionUrl property in $scriptDir/.mvn/wrapper/maven-wrapper.properties"
+
+case "${distributionUrl##*/}" in
+maven-mvnd-*bin.*)
+  MVN_CMD=mvnd.sh _MVNW_REPO_PATTERN=/maven/mvnd/
+  case "${PROCESSOR_ARCHITECTURE-}${PROCESSOR_ARCHITEW6432-}:$(uname -a)" in
+  *AMD64:CYGWIN* | *AMD64:MINGW*) distributionPlatform=windows-amd64 ;;
+  :Darwin*x86_64) distributionPlatform=darwin-amd64 ;;
+  :Darwin*arm64) distributionPlatform=darwin-aarch64 ;;
+  :Linux*x86_64*) distributionPlatform=linux-amd64 ;;
+  *)
+    echo "Cannot detect native platform for mvnd on $(uname)-$(uname -m), use pure java version" >&2
+    distributionPlatform=linux-amd64
+    ;;
+  esac
+  distributionUrl="${distributionUrl%-bin.*}-$distributionPlatform.zip"
+  ;;
+maven-mvnd-*) MVN_CMD=mvnd.sh _MVNW_REPO_PATTERN=/maven/mvnd/ ;;
+*) MVN_CMD="mvn${scriptName#mvnw}" _MVNW_REPO_PATTERN=/org/apache/maven/ ;;
+esac
+
+# apply MVNW_REPOURL and calculate MAVEN_HOME
+# maven home pattern: ~/.m2/wrapper/dists/{apache-maven-<version>,maven-mvnd-<version>-<platform>}/<hash>
+[ -z "${MVNW_REPOURL-}" ] || distributionUrl="$MVNW_REPOURL$_MVNW_REPO_PATTERN${distributionUrl#*"$_MVNW_REPO_PATTERN"}"
+distributionUrlName="${distributionUrl##*/}"
+distributionUrlNameMain="${distributionUrlName%.*}"
+distributionUrlNameMain="${distributionUrlNameMain%-bin}"
+MAVEN_USER_HOME="${MAVEN_USER_HOME:-${HOME}/.m2}"
+MAVEN_HOME="${MAVEN_USER_HOME}/wrapper/dists/${distributionUrlNameMain-}/$(hash_string "$distributionUrl")"
+
+exec_maven() {
+  unset MVNW_VERBOSE MVNW_USERNAME MVNW_PASSWORD MVNW_REPOURL || :
+  exec "$MAVEN_HOME/bin/$MVN_CMD" "$@" || die "cannot exec $MAVEN_HOME/bin/$MVN_CMD"
+}
+
+if [ -d "$MAVEN_HOME" ]; then
+  verbose "found existing MAVEN_HOME at $MAVEN_HOME"
+  exec_maven "$@"
+fi
+
+case "${distributionUrl-}" in
+*?-bin.zip | *?maven-mvnd-?*-?*.zip) ;;
+*) die "distributionUrl is not valid, must match *-bin.zip or maven-mvnd-*.zip, but found '${distributionUrl-}'" ;;
+esac
+
+# prepare tmp dir
+if TMP_DOWNLOAD_DIR="$(mktemp -d)" && [ -d "$TMP_DOWNLOAD_DIR" ]; then
+  clean() { rm -rf -- "$TMP_DOWNLOAD_DIR"; }
+  trap clean HUP INT TERM EXIT
+else
+  die "cannot create temp dir"
+fi
+
+mkdir -p -- "${MAVEN_HOME%/*}"
+
+# Download and Install Apache Maven
+verbose "Couldn't find MAVEN_HOME, downloading and installing it ..."
+verbose "Downloading from: $distributionUrl"
+verbose "Downloading to: $TMP_DOWNLOAD_DIR/$distributionUrlName"
+
+# select .zip or .tar.gz
+if ! command -v unzip >/dev/null; then
+  distributionUrl="${distributionUrl%.zip}.tar.gz"
+  distributionUrlName="${distributionUrl##*/}"
+fi
+
+# verbose opt
+__MVNW_QUIET_WGET=--quiet __MVNW_QUIET_CURL=--silent __MVNW_QUIET_UNZIP=-q __MVNW_QUIET_TAR=''
+[ "${MVNW_VERBOSE-}" != true ] || __MVNW_QUIET_WGET='' __MVNW_QUIET_CURL='' __MVNW_QUIET_UNZIP='' __MVNW_QUIET_TAR=v
+
+# normalize http auth
+case "${MVNW_PASSWORD:+has-password}" in
+'') MVNW_USERNAME='' MVNW_PASSWORD='' ;;
+has-password) [ -n "${MVNW_USERNAME-}" ] || MVNW_USERNAME='' MVNW_PASSWORD='' ;;
+esac
+
+if [ -z "${MVNW_USERNAME-}" ] && command -v wget >/dev/null; then
+  verbose "Found wget ... using wget"
+  wget ${__MVNW_QUIET_WGET:+"$__MVNW_QUIET_WGET"} "$distributionUrl" -O "$TMP_DOWNLOAD_DIR/$distributionUrlName" || die "wget: Failed to fetch $distributionUrl"
+elif [ -z "${MVNW_USERNAME-}" ] && command -v curl >/dev/null; then
+  verbose "Found curl ... using curl"
+  curl ${__MVNW_QUIET_CURL:+"$__MVNW_QUIET_CURL"} -f -L -o "$TMP_DOWNLOAD_DIR/$distributionUrlName" "$distributionUrl" || die "curl: Failed to fetch $distributionUrl"
+elif set_java_home; then
+  verbose "Falling back to use Java to download"
+  javaSource="$TMP_DOWNLOAD_DIR/Downloader.java"
+  targetZip="$TMP_DOWNLOAD_DIR/$distributionUrlName"
+  cat >"$javaSource" <<-END
+	public class Downloader extends java.net.Authenticator
+	{
+	  protected java.net.PasswordAuthentication getPasswordAuthentication()
+	  {
+	    return new java.net.PasswordAuthentication( System.getenv( "MVNW_USERNAME" ), System.getenv( "MVNW_PASSWORD" ).toCharArray() );
+	  }
+	  public static void main( String[] args ) throws Exception
+	  {
+	    setDefault( new Downloader() );
+	    java.nio.file.Files.copy( java.net.URI.create( args[0] ).toURL().openStream(), java.nio.file.Paths.get( args[1] ).toAbsolutePath().normalize() );
+	  }
+	}
+	END
+  # For Cygwin/MinGW, switch paths to Windows format before running javac and java
+  verbose " - Compiling Downloader.java ..."
+  "$(native_path "$JAVACCMD")" "$(native_path "$javaSource")" || die "Failed to compile Downloader.java"
+  verbose " - Running Downloader.java ..."
+  "$(native_path "$JAVACMD")" -cp "$(native_path "$TMP_DOWNLOAD_DIR")" Downloader "$distributionUrl" "$(native_path "$targetZip")"
+fi
+
+# If specified, validate the SHA-256 sum of the Maven distribution zip file
+if [ -n "${distributionSha256Sum-}" ]; then
+  distributionSha256Result=false
+  if [ "$MVN_CMD" = mvnd.sh ]; then
+    echo "Checksum validation is not supported for maven-mvnd." >&2
+    echo "Please disable validation by removing 'distributionSha256Sum' from your maven-wrapper.properties." >&2
+    exit 1
+  elif command -v sha256sum >/dev/null; then
+    if echo "$distributionSha256Sum  $TMP_DOWNLOAD_DIR/$distributionUrlName" | sha256sum -c - >/dev/null 2>&1; then
+      distributionSha256Result=true
+    fi
+  elif command -v shasum >/dev/null; then
+    if echo "$distributionSha256Sum  $TMP_DOWNLOAD_DIR/$distributionUrlName" | shasum -a 256 -c >/dev/null 2>&1; then
+      distributionSha256Result=true
+    fi
+  else
+    echo "Checksum validation was requested but neither 'sha256sum' or 'shasum' are available." >&2
+    echo "Please install either command, or disable validation by removing 'distributionSha256Sum' from your maven-wrapper.properties." >&2
+    exit 1
+  fi
+  if [ $distributionSha256Result = false ]; then
+    echo "Error: Failed to validate Maven distribution SHA-256, your Maven distribution might be compromised." >&2
+    echo "If you updated your Maven version, you need to update the specified distributionSha256Sum property." >&2
+    exit 1
+  fi
+fi
+
+# unzip and move
+if command -v unzip >/dev/null; then
+  unzip ${__MVNW_QUIET_UNZIP:+"$__MVNW_QUIET_UNZIP"} "$TMP_DOWNLOAD_DIR/$distributionUrlName" -d "$TMP_DOWNLOAD_DIR" || die "failed to unzip"
+else
+  tar xzf${__MVNW_QUIET_TAR:+"$__MVNW_QUIET_TAR"} "$TMP_DOWNLOAD_DIR/$distributionUrlName" -C "$TMP_DOWNLOAD_DIR" || die "failed to untar"
+fi
+
+# Find the actual extracted directory name (handles snapshots where filename != directory name)
+actualDistributionDir=""
+
+# First try the expected directory name (for regular distributions)
+if [ -d "$TMP_DOWNLOAD_DIR/$distributionUrlNameMain" ]; then
+  if [ -f "$TMP_DOWNLOAD_DIR/$distributionUrlNameMain/bin/$MVN_CMD" ]; then
+    actualDistributionDir="$distributionUrlNameMain"
+  fi
+fi
+
+# If not found, search for any directory with the Maven executable (for snapshots)
+if [ -z "$actualDistributionDir" ]; then
+  # enable globbing to iterate over items
+  set +f
+  for dir in "$TMP_DOWNLOAD_DIR"/*; do
+    if [ -d "$dir" ]; then
+      if [ -f "$dir/bin/$MVN_CMD" ]; then
+        actualDistributionDir="$(basename "$dir")"
+        break
+      fi
+    fi
+  done
+  set -f
+fi
+
+if [ -z "$actualDistributionDir" ]; then
+  verbose "Contents of $TMP_DOWNLOAD_DIR:"
+  verbose "$(ls -la "$TMP_DOWNLOAD_DIR")"
+  die "Could not find Maven distribution directory in extracted archive"
+fi
+
+verbose "Found extracted Maven distribution directory: $actualDistributionDir"
+printf %s\\n "$distributionUrl" >"$TMP_DOWNLOAD_DIR/$actualDistributionDir/mvnw.url"
+mv -- "$TMP_DOWNLOAD_DIR/$actualDistributionDir" "$MAVEN_HOME" || [ -d "$MAVEN_HOME" ] || die "fail to move MAVEN_HOME"
+
+clean || :
+exec_maven "$@"

package/dist/templates/java/pom.xml.tmpl

@@ -0,0 +1,65 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+
+  <groupId>{{JAVA_PACKAGE}}</groupId>
+  <artifactId>{{PACK_NAME}}</artifactId>
+  <version>{{PACK_VERSION}}</version>
+  <name>{{PACK_NAME}}</name>
+  <description>A Kindgi pack in Java: its tools, guardrail checks, agents and flows.</description>
+
+  <properties>
+    <maven.compiler.release>17</maven.compiler.release>
+    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+    <kindgi.version>{{KINDGI_JAVA_VERSION}}</kindgi.version>
+  </properties>
+
+  <dependencies>
+    <!-- Tools, guardrail checks, the indexer and the pack service. -->
+    <dependency>
+      <groupId>com.kindgi</groupId>
+      <artifactId>kindgi-pack</artifactId>
+      <version>${kindgi.version}</version>
+    </dependency>
+    <!-- Constraints on tool inputs (@Size, @Min, @Email, …) become their schemas' keywords. -->
+    <dependency>
+      <groupId>jakarta.validation</groupId>
+      <artifactId>jakarta.validation-api</artifactId>
+      <version>3.0.2</version>
+    </dependency>
+
+    <dependency>
+      <groupId>org.junit.jupiter</groupId>
+      <artifactId>junit-jupiter</artifactId>
+      <version>6.1.3</version>
+      <scope>test</scope>
+    </dependency>
+  </dependencies>
+
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-resources-plugin</artifactId>
+        <version>3.5.0</version>
+      </plugin>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-compiler-plugin</artifactId>
+        <version>3.16.0</version>
+      </plugin>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-surefire-plugin</artifactId>
+        <version>3.6.0</version>
+      </plugin>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-dependency-plugin</artifactId>
+        <version>3.11.0</version>
+      </plugin>
+    </plugins>
+  </build>
+</project>

package/dist/templates/java/src/main/java/__PACKAGE__/agents/EchoAgent.java.tmpl

@@ -0,0 +1,27 @@
+package {{JAVA_PACKAGE}}.agents;
+
+import {{JAVA_PACKAGE}}.guardrails.ResponseNotEmpty;
+import {{JAVA_PACKAGE}}.tools.Echo;
+import {{JAVA_PACKAGE}}.tools.Greet;
+import com.kindgi.pack.Agent;
+import java.util.List;
+import java.util.Map;
+
+/** {{PACK_ID}}.echo-agent — uses both tools; the response-not-empty guardrail guards its answer. */
+public final class EchoAgent {
+  public static final Agent AGENT = Agent.define("{{PACK_ID}}.echo-agent")
+      .version("{{PACK_VERSION}}")
+      .name("Echo Agent")
+      .description("Uses the pack's echo and greet tools; the response-not-empty guardrail guards the output.")
+      .instructions("For each user message: if the user sends a name, greet them with the greet tool. "
+          + "Otherwise echo their message with the echo tool. Quote the tool result verbatim.")
+      .capability(Map.of("needs", List.of(Map.of("feature", "tool-use"))))
+      .tool(Echo.TOOL)
+      .tool(Greet.TOOL)
+      .guardrail(ResponseNotEmpty.GUARDRAIL)
+      .set("conversationPolicy", Map.of("historyLimit", 10))
+      .set("budget", Map.of("maxSteps", 4, "maxCostUsd", 0.1, "maxWallMs", 60_000))
+      .build();
+
+  private EchoAgent() {}
+}

package/dist/templates/java/src/main/java/__PACKAGE__/flows/EchoFlow.java.tmpl

@@ -0,0 +1,18 @@
+package {{JAVA_PACKAGE}}.flows;
+
+import {{JAVA_PACKAGE}}.tools.Echo;
+import com.kindgi.pack.Flow;
+
+/** {{PACK_ID}}.echo-flow — runs the pack's echo tool, then ends. */
+public final class EchoFlow {
+  public static final Flow FLOW = Flow.define("{{PACK_ID}}.echo-flow")
+      .version("{{PACK_VERSION}}")
+      .set("name", "Echo Flow")
+      .set("description", "Runs the pack's echo tool and terminates.")
+      .toolNode("echo", Echo.TOOL)
+      .edge("e-start", "$start", "echo")
+      .edge("e-end", "echo", "$end")
+      .build();
+
+  private EchoFlow() {}
+}

package/dist/templates/java/src/main/java/__PACKAGE__/guardrails/ResponseNotEmpty.java.tmpl

@@ -0,0 +1,28 @@
+package {{JAVA_PACKAGE}}.guardrails;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.kindgi.pack.CheckResult;
+import com.kindgi.pack.Guardrail;
+import jakarta.validation.constraints.Min;
+import java.util.Map;
+
+/** {{PACK_ID}}.response-not-empty — a zero-LLM guardrail: the run's answer has content. */
+public final class ResponseNotEmpty {
+  public record Config(@JsonProperty(defaultValue = "1") @Min(0) int minLength) {}
+
+  public static final Guardrail<Config> GUARDRAIL = Guardrail.define("{{PACK_ID}}.response-not-empty")
+      .name("Response is non-empty")
+      .checkId("{{PACK_ID}}.checks.response-not-empty")
+      .onViolation("halt")
+      .severity("error")
+      .set("scope", Map.of("when", "runtime-only"))
+      .config(Config.class)
+      .check((config, trace) -> {
+        String text = trace.output() == null ? "" : trace.output().strip();
+        return text.length() >= config.minLength()
+            ? CheckResult.pass()
+            : CheckResult.fail("Response too short: " + text.length() + " chars, expected >= " + config.minLength() + ".");
+      });
+
+  private ResponseNotEmpty() {}
+}

package/dist/templates/java/src/main/java/__PACKAGE__/tools/Echo.java.tmpl

@@ -0,0 +1,22 @@
+package {{JAVA_PACKAGE}}.tools;
+
+import com.kindgi.pack.Tool;
+import jakarta.validation.constraints.PositiveOrZero;
+import jakarta.validation.constraints.Size;
+import java.time.Instant;
+
+/** {{PACK_ID}}.echo — echoes the message back with a UTC timestamp and its length. */
+public final class Echo {
+  public record Input(@Size(min = 1, max = 500) String message) {}
+
+  public record Output(String echo, Instant echoedAt, @PositiveOrZero int characterCount) {}
+
+  public static final Tool<Input, Output> TOOL = Tool.define("{{PACK_ID}}.echo")
+      .description("Echoes the caller-provided message with a UTC timestamp and character count.")
+      .input(Input.class)
+      .output(Output.class)
+      .mutating(false)
+      .handler((input, ctx) -> new Output(input.message(), Instant.now(), input.message().length()));
+
+  private Echo() {}
+}

package/dist/templates/java/src/main/java/__PACKAGE__/tools/Greet.java.tmpl

@@ -0,0 +1,23 @@
+package {{JAVA_PACKAGE}}.tools;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.kindgi.pack.Tool;
+import jakarta.validation.constraints.Size;
+
+/** {{PACK_ID}}.greet — greets a named recipient. */
+public final class Greet {
+  public record Input(
+      @Size(min = 1, max = 100) String name,
+      @JsonProperty(defaultValue = "Hello") @Size(min = 1, max = 50) String greeting) {}
+
+  public record Output(String message) {}
+
+  public static final Tool<Input, Output> TOOL = Tool.define("{{PACK_ID}}.greet")
+      .description("Formats a greeting for the named recipient.")
+      .input(Input.class)
+      .output(Output.class)
+      .mutating(false)
+      .handler((input, ctx) -> new Output(input.greeting() + ", " + input.name() + "!"));
+
+  private Greet() {}
+}

package/dist/templates/java/src/test/java/__PACKAGE__/ToolsTest.java.tmpl

@@ -0,0 +1,30 @@
+package {{JAVA_PACKAGE}};
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+
+import {{JAVA_PACKAGE}}.tools.Echo;
+import {{JAVA_PACKAGE}}.tools.Greet;
+import com.kindgi.pack.ToolContext;
+import org.junit.jupiter.api.Test;
+
+/** The pack's tools, called directly — `./mvnw test`. */
+class ToolsTest {
+  @Test
+  void echoRoundTripsTheMessage() throws Exception {
+    Echo.Output out = Echo.TOOL.call(new Echo.Input("hello"), ToolContext.forTest());
+    assertEquals("hello", out.echo());
+    assertEquals(5, out.characterCount());
+  }
+
+  @Test
+  void greetUsesTheGreetingItIsGiven() throws Exception {
+    assertEquals("Hi, Ada!", Greet.TOOL.call(new Greet.Input("Ada", "Hi"), ToolContext.forTest()).message());
+  }
+
+  @Test
+  void theToolsSayTheyOnlyRead() {
+    assertFalse(Echo.TOOL.mutating());
+    assertFalse(Greet.TOOL.mutating());
+  }
+}

package/dist/templates/minimal/README.md.tmpl

@@ -34,16 +34,16 @@ assistant in the loop.
 ## Run
 
 ```sh
-pnpm install
-pnpm typecheck              # verify the pack compiles
-kindgi dev                  # runs the Kindgi runtime (Docker) + hot-reloads this pack
+{{INSTALL}}
+{{TYPECHECK}}  # verify the pack compiles
+{{KINDGI}} dev  # runs the Kindgi runtime (Docker) + hot-reloads this pack
 ```
 
 The api-server ships with a built-in `demo.echo-agent` you can hit to
 verify boot before authoring anything:
 
 ```sh
-kindgi runs start --agent=demo.echo-agent --input='{"userMessage":"hi"}'
+{{KINDGI}} runs start --agent=demo.echo-agent --input='{"userMessage":"hi"}'
 ```
 
 ## Use a real model
@@ -55,8 +55,8 @@ use a real model, set one LLM provider's key and register its preset, with
 `kindgi dev` running, from another terminal. For Claude:
 
 ```sh
-kindgi secrets set ANTHROPIC_API_KEY --env=local --scope=tenant   # no-echo prompt; writes .env.local
-kindgi providers register --preset=anthropic                      # Opus 5.5, Sonnet 5.5 (default), Haiku 5.5, Haiku 4.5
+{{KINDGI}} secrets set ANTHROPIC_API_KEY --env=local --scope=tenant   # no-echo prompt; writes .env.local
+{{KINDGI}} providers register --preset=anthropic                      # Opus 5.5, Sonnet 5.5 (default), Haiku 5.5, Haiku 4.5
 ```
 
 Claude takes over from dev-echo on the next turn; nothing to restart.
@@ -67,9 +67,3 @@ OpenRouter, a hosted service your prompts pass through (`OPENROUTER_API_KEY`,
 `--preset=openrouter`), work the same way; `kindgi providers presets` lists
 the presets (Gemini on Vertex AI too). Picking a model per
 agent, and other providers: `.claude/skills/kindgi-authoring-providers/SKILL.md`.
-
-## Note on `@kindgi/sdk` versioning
-
-This template pins `@kindgi/sdk: "workspace:*"` because the SDK is not
-yet published to npm. Until it is, add the pack to a pnpm workspace that
-contains the Kindgi packages (`pnpm-workspace.yaml`).

package/dist/templates/python/README.md.tmpl

@@ -23,14 +23,14 @@ that uses both tools and the guardrail, and one flow that runs the echo tool.
 ```sh
 uv sync          # .venv with kindgi and the dev tools
 uv run pytest
-kindgi dev       # boots Kindgi locally and runs this pack's code, reloading on save
+{{KINDGI}} dev  # boots Kindgi locally and runs this pack's code, reloading on save
 ```
 
 `kindgi dev` uses the pack's `.venv/bin/python` (or `dev.python` in
 `[tool.kindgi]`). Then, from another terminal:
 
 ```sh
-kindgi runs start --agent={{PACK_ID}}.echo-agent --input='{"userMessage":"hi"}'
+{{KINDGI}} runs start --agent={{PACK_ID}}.echo-agent --input='{"userMessage":"hi"}'
 ```
 
 ## Use a real model
@@ -42,8 +42,8 @@ use a real model, set one LLM provider's key and register its preset, with
 `kindgi dev` running, from another terminal. For Claude:
 
 ```sh
-kindgi secrets set ANTHROPIC_API_KEY --env=local --scope=tenant   # no-echo prompt; writes .env.local
-kindgi providers register --preset=anthropic                      # Opus 5.5, Sonnet 5.5 (default), Haiku 5.5, Haiku 4.5
+{{KINDGI}} secrets set ANTHROPIC_API_KEY --env=local --scope=tenant   # no-echo prompt; writes .env.local
+{{KINDGI}} providers register --preset=anthropic                      # Opus 5.5, Sonnet 5.5 (default), Haiku 5.5, Haiku 4.5
 ```
 
 Claude takes over from dev-echo on the next turn; nothing to restart.

package/dist/templates/sample/README.md.tmpl

@@ -28,9 +28,9 @@ run with `kindgi dev`.
 ## Run
 
 ```sh
-pnpm install
-pnpm typecheck                                # verify the pack compiles
-kindgi dev                                 # runs the Kindgi runtime (Docker) + hot-reloads this pack
+{{INSTALL}}
+{{TYPECHECK}}  # verify the pack compiles
+{{KINDGI}} dev  # runs the Kindgi runtime (Docker) + hot-reloads this pack
 ```
 
 `kindgi dev` bundles every primitive under the four folders above,
@@ -47,8 +47,8 @@ use a real model, set one LLM provider's key and register its preset, with
 `kindgi dev` running, from another terminal. For Claude:
 
 ```sh
-kindgi secrets set ANTHROPIC_API_KEY --env=local --scope=tenant   # no-echo prompt; writes .env.local
-kindgi providers register --preset=anthropic                      # Opus 5.5, Sonnet 5.5 (default), Haiku 5.5, Haiku 4.5
+{{KINDGI}} secrets set ANTHROPIC_API_KEY --env=local --scope=tenant   # no-echo prompt; writes .env.local
+{{KINDGI}} providers register --preset=anthropic                      # Opus 5.5, Sonnet 5.5 (default), Haiku 5.5, Haiku 4.5
 ```
 
 Claude takes over from dev-echo on the next turn; nothing to restart.
@@ -83,9 +83,3 @@ import { z } from 'zod';
 
 Every `define*` export ships with JSDoc — hover it in your editor for
 field-level docs.
-
-## Note on `@kindgi/sdk` versioning
-
-This template pins `@kindgi/sdk: "workspace:*"` because the SDK is not
-yet published to npm. Until it is, add the pack to a pnpm workspace that
-contains the Kindgi packages (`pnpm-workspace.yaml`).

package/dist/templates/scala/AGENTS.md

@@ -0,0 +1,32 @@
+# AGENTS.md
+
+This directory is a Kindgi pack written in Scala (`com.kindgi %% kindgi-pack-scala`,
+package `com.kindgi.pack.scaladsl`). Tools (`Tool[Input, Output](id)`) and
+guardrail checks (`Guardrail[Config](id)`) are `val`s of an object named like
+its file, under `src/main/scala/**/tools/` and `…/guardrails/`; agents
+(`Agent(id)`) and flows (`Flow(id)`) are data, under `…/agents/` and
+`…/flows/`. A tool's input and output schemas come from its case classes:
+`Option` is optional, a parameter's default is the schema's default, Jakarta
+Validation constraints become their keywords (in Scala 3, name their arguments:
+`@Min(value = 0)`). A tool defined as a `def` or a `lazy val` isn't indexed:
+make it a `val`. The config is `kindgi.config.json`.
+
+- `./kindgiw dev` boots Kindgi locally, compiles this pack through sbt's server
+  and runs it with its JDK (17 or later), recompiling on every save.
+- `sbt test` runs the tests; `tool.call(input, ToolContext.forTest())` calls a
+  handler directly.
+- `java -cp "$(sbt -batch -error 'export Runtime/fullClasspath')" com.kindgi.pack.Main index --pack-dir .`
+  shows what Kindgi sees.
+- Agents answer through a model provider. `kindgi dev` gives a new pack
+  `dev-echo`, a fallback that isn't a model: it calls the first tool and
+  replies "Tool responded: …" after a warning line, while no other provider
+  fits. For a real model, put one LLM provider's key in `.env`
+  (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `GROQ_API_KEY` or
+  `OPENROUTER_API_KEY`) and add a `providers` list with its preset
+  (`[{"preset": "anthropic"}]`, or `"openai"`, `"gemini-api"`, `"groq"`,
+  `"openrouter"`) to `kindgi.config.json`: `kindgi dev` then registers it on
+  every boot, in every worktree.
+
+When you diagnose a framework bug (something in Kindgi itself, not in this
+pack's code), append an entry to `FEEDBACK.md` at the pack root with
+`./kindgiw feedback write`.