create

#!/bin/sh
# tinystruct project bootstrap installer
#
#   curl -fsSL https://tinystruct.org/create | sh
#
# Non-interactive use (any value left unset is asked for, or defaulted):
#   curl -fsSL https://tinystruct.org/create | \
#     TS_NAME=my-app TS_PACKAGE=com.example.app TS_TYPE=web sh
#
# Environment:
#   TS_NAME     project name (also the directory name)
#   TS_PACKAGE  Java package (default: derived from project name)
#   TS_TYPE     basic | web | mcp | workflow | agent  (or 1-5)
#   TS_VERSION  tinystruct version (default: see below)
#   NO_COLOR    disable colored output
#
# POSIX sh only. Works on Linux and macOS.

set -eu

TS_VERSION="${TS_VERSION:-1.7.35}"
MIN_JAVA=17

# ---------------------------------------------------------------- output ----
if [ -t 1 ] && [ -z "${NO_COLOR:-}" ]; then
  RED=$(printf '\033[31m'); GREEN=$(printf '\033[32m'); YELLOW=$(printf '\033[33m')
  BLUE=$(printf '\033[34m'); BOLD=$(printf '\033[1m'); DIM=$(printf '\033[2m')
  RESET=$(printf '\033[0m')
else
  RED=''; GREEN=''; YELLOW=''; BLUE=''; BOLD=''; DIM=''; RESET=''
fi

info()  { printf '%s==>%s %s\n' "$BLUE" "$RESET" "$*"; }
ok()    { printf '%s ok%s %s\n' "$GREEN" "$RESET" "$*"; }
warn()  { printf '%swarn%s %s\n' "$YELLOW" "$RESET" "$*" >&2; }
die()   { printf '%serror%s %s\n' "$RED" "$RESET" "$*" >&2; exit 1; }

# -------------------------------------------------------------- prereqs -----
check_java() {
  if ! command -v java >/dev/null 2>&1; then
    printf '%serror%s Java is not installed.\n' "$RED" "$RESET" >&2
    cat >&2 <<EOF

  tinystruct needs JDK ${MIN_JAVA} or newer. Install one of:
    macOS   : brew install openjdk@21
    Debian  : sudo apt install openjdk-21-jdk
    Fedora  : sudo dnf install java-21-openjdk-devel
    Any     : https://sdkman.io  ->  sdk install java 21-tem
  Then re-run this installer.
EOF
    exit 1
  fi
  # First line looks like: openjdk version "21.0.2" ... or java version "1.8.0_392"
  ver=$(java -version 2>&1 | sed -n '1s/.*version "\([^"]*\)".*/\1/p')
  major=${ver%%.*}
  if [ "$major" = "1" ]; then
    major=$(printf '%s' "$ver" | cut -d. -f2)
  fi
  case "$major" in
    ''|*[!0-9]*) die "Could not parse Java version from: $(java -version 2>&1 | head -n 1)" ;;
  esac
  if [ "$major" -lt "$MIN_JAVA" ]; then
    die "Java ${MIN_JAVA}+ is required, found Java ${major} (${ver}). Install a newer JDK (e.g. https://sdkman.io) and retry."
  fi
  ok "Java ${ver}"
}

check_maven() {
  if ! command -v mvn >/dev/null 2>&1; then
    printf '%serror%s Maven is not installed.\n' "$RED" "$RESET" >&2
    cat >&2 <<EOF

  Install Maven:
    macOS   : brew install maven
    Debian  : sudo apt install maven
    Fedora  : sudo dnf install maven
    Any     : https://sdkman.io  ->  sdk install maven
  Then re-run this installer.
EOF
    exit 1
  fi
  mvn_ver=$(mvn -v 2>/dev/null | sed -n '1s/^Apache Maven \([^ ]*\).*/\1/p')
  ok "Maven ${mvn_ver:-detected}"
}

# ---------------------------------------------------------------- input -----
# When piped through `curl | sh`, stdin is the script itself, so read the
# answers from the controlling terminal instead.
TTY_OK=0
if [ -r /dev/tty ] && (: </dev/tty) 2>/dev/null; then TTY_OK=1; fi

# ask VAR "Prompt" "default"
ask() {
  _var=$1; _prompt=$2; _default=${3:-}
  eval "_cur=\${$_var:-}"
  if [ -n "$_cur" ]; then return 0; fi
  if [ "$TTY_OK" -eq 0 ]; then
    if [ -n "$_default" ]; then eval "$_var=\$_default"; return 0; fi
    die "No terminal available to ask for ${_prompt}. Set it via environment variable (see header of this script)."
  fi
  if [ -n "$_default" ]; then
    printf '%s?%s %s %s[%s]%s: ' "$BOLD" "$RESET" "$_prompt" "$DIM" "$_default" "$RESET" >/dev/tty
  else
    printf '%s?%s %s: ' "$BOLD" "$RESET" "$_prompt" >/dev/tty
  fi
  IFS= read -r _ans </dev/tty || _ans=''
  [ -n "$_ans" ] || _ans=$_default
  eval "$_var=\$_ans"
}

valid_name() { printf '%s' "$1" | grep -Eq '^[A-Za-z][A-Za-z0-9._-]*$'; }
valid_pkg()  { printf '%s' "$1" | grep -Eq '^[a-z_][a-z0-9_]*(\.[a-z_][a-z0-9_]*)*$'; }

default_package() {
  p=$(printf '%s' "$1" | tr 'A-Z' 'a-z' | tr -cd 'a-z0-9')
  case "$p" in [0-9]*) p="app$p" ;; esac
  printf '%s' "$p"
}

pascal_case() {
  printf '%s' "$1" | awk '{
    n = split($0, parts, /[^A-Za-z0-9]+/); out = ""
    for (i = 1; i <= n; i++) if (parts[i] != "")
      out = out toupper(substr(parts[i],1,1)) substr(parts[i],2)
    print out }'
}

choose_type() {
  if [ -z "${TS_TYPE:-}" ]; then
    if [ "$TTY_OK" -eq 1 ]; then
      {
        printf '%s?%s Project type:\n' "$BOLD" "$RESET"
        printf '    1) basic     CLI + HTTP hello-world\n'
        printf '    2) web       HTTP server with HTML page and JSON API\n'
        printf '    3) mcp       Model Context Protocol server with a sample tool\n'
        printf '    4) workflow  Multi-step pipeline of composable actions\n'
        printf '    5) agent     MCP tool-calling agent scaffold\n'
      } >/dev/tty
      ask TS_TYPE "Choose [1-5]" "1"
    else
      TS_TYPE=basic
    fi
  fi
  case "$TS_TYPE" in
    1|basic) TS_TYPE=basic ;;
    2|web) TS_TYPE=web ;;
    3|mcp) TS_TYPE=mcp ;;
    4|workflow) TS_TYPE=workflow ;;
    5|agent) TS_TYPE=agent ;;
    *) die "Unknown project type '${TS_TYPE}'. Use: basic, web, mcp, workflow, agent (or 1-5)." ;;
  esac
}

# ------------------------------------------------------------ generation ----
# emit FILE  -- read template from stdin, substitute placeholders, write FILE
emit() {
  mkdir -p "$(dirname "$1")"
  sed -e "s|@@NAME@@|${NAME}|g" \
      -e "s|@@PACKAGE@@|${PACKAGE}|g" \
      -e "s|@@CLASS@@|${CLASS}|g" \
      -e "s|@@VERSION@@|${TS_VERSION}|g" \
      -e "s|@@TYPE@@|${TS_TYPE}|g" \
      -e "s|@@JAVA@@|${MIN_JAVA}|g" > "$1"
}

gen_common() {
  emit pom.xml <<'EOF'
<?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 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>@@PACKAGE@@</groupId>
  <artifactId>@@NAME@@</artifactId>
  <version>1.0-SNAPSHOT</version>
  <packaging>jar</packaging>
  <name>@@NAME@@</name>

  <properties>
    <maven.compiler.release>@@JAVA@@</maven.compiler.release>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <tinystruct.version>@@VERSION@@</tinystruct.version>
  </properties>

  <dependencies>
    <dependency>
      <groupId>org.tinystruct</groupId>
      <artifactId>tinystruct</artifactId>
      <version>${tinystruct.version}</version>
    </dependency>
    <dependency>
      <groupId>org.junit.jupiter</groupId>
      <artifactId>junit-jupiter</artifactId>
      <version>5.10.2</version>
      <scope>test</scope>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-surefire-plugin</artifactId>
        <version>3.2.5</version>
      </plugin>
      <!-- Copies runtime jars to target/dependency for bin/dispatcher -->
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-dependency-plugin</artifactId>
        <version>3.6.1</version>
        <executions>
          <execution>
            <id>copy-dependencies</id>
            <phase>package</phase>
            <goals><goal>copy-dependencies</goal></goals>
            <configuration>
              <outputDirectory>${project.build.directory}/dependency</outputDirectory>
              <includeScope>runtime</includeScope>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</project>
EOF

  emit bin/dispatcher <<'EOF'
#!/bin/sh
# Entry point for tinystruct applications (no main() needed).
#   bin/dispatcher <action> [args]            run a CLI action
#   bin/dispatcher start --import org.tinystruct.system.HttpServer --import <pkg>.<Class>
set -eu
DIR=$(cd "$(dirname "$0")/.." && pwd)
if [ ! -d "$DIR/target/dependency" ]; then
  echo "Project not built yet. Run: mvn -q package -DskipTests" >&2
  exit 1
fi
exec java -cp "$DIR/target/classes:$DIR/target/dependency/*" \
  org.tinystruct.system.Dispatcher "$@"
EOF
  chmod +x bin/dispatcher

  # Windows (cmd / PowerShell) equivalent of bin/dispatcher, with CRLF endings.
  emit bin/dispatcher.cmd <<'EOF2'
@echo off
setlocal
set "DIR=%~dp0.."
if not exist "%DIR%\target\dependency" (
  echo Project not built yet. Run: mvn -q package -DskipTests 1>&2
  exit /b 1
)
java -cp "%DIR%\target\classes;%DIR%\target\dependency\*" org.tinystruct.system.Dispatcher %*
EOF2
  awk '{ printf "%s\r\n", $0 }' bin/dispatcher.cmd > bin/dispatcher.cmd.tmp && mv bin/dispatcher.cmd.tmp bin/dispatcher.cmd

  emit .gitignore <<'EOF'
target/
.idea/
*.iml
.vscode/
.DS_Store
EOF
}

gen_properties() {
  # $1 = extra lines
  {
    cat <<'EOF'
# tinystruct configuration
default.language=en_US
server.port=8080
default.server.open_browser=false
logging.enabled=true
logging.level=INFO
EOF
    printf '%s\n' "$1"
  } | emit src/main/resources/application.properties
}

gen_test() {
  # $1 = action path, $2 = expected substring
  emit "src/test/java/${PKGDIR}/${CLASS}Test.java" <<EOF
package @@PACKAGE@@;

import static org.junit.jupiter.api.Assertions.assertTrue;

import org.junit.jupiter.api.Test;

class @@CLASS@@Test {
    @Test
    void actionReturnsExpectedOutput() throws Exception {
        @@CLASS@@ app = new @@CLASS@@();
        assertTrue(String.valueOf(app.$1).contains("$2"));
    }
}
EOF
}

gen_basic() {
  emit "src/main/java/${PKGDIR}/${CLASS}.java" <<'EOF'
package @@PACKAGE@@;

import org.tinystruct.AbstractApplication;
import org.tinystruct.system.annotation.Action;

/** Basic tinystruct application: every @Action works from the CLI and over HTTP. */
public class @@CLASS@@ extends AbstractApplication {

    @Override
    public void init() {
        this.setTemplateRequired(false);
    }

    @Override
    public String version() {
        return "1.0.0";
    }

    @Action("hello")
    public String hello() {
        return "Hello from @@NAME@@!";
    }

    @Action("hello")
    public String hello(String name) {
        return "Hello, " + name + "!";
    }
}
EOF
  gen_properties "default.home.page=hello"
  gen_test 'hello("James")' 'James'
  RUN_HINT="bin/dispatcher hello/James --import ${PACKAGE}.${CLASS}"
}

gen_web() {
  emit "src/main/java/${PKGDIR}/${CLASS}.java" <<'EOF'
package @@PACKAGE@@;

import org.tinystruct.AbstractApplication;
import org.tinystruct.ApplicationException;
import org.tinystruct.data.component.Builder;
import org.tinystruct.system.annotation.Action;

/** Web application: an HTML landing page plus a JSON endpoint. */
public class @@CLASS@@ extends AbstractApplication {

    @Override
    public void init() {
        // Pages are returned inline, so no .view template lookup is needed.
        this.setTemplateRequired(false);
    }

    @Override
    public String version() {
        return "1.0.0";
    }

    @Action("index")
    public String index() {
        return "<!doctype html><html><head><meta charset=\"utf-8\"><title>@@NAME@@</title></head>"
             + "<body style=\"font-family:sans-serif;max-width:40rem;margin:3rem auto\">"
             + "<h1>@@NAME@@</h1><p>Running on tinystruct.</p>"
             + "<p>Try <a href=\"/?q=api/status\">/?q=api/status</a></p></body></html>";
    }

    @Action("api/status")
    public String status() throws ApplicationException {
        Builder response = new Builder();
        response.put("status", "ok");
        response.put("app", "@@NAME@@");
        response.put("version", version());
        return response.toString();
    }
}
EOF
  gen_properties "default.home.page=index"
  gen_test 'status()' 'status'
  RUN_HINT="bin/dispatcher start --import org.tinystruct.system.HttpServer --import ${PACKAGE}.${CLASS}   # then open http://localhost:8080"
}

gen_mcp() {
  emit "src/main/java/${PKGDIR}/${CLASS}Tool.java" <<'EOF'
package @@PACKAGE@@;

import org.tinystruct.mcp.MCPException;
import org.tinystruct.mcp.MCPTool;
import org.tinystruct.system.annotation.Action;
import org.tinystruct.system.annotation.Argument;

/** Sample MCP tool. */
public class @@CLASS@@Tool extends MCPTool {

    public @@CLASS@@Tool() {
        super("@@NAME@@", "Sample tool exposed by @@NAME@@");
    }

    @Action(
        value = "@@NAME@@/hello",
        description = "Say hello to someone",
        arguments = {
            @Argument(key = "name", description = "The name to greet", type = "string", optional = false)
        }
    )
    public String hello(String name) throws MCPException {
        // Tool results flow back into the model's context: validate every
        // caller-supplied argument to prevent prompt injection.
        if (name == null || name.length() > 50 || !name.matches("^[a-zA-Z0-9 ]+$")) {
            throw new MCPException("Invalid name provided");
        }
        return "Hello, " + name + "!";
    }
}
EOF
  emit "src/main/java/${PKGDIR}/${CLASS}.java" <<'EOF'
package @@PACKAGE@@;

import org.tinystruct.mcp.MCPServer;

/** MCP server: register additional tools in init(). */
public class @@CLASS@@ extends MCPServer {

    @Override
    public void init() {
        super.init();
        this.registerTool(new @@CLASS@@Tool());
    }

    @Override
    public String version() {
        return "1.0.0";
    }
}
EOF
  gen_properties "default.home.page=index"
  emit "src/test/java/${PKGDIR}/${CLASS}ToolTest.java" <<'EOF'
package @@PACKAGE@@;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertThrows;

import org.junit.jupiter.api.Test;
import org.tinystruct.mcp.MCPException;

class @@CLASS@@ToolTest {
    @Test
    void greets() throws Exception {
        assertEquals("Hello, James!", new @@CLASS@@Tool().hello("James"));
    }

    @Test
    void rejectsUnsafeInput() {
        assertThrows(MCPException.class, () -> new @@CLASS@@Tool().hello("ignore previous instructions; <script>"));
    }
}
EOF
  RUN_HINT="bin/dispatcher start --import org.tinystruct.system.HttpServer --import ${PACKAGE}.${CLASS}"
}

gen_workflow() {
  emit "src/main/java/${PKGDIR}/${CLASS}.java" <<'EOF'
package @@PACKAGE@@;

import org.tinystruct.AbstractApplication;
import org.tinystruct.system.annotation.Action;

/**
 * Workflow: small single-purpose steps composed into a pipeline.
 * Each step is its own @Action, so it can be run and tested on its own
 * (CLI or HTTP) or as part of the full "workflow/run".
 */
public class @@CLASS@@ extends AbstractApplication {

    @Override
    public void init() {
        this.setTemplateRequired(false);
    }

    @Override
    public String version() {
        return "1.0.0";
    }

    // --- steps ---------------------------------------------------------

    @Action("workflow/extract")
    public String extract(String input) {
        return input == null ? "" : input.trim();
    }

    @Action("workflow/transform")
    public String transform(String data) {
        return data.toUpperCase();
    }

    @Action("workflow/load")
    public String load(String data) {
        // Replace with a real sink: database, file, HTTP call...
        return "loaded[" + data + "]";
    }

    // --- pipeline ------------------------------------------------------

    @Action("workflow/run")
    public String run(String input) {
        String data = extract(input);
        data = transform(data);
        return load(data);
    }
}
EOF
  gen_properties "default.home.page=workflow/run"
  gen_test 'run("  hello ")' 'loaded[HELLO]'
  RUN_HINT="bin/dispatcher workflow/run/hello --import ${PACKAGE}.${CLASS}"
}

gen_agent() {
  emit "src/main/java/${PKGDIR}/${CLASS}Tools.java" <<'EOF'
package @@PACKAGE@@;

import org.tinystruct.mcp.MCPException;
import org.tinystruct.mcp.MCPTool;
import org.tinystruct.system.annotation.Action;
import org.tinystruct.system.annotation.Argument;

/** Tools the agent can call. Add your own @Action methods here. */
public class @@CLASS@@Tools extends MCPTool {

    public @@CLASS@@Tools() {
        super("tools", "Tools available to the @@NAME@@ agent");
    }

    @Action(
        value = "tools/echo",
        description = "Echo text back to the caller",
        arguments = {
            @Argument(key = "text", description = "Text to echo", type = "string", optional = false)
        }
    )
    public String echo(String text) throws MCPException {
        // Validate: tool output goes straight back into the model's context.
        if (text == null || text.length() > 500) {
            throw new MCPException("Invalid text");
        }
        return text.replaceAll("[\\p{Cntrl}&&[^\\n\\t]]", "");
    }
}
EOF
  emit "src/main/java/${PKGDIR}/${CLASS}.java" <<'EOF'
package @@PACKAGE@@;

import org.tinystruct.mcp.MCPServer;

/**
 * Agent scaffold: an MCP server that publishes the agent's tools so any
 * MCP-capable model/client can discover and call them. Wire your LLM
 * client of choice to this server's endpoint.
 */
public class @@CLASS@@ extends MCPServer {

    @Override
    public void init() {
        super.init();
        this.registerTool(new @@CLASS@@Tools());
    }

    @Override
    public String version() {
        return "1.0.0";
    }
}
EOF
  gen_properties "default.home.page=index"
  emit "src/test/java/${PKGDIR}/${CLASS}ToolsTest.java" <<'EOF'
package @@PACKAGE@@;

import static org.junit.jupiter.api.Assertions.assertEquals;

import org.junit.jupiter.api.Test;

class @@CLASS@@ToolsTest {
    @Test
    void echoes() throws Exception {
        assertEquals("hi", new @@CLASS@@Tools().echo("hi"));
    }
}
EOF
  RUN_HINT="bin/dispatcher start --import org.tinystruct.system.HttpServer --import ${PACKAGE}.${CLASS}"
}

gen_readme() {
  emit README.md <<EOF
# @@NAME@@

A tinystruct (@@VERSION@@) \`@@TYPE@@\` project.

## Build

    mvn package

## Run

    ${RUN_HINT}

On Windows (cmd/PowerShell) use \`bin\dispatcher.cmd\` in place of \`bin/dispatcher\`.

## Test

    mvn test

Docs: https://tinystruct.org
EOF
}

# ------------------------------------------------------------------ main ----
printf '\n%stinystruct%s project creator %s(framework %s)%s\n\n' "$BOLD" "$RESET" "$DIM" "$TS_VERSION" "$RESET"

info "Checking prerequisites"
check_java
check_maven
printf '\n'

NAME=${TS_NAME:-}
ask NAME "Project name" ""
valid_name "$NAME" || die "Invalid project name '${NAME}'. Use letters, digits, '.', '-' or '_', starting with a letter."

PACKAGE=${TS_PACKAGE:-}
ask PACKAGE "Package name" "$(default_package "$NAME")"
valid_pkg "$PACKAGE" || die "Invalid package '${PACKAGE}'. Use lowercase Java identifiers separated by dots (e.g. com.example.app)."

choose_type

CLASS="$(pascal_case "$NAME")App"
[ "$TS_TYPE" = basic ] || CLASS="$(pascal_case "$NAME")"
case "$CLASS" in [0-9]*|"") CLASS="App${CLASS}" ;; esac
PKGDIR=$(printf '%s' "$PACKAGE" | tr . /)
RUN_HINT=''

[ ! -e "$NAME" ] || die "Directory '${NAME}' already exists. Pick another name or remove it."

printf '\n'
info "Creating ${BOLD}${NAME}${RESET} (${TS_TYPE}, package ${PACKAGE})"
mkdir -p "$NAME"
cd "$NAME"

gen_common
case "$TS_TYPE" in
  basic)    gen_basic ;;
  web)      gen_web ;;
  mcp)      gen_mcp ;;
  workflow) gen_workflow ;;
  agent)    gen_agent ;;
esac
gen_readme
ok "Project files generated"

if [ -d .git ] || ! command -v git >/dev/null 2>&1; then :; else
  git init -q >/dev/null 2>&1 && ok "Initialized git repository" || true
fi

info "Building (mvn package)"
if mvn -q -B package; then
  ok "Build succeeded"
else
  warn "Build failed. The project was created; fix the issue and run 'mvn package' in ${NAME}/."
fi

cat <<EOF

${GREEN}${BOLD}Done!${RESET} Next steps:

  cd ${NAME}
  ${RUN_HINT}

EOF