Interpretadores

Por padrão, o Invowk™ executa scripts usando um shell. Mas você pode usar outros interpretadores como Python, Ruby, Node.js ou qualquer executável que possa rodar scripts.

Auto-Detecção a partir do Shebang

Quando um script começa com um shebang (#!), o Invowk automaticamente usa esse interpretador:

{
    name: "analyze"
    implementations: [{
        script: {content: """
            #!/usr/bin/env python3
            import sys
            import json
            
            data = {"status": "ok", "python": sys.version}
            print(json.dumps(data, indent=2))
            """}
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

Padrões comuns de shebang:

Shebang	Interpretador
#!/usr/bin/env python3	Python 3 (portável)
#!/usr/bin/env node	Node.js
#!/usr/bin/env ruby	Ruby
#!/usr/bin/env perl	Perl
#!/bin/bash	Bash (caminho direto)

Interpretador Explícito

Especifique um interpretador diretamente no objeto script:

{
    name: "script"
    implementations: [{
        script: {
            content: """
            import sys
            print(f"Python {sys.version_info.major}.{sys.version_info.minor}")
            """
            interpreter: "python3"  // Explicit
        }
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

O interpretador explícito tem precedência sobre a detecção de shebang. Se o conteúdo resolvido do script também tiver um shebang com outro interpretador ou outra lista de argumentos, o Invowk mantém script.interpreter como autoridade e reporta um aviso informativo em invowk validate e --ivk-dry-run.

interpreter: "auto" se comporta como um interpretador omitido: o Invowk usa o shebang quando presente e volta ao comportamento de shell do runtime caso contrário.

Interpretador com Argumentos

Passe argumentos para o interpretador:

{
    name: "unbuffered"
    implementations: [{
        script: {
            content: """
            import time
            for i in range(5):
                print(f"Count: {i}")
                time.sleep(1)
            """
            interpreter: "python3 -u"  // Unbuffered output
        }
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

Mais exemplos:

// Perl with warnings
script: {content: "...", interpreter: "perl -w"}

// Ruby with debug mode
script: {content: "...", interpreter: "ruby -d"}

// Node with specific options
script: {content: "...", interpreter: "node --max-old-space-size=4096"}

Interpretadores em Containers

Interpretadores funcionam em containers também:

{
    name: "analyze"
    implementations: [{
        script: {content: """
            #!/usr/bin/env python3
            import os
            print(f"Running in container at {os.getcwd()}")
            """}
        runtimes: [{
            name: "container"
            image: "python:3-slim"
        }]
        platforms: [{name: "linux"}]
    }]
}

Ou com interpretador explícito:

{
    name: "script"
    implementations: [{
        script: {
            content: """
            console.log('Hello from Node in container!')
            console.log('Node version:', process.version)
            """
            interpreter: "node"
        }
        runtimes: [{
            name: "container"
            image: "node:22-slim"
        }]
        platforms: [{name: "linux"}]
    }]
}

Acessando Argumentos

Argumentos funcionam da mesma forma com qualquer interpretador:

{
    name: "greet"
    args: [{name: "name", description: "Name to greet", default_value: "World"}]
    implementations: [{
        script: {content: """
            #!/usr/bin/env python3
            import sys
            import os
            
            # Via command line args
            name = sys.argv[1] if len(sys.argv) > 1 else "World"
            print(f"Hello, {name}!")
            
            # Or via environment variable
            name = os.environ.get("INVOWK_ARG_NAME", "World")
            print(f"Hello again, {name}!")
            """}
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

Interpretadores Suportados

O Invowk valida nomes de interpretadores contra uma lista de permissão por segurança (SC-08). Os seguintes interpretadores são aceitos:

• Shell: sh, bash, zsh, fish, dash, ksh, mksh
• Python: python3, python, python2
• JavaScript: node, deno, bun
• Ruby: ruby
• Perl: perl
• PHP: php
• Lua: lua
• R: Rscript
• Windows: pwsh, powershell, cmd

Interpretadores que não estão nesta lista são rejeitados com um UnsafeInterpreterSpecError. Metacaracteres de shell (;|& etc.) nas especificações de interpretador também são rejeitados. Ao usar /usr/bin/env, o interpretador real (segundo argumento) é validado contra a mesma lista de permissão.

Limitação do Runtime Virtual-Sh

Valores não-shell em script.interpreter não são suportados com o runtime virtual-sh:

// This will NOT work with the virtual-sh runtime.
// Runtime validation error: virtual-sh uses mvdan/sh and
// cannot execute non-shell script interpreters.
{
    name: "bad"
    implementations: [{
        script: {content: "print('hello')", interpreter: "python3"}
        runtimes: [{name: "virtual-sh"}]
        platforms: [{name: "linux"}, {name: "macos"}, {name: "windows"}]
    }]
}

O runtime virtual-sh usa o interpretador mvdan/sh embutido e não pode executar Python, Ruby ou outros interpretadores. Use runtime native, virtual-lua ou container em vez disso. Configurações de runtime não aceitam interpreter; uma forma como runtimes: [{name: "native", interpreter: "python3"}] é inválida.

Comportamento de Fallback

Quando não há shebang e nenhum script.interpreter:

• Runtime native: Usa o shell padrão do sistema
• Runtime container: Usa /bin/sh -c

--ivk-dry-run imprime a proveniência do interpretador para mostrar se a execução usará um interpretador explícito, um shebang detectado ou o comportamento padrão de shell.

Melhores Práticas

1. Use shebang para portabilidade: Scripts funcionam standalone também
2. Use /usr/bin/env: Mais portável que caminhos diretos
3. Interpretador explícito para scripts sem shebang: Quando você não quer uma linha de shebang
4. Combine imagem do container: Garanta que o interpretador existe na imagem

Próximos Passos

• Diretório de Trabalho - Controlar local de execução
• Específico de Plataforma - Implementações por plataforma