Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
25 commits
Select commit Hold shift + click to select a range
893b68b
ADFA-3570 | Add the Shell Hooks plugin skeleton
davidschachterADFA Nov 11, 2026
dde8a08
ADFA-3570 | Shell Hooks engine: find, trust and run hook scripts
davidschachterADFA Nov 11, 2026
ac51ed5
ADFA-3570 | Shell Hooks: wire the IDE's events, settings and Hooks tab
davidschachterADFA Nov 11, 2026
5d69a04
ADFA-3570 | Document Shell Hooks and test its samples
davidschachterADFA Nov 11, 2026
c569376
ADFA-3570 | Shell Hooks: fix the engine, wrapper and screens per review
davidschachterADFA Nov 11, 2026
67e32b3
ADFA-3570 | Shell Hooks: honest docs and a complete manifest
davidschachterADFA Nov 11, 2026
c69d1b8
ADFA-3570 | Shell Hooks: project-opened does not run before the sync
davidschachterADFA Nov 11, 2026
0d36705
ADFA-3570 | Shell Hooks: review dialog shows everything outside plain…
davidschachterADFA Nov 11, 2026
b03919d
ADFA-3570 | Shell Hooks: stop the script when the IDE kills the wrapper
davidschachterADFA Nov 11, 2026
2153ce5
ADFA-3570 | Shell Hooks: docs match the reveal, the stop and ide-started
davidschachterADFA Nov 11, 2026
85dbcc7
ADFA-3570 | Shell Hooks: reveal carriage returns and line-ending blan…
davidschachterADFA Nov 12, 2026
eec9fb9
ADFA-3570 | Shell Hooks: classify timeouts by a monotonic clock, tigh…
davidschachterADFA Nov 12, 2026
a2cafda
ADFA-3570 | Shell Hooks: docs say what the review reveals, and its cost
davidschachterADFA Nov 12, 2026
c7bf768
ADFA-3570 | Shell Hooks: only plain project scripts can be trusted
davidschachterADFA Nov 12, 2026
de57af7
ADFA-3570 | Shell Hooks: watchdog, own session and timeout wiring
davidschachterADFA Nov 12, 2026
cddf83a
ADFA-3570 | Shell Hooks: docs describe the plain-script rule
davidschachterADFA Nov 12, 2026
e1e2d4b
ADFA-3570 | Shell Hooks: mark lines worth a closer look, guard the wa…
davidschachterADFA Nov 12, 2026
611346a
ADFA-3570 | Shell Hooks: review dialog marks wraps and checks; trust …
davidschachterADFA Nov 12, 2026
2f6c9b0
ADFA-3570 | Shell Hooks: docs say review is code review, and what tru…
davidschachterADFA Nov 12, 2026
cf91ae4
ADFA-3570 | Shell Hooks: state the shell rules only as far as they hold
davidschachterADFA Nov 12, 2026
a4f896d
ADFA-3570 | Shell Hooks: match the docs to what the device QA saw
davidschachterADFA Nov 13, 2026
85a97a9
ADFA-3570 | Shell Hooks: run scripts with no project in HOME
davidschachterADFA Nov 13, 2026
63e1c17
Merge branch 'main' into feature/ADFA-3570
davidschachterADFA Nov 13, 2026
a78bc1f
ADFA-3570 | Shell Hooks: a background job no longer holds a run open
davidschachterADFA Nov 16, 2026
6cfe241
ADFA-3570 | Shell Hooks: one variable list for hooks and actions; Hoo…
davidschachterADFA Nov 16, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,7 @@ See the official [plugin documentation](https://www.appdevforall.org/codeonthego
| [`plugins/Python-Tools/`](plugins/Python-Tools/) | Adds Python and Flask project templates, and runs them. |
| [`plugins/Rainbow-Brackets/`](plugins/Rainbow-Brackets/) | Colours brackets by depth so pairs are easy to see. |
| [`plugins/Random-XKCD/`](plugins/Random-XKCD/) | Shows xkcd comics in the editor's bottom sheet. |
| [`plugins/Shell-Hooks/`](plugins/Shell-Hooks/) | Runs your shell scripts when the IDE opens a project, saves a file, or finishes a build. |
| [`plugins/Sketch-to-UI/`](plugins/Sketch-to-UI/) | Turns a drawing or screenshot into an Android layout. |
| [`plugins/Speech-to-Text/`](plugins/Speech-to-Text/) | Dictates code and text into the editor with your voice. |
| [`plugins/Vector-Search/`](plugins/Vector-Search/) | Searches the project by meaning, not only by exact text. |
Expand Down
29 changes: 29 additions & 0 deletions plugins/Shell-Hooks/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
# Gradle
.gradle/
build/
gradle-app.setting
!gradle-wrapper.jar
.gradletasknamecache

# IDE
.idea/
*.iml
*.ipr
*.iws
.project
.classpath
.settings/
.kotlin/

# Local configuration
local.properties

# OS
.DS_Store
Thumbs.db

# Logs
*.log

# Test outputs
test-results/
165 changes: 165 additions & 0 deletions plugins/Shell-Hooks/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,165 @@
# Shell Hooks

Runs the user's shell scripts at Code on the Go's integration points, git-hooks style, so IT
staff can fit the IDE into existing workflows without Android development (ADFA-3570).

Off until the user turns it on. Requires Code on the Go **26.47** (`plugin.min_ide_version`),
the first release with `IdeProjectService.addProjectLifecycleListener` and
`IdeEditorService.addFileSaveListener`.

The user-facing guide is `src/main/assets/docs/index.html` (the Tier 3 page) and the gallery
page is `shell-hooks.html`. Both document the hook table, environment, layout and trust model;
keep them in step with `engine/Hook.kt` and `engine/HookRunner.kt`.

## Hooks

| Script | Source | `$*` |
|---|---|---|
| `ide-started` | `IPlugin.activate` through `IdeStartedTrigger`: the first start with hooks on in each IDE launch | none; `COGO_PROJECT_DIR` is empty, so it runs in `HOME`; global scripts only |
| `project-opened` / `project-closed` | `ProjectLifecycleListener` | `$1` = project folder |
| `file-opened` / `file-closed` | `FileOpenExtension.onFileOpened` / `onFileClosed` | `$1` = file |
| `file-activated` | `FileChangeListener`, last of a 500 ms burst | `$1` = file or empty |
| `file-saved` | `FileSaveListener` | `$1` = file |
| `build-started` / `build-succeeded` / `build-failed` | `BuildStatusListener`; a project sync is a Gradle build too | failed: `$1` = the IDE's message (`BUILD FAILED in 12s`), trailing whitespace removed, also on a cancel |

Environment: `COGO_HOOK`, `COGO_PROJECT_DIR`, `COGO_HOOKS_DIR`, `COGO_HOOK_SCRIPT`,
`COGO_HOOK_SOURCE` (`global`/`project`), `COGO_IDE_VERSION` when known. `COGO_PROJECT_DIR` is the
event's project for project-opened and project-closed, otherwise
`IdeProjectService.getCurrentProject()?.rootDir`, which the host does not clear when a project
closes, so it can be the last project opened; it is empty for `ide-started`.

Layout: `~/.config/codeonthego/hooks/<hook>`, then `<hook>.d/*` in byte order; executable files
only; `*.sample`, dotfiles and `*~` skipped. `hooks/actions/*` become "Run <name>" file-menu
entries (files only, not folders) that run in the Terminal. A project's own hooks live in
`.codeonthego/hooks/`, for every hook but `ide-started`, which has no project for `HookResolver`
to look in, and need no executable bit: projects sit on shared storage, which is mounted noexec,
and a trusted project script runs from a private copy the plugin marks executable.

## Design decisions

- **Values travel as argv.** Headless hooks run as
`ShellCommand("sh", [cogo-hook-run.sh, script, args...])`; no value is ever part of a shell
string. Only actions go through a command line (the Terminal takes one), built with
`ShellQuote`.
- **`cogo-hook-run.sh`** maps a shebang under `/bin`, `/usr/bin` or `/usr/local/bin` onto
`$PREFIX/bin` the way termux-exec would, because the IDE's command service does not preload
termux-exec and Android has no `/usr/bin/env` or `/bin/bash`. Any other interpreter path
(`/system/bin/sh`, a virtualenv's python) runs as written. It also `cd`s to `COGO_PROJECT_DIR`:
the host refuses a working directory outside the *open* project, which `project-closed` would hit.
When that is empty or is no longer a folder it `cd`s to `HOME` (`/` without one): given no
directory, the host uses its current project's root, which can be the last project opened even
after it closed, so another project's folder.
- **Timeouts stop the whole script.** The wrapper runs the script under the Terminal's GNU
`timeout` (`COGO_TIMEOUT_SECONDS`), which puts it in its own process group and stops the group,
so a hung `git` or `gradlew` the script started does not outlive it. The host gets the limit plus
10 s and the runner gives up 5 s after that. The IDE stops a hook on disable, unload or update by
SIGKILLing the process it started; were that `timeout` itself, the script would run on with no
limit. So the wrapper runs `timeout` as a child, not with `exec`, and a watchdog sends `timeout`
TERM within about a second of the wrapper being gone, and the group stops within a few seconds of
that (`-k 5` KILLs what ignores TERM). Counted from Disable, device QA saw a script's processes
gone after 10 to 25 s, so the user docs promise about half a minute. The release bootstraps
ship GNU coreutils `timeout`. Without it, the IDE stops only the script's first process. Under
`timeout` a script's standard input is `/dev/null`. The watchdog avoids signalling a process
that has ended: its TERM trap only sets a flag; it stops its own `sleep` only when that flag is
set and the `wait` returned over 128 (a `sleep` killed from outside is already reaped and is left
alone); and it signals `timeout` only while `/proc/<pid>/comm` still reads `timeout`. The gap
left is a PID reused, between that check and the signal, by another process named `timeout`.
- **Output is printed when the script ends.** Under `timeout`, the wrapper sends the script's
stdout and stderr to two files in `TMPDIR`, deletes them while keeping them open, and prints them
once the script exits. The host waits for its pipes to close, not for the wrapper, so a job the
script left running with a bare `&` would otherwise hold them: the run would look hung until the
limit, then be recorded as timed out. A run the IDE stops loses its output. Without a writable
`TMPDIR`, or without `timeout`, output goes straight to the host as before, and a bare `&` still
holds the run open.
- **Own session without `timeout`.** Without `timeout` the script would share the IDE's process
group, and `trap 'kill 0' EXIT` would signal Code on the Go. So a headless run (input not a
terminal) from a shell that does not lead its group runs the script under `setsid`, preferring
`$PREFIX/bin/setsid` (util-linux 2.41.2 in the release bootstraps). Not leading its group,
`setsid` does not fork, so the script keeps the PID the IDE stops it by. Actions run in the
Terminal keep the Terminal's foreground group, so Ctrl-C still reaches them.
- **One script at a time**, from a 64-event queue that drops the oldest, in the order events reach
the plugin. That is not always the order things happened: the IDE reports project and save events
through a thread of its own. The host allows three concurrent commands per plugin and throws
beyond that; serial execution also keeps a burst of saves from starting a burst of processes.
Per-script timeout from settings (default 60 s).
- **Project hooks need trust.** A script can arrive with a project (a cloned repository, an AI
agent's edit, a plugin that can only write project files), so a project hook that ran unprompted
would run commands the user never approved. Trust is keyed on project + relative path + SHA-256;
a trusted script runs from a private copy of the trusted bytes (`<plugin data>/verified/<sha>`,
pruned of untrusted hashes on activation) to close the check-then-run window.
- **Only plain project scripts can be trusted** (`ScriptReview.assess`). Three independent reviews
each found another way to make a script read differently in the review dialog from how a shell
runs it: a no-break space bash takes as part of a word (`true<NBSP>#` as a function name), a
backslash before an invisible carriage return or trailing blank that reads as a line
continuation, a long run of spaces whose soft wrap looks like a new line, a tab that looks like a
space where `<<-` tells them apart. Instead of displaying each trick, a project script can be
reviewed, trusted or run only if it is at most 64 KB of printable ASCII and LF, with no line over
100 characters or ending in a space, under a name matching `[A-Za-z0-9._/-]+` with no part
starting with `.` (discovery skips such names anyway). Anything else is listed in the Hooks tab with the first reason ("line 3,
column 12: a tab") and no Trust action. `HookResolver` re-checks the bytes on every run, so an
approval of bytes that cannot be reviewed never runs, and `TrustStore.trust` refuses them. The
dialog shows one numbered row per line (a RecyclerView), monospace and left-to-right, without
hyphenation. Every row a line wraps onto shows `↳` in the number column (`LineGutter`, which draws
at the text's own baselines, so a fallback glyph cannot change a row's height), so a wrap never
reads as a new line. Global hooks are unaffected. Cost: project hooks cannot use tabs, non-ASCII
comments or long lines.
- **Review is still code review.** Plain text guarantees the reader sees every byte, not that a
skim tells what the shell does. The reviews wrote plain scripts that read as inert and run a
command: a line ending in `\` that joins a following `#;cmd` line into a word, so it is no
comment; in an unquoted here-document's "help text", the lines `EO\` and `F`, which every shell
joins and bash then takes as the delimiter `EOF`, so the lines after them run (dash and busybox
keep them as text); `<<E"O"F`, which ends at the line `EOF` rather than `E"O"F`; backticks or
`$(` in an unquoted here-document's "help text"; and `(( n = 1 << 1 ))`, which dash and busybox
read as a here-document. The dialog's intro tells the reader to read the script as the shell will, and
names these tricks, including that a backslash ending a comment, or escaped by another backslash, joins nothing.
- **A best-effort check, not a guarantee** (`ScriptHints`). Above the script the dialog lists, by
kind, every line that contains `<<` (may start a here-document), ends in `\` (in code or in
unquoted here-document text, usually joins the next line), or contains a backtick or `$(` (may run a command), and marks each `!` beside its
number. Each line is judged on its own: nothing is carried from line to line, and no quotes,
comments or here-documents are tracked, so no line can change how later lines are marked. That
is the whole rule: it marks many harmless lines (comments and strings too), and it misses every
trick outside those three kinds, such as an alias, `IFS` or a function named `[`. A line without
a mark can still do anything, and the dialog says so. It never says where a here-document ends
or whether its text is expanded; an earlier version that tried was wrong often enough to point
readers the wrong way. A kind marked on more than 100 lines lists 100 and counts the rest.
- **Names the project chose** (project folders, a run's file, the name of a script that cannot be
reviewed) are shown through `ScriptReview.reveal`: every character outside printable ASCII,
including tab and newline, and any space ending the name or a line in it, as `<U+XXXX>` with a
highlighted background, so a code typed into a name looks different from a revealed one, and a
newline in a folder name cannot add a line of text to a dialog. An unreadable script's error shows a fixed message and the
revealed path, never the exception text, which starts with the raw path.
- **What trust does not cover.** A plugin with `system.commands`, or one that writes files
in-process, can already write the global hooks folder or the trust store. Global hooks run
without review because they live in the user's own home folder; install only trusted plugins.
Trust also covers only the hook's own bytes: a trusted hook runs in the project folder, and
project files it runs (`./gradlew`, `. ./scripts/x.sh`) are not reviewed and can change later.
Nor is configuration that tools read by themselves from the project: `.git/config` can make
`git status` run a program (`core.fsmonitor`), and Gradle and npm read the project's build files
and scripts. Keep project hooks self-contained, or review what they call.
- **The UI thread.** Reading, checking and marking a script happen off the main thread, and so do
Trust and Revoke, which resolve a canonical path and `commit()` to disk, and loading Settings'
list of trusted projects, which resolves each project's canonical path. The Hooks tab is one
RecyclerView (`PanelRow`) whose `ListAdapter` compares the rows off the main thread, so a
finished hook binds its one new row. It lists at most 50 pending scripts and counts the rest,
so a project with thousands of them does not push the runs out of reach.
- **Notifications only.** No hook can veto a save or a build; the host callbacks report the past.
- **Paths.** `HOME` and `PREFIX` are `<app files>/home` and `<app files>/usr`, the values
`TermuxProcessEnvironment` gives every command, derived from `PluginContext.getAppFilesDir()`.
- **Older IDEs.** The 26.47 listeners live in `WorkspaceHooks`, which only loads inside a guarded
block, so on an older IDE the plugin still loads and runs every hook except project-opened,
project-closed and file-saved. Actions need the plugin Terminal service from 26.42; before that
"Run <name>" records a run that did not start instead of failing. (The host does not enforce
`min_ide_version`.)
- **Permissions.** `system.commands` runs scripts; `filesystem.read` covers the open file, the
project root and the listeners; `filesystem.write` covers "Create sample hooks".

## Build and test

```sh
cd plugins/Shell-Hooks
../../gradlew assemblePlugin # build/plugin/shell-hooks.cgp
../../gradlew testDebugUnitTest
```

`WrapperScriptTest` runs the wrapper under every POSIX shell it finds (`/bin/sh`, dash, bash,
busybox ash). Android runs it with mksh, which those tests do not cover.
16 changes: 16 additions & 0 deletions plugins/Shell-Hooks/addon.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
{
"summary": "Runs your shell scripts when the IDE opens a project, saves a file, or finishes a build.",
"description": "Hooks Code on the Go into the workflows you already script. Put an executable script in a hooks folder and it runs when a project opens or closes, a file is opened, saved or closed, or a build starts, succeeds or fails, with the file or project passed in $1. Scripts kept in a project run only after you review and trust them. Off until you turn it on.",
"tags": [
"shell",
"automation",
"scripts",
"hooks"
],
"origin": "appdevforall",
"license": "AGPL-3.0-or-later",
"author": {
"name": "App Dev For All",
"url": "https://www.appdevforall.org"
}
}
84 changes: 84 additions & 0 deletions plugins/Shell-Hooks/build.gradle.kts
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
import org.jetbrains.kotlin.gradle.dsl.JvmTarget

plugins {
id("com.android.application")
id("com.itsaky.androidide.plugins.build")
}

pluginBuilder {
pluginName = "shell-hooks"
}

android {
namespace = "org.appdevforall.shellhooks"
compileSdk = 36

defaultConfig {
applicationId = "org.appdevforall.shellhooks"
minSdk = 26
targetSdk = 36
versionCode = 1
versionName = "1.0.0"
}

buildTypes {
release {
isMinifyEnabled = false
proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"), "proguard-rules.pro")
}
}

compileOptions {
sourceCompatibility = JavaVersion.VERSION_17
targetCompatibility = JavaVersion.VERSION_17
}

packaging {
resources {
excludes += setOf(
"META-INF/versions/9/OSGI-INF/MANIFEST.MF",
"META-INF/DEPENDENCIES",
"META-INF/LICENSE",
"META-INF/LICENSE.txt",
"META-INF/NOTICE",
"META-INF/NOTICE.txt"
)
}
}

testOptions {
unitTests.isReturnDefaultValues = true
}
}

kotlin {
compilerOptions {
jvmTarget.set(JvmTarget.JVM_17)
}
}

dependencies {
// The plugin-api jar is the canonical contract for plugins. Available
// at compile time; the IDE provides it at runtime.
compileOnly(files("../../libs/plugin-api.jar"))

implementation("androidx.appcompat:appcompat:1.6.1")
implementation("com.google.android.material:material:1.10.0")
implementation("androidx.fragment:fragment-ktx:1.8.8")
implementation("androidx.core:core-ktx:1.13.1")
implementation("org.jetbrains.kotlin:kotlin-stdlib:2.3.21")
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.8.1")

testImplementation(files("../../libs/plugin-api.jar"))
testImplementation("junit:junit:4.13.2")
testImplementation("org.jetbrains.kotlinx:kotlinx-coroutines-test:1.8.1")
}

// Disable AAR metadata checks that fail under the plugin-builder
// pipeline (Voice Alerts + Forms use the same workaround).
tasks.matching {
it.name.contains("checkDebugAarMetadata") ||
it.name.contains("checkReleaseAarMetadata")
}.configureEach {
enabled = false
}
4 changes: 4 additions & 0 deletions plugins/Shell-Hooks/gradle.properties
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
android.useAndroidX=true
android.nonTransitiveRClass=true
kotlin.code.style=official
org.gradle.jvmargs=-Xmx2048m -Dfile.encoding=UTF-8
5 changes: 5 additions & 0 deletions plugins/Shell-Hooks/proguard-rules.pro
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
# Add project specific ProGuard rules here.

# Keep plugin classes — the IDE loads them by reflection via plugin.main_class,
# and the settings fragment by name from PluginSettingsEntry.fragmentClassName.
-keep class org.appdevforall.shellhooks.** { *; }
30 changes: 30 additions & 0 deletions plugins/Shell-Hooks/settings.gradle.kts
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
pluginManagement {
repositories {
google()
mavenCentral()
gradlePluginPortal()
}
}

buildscript {
repositories {
google()
mavenCentral()
}
dependencies {
classpath(files("../../libs/plugin-api.jar"))
classpath(files("../../libs/gradle-plugin.jar"))
classpath("com.android.tools.build:gradle:9.3.1")
classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:2.3.21")
}
}

dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
repositories {
google()
mavenCentral()
}
}

rootProject.name = "shell-hooks"
Loading
Loading