> For the complete documentation index, see [llms.txt](https://docs.kira.thiennguyen.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kira.thiennguyen.dev/extension-development/authoring-workflow.md).

# Authoring Workflow

Practical guidance for building, debugging, and shipping an extension.

## Editor setup

`import "kira"` is provided by the interpreter **at runtime**, so out of the box your editor reports `could not import kira (no required module provides package "kira")`. Fix it with a **compile-only stub**: a package literally named `kira` whose function bodies `panic` — they never run, because Yaegi supplies the real implementation. A ready-made stub ships with Kira's sample extensions; copy it next to your sources and point a `replace` at it:

```
// go.mod next to your action sources
module my-extension

go 1.25

require kira v0.0.0
replace kira => ./kira-sdk   // path to the copied stub
```

Now gopls / `go vet` / `go build` resolve `import "kira"` with full autocomplete.

{% hint style="info" %}
**One `Run` per directory.** Each action file is `package action` + `func Run`, and Yaegi interprets one file at a time — but `go build` compiles a whole directory at once, so two action files in the same folder collide with `Run redeclared in this block`. For a clean editor, give each action its own directory (each still `package action`) and point its manifest `entry` there.
{% endhint %}

## Cancellation & timeouts

* A run is capped at **60 seconds** — but the cap is **paused** while an `Alert` / `Confirm` / `Ask` / `ShowHTML` modal is open, so waiting on the user never times the run out.
* The user can **Cancel** a run from the console. Cancellation is **cooperative**: an interpreted script can't be force-killed mid-execution. To be promptly cancellable:
  * Use `k.HTTP()` for requests — they're bound to the run context and abort immediately.
  * Pass `k.Context()` to blocking calls (`http.NewRequestWithContext`, `select`/timers) and check `k.Context().Err()` in long loops.

```go
ctx := k.Context()
for i := 0; i < n; i++ {
    if ctx.Err() != nil {
        return ctx.Err() // user cancelled / timed out
    }
    // ... work ...
}
```

## Debugging

* The **Output console** streams `k.Log` / `Logf` and stdout/stderr live, shows status + duration, and has a Cancel button. Closing it doesn't kill the run; reopen it via the **Output** button in the Extensions header.
* A failed run shows the returned `error` (or a panic) in red.
* **Iterating:** edit the source, re-zip, **remove** the old install, then re-install. The registry caches the manifest at install time, so reinstall after changing manifest fields.

## Versioning & compatibility

Set `minKiraVersion` when your script uses a newer SDK method. On older Kira the extension still installs, but its actions are disabled (red `Kira ≥ X` badge) and won't run — the user is told to update. Bump your own `version` for your records; it's shown as a pill in the list.

## Distributing

* **File** — share the `.kext`; users pick it via **Install extension → Choose file…**.
* **URL** — host the `.kext` over **https** (≤ 5 MB); users paste the link in the install dialog. Kira downloads it, shows the trust gate, then installs.

Either way the user reviews the source and confirms once before anything runs. See [Using Extensions](/user-guide/extensions-using.md) for the install flow from the user's side.

## Limitations (Yaegi / WKWebView)

* **Stdlib up to Go 1.22.** No cgo. A few advanced generics / `unsafe` corners may interpret differently from compiled Go — test your script.
* **No force-kill** of a runaway CPU loop — honour the context (see above).
* **Printing / large windows** happen in the system browser, not in-app (the in-app web view has no `window.print()` and a single fixed window).
* The `import "kira"` package only exists inside Kira — your editor / `go vet` / `go build` can't resolve it without the compile-only stub (see [Editor setup](#editor-setup)).

## Reference sample

Kira ships a complete, working sample extension (the **Trigger** bundle). It demonstrates shared-file actions, a `none`-context action, `Ask` inputs (text / number / select), an `ShowHTML` report, per-action `config`, `minKiraVersion`, and an icon. Import it from the Extensions screen and read its `manifest.json` + `actions/*.go` alongside this guide.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.kira.thiennguyen.dev/extension-development/authoring-workflow.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.