sercon

Sercon – Reconnaissance, shaped by code

sercon is a CLI tool for running TypeScript scripts for reconnaissance, troubleshooting, and testing. Write a short .ts file, hand it to sercon, and probe a service, inspect an endpoint, reproduce a bug, or script a quick check — without spinning up a Node project or pulling in a dependency tree. A small set of built-in globals gives scripts HTTP, shell exec, logging, and more, and the whole thing ships as a single static binary. Pure Go (no cgo), no Node.

Under the hood it's a TypeScript script engine in Go:

• CLI: cmd/sercon — the supported product. Runs .ts files against the built-in global surface. Reach for it when you need a repeatable, scriptable alternative to a pile of ad-hoc curl/jq/shell one-liners for recon, debugging, and test checks. Available via the codedeviate/cli Homebrew tap: brew install codedeviate/cli/sercon.
• Library: pkg/scriptengine — the engine the CLI is built on. You can embed it in your own Go program and register Go-callable bindings, but library use is unsupported: the package exists to serve the CLI, its API may change without notice, and there are no stability or sandboxing guarantees. Use it as a library at your own risk.

Runtime: goja. TypeScript is transpiled in-process with esbuild. Promises, setTimeout, and require come from goja_nodejs.

Quickstart

go build -o sercon ./cmd/sercon

cat > hello.ts <<'EOF'
log("hello", await http.get("https://example.com").then(r => r.status));
EOF

./sercon hello.ts

Library usage:

eng := scriptengine.New(scriptengine.Options{
    Timeout:    5 * time.Second,
    ScriptRoot: "./scripts",
})
eng.Register("greet", func(name string) string { return "hi " + name })
_, err := eng.RunFile(ctx, "./scripts/main.ts")

Register an I/O-bound binding that returns a Promise:

eng.RegisterFactory("httpGet", func(vm *goja.Runtime, loop *eventloop.EventLoop) any {
    return scriptengine.PromisifyAsync(vm, loop,
        func(ctx context.Context, call goja.FunctionCall) (map[string]any, error) {
            // do work, return map / struct / error
        })
})

Set up editor autocomplete + hover docs (any TypeScript-aware editor — VSCode, Zed, Neovim, …) in a script directory with one command:

sercon init           # drops sercon.d.ts + jsconfig.json into the current dir
sercon init ./scripts # …or a target dir

sercon init writes the binding declarations (sercon.d.ts) plus a jsconfig.json that points the editor's language server at them — no plugin needed. To just emit the declarations (e.g. for your own config), use ./sercon -emit-dts sercon.d.ts.

Database engines — test status

sercon ships SQL clients (db.sqlite, db.postgres, db.mysql, db.mssql, db.clickhouse, db.oracle) and a few non-SQL stores (db.redis, db.memcached, db.ldap, db.dict). They share one proven handle shape, but not all are exercised against a real server in CI:

• Verified end-to-end: db.sqlite (in-memory), db.redis (miniredis), db.memcached and db.dict (in-process stub servers).
• Not yet verified against a live server — use at your own risk: db.postgres, db.mysql, db.mssql, db.clickhouse, db.oracle (DSN assembly and connection wiring are unit-tested, but there's no functional round-trip against the real engine), plus db.ldap (error paths only). They follow the same pattern as the verified engines and should work, but haven't been confirmed against the real servers — treat them as provisional.

This list is updated as engines are manually verified; feedback on any of the provisional ones is welcome.