diff --git a/README.md b/README.md index 023c87d8..8582dfc8 100644 --- a/README.md +++ b/README.md @@ -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. | diff --git a/plugins/Shell-Hooks/.gitignore b/plugins/Shell-Hooks/.gitignore new file mode 100644 index 00000000..6af499b7 --- /dev/null +++ b/plugins/Shell-Hooks/.gitignore @@ -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/ diff --git a/plugins/Shell-Hooks/README.md b/plugins/Shell-Hooks/README.md new file mode 100644 index 00000000..895055ac --- /dev/null +++ b/plugins/Shell-Hooks/README.md @@ -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/`, then `.d/*` in byte order; executable files +only; `*.sample`, dotfiles and `*~` skipped. `hooks/actions/*` become "Run " 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//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 (`/verified/`, + 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#` 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); `<` 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 `/home` and `/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 " 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. diff --git a/plugins/Shell-Hooks/addon.json b/plugins/Shell-Hooks/addon.json new file mode 100644 index 00000000..a2d0fb1a --- /dev/null +++ b/plugins/Shell-Hooks/addon.json @@ -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" + } +} diff --git a/plugins/Shell-Hooks/build.gradle.kts b/plugins/Shell-Hooks/build.gradle.kts new file mode 100644 index 00000000..8b1717a1 --- /dev/null +++ b/plugins/Shell-Hooks/build.gradle.kts @@ -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 +} diff --git a/plugins/Shell-Hooks/gradle.properties b/plugins/Shell-Hooks/gradle.properties new file mode 100644 index 00000000..9ba44411 --- /dev/null +++ b/plugins/Shell-Hooks/gradle.properties @@ -0,0 +1,4 @@ +android.useAndroidX=true +android.nonTransitiveRClass=true +kotlin.code.style=official +org.gradle.jvmargs=-Xmx2048m -Dfile.encoding=UTF-8 diff --git a/plugins/Shell-Hooks/proguard-rules.pro b/plugins/Shell-Hooks/proguard-rules.pro new file mode 100644 index 00000000..331df750 --- /dev/null +++ b/plugins/Shell-Hooks/proguard-rules.pro @@ -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.** { *; } diff --git a/plugins/Shell-Hooks/settings.gradle.kts b/plugins/Shell-Hooks/settings.gradle.kts new file mode 100644 index 00000000..349fb979 --- /dev/null +++ b/plugins/Shell-Hooks/settings.gradle.kts @@ -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" diff --git a/plugins/Shell-Hooks/shell-hooks.html b/plugins/Shell-Hooks/shell-hooks.html new file mode 100644 index 00000000..61af50d2 --- /dev/null +++ b/plugins/Shell-Hooks/shell-hooks.html @@ -0,0 +1,373 @@ + + + + + +Shell Hooks + + + + +
+

Shell Hooks

+

Run your own shell scripts when Code on the Go opens a project, saves a file, or finishes a build

+
Version 1.0.0 · Author: App Dev For All · Package: org.appdevforall.shellhooks · Needs Code on the Go 26.47 or later
+
+ + + + +
+

1. Executive Overview

+

+ Shell Hooks lets anyone who can write a shell script fit Code on the Go into the workflow they + already have, with no Android development. Drop an executable script named after a hook into + ~/.config/codeonthego/hooks/ and it runs at that moment: when a project opens, when + a file is saved, when a build fails. The file or project arrives in $1, exactly as a + git hook gets its arguments. +

+

+ Typical uses: pull the latest changes when a project opens, run a linter or formatter on save, + copy a fresh APK to a shared folder when a build succeeds, or post a message when one fails. +

+
+ The plugin is off until you turn it on in Preferences → Shell Hooks. + Hooks only report what happened: a script cannot stop a save or a build. +
+
+ + +
+

2. Core Functionality

+ +

Hooks and their arguments

+ + + + + + + + + + + + +
Script nameRuns when$*
ide-startedonce in each launch of Code on the Go, the first time Shell Hooks starts with hooks on. If hooks are off, or the plugin is disabled, when the IDE starts, it runs later in that launch, when the plugin next starts with hooks onnone
project-openedthe editor opens a project; its sync starts without waiting for the hook$1 = project folder
project-closedthe editor closes a project$1 = project folder
file-openeda file opens in the editor$1 = file
file-closeda file's tab is closed$1 = file
file-activatedyou switch to another tab (the last of a quick burst only)$1 = file, or empty when no file is open
file-savedthe editor writes a file to disk$1 = file
build-starteda Gradle build starts, including a project syncnone
build-succeededa Gradle build succeeds, including a project syncnone
build-faileda Gradle build fails, including a project sync, or you cancel it$1 = the IDE's message, such as BUILD FAILED in 12s; the message for a cancel is in the IDE's language
+ +

Environment

+ + + + + + + + +
VariableValue
COGO_HOOKthe hook's name, e.g. file-saved (action for an action)
COGO_PROJECT_DIRthe IDE's current project folder, which can be the last one opened even after it closes; empty for ide-started
COGO_HOOKS_DIRthe hooks folder the script is in
COGO_HOOK_SCRIPTthe script's own path
COGO_HOOK_SOURCEglobal, or project for a script stored in a project
COGO_IDE_VERSIONCode on the Go's version, when known
+

+ HOME, PREFIX and PATH are the Terminal's, so every + Terminal package is available. A script runs in COGO_PROJECT_DIR, or in + HOME when that is empty or the folder is gone. +

+ +

Folder layout

+
~/.config/codeonthego/hooks/
+  file-saved            runs first
+  file-saved.d/
+    10-format           then these, in name order
+    20-lint
+  build-failed.sample   never runs: rename it and chmod +x to use it
+  actions/
+    word-count          "Run word-count" on a file's menu
+
    +
  • In your folder, only files with the executable bit run (chmod +x). A project's scripts need no executable bit: projects sit on shared storage, which keeps none.
  • +
  • Names ending in .sample or ~, and names starting with ., never run, so an editor's swap file is never executed.
  • +
  • A shebang under /bin, /usr/bin or /usr/local/bin, such as #!/usr/bin/env python3 or #!/bin/bash, is resolved to the Terminal's program, as in the Terminal. Any other interpreter path, such as a virtualenv's python, runs as written. A script with no shebang runs with bash.
  • +
  • Create sample hooks in settings writes one .sample per hook, documenting its arguments.
  • +
+ +

Actions

+

+ Executable scripts in hooks/actions/ appear as Run <name> + when you long-press a file (not a folder) in the file tree or an editor tab. They run in the + visible Terminal, with the file in $1, so you see what they print. An action that + cannot start is listed in the Hooks tab with the reason. +

+ +

Hooks tab

+

+ The Hooks tab in the editor's bottom panel lists the last 100 runs: hook, + script, file, outcome, exit code, time and duration. Tap a run to see its output (the last 64 KB). + Project scripts waiting for review are listed above the runs. +

+ +

Timeouts and ordering

+

+ Scripts run one at a time, in the order their events reach the plugin, global scripts before + project scripts. The IDE reports project and save events through a thread of its own, so a save + just before a build can be reported after the build starts. A script still running after the + timeout (60 seconds unless you change it) is stopped, and with the Terminal's + timeout (coreutils) installed so is every program it started. Disabling, + unloading or updating the plugin while a script runs stops it the same way within about half + a minute; release builds of Code on the Go ship timeout, and without it only the + script's own process is stopped. If events arrive faster than scripts + finish, up to 64 wait; past that the oldest is dropped. Start long jobs in the background + (nohup long-job >/dev/null 2>&1 &). +

+
+ + +
+

3. Security Model

+

+ A hook runs with Code on the Go's own access, the same as a command typed in the Terminal: it + can read and change your projects and use the network. Who wrote the script decides whether it + can run. +

+
    +
  • Your hooks in ~/.config/codeonthego/hooks/ are scripts you + put there yourself, so they run once hooks are on.
  • +
  • Project hooks in a project's .codeonthego/hooks/ use the same + layout, for every hook but ide-started, which has no project, so only yours + runs. They come with the project: from a cloned repository, an AI agent's edit, or a + plugin that can only write project files. A project hook would otherwise run commands you never approved. They + therefore need two things: the Run hooks stored in projects switch (off by + default), and your trust in that exact script. An untrusted script is skipped and listed in + the Hooks tab; Review shows all of it, one numbered row per line, before + you can trust it. Every row a line wraps onto is marked ↳ in the number column, so a + wrap never reads as a new line.
  • +
  • Only plain scripts can be trusted. A project script can be reviewed only + if it is at most 64 KB of printable ASCII and newlines: no tabs, no carriage returns, no + other control or non-ASCII characters, no line longer than 100 characters or ending in a + space, and a name of letters, digits, ., _, - and + /, with no part starting with a dot (such names are skipped altogether). + Anything else is listed with the reason it can't be reviewed, and never + runs. Each of these can make a script run differently from how it reads: a no-break space + bash takes as part of a word, a backslash before an invisible carriage return or trailing + space that looks like a line continuation, a long run of spaces whose wrap looks like a new + line, a tab that looks like a space where <<- tells them apart. Your own + hooks have no such limits.
  • +
  • Reviewing is reading code. Plain text guarantees you see every byte, not + that a quick look tells you what the shell does, so read the script as the shell will. A + plain script can still mislead a skim: a backslash ending a line of code usually joins the + next one to it, and a # starting that line may then be no comment (a + backslash that ends a comment, or is escaped by another backslash, joins nothing); a + here-document ends at a line matching its delimiter (<<E"O"F ends at + EOF, and the lines after it run), and in an unquoted here-document's text a + backslash ending a line joins the next one too, so in bash, which runs a script with no + #! line, lines such as EO\ and F can end it early; + and backticks, or $( in an unquoted here-document's text, can run a command + inside what looks like text.
  • +
  • A best-effort check, not a guarantee. The dialog marks ! + beside its number every line that contains <<, a backtick or + $(, or ends in a backslash, and lists them above the script by kind. It judges + each line on its own, in comments and strings too, so it marks many harmless lines, and it + misses every other kind of trick, such as an alias or IFS. A line without a + mark can still do anything, so read every line.
  • +
  • Trust is recorded per project, per script path, against the SHA-256 of the script's bytes. + Editing the script, or adding another, needs a new review. Settings lists the trusted + projects, each with Revoke.
  • +
  • A trusted project script runs from a private copy of the bytes you trusted, so it cannot be + swapped between the check and the run.
  • +
  • File names and other values reach hook scripts as separate arguments, never through a + shell command line, so a file named $(rm -rf ~) is just a name. Actions are the + exception: the Terminal takes a command line, so an action's command is built with every + value in single quotes, which the shell never expands.
  • +
  • What review does not cover. A plugin that can run commands, or one that + writes files from inside the IDE, can already change your own hooks folder or the record of + what you trusted. Install only plugins you trust. Trust also covers only the hook's own + text: files it runs from the project, such as ./gradlew or + ./scripts/setup.sh, are not reviewed and can change later. Neither is + configuration that tools read by themselves from the project: a hook in + .git/config such as core.fsmonitor runs a program on + git status, and Gradle and npm read the project's build files and scripts. + Keep project hooks self-contained, or review what they call.
  • +
+
+ + +
+

4. Technical Architecture

+
IDE event (listener / extension callback) + | + v +ShellHooksPlugin.submit() -- off? hook disabled? drop it + | + v +HookRunner queue (64, drop oldest) -- one worker, one script at a time + | + v +HookResolver -- global scripts, then trusted project scripts + | + v +IdeCommandService: sh cogo-hook-run.sh SCRIPT ARG... + | + v +HookLog -> Hooks tab
+ + + + + + + + + + +
ClassRole
ShellHooksPluginLifecycle; registers the listeners in activate(), removes them in deactivate(); settings, tab and file-menu contributions.
engine/HookRunnerThe bounded queue and its single worker; timeouts; outcome recording.
engine/HookResolverTurns an event into scripts; enforces the switches and project trust.
engine/HookDiscoveryThe git-hooks layout: <hook>, then <hook>.d/*.
engine/TrustStoreApprovals keyed on project, path and SHA-256.
engine/ShellQuoteQuoting for the Terminal, which takes a command line.
assets/cogo-hook-run.shMaps a /bin or /usr/bin shebang onto $PREFIX/bin, changes to the event's project folder (to HOME with none, or when it is gone), and runs the script under timeout so a timeout stops the whole process group. Under timeout it keeps the script's output in deleted files and prints it when the script ends, so a job left running in the background does not hold the run open.
WorkspaceHooksThe 26.47 project and save listeners, kept apart so an older IDE runs the other hooks.
+
+ + +
+

5. Integration Points

+ + + + + + + + + + +
HookPlugin API
project-opened / project-closedIdeProjectService.addProjectLifecycleListener (26.47)
file-savedIdeEditorService.addFileSaveListener (26.47)
file-activatedIdeEditorService.addFileChangeListener
file-opened / file-closedFileOpenExtension.onFileOpened / onFileClosed
build-*IdeBuildService.addBuildStatusListener
Running scriptsIdeCommandService.executeCommand with CommandSpec.ShellCommand
ActionsFileOpenExtension.getFileTabMenuItems, IdeTerminalService.runInTerminal
Settings, tab, helpSettingsExtension, UIExtension.getEditorTabs, DocumentationExtension
+

+ Permissions: system.commands to run scripts, filesystem.read for the + file and project listeners, and filesystem.write to write the sample hooks. On an + IDE older than 26.47 the plugin still loads; project-opened, project-closed and file-saved never + run there. Actions need the Terminal service plugins got in 26.42; on an older IDE, + "Run <name>" records a run that did not start. +

+

+ Not hooked on purpose: editor content changes (one process per keystroke). Hooks cannot veto: + every IDE callback here reports something that already happened. +

+
+ + +
+

6. Deployment & Usage

+

Build the installable plugin from the plugin folder:

+
cd plugins/Shell-Hooks
+../../gradlew assemblePlugin
+

+ The .cgp lands in build/plugin/shell-hooks.cgp. Install it with the + Plugin Manager, then: +

+
    +
  1. Open Preferences → Shell Hooks and turn on Run hooks.
  2. +
  3. Tap Create sample hooks.
  4. +
  5. In the Terminal: cd ~/.config/codeonthego/hooks && mv file-saved.sample file-saved && chmod +x file-saved
  6. +
  7. Save a file, then open the Hooks tab to see the run. The sample appends a line to ~/codeonthego-hooks.log.
  8. +
+
+ + +
+

7. Key Benefits

+
    +
  • No Android development. Anything a shell script can do becomes an IDE integration.
  • +
  • Familiar model. Named scripts and .d folders, as in git hooks and run-parts.
  • +
  • Safe by default. Off until enabled; project scripts need your review; hook values never pass through a shell parser.
  • +
  • Visible. Every run's outcome and output in one tab.
  • +
+
+ +
+ Shell Hooks Plugin Documentation · Version 1.0.0 · org.appdevforall.shellhooks +
+ + + diff --git a/plugins/Shell-Hooks/src/main/AndroidManifest.xml b/plugins/Shell-Hooks/src/main/AndroidManifest.xml new file mode 100644 index 00000000..cc8a3f8b --- /dev/null +++ b/plugins/Shell-Hooks/src/main/AndroidManifest.xml @@ -0,0 +1,75 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/plugins/Shell-Hooks/src/main/assets/cogo-hook-run.sh b/plugins/Shell-Hooks/src/main/assets/cogo-hook-run.sh new file mode 100644 index 00000000..c1cabc9e --- /dev/null +++ b/plugins/Shell-Hooks/src/main/assets/cogo-hook-run.sh @@ -0,0 +1,179 @@ +# Shell Hooks runner. Usage: sh cogo-hook-run.sh SCRIPT [ARG...] +# +# Runs SCRIPT with its arguments untouched. Android has no /usr/bin/env or /bin/bash, and the +# IDE's command service does not preload termux-exec, so a shebang naming /bin, /usr/bin or +# /usr/local/bin is looked up in $PREFIX/bin, as termux-exec would do. Any other interpreter path +# runs as written. POSIX sh only: this runs under Android's /system/bin/sh, not bash. + +script=$1 +shift + +# The event's project, which for project-closed the IDE no longer has open. With none, as for +# ide-started, or one whose folder is gone, HOME: given no folder, the IDE starts this shell in the +# last project opened, even one since closed, and that can be another project. +if [ -n "${COGO_PROJECT_DIR:-}" ] && [ -d "$COGO_PROJECT_DIR" ]; then + cd "$COGO_PROJECT_DIR" || exit 126 +else + cd "${HOME:-/}" || exit 126 +fi + +# With COGO_TIMEOUT_SECONDS set and the Terminal's GNU timeout installed, the script runs under +# it: timeout puts the script in its own process group and stops the whole group at the limit +# (KILL 5 s after TERM), so programs the script started do not outlive it. timeout runs as a child, +# not in place of this shell: the IDE stops a hook (on disable, unload or update) by killing the +# process it started, and if that were timeout the script would run on with no limit. A watchdog +# notices this shell is gone and sends timeout TERM, which stops the whole group the same way. +# Without timeout, the IDE's own stop ends only the script's first process. +# +# The script's output goes to files and is printed once it ends. The IDE waits for its pipes to +# close, not for this shell to exit, so a job the script left running with a bare `&` would hold +# them open and the run would look hung until the limit. The files are deleted as soon as they are +# open, so a run that is stopped leaves none behind; its output is lost. +run() { + if [ -n "${COGO_TIMEOUT_SECONDS:-}" ] && in_prefix timeout; then + capture + if [ -n "$captured" ]; then + "$PREFIX/bin/timeout" -k 5 "$COGO_TIMEOUT_SECONDS" "$@" >&3 2>&4 3>&- 4>&- 5<&- 6<&- & + child=$! + exec 3>&- 4>&- + else + "$PREFIX/bin/timeout" -k 5 "$COGO_TIMEOUT_SECONDS" "$@" & + child=$! + fi + # Its output goes nowhere, so it never keeps the IDE's pipes open. Redirected with exec inside + # a subshell: dash and busybox, given `watch ... >/dev/null &`, keep a saved copy of the + # original stdout open in the background job. ($$ in a subshell is still this wrapper.) + (exec /dev/null 2>&1; watch "$$" "$child") & + watchdog=$! + wait "$child" + status=$? + kill "$watchdog" 2>/dev/null + if [ -n "$captured" ]; then + cat <&5 + cat <&6 >&2 + fi + exit "$status" + fi + # Without timeout the script would share the IDE's process group, so one that signals its own + # group (`trap 'kill 0' EXIT`) would signal Code on the Go. setsid gives it a session and group + # of its own; as this shell does not lead its group, setsid does not fork, and the script keeps + # this process ID, which the IDE stops it by. Not when run in the Terminal (input from a + # terminal): there the script stays in the Terminal's foreground group, so Ctrl-C reaches it. + if [ ! -t 0 ] && shares_group; then + if in_prefix setsid; then + exec "$PREFIX/bin/setsid" "$@" + fi + if command -v setsid >/dev/null 2>&1; then + exec setsid "$@" + fi + fi + exec "$@" +} + +# True when this shell is in a process group it does not lead, such as the IDE's. +shares_group() { + [ -r "/proc/$$/stat" ] || return 1 + IFS= read -r stat < "/proc/$$/stat" || return 1 + # Fields after the command name, which may itself hold spaces or parentheses: state, ppid, pgrp. + set -- ${stat##*") "} + [ "${3:-}" != "$$" ] +} + +# Waits while process $1 (this wrapper) lives, then sends TERM to $2 (timeout). The wrapper sends +# it TERM when the script ends normally; the trap only notes that, so the loop never signals a +# sleep it has already waited for, whose ID may belong to another process by then. Only a TERM +# that interrupts the wait leaves that sleep running, and only then is it stopped: a wait over 128 +# can also mean the sleep itself was killed from outside and already reaped. +watch() { + stop= + trap 'stop=1' TERM + while [ -z "$stop" ] && kill -0 "$1" 2>/dev/null; do + sleep 1 & + nap=$! + wait "$nap" + napped=$? + if [ -n "$stop" ] && [ "$napped" -gt 128 ]; then + kill "$nap" 2>/dev/null + fi + done + [ -z "$stop" ] || exit 0 + # Only while $2 is still timeout: if timeout ended in the last second, its process ID may + # already be another process's. + if [ -r "/proc/$2/comm" ]; then + IFS= read -r comm < "/proc/$2/comm" || comm= + [ "$comm" = timeout ] || exit 0 + fi + kill -s TERM "$2" 2>/dev/null +} + +in_prefix() { + [ -n "$1" ] && [ -n "${PREFIX:-}" ] && [ -f "$PREFIX/bin/$1" ] && [ -x "$PREFIX/bin/$1" ] +} + +# Opens a file for the script's stdout on 3 and 5 (write, read) and one for its stderr on 4 and 6, +# then deletes both: the descriptors keep them. Sets captured only if that worked; without a +# writable TMPDIR the output goes straight to the IDE, as it did before. +capture() { + captured= + dir=${TMPDIR:-/tmp} + out=$(mktemp -p "$dir" cogo-hook.XXXXXX 2>/dev/null) || return 0 + if ! err=$(mktemp -p "$dir" cogo-hook.XXXXXX 2>/dev/null); then + rm -f "$out" + return 0 + fi + exec 3>"$out" 4>"$err" 5<"$out" 6<"$err" + rm -f "$out" "$err" + captured=1 +} + +first= +IFS= read -r first < "$script" || : +cr=$(printf '\r') +first=${first%"$cr"} + +trim() { + value=$1 + while :; do + case $value in + [' ']*) value=${value#?} ;; + *[' ']) value=${value%?} ;; + *) break ;; + esac + done + printf '%s' "$value" +} + +case $first in +'#!'*) + line=$(trim "${first#??}") + interp=${line%%[' ']*} + arg=$(trim "${line#"$interp"}") + case $interp in + /bin/* | /usr/bin/* | /usr/local/bin/*) + name=${interp##*/} + if [ "$name" = env ]; then + name=${arg%%[' ']*} + arg=$(trim "${arg#"$name"}") + fi + if in_prefix "$name"; then + if [ -n "$arg" ]; then + run "$PREFIX/bin/$name" "$arg" "$script" "$@" + fi + run "$PREFIX/bin/$name" "$script" "$@" + fi + ;; + esac + # Any other interpreter, e.g. #!/system/bin/sh or a virtualenv's python: the kernel reads the + # shebang as written. + run "$script" "$@" + ;; +"$(printf '\177')ELF"*) + run "$script" "$@" + ;; +esac + +# No shebang: a shell script, as a terminal user would expect. +if in_prefix bash; then + run "$PREFIX/bin/bash" "$script" "$@" +fi +run sh "$script" "$@" diff --git a/plugins/Shell-Hooks/src/main/assets/docs/index.html b/plugins/Shell-Hooks/src/main/assets/docs/index.html new file mode 100644 index 00000000..bf51e976 --- /dev/null +++ b/plugins/Shell-Hooks/src/main/assets/docs/index.html @@ -0,0 +1,163 @@ + + + + + +Shell Hooks guide + + + + +

Shell Hooks guide

+

+ Shell Hooks runs your own shell scripts when Code on the Go opens a project, opens, saves or + closes a file, or starts or finishes a build. If you can write a shell script, you can fit the + IDE into your workflow. +

+

+ Nothing runs until you turn on Run hooks in Preferences > Shell Hooks. Hooks only + report what happened: a script cannot stop a save or a build. +

+ +

Your first hook

+
    +
  1. Preferences > Shell Hooks: turn on Run hooks, then tap Create sample hooks.
  2. +
  3. In the Terminal: +
    cd ~/.config/codeonthego/hooks
    +mv file-saved.sample file-saved
    +chmod +x file-saved
  4. +
  5. Save a file. The Hooks tab in the bottom panel shows the run; tap it to see the output. + The sample adds a line to ~/codeonthego-hooks.log.
  6. +
+ +

Hooks

+ + + + + + + + + + + + +
Script nameRuns whenArguments
ide-startedonce in each launch of Code on the Go, the first time Shell Hooks starts with hooks onnone
project-openeda project opens (its sync does not wait for the hook)$1 = project folder
project-closeda project closes$1 = project folder
file-openeda file opens in the editor$1 = file
file-closeda file's tab closes$1 = file
file-activatedyou switch tabs (the last of a quick burst)$1 = file, or empty
file-saveda file is written to disk$1 = file
build-starteda build starts, including a project syncnone
build-succeededa build succeeds, including a project syncnone
build-faileda build fails, including a project sync, or you cancel it$1 = the IDE's message, such as BUILD FAILED in 12s
+

Every script also gets these environment variables:

+ + + + + + + + +
VariableValue
COGO_HOOKthe hook's name (action for an action)
COGO_PROJECT_DIRthe IDE's current project folder, which can be the last one opened even after it closes; empty for ide-started
COGO_HOOKS_DIRthe hooks folder the script is in
COGO_HOOK_SCRIPTthe script's own path
COGO_HOOK_SOURCEglobal or project
COGO_IDE_VERSIONthe IDE's version, when known
+

The script runs in COGO_PROJECT_DIR, or in HOME when that is empty, with the Terminal's HOME, PREFIX and PATH.

+ +

Where scripts go

+
~/.config/codeonthego/hooks/
+  file-saved          runs first
+  file-saved.d/       then every script here, in name order
+  actions/            "Run <name>" on a file's menu
+
    +
  • In your folder, only executable files run: chmod +x. A project's scripts need no executable bit.
  • +
  • Files ending in .sample or ~, or starting with ., never run.
  • +
  • #!/usr/bin/env python3 or #!/bin/bash use the Terminal's programs, as any interpreter under /bin, /usr/bin or /usr/local/bin does. Any other path, such as a virtualenv's python, runs as written. No shebang means bash.
  • +
  • Settings can turn single hooks off without deleting their scripts.
  • +
+ +

Actions

+

+ An executable script in hooks/actions/ appears as Run <name> when you + long-press a file (not a folder) in the file tree or an editor tab. It runs in the Terminal with + the file in $1, so you see its output. If it cannot start, the Hooks tab says why. +

+ +

Timeouts and order

+

+ Scripts run one at a time, in the order events reach the plugin, which can differ slightly from + the order things happened: your scripts first, then the project's. A script still running after + the timeout (60 seconds by default, set in Preferences) is stopped, together with the programs it + started, when the Terminal has timeout (coreutils). Disabling or updating the plugin + while a script runs stops it the same way, within about half a minute. Up to 64 events can wait; after that the oldest is + dropped. Run long jobs in the background: nohup long-job >/dev/null 2>&1 & +

+ +

Hooks stored in a project

+

+ A project can carry its own hooks in .codeonthego/hooks/, with the same layout, + except ide-started: it has no project, so only yours runs. They run only if you + turn on Run hooks stored in projects and trust each script. +

+

+ Why: a hook runs with the same access as the Terminal, including your files and the network, and + a script can arrive with a project: a cloned repository, or an AI agent's edit. If such scripts + ran by themselves, they could run commands you never approved. +

+
    +
  • An untrusted script is skipped and listed in the Hooks tab. Review shows the whole + script, one numbered row per line, and a row marked ↳ continues the line above it; + Trust approves exactly what you read.
  • +
  • Editing a trusted script, or adding one, needs a new review.
  • +
  • Only plain scripts can be trusted: at most 64 KB of printable ASCII and newlines, with no + tabs, carriage returns or other control or non-ASCII characters, no line longer than 100 + characters or ending in a space, and a name of letters, digits, ., + _, - and / with no part starting with a dot (such + names are skipped altogether). Anything else is listed with the reason it + can't be reviewed, and never runs: such characters can make a script run differently from + how it reads, for example a backslash before an invisible carriage return that looks like a + line continuation while the next line runs as its own command. Your own hooks have no such + limits.
  • +
  • Reviewing is reading code. Plain text means you see every character, not that a + quick look tells you what runs: read the script as the shell will. Watch for three things: +
      +
    • A backslash at the end of a line of code usually joins the next line to it, and a + # starting that line may then not begin a comment. A backslash that ends + a comment, or is escaped by another backslash, joins nothing.
    • +
    • A here-document ends at a line matching its delimiter, which may not be the one you + expect: <<E"O"F ends at EOF, and the + lines after that run. If the delimiter is not quoted, a backslash ending a line of + the text joins the next line to it too, and in bash, which runs a script with no + #! line, lines such as EO\ and F can then + form the delimiter and end the here-document early.
    • +
    • Backticks, or $( in the text of a here-document whose delimiter is not + quoted, can run a command inside what looks like text.
    • +
    + A best-effort check, not a guarantee, marks ! beside its number every line that + contains <<, a backtick or $(, or ends in a backslash, and + lists them above the script by kind. It judges each line on its own, in comments and strings + too, so it marks many harmless lines, and it misses every other kind of trick, such as an + alias or IFS. A line without a mark can still do anything, so read every + line.
  • +
  • Trust covers only that script. Files it runs from the project, such as + ./gradlew, are not reviewed and can change later. Neither are settings that + tools read by themselves from the project: a hook in .git/config (such as + core.fsmonitor) runs a program when the script calls git status, + and Gradle and npm read the project's build files and scripts. Keep project hooks + self-contained, or review what they run.
  • +
  • Preferences lists the projects you trusted scripts in; Revoke forgets them.
  • +
  • A trusted script runs from a private copy of what you approved, so it cannot be swapped + after you approve it. Use $COGO_HOOK_SCRIPT to find the original.
  • +
+ +

Your own hooks are trusted

+

+ Scripts in ~/.config/codeonthego/hooks/ are yours, so they run without review once + hooks are on. Like anything you run in the Terminal, they can read and change your projects and + use the network. Reviewing project scripts does not protect you from a plugin that can run + commands: such a plugin can already change this folder. Install only plugins you trust. +

+ + + diff --git a/plugins/Shell-Hooks/src/main/assets/icon_day.png b/plugins/Shell-Hooks/src/main/assets/icon_day.png new file mode 100644 index 00000000..f9a4762f Binary files /dev/null and b/plugins/Shell-Hooks/src/main/assets/icon_day.png differ diff --git a/plugins/Shell-Hooks/src/main/assets/icon_night.png b/plugins/Shell-Hooks/src/main/assets/icon_night.png new file mode 100644 index 00000000..7c5544e6 Binary files /dev/null and b/plugins/Shell-Hooks/src/main/assets/icon_night.png differ diff --git a/plugins/Shell-Hooks/src/main/kotlin/org/appdevforall/shellhooks/ShellHooksHelp.kt b/plugins/Shell-Hooks/src/main/kotlin/org/appdevforall/shellhooks/ShellHooksHelp.kt new file mode 100644 index 00000000..db523922 --- /dev/null +++ b/plugins/Shell-Hooks/src/main/kotlin/org/appdevforall/shellhooks/ShellHooksHelp.kt @@ -0,0 +1,152 @@ +package org.appdevforall.shellhooks + +import com.itsaky.androidide.plugins.extensions.PluginTooltipButton +import com.itsaky.androidide.plugins.extensions.PluginTooltipEntry + +/** + * The plugin's in-IDE help. Every tag here is attached to a UI element; each entry's button opens + * the full guide, `assets/docs/index.html`. + */ +object ShellHooksHelp { + const val TAG_TAB = "shellhooks.tab" + const val TAG_SETTINGS = "shellhooks.settings" + const val TAG_FOLDER = "shellhooks.folder" + const val TAG_HOOKS = "shellhooks.hooks" + const val TAG_TIMEOUT = "shellhooks.timeout" + const val TAG_PROJECT_HOOKS = "shellhooks.project_hooks" + const val TAG_REVIEW = "shellhooks.review" + const val TAG_ACTION = "shellhooks.action" + const val TAG_BACK = "shellhooks.back" + + private val guide = listOf(PluginTooltipButton(description = "Shell Hooks guide", uri = "index.html", order = 0)) + + fun entries(): List = + listOf( + PluginTooltipEntry( + tag = TAG_TAB, + summary = "What your hook scripts did: each run's exit code and output.", + detail = + """ +

Lists the last 100 hook runs, newest first. Tap a run to see what the script printed.

+

Scripts stored in a project wait here for your review before they run.

+ """.trimIndent(), + buttons = guide, + ), + PluginTooltipEntry( + tag = TAG_SETTINGS, + summary = "Runs your shell scripts when the IDE opens a project, saves a file, or builds.", + detail = + """ +

Off until you turn it on. Put an executable script named after a hook, such as + file-saved, in your hooks folder. It gets the file or project in $1.

+

Hooks only report what happened: a script cannot stop a save or a build.

+ """.trimIndent(), + buttons = guide, + ), + PluginTooltipEntry( + tag = TAG_FOLDER, + summary = "Your hooks live in ~/.config/codeonthego/hooks.", + detail = + """ +

For each hook, the script <hook> runs first, then every script in + <hook>.d/ in name order. Only executable files run + (chmod +x); .sample files never do.

+

Scripts in actions/ appear as Run <name> on a file's menu.

+ """.trimIndent(), + buttons = guide, + ), + PluginTooltipEntry( + tag = TAG_HOOKS, + summary = "Turn single hooks off without deleting their scripts.", + detail = + """ +

Each switch is one hook; under it is what the script gets in $1. A hook that + is off runs none of its scripts, yours or a project's. The scripts stay where they are.

+

ide-started runs once in each launch of Code on the Go, the first time Shell + Hooks starts with hooks on. It has no project, so it runs only your scripts, in your home + folder.

+ """.trimIndent(), + buttons = guide, + ), + PluginTooltipEntry( + tag = TAG_TIMEOUT, + summary = "A script still running after this many seconds is stopped.", + detail = + """ +

Scripts run one at a time, so a slow one delays the next. With the Terminal's + timeout installed, the programs a script started are stopped with it. + Run long jobs in the background: nohup long-job >/dev/null 2>&1 &. + Without the redirect, the job keeps the script's output open and the script counts as + still running.

+ """.trimIndent(), + buttons = guide, + ), + PluginTooltipEntry( + tag = TAG_PROJECT_HOOKS, + summary = "Scripts stored in a project run only after you review and trust them.", + detail = + """ +

A project can carry hooks in .codeonthego/hooks/, for every hook but + ide-started, which has no project. A script can arrive with a + project, from a cloned repository or an AI agent's edit, so none runs until you read it in + the Hooks tab and trust it. Editing a trusted script makes it untrusted again.

+

Only plain scripts can be trusted: at most 64 KB of printable ASCII and newlines, no tabs, + no line over 100 characters or ending in a space, and a name with no part starting with a + dot. Anything else never runs.

+

Trust covers the script's own text, not project files or settings it uses, such as + .git/config or Gradle and npm files.

+

This does not protect you from a plugin that can run commands: such a plugin can already + change your own hooks folder. Install only plugins you trust.

+ """.trimIndent(), + buttons = guide, + ), + PluginTooltipEntry( + tag = TAG_REVIEW, + summary = "Read the script before you trust it: it runs with the Terminal's access.", + detail = + """ +

Trust approves exactly the text shown, one numbered row per line; a row marked + ↳ continues the line above it. If the file changes afterwards it waits for review + again.

+

Only a plain script can be reviewed: at most 64 KB of printable ASCII and newlines, with + no tabs, carriage returns or other characters, no line over 100 characters or ending in a + space, and a name with no part starting with a dot. Those could make a script run + differently from how it reads, so a script that has them never runs. It is listed with + the reason, except a name starting with a dot, which is skipped and not listed.

+

You see every character, but reviewing is reading code: read it as the shell will. A + backslash ending a line of code usually joins the next line to it, and a + # starting that line may then be no comment (a backslash that ends a + comment, or is escaped by another backslash, joins nothing); a here-document ends at a + line matching its delimiter, which may not be the one you expect, and in the text of an + unquoted here-document a backslash ending a line joins the next one too, so in bash, + which runs a script with no #! line, two lines can end it early; + backticks, or $( in the text of an unquoted here-document, can run + commands.

+

A best-effort check, not a guarantee, marks ! every line that contains + <<, a backtick or $(, or ends in a backslash, and lists + them above the script by kind. It judges each line on its own, in comments and strings + too, so it marks many harmless lines, and it misses every other kind of trick: a line + without a mark can still do anything. Read every line.

+

Trust covers only this script: not files it runs from the project, nor settings tools + read by themselves, such as hooks in .git/config or Gradle and npm files.

+ """.trimIndent(), + buttons = guide, + ), + PluginTooltipEntry( + tag = TAG_ACTION, + summary = "Runs this script from your actions folder on the file, in the Terminal.", + detail = + """ +

Every executable script in ~/.config/codeonthego/hooks/actions/ appears here, + for files only. It runs in the Terminal so you see what it prints, with the file in + $1. If it cannot start, the Hooks tab says why.

+ """.trimIndent(), + buttons = guide, + ), + PluginTooltipEntry( + tag = TAG_BACK, + summary = "Back to Preferences. Your changes are already saved.", + buttons = guide, + ), + ) +} diff --git a/plugins/Shell-Hooks/src/main/kotlin/org/appdevforall/shellhooks/ShellHooksPlugin.kt b/plugins/Shell-Hooks/src/main/kotlin/org/appdevforall/shellhooks/ShellHooksPlugin.kt new file mode 100644 index 00000000..5c22e59a --- /dev/null +++ b/plugins/Shell-Hooks/src/main/kotlin/org/appdevforall/shellhooks/ShellHooksPlugin.kt @@ -0,0 +1,349 @@ +package org.appdevforall.shellhooks + +import com.itsaky.androidide.plugins.IPlugin +import com.itsaky.androidide.plugins.PluginContext +import com.itsaky.androidide.plugins.extensions.DocumentationExtension +import com.itsaky.androidide.plugins.extensions.FileOpenExtension +import com.itsaky.androidide.plugins.extensions.FileTabMenuItem +import com.itsaky.androidide.plugins.extensions.PluginSettingsEntry +import com.itsaky.androidide.plugins.extensions.PluginTooltipEntry +import com.itsaky.androidide.plugins.extensions.SettingsExtension +import com.itsaky.androidide.plugins.extensions.TabItem +import com.itsaky.androidide.plugins.extensions.UIExtension +import com.itsaky.androidide.plugins.services.BuildStatusListener +import com.itsaky.androidide.plugins.services.FileChangeListener +import com.itsaky.androidide.plugins.services.IdeBuildService +import com.itsaky.androidide.plugins.services.IdeCommandService +import com.itsaky.androidide.plugins.services.IdeEditorService +import com.itsaky.androidide.plugins.services.IdeProjectService +import com.itsaky.androidide.plugins.services.IdeTerminalService +import com.itsaky.androidide.plugins.services.TerminalCommandResult +import kotlinx.coroutines.CancellationException +import kotlinx.coroutines.CoroutineScope +import kotlinx.coroutines.Dispatchers +import kotlinx.coroutines.SupervisorJob +import kotlinx.coroutines.cancel +import kotlinx.coroutines.launch +import org.appdevforall.shellhooks.engine.Coalescer +import org.appdevforall.shellhooks.engine.Hook +import org.appdevforall.shellhooks.engine.HookDiscovery +import org.appdevforall.shellhooks.engine.HookEvent +import org.appdevforall.shellhooks.engine.HookInvocation +import org.appdevforall.shellhooks.engine.HookLog +import org.appdevforall.shellhooks.engine.HookPaths +import org.appdevforall.shellhooks.engine.HookRun +import org.appdevforall.shellhooks.engine.HookRunner +import org.appdevforall.shellhooks.engine.HookRunners +import org.appdevforall.shellhooks.engine.IdeCommandRunner +import org.appdevforall.shellhooks.engine.IdeStartedTrigger +import org.appdevforall.shellhooks.engine.LaunchGate +import org.appdevforall.shellhooks.engine.Outcome +import org.appdevforall.shellhooks.engine.SampleHooks +import org.appdevforall.shellhooks.engine.ScriptSource +import org.appdevforall.shellhooks.engine.ShellQuote +import org.appdevforall.shellhooks.engine.TrustStore +import org.appdevforall.shellhooks.engine.VerifiedCopies +import org.appdevforall.shellhooks.ui.HooksPanelFragment +import org.appdevforall.shellhooks.ui.ShellHooksSettingsFragment +import java.io.File +import java.io.IOException + +/** + * Runs the user's shell scripts at the IDE's integration points. The plugin only listens and + * queues; [HookRunner] finds the scripts for each event and runs them one at a time through the + * IDE's command service. Nothing runs until the user turns hooks on in Preferences. + */ +class ShellHooksPlugin : + IPlugin, + UIExtension, + FileOpenExtension, + SettingsExtension, + DocumentationExtension { + private lateinit var context: PluginContext + lateinit var paths: HookPaths + private set + lateinit var settings: ShellHooksSettings + private set + lateinit var trust: TrustStore + private set + private lateinit var launchGate: LaunchGate + val log = HookLog() + + private var scope: CoroutineScope? = null + private var runner: HookRunner? = null + private var coalescer: Coalescer? = null + + @Volatile + private var wrapper: File? = null + + // Created inside a guarded block, never at construction: see WorkspaceHooks. + private var workspaceHooks: WorkspaceHooks? = null + + private val fileChangeListener = + FileChangeListener { file -> + if (isOn()) coalescer?.offer(HookEvent.fileActivated(file, currentProjectDir())) + } + + private val buildListener = + object : BuildStatusListener { + override fun onBuildStarted() = submit(HookEvent.buildStarted(currentProjectDir())) + + override fun onBuildFinished() = submit(HookEvent.buildSucceeded(currentProjectDir())) + + override fun onBuildFailed(error: String?) = submit(HookEvent.buildFailed(error, currentProjectDir())) + } + + override fun initialize(context: PluginContext): Boolean = + try { + this.context = context + paths = HookPaths(context.getAppFilesDir()) + settings = ShellHooksSettings(context.getPluginSharedPreferences(ShellHooksSettings.PREFS)) + trust = TrustStore(PrefsKeyValueStore(context.getPluginSharedPreferences(ShellHooksSettings.TRUST_PREFS))) + launchGate = LaunchGate(PrefsKeyValueStore(context.getPluginSharedPreferences(ShellHooksSettings.PREFS))) + instance = this + true + } catch (t: Throwable) { + context.logger.error("Shell Hooks failed to initialize", t) + false + } + + override fun activate(): Boolean { + val scope = CoroutineScope(SupervisorJob() + Dispatchers.IO).also { scope = it } + wrapper = installWrapper() + val warn: (String) -> Unit = { context.logger.warn(it) } + val verifiedDir = File(context.getPluginDataDir(), VERIFIED_DIR) + // Before the runner exists, so no copy is staged while this deletes. + runCatching { VerifiedCopies.prune(verifiedDir, trust.trustedShas()) } + .onFailure { context.logger.warn("Shell Hooks: cannot prune old trusted copies", it) } + runner = + HookRunners.create( + scope = scope, + paths = paths, + switches = settings, + trust = trust, + log = log, + verifiedDir = verifiedDir, + commands = IdeCommandRunner { service(IdeCommandService::class.java) }, + wrapper = { wrapper }, + timeoutMs = { settings.timeoutSeconds * 1000L }, + ideVersion = ideVersion(), + warn = warn, + ) + coalescer = Coalescer(scope, FILE_ACTIVATED_DEBOUNCE_MS) { submit(it) } + + // Each in its own try: a host without one listener, or a refused permission, must not + // cost the others. + listen("project") { service(IdeProjectService::class.java)?.let { workspace().addTo(it) } } + listen("file change") { service(IdeEditorService::class.java)?.addFileChangeListener(fileChangeListener) } + listen("file save") { service(IdeEditorService::class.java)?.let { workspace().addTo(it) } } + listen("build") { service(IdeBuildService::class.java)?.addBuildStatusListener(buildListener) } + + // activate() also runs when the user re-enables or updates the plugin mid-session. + IdeStartedTrigger(launchGate, { isOn() && settings.isHookEnabled(Hook.IDE_STARTED) }) { + submit(HookEvent.ideStarted()) + }.onActivate(launchId()) + return true + } + + override fun deactivate(): Boolean { + val workspace = workspaceHooks + if (workspace != null) { + listen("project") { service(IdeProjectService::class.java)?.let { workspace.removeFrom(it) } } + listen("file save") { service(IdeEditorService::class.java)?.let { workspace.removeFrom(it) } } + } + workspaceHooks = null + listen("file change") { service(IdeEditorService::class.java)?.removeFileChangeListener(fileChangeListener) } + listen("build") { service(IdeBuildService::class.java)?.removeBuildStatusListener(buildListener) } + coalescer?.cancel() + coalescer = null + runner?.close() + runner = null + scope?.cancel() + scope = null + return true + } + + override fun dispose() { + if (instance === this) instance = null + } + + // FileOpenExtension + + override fun onFileOpened(file: File) = submit(HookEvent.fileOpened(file, currentProjectDir())) + + override fun onFileClosed(file: File) = submit(HookEvent.fileClosed(file, currentProjectDir())) + + /** + * One "Run " per script in the actions folder, for a file only: the host also asks for + * folders, from the file tree's long-press menu. + */ + override fun getFileTabMenuItems(file: File): List { + if (!isOn()) return emptyList() + return HookDiscovery.actionsFor(file, paths.actions).mapIndexed { index, action -> + FileTabMenuItem( + id = "action:${action.name}", + title = "Run ${action.name}", + order = ACTION_MENU_ORDER + index, + tooltipTag = ShellHooksHelp.TAG_ACTION, + action = { runAction(action, file) }, + ) + } + } + + // UIExtension + + override fun getEditorTabs(): List = + listOf( + TabItem( + id = TAB_ID, + title = "Hooks", + fragmentFactory = { HooksPanelFragment() }, + order = 210, + tooltipTag = ShellHooksHelp.TAG_TAB, + ), + ) + + // SettingsExtension + + override fun getSettingsEntries(): List = + listOf( + PluginSettingsEntry( + id = "shell_hooks", + title = "Shell Hooks", + summary = "Run your scripts when a project opens, a file is saved, or a build ends", + fragmentClassName = ShellHooksSettingsFragment::class.java.name, + ), + ) + + // DocumentationExtension + + override fun getTooltipCategory(): String = TOOLTIP_CATEGORY + + override fun getTooltipEntries(): List = ShellHooksHelp.entries() + + override fun getTier3DocsAssetPath(): String = "docs" + + /** Writes the sample hooks; returns how many files, or throws when the folder is not writable. */ + @Throws(IOException::class) + fun writeSamples(): Int = SampleHooks.write(paths) + + fun isOn(): Boolean = ::settings.isInitialized && settings.enabled + + fun service(type: Class): T? = runCatching { context.services.get(type) }.getOrNull() + + fun logger() = context.logger + + private fun submit(event: HookEvent) { + if (!isOn() || !settings.isHookEnabled(event.hook)) return + runner?.submit(event) + } + + private fun currentProjectDir(): File? = + runCatching { service(IdeProjectService::class.java)?.getCurrentProject()?.rootDir }.getOrNull() + + private fun workspace(): WorkspaceHooks = + workspaceHooks ?: WorkspaceHooks(::submit, ::currentProjectDir).also { workspaceHooks = it } + + // Same for every activation within one IDE process, different after a restart. + private fun launchId(): String = "${android.os.Process.myPid()}:${android.os.Process.getStartElapsedRealtime()}" + + /** + * Runs [action] on [file] in the visible Terminal, so the user sees what it prints. If it + * cannot start, the Hooks tab says so. + */ + private fun runAction( + action: File, + file: File, + ) { + val scope = scope ?: return + val started = System.currentTimeMillis() + val failed = { reason: String -> + context.logger.warn("Shell Hooks: action ${action.name} did not start: $reason") + log.record( + HookRun( + startedAtMillis = started, + hook = null, + script = action, + source = ScriptSource.GLOBAL, + target = file.path, + outcome = Outcome.NOT_STARTED, + exitCode = null, + durationMillis = System.currentTimeMillis() - started, + output = reason, + ), + ) + } + val runnerScript = wrapper ?: return failed("The hook runner script is missing") + val terminal = + try { + service(IdeTerminalService::class.java) + } catch (e: LinkageError) { + // The class itself is missing: plugins got a Terminal service in Code on the Go 26.42. + return failed("This IDE has no Terminal service for plugins; Code on the Go 26.42 or later is needed") + } ?: return failed("The IDE's Terminal is not available") + // The Terminal takes a command line, so every value is quoted as one word. + val command = + ShellQuote.command( + HookInvocation.actionEnvironment(action, paths.actions, currentProjectDir(), ideVersion()), + listOf("sh", runnerScript.path, action.path, file.path), + ) + scope.launch { + try { + val result = terminal.runInTerminal(command) + if (result is TerminalCommandResult.NotStarted) failed(result.reason) + } catch (e: CancellationException) { + throw e + } catch (e: Exception) { + failed(e.message ?: e.javaClass.simpleName) + } + } + } + + // The runner script ships as an asset and is copied out on every activation, so an update to + // the plugin replaces it. + private fun installWrapper(): File? = + try { + val target = File(context.getPluginDataDir(), WRAPPER_NAME) + val stream = context.resources.openPluginAsset(WRAPPER_NAME) ?: throw IOException("asset missing") + stream.use { input -> target.outputStream().use { input.copyTo(it) } } + target + } catch (e: Exception) { + context.logger.error("Shell Hooks: cannot install $WRAPPER_NAME; no hook will run", e) + null + } + + private fun ideVersion(): String? = + runCatching { + val app = context.androidContext.applicationContext + app.packageManager.getPackageInfo(app.packageName, 0).versionName + }.getOrNull() + + private inline fun listen( + what: String, + block: () -> Unit, + ) { + try { + block() + } catch (e: Exception) { + context.logger.warn("Shell Hooks: no $what events: ${e.message}") + } catch (e: LinkageError) { + // A host older than 26.47 has no such method; that hook simply never fires. + context.logger.warn("Shell Hooks: this IDE has no $what events") + } + } + + companion object { + const val PLUGIN_ID = "org.appdevforall.shellhooks" + const val TOOLTIP_CATEGORY = "plugin_$PLUGIN_ID" + const val TAB_ID = "shell_hooks_tab" + const val WRAPPER_NAME = "cogo-hook-run.sh" + private const val VERIFIED_DIR = "verified" + private const val FILE_ACTIVATED_DEBOUNCE_MS = 500L + private const val ACTION_MENU_ORDER = 500 + + @Volatile + private var instance: ShellHooksPlugin? = null + + fun getInstance(): ShellHooksPlugin? = instance + } +} diff --git a/plugins/Shell-Hooks/src/main/kotlin/org/appdevforall/shellhooks/ShellHooksSettings.kt b/plugins/Shell-Hooks/src/main/kotlin/org/appdevforall/shellhooks/ShellHooksSettings.kt new file mode 100644 index 00000000..05a8ba63 --- /dev/null +++ b/plugins/Shell-Hooks/src/main/kotlin/org/appdevforall/shellhooks/ShellHooksSettings.kt @@ -0,0 +1,66 @@ +package org.appdevforall.shellhooks + +import android.content.SharedPreferences +import org.appdevforall.shellhooks.engine.Hook +import org.appdevforall.shellhooks.engine.HookSwitches +import org.appdevforall.shellhooks.engine.KeyValueStore +import org.appdevforall.shellhooks.engine.TimeoutSetting + +/** What the user chose on the settings screen. Everything starts off: hooks run only once enabled. */ +class ShellHooksSettings( + private val prefs: SharedPreferences, +) : HookSwitches { + override var enabled: Boolean + get() = prefs.getBoolean(KEY_ENABLED, false) + set(value) = prefs.edit().putBoolean(KEY_ENABLED, value).apply() + + override var projectHooksEnabled: Boolean + get() = prefs.getBoolean(KEY_PROJECT_HOOKS, false) + set(value) = prefs.edit().putBoolean(KEY_PROJECT_HOOKS, value).apply() + + override fun isHookEnabled(hook: Hook): Boolean = prefs.getBoolean(hookKey(hook), true) + + fun setHookEnabled( + hook: Hook, + enabled: Boolean, + ) = prefs.edit().putBoolean(hookKey(hook), enabled).apply() + + /** Set only from [TimeoutSetting.parse]; a value out of range is refused, not clamped. */ + var timeoutSeconds: Int + get() = prefs.getInt(KEY_TIMEOUT, DEFAULT_TIMEOUT_SECONDS).coerceIn(MIN_TIMEOUT_SECONDS, MAX_TIMEOUT_SECONDS) + set(value) { + require(value in MIN_TIMEOUT_SECONDS..MAX_TIMEOUT_SECONDS) { "Timeout out of range: $value" } + prefs.edit().putInt(KEY_TIMEOUT, value).apply() + } + + private fun hookKey(hook: Hook) = "hook.${hook.id}" + + companion object { + const val PREFS = "settings" + const val TRUST_PREFS = "trust" + const val DEFAULT_TIMEOUT_SECONDS = TimeoutSetting.DEFAULT_SECONDS + const val MIN_TIMEOUT_SECONDS = TimeoutSetting.MIN_SECONDS + const val MAX_TIMEOUT_SECONDS = TimeoutSetting.MAX_SECONDS + + private const val KEY_ENABLED = "enabled" + private const val KEY_PROJECT_HOOKS = "project_hooks" + private const val KEY_TIMEOUT = "timeout_seconds" + } +} + +/** [KeyValueStore] over SharedPreferences, for the trust store. */ +class PrefsKeyValueStore( + private val prefs: SharedPreferences, +) : KeyValueStore { + override fun getString(key: String): String? = prefs.getString(key, null) + + // commit, not apply: a trust decision must be on disk before the script it covers can run. + override fun putString( + key: String, + value: String?, + ) { + prefs.edit().apply { if (value == null) remove(key) else putString(key, value) }.commit() + } + + override fun keys(): Set = prefs.all.keys +} diff --git a/plugins/Shell-Hooks/src/main/kotlin/org/appdevforall/shellhooks/WorkspaceHooks.kt b/plugins/Shell-Hooks/src/main/kotlin/org/appdevforall/shellhooks/WorkspaceHooks.kt new file mode 100644 index 00000000..3ee8f548 --- /dev/null +++ b/plugins/Shell-Hooks/src/main/kotlin/org/appdevforall/shellhooks/WorkspaceHooks.kt @@ -0,0 +1,36 @@ +package org.appdevforall.shellhooks + +import com.itsaky.androidide.plugins.services.FileSaveListener +import com.itsaky.androidide.plugins.services.IdeEditorService +import com.itsaky.androidide.plugins.services.IdeProjectService +import com.itsaky.androidide.plugins.services.ProjectLifecycleListener +import org.appdevforall.shellhooks.engine.HookEvent +import java.io.File + +/** + * The listeners for the IDE events added in 26.47: project opened and closed, and file saved. + * They live in their own class so that [ShellHooksPlugin] never names those types itself. On an + * older IDE only this class fails to load, inside the plugin's guarded `listen` blocks, and the + * plugin runs with the other hooks instead of failing to load. + */ +internal class WorkspaceHooks( + private val submit: (HookEvent) -> Unit, + private val currentProjectDir: () -> File?, +) { + private val projectListener = + object : ProjectLifecycleListener { + override fun onProjectOpened(projectDir: File) = submit(HookEvent.projectOpened(projectDir)) + + override fun onProjectClosed(projectDir: File) = submit(HookEvent.projectClosed(projectDir)) + } + + private val saveListener = FileSaveListener { file -> submit(HookEvent.fileSaved(file, currentProjectDir())) } + + fun addTo(service: IdeProjectService) = service.addProjectLifecycleListener(projectListener) + + fun removeFrom(service: IdeProjectService) = service.removeProjectLifecycleListener(projectListener) + + fun addTo(service: IdeEditorService) = service.addFileSaveListener(saveListener) + + fun removeFrom(service: IdeEditorService) = service.removeFileSaveListener(saveListener) +} diff --git a/plugins/Shell-Hooks/src/main/kotlin/org/appdevforall/shellhooks/engine/Hook.kt b/plugins/Shell-Hooks/src/main/kotlin/org/appdevforall/shellhooks/engine/Hook.kt new file mode 100644 index 00000000..202d8640 --- /dev/null +++ b/plugins/Shell-Hooks/src/main/kotlin/org/appdevforall/shellhooks/engine/Hook.kt @@ -0,0 +1,77 @@ +package org.appdevforall.shellhooks.engine + +import java.io.File + +/** + * The moments a script can hook. [id] is the script's file name in a hooks folder, so it never + * changes once shipped. [argsDoc] says what arrives in `$*`, for the samples and the settings + * screen. + */ +enum class Hook( + val id: String, + val title: String, + val argsDoc: String, +) { + IDE_STARTED("ide-started", "IDE started", "no arguments; runs once per launch of Code on the Go, the first time hooks are on"), + PROJECT_OPENED("project-opened", "Project opened", "\$1 = the project folder"), + PROJECT_CLOSED("project-closed", "Project closed", "\$1 = the project folder"), + FILE_OPENED("file-opened", "File opened", "\$1 = the file"), + FILE_CLOSED("file-closed", "File closed", "\$1 = the file"), + FILE_ACTIVATED("file-activated", "Switched to a file", "\$1 = the file, or empty when no file is open"), + FILE_SAVED("file-saved", "File saved", "\$1 = the file"), + BUILD_STARTED("build-started", "Build started", "no arguments; a project sync is a build too"), + BUILD_SUCCEEDED("build-succeeded", "Build succeeded", "no arguments; a project sync is a build too"), + BUILD_FAILED("build-failed", "Build failed", "\$1 = the IDE's message, such as BUILD FAILED in 12s, also when you cancel; a project sync is a build too"), + ; + + companion object { + fun fromId(id: String): Hook? = entries.firstOrNull { it.id == id } + } +} + +/** + * One moment to report: which [hook], the positional arguments its scripts get, and the + * project it concerns ([projectDir]): the event's own for project-opened and project-closed, + * otherwise the IDE's current project, which can be the last one opened even after it closed. + * Null for ide-started, or when the IDE has no current project. + */ +data class HookEvent( + val hook: Hook, + val args: List, + val projectDir: File?, +) { + /** A short label for the run log: the file or project the event is about, if any. */ + val target: String? get() = args.firstOrNull()?.takeIf { it.isNotEmpty() } + + companion object { + // The IDE always passes its own message, cancels included; this only covers a host that + // passes none, and is not part of the documented contract. + const val BUILD_CANCELLED = "cancelled" + + // No project: the event is the IDE starting, and at launch the IDE's current project is + // the last one opened, which need not be open. + fun ideStarted() = HookEvent(Hook.IDE_STARTED, emptyList(), null) + + fun projectOpened(projectDir: File) = HookEvent(Hook.PROJECT_OPENED, listOf(projectDir.path), projectDir) + + fun projectClosed(projectDir: File) = HookEvent(Hook.PROJECT_CLOSED, listOf(projectDir.path), projectDir) + + fun fileOpened(file: File, projectDir: File?) = HookEvent(Hook.FILE_OPENED, listOf(file.path), projectDir) + + fun fileClosed(file: File, projectDir: File?) = HookEvent(Hook.FILE_CLOSED, listOf(file.path), projectDir) + + // Always one argument, so a script can test "$1" without checking $# first. + fun fileActivated(file: File?, projectDir: File?) = + HookEvent(Hook.FILE_ACTIVATED, listOf(file?.path ?: ""), projectDir) + + fun fileSaved(file: File, projectDir: File?) = HookEvent(Hook.FILE_SAVED, listOf(file.path), projectDir) + + fun buildStarted(projectDir: File?) = HookEvent(Hook.BUILD_STARTED, emptyList(), projectDir) + + fun buildSucceeded(projectDir: File?) = HookEvent(Hook.BUILD_SUCCEEDED, emptyList(), projectDir) + + // The IDE's message ends in a newline, which a script would otherwise get in $1. + fun buildFailed(error: String?, projectDir: File?) = + HookEvent(Hook.BUILD_FAILED, listOf(error?.trimEnd() ?: BUILD_CANCELLED), projectDir) + } +} diff --git a/plugins/Shell-Hooks/src/main/kotlin/org/appdevforall/shellhooks/engine/HookLog.kt b/plugins/Shell-Hooks/src/main/kotlin/org/appdevforall/shellhooks/engine/HookLog.kt new file mode 100644 index 00000000..996cc678 --- /dev/null +++ b/plugins/Shell-Hooks/src/main/kotlin/org/appdevforall/shellhooks/engine/HookLog.kt @@ -0,0 +1,156 @@ +package org.appdevforall.shellhooks.engine + +import kotlinx.coroutines.flow.MutableStateFlow +import kotlinx.coroutines.flow.StateFlow +import kotlinx.coroutines.flow.asStateFlow +import kotlinx.coroutines.flow.update +import java.io.File +import java.util.concurrent.atomic.AtomicLong + +enum class ScriptSource( + val id: String, +) { + GLOBAL("global"), + PROJECT("project"), +} + +enum class Outcome { + SUCCEEDED, + FAILED, + TIMED_OUT, + CANCELLED, + + /** The command never started: no command service, a refused start, or a missing wrapper. */ + NOT_STARTED, +} + +/** + * One script's run, as the Hooks tab shows it. [hook] is null for an action the user ran from a + * file's menu. [output] is stdout then stderr, tail-capped. [id] is unique within the process. + */ +data class HookRun( + val startedAtMillis: Long, + val hook: Hook?, + val script: File, + val source: ScriptSource, + val target: String?, + val outcome: Outcome, + val exitCode: Int?, + val durationMillis: Long, + val output: String, + val id: Long = nextRunId.incrementAndGet(), +) { + /** The hook's id, or `action` for an action. */ + val name: String get() = hook?.id ?: ACTION + + /** + * What the run was about, for its one-line title: the file or project name, or for + * build-failed the first line of the IDE's message, which is text rather than a path. + */ + val targetLabel: String? + get() { + val value = target?.takeIf { it.isNotEmpty() } ?: return null + if (hook == Hook.BUILD_FAILED) { + val line = value.lineSequence().first().trim() + return if (line.length <= MAX_TITLE_CHARS) line else line.take(MAX_TITLE_CHARS - 3) + "..." + } + return File(value).name.ifEmpty { value } + } + + companion object { + const val ACTION = "action" + const val MAX_TITLE_CHARS = 80 + private val nextRunId = AtomicLong() + } +} + +/** + * A project hook that was skipped because the user has not trusted this content of it, or because + * it cannot be reviewed ([notReviewable] says why), which never runs. + */ +data class PendingTrust( + val projectDir: File, + val relativePath: String, + val file: File, + val sha256: String, + val notReviewable: String? = null, +) + +/** The recent runs and the project hooks awaiting review, observed by the Hooks tab. */ +class HookLog( + private val capacity: Int = DEFAULT_CAPACITY, +) { + private val _runs = MutableStateFlow>(emptyList()) + private val _pending = MutableStateFlow>(emptyList()) + + /** Newest first. */ + val runs: StateFlow> = _runs.asStateFlow() + val pending: StateFlow> = _pending.asStateFlow() + + fun record(run: HookRun) { + _runs.update { (listOf(run) + it).take(capacity) } + } + + /** Lists [entry] for review once; a later sighting of the same script replaces it. */ + fun addPending(entry: PendingTrust) { + _pending.update { list -> list.filterNot { it.sameScript(entry) } + entry } + } + + fun removePending( + projectDir: File, + relativePath: String, + ) { + _pending.update { list -> list.filterNot { it.projectDir == projectDir && it.relativePath == relativePath } } + } + + fun clearRuns() { + _runs.value = emptyList() + } + + private fun PendingTrust.sameScript(other: PendingTrust) = + projectDir == other.projectDir && relativePath == other.relativePath + + companion object { + const val DEFAULT_CAPACITY = 100 + + /** The most of one run's output kept: the end, where errors are. */ + const val MAX_OUTPUT_CHARS = 64 * 1024 + + fun combineOutput( + stdout: String, + stderr: String, + ): String { + val combined = + when { + stderr.isBlank() -> stdout + stdout.isBlank() -> stderr + else -> stdout.trimEnd() + "\n" + stderr + } + return capTail(combined, MAX_OUTPUT_CHARS) + } + + fun capTail( + text: String, + max: Int, + ): String = if (text.length <= max) text else "[...]\n" + text.takeLast(max) + } +} + +/** + * The end of a command's output as its lines arrive, for a run that is stopped before the host + * reports what it printed. Keeps at most [max] characters, from the end. + */ +class OutputTail( + private val max: Int = HookLog.MAX_OUTPUT_CHARS, +) { + private val buffer = StringBuilder() + + fun append(line: String) { + synchronized(buffer) { + buffer.append(line).append('\n') + if (buffer.length > 2 * max) buffer.delete(0, buffer.length - max) + } + } + + fun text(): String = synchronized(buffer) { HookLog.capTail(buffer.toString(), max) } +} diff --git a/plugins/Shell-Hooks/src/main/kotlin/org/appdevforall/shellhooks/engine/HookPaths.kt b/plugins/Shell-Hooks/src/main/kotlin/org/appdevforall/shellhooks/engine/HookPaths.kt new file mode 100644 index 00000000..99591a10 --- /dev/null +++ b/plugins/Shell-Hooks/src/main/kotlin/org/appdevforall/shellhooks/engine/HookPaths.kt @@ -0,0 +1,90 @@ +package org.appdevforall.shellhooks.engine + +import java.io.File + +/** + * Where hooks live. [appFilesDir] is the IDE's files directory, the root its command service + * gives every process: `HOME` is `/home` and `PREFIX` is `/usr`, the + * same folders the Terminal uses, so `~/.config/codeonthego/hooks` here is the one a user edits + * there. + */ +class HookPaths( + appFilesDir: File, +) { + val home = File(appFilesDir, "home") + val prefix = File(appFilesDir, "usr") + + /** The user's own hooks: `~/.config/codeonthego/hooks`. */ + val globalHooks = File(home, ".config/codeonthego/hooks") + + /** Scripts offered as "Run " on a file's menu. */ + val actions = File(globalHooks, ACTIONS_DIR) + + /** + * Whether the Terminal has `timeout`, which the wrapper then runs each script under: the same + * test the wrapper makes, so only then is its exit 124 or 137 the wrapper's own timeout. + */ + fun hasTimeout(): Boolean = File(prefix, "bin/timeout").let { it.isFile && it.canExecute() } + + companion object { + const val ACTIONS_DIR = "actions" + const val PROJECT_HOOKS = ".codeonthego/hooks" + + /** A project's own hooks, which run only once trusted. */ + fun projectHooks(projectDir: File) = File(projectDir, PROJECT_HOOKS) + } +} + +/** Finds the scripts a hook runs, git-hooks style. */ +object HookDiscovery { + const val SAMPLE_SUFFIX = ".sample" + + /** + * The scripts in [root] for [hookId]: the file ``, then every script in + * `.d/` in byte order of their names (as `LC_ALL=C ls` sorts them). + * + * [requireExecutable] is false for a project's hooks: projects usually live on shared storage, + * which is mounted noexec and keeps no executable bits, and a trusted project script runs from + * a private copy the plugin marks executable itself. + */ + fun discover( + root: File, + hookId: String, + requireExecutable: Boolean = true, + ): List { + val scripts = mutableListOf() + File(root, hookId).takeIf { isRunnable(it, requireExecutable) }?.let(scripts::add) + File(root, "$hookId.d").listFiles() + ?.filter { isRunnable(it, requireExecutable) } + ?.sortedBy { it.name } + ?.let(scripts::addAll) + return scripts + } + + /** The actions offered on a file's menu, sorted by name. */ + fun actions(actionsDir: File): List = + actionsDir.listFiles()?.filter { isRunnable(it) }?.sortedBy { it.name }.orEmpty() + + /** + * The actions to offer for [target]: none for a folder, which the file tree's long-press menu + * also asks about, since an action's `$1` is a file. + */ + fun actionsFor( + target: File, + actionsDir: File, + ): List = if (target.isFile) actions(actionsDir) else emptyList() + + /** + * A regular file, with its executable bit set when [requireExecutable]. Samples, dotfiles + * (editor swap files) and `name~` backups are skipped, so editing a hook in place never runs a + * half-written copy. + */ + fun isRunnable( + file: File, + requireExecutable: Boolean = true, + ): Boolean { + val name = file.name + if (name.startsWith(".") || name.endsWith("~") || name.endsWith(SAMPLE_SUFFIX)) return false + return file.isFile && (!requireExecutable || file.canExecute()) + } +} diff --git a/plugins/Shell-Hooks/src/main/kotlin/org/appdevforall/shellhooks/engine/HookResolver.kt b/plugins/Shell-Hooks/src/main/kotlin/org/appdevforall/shellhooks/engine/HookResolver.kt new file mode 100644 index 00000000..32a5bede --- /dev/null +++ b/plugins/Shell-Hooks/src/main/kotlin/org/appdevforall/shellhooks/engine/HookResolver.kt @@ -0,0 +1,135 @@ +package org.appdevforall.shellhooks.engine + +import java.io.File +import java.io.IOException + +/** + * A script ready to run. [executable] is what runs; for a project hook it is a private copy of + * the bytes the user trusted, so the file cannot change between the check and the run. + * [original] is the script the user sees and edits. + */ +data class ResolvedScript( + val executable: File, + val original: File, + val source: ScriptSource, + val hooksDir: File, +) + +/** Turns an event into the scripts to run for it. */ +fun interface ScriptResolver { + fun resolve(event: HookEvent): List +} + +/** What the user turned on; read on every event, so a change applies to the next one. */ +interface HookSwitches { + val enabled: Boolean + val projectHooksEnabled: Boolean + + fun isHookEnabled(hook: Hook): Boolean +} + +/** + * Finds the user's global scripts for an event, then the project's own, which run only when + * project hooks are on, they can be reviewed ([ScriptReview]), and the user trusted their exact + * content. Any other project script is skipped and listed in [log], for review or with the reason + * it cannot be reviewed. + */ +class HookResolver( + private val paths: HookPaths, + private val switches: HookSwitches, + private val trust: TrustStore, + private val log: HookLog, + private val verifiedDir: File, + private val warn: (String) -> Unit = {}, +) : ScriptResolver { + override fun resolve(event: HookEvent): List { + if (!switches.enabled || !switches.isHookEnabled(event.hook)) return emptyList() + val global = + HookDiscovery.discover(paths.globalHooks, event.hook.id).map { + ResolvedScript(it, it, ScriptSource.GLOBAL, paths.globalHooks) + } + val projectDir = event.projectDir + if (!switches.projectHooksEnabled || projectDir == null) return global + val root = HookPaths.projectHooks(projectDir) + val project = + HookDiscovery.discover(root, event.hook.id, requireExecutable = false) + .mapNotNull { verify(projectDir, root, it) } + return global + project + } + + // Runs a project script only if its bytes now can be reviewed AND are trusted: an approval of + // bytes that cannot be reviewed (say, from an older version of this plugin) never runs. + private fun verify( + projectDir: File, + root: File, + script: File, + ): ResolvedScript? { + val relativePath = script.relativeTo(root).path + // Listed under the canonical folder, which trust is keyed on too: the IDE reports + // project-opened and project-closed with that, and other events with the path as stored, so + // one project can arrive under two names. + val listedDir = File(TrustStore.canonical(projectDir)) + val (bytes, sha) = + when (val assessed = ScriptReview.assess(script, relativePath)) { + is ScriptReview.Assessment.Unreadable -> { + warn("Shell Hooks: cannot read a project script: ${assessed.cause}") + return null + } + is ScriptReview.Assessment.NotReviewable -> { + log.addPending(PendingTrust(listedDir, relativePath, script, sha256 = "", notReviewable = assessed.reason.message)) + return null + } + is ScriptReview.Assessment.Reviewable -> assessed.bytes to assessed.sha256 + } + if (!trust.isTrusted(projectDir, relativePath, sha)) { + log.addPending(PendingTrust(listedDir, relativePath, script, sha)) + return null + } + log.removePending(listedDir, relativePath) + val copy = verifiedCopy(bytes, sha) ?: return null + return ResolvedScript(copy, script, ScriptSource.PROJECT, root) + } + + // Named by content hash, so one copy serves every run of the same bytes. Written to a temporary + // name first: a half-written copy must never be executable under the final name. + private fun verifiedCopy( + bytes: ByteArray, + sha: String, + ): File? = + try { + verifiedDir.mkdirs() + val copy = File(verifiedDir, sha) + val existing = if (copy.isFile) ScriptReview.readAtMost(copy, ScriptReview.MAX_BYTES) else null + if (existing == null || TrustStore.sha256(existing) != sha) { + val temp = File(verifiedDir, "$sha$TEMP_SUFFIX") + temp.writeBytes(bytes) + temp.setExecutable(true, true) + if (!temp.renameTo(copy)) throw IOException("rename failed") + } + copy.setExecutable(true, true) + copy + } catch (e: IOException) { + warn("Shell Hooks: cannot stage a trusted copy: ${e.message}") + null + } + + companion object { + const val TEMP_SUFFIX = ".tmp" + } +} + +/** The private copies of trusted project scripts, one per content hash. */ +object VerifiedCopies { + /** + * Deletes every copy in [dir] whose hash no trust entry still names, and any half-written + * temporary file. Returns how many files it deleted. + */ + fun prune( + dir: File, + trusted: Set, + ): Int = + dir.listFiles() + ?.filter { it.isFile && (it.name.endsWith(HookResolver.TEMP_SUFFIX) || it.name !in trusted) } + ?.count { it.delete() } + ?: 0 +} diff --git a/plugins/Shell-Hooks/src/main/kotlin/org/appdevforall/shellhooks/engine/HookRunner.kt b/plugins/Shell-Hooks/src/main/kotlin/org/appdevforall/shellhooks/engine/HookRunner.kt new file mode 100644 index 00000000..62fa4f3d --- /dev/null +++ b/plugins/Shell-Hooks/src/main/kotlin/org/appdevforall/shellhooks/engine/HookRunner.kt @@ -0,0 +1,300 @@ +package org.appdevforall.shellhooks.engine + +import com.itsaky.androidide.plugins.extensions.CommandOutput +import com.itsaky.androidide.plugins.extensions.CommandResult +import com.itsaky.androidide.plugins.extensions.CommandSpec +import com.itsaky.androidide.plugins.services.IdeCommandService +import kotlinx.coroutines.CancellationException +import kotlinx.coroutines.CoroutineScope +import kotlinx.coroutines.Job +import kotlinx.coroutines.channels.BufferOverflow +import kotlinx.coroutines.channels.Channel +import kotlinx.coroutines.coroutineScope +import kotlinx.coroutines.delay +import kotlinx.coroutines.launch +import kotlinx.coroutines.withTimeoutOrNull +import java.io.File + +/** + * Runs one command and suspends until it ends; cancelling the caller stops the command. Each line + * the command prints also goes to [output] as it arrives, so a run that is stopped before the + * host reports keeps what it printed. + */ +fun interface CommandRunner { + suspend fun run( + spec: CommandSpec.ShellCommand, + timeoutMs: Long, + output: OutputTail, + ): CommandResult +} + +/** [CommandRunner] over the IDE's headless command service. */ +class IdeCommandRunner( + private val service: () -> IdeCommandService?, +) : CommandRunner { + override suspend fun run( + spec: CommandSpec.ShellCommand, + timeoutMs: Long, + output: OutputTail, + ): CommandResult { + val commands = service() ?: return CommandResult.Failure(-1, "", "", "The IDE's command service is unavailable", 0) + val execution = commands.executeCommand(spec, timeoutMs) + return try { + coroutineScope { + // The host buffers every output line until someone reads them; drain them so a + // chatty script does not hold its whole output twice, and keep the tail for a run + // that is stopped before the host reports. + val drain = + launch { + execution.output.collect { line -> + when (line) { + is CommandOutput.StdOut -> output.append(line.line) + is CommandOutput.StdErr -> output.append(line.line) + is CommandOutput.ExitCode -> Unit + } + } + } + execution.await().also { drain.cancel() } + } + } catch (e: CancellationException) { + execution.cancel() + throw e + } + } +} + +/** How each script is launched: the bundled wrapper, the script, then the event's arguments. */ +object HookInvocation { + /** The wrapper's own timeout signal, telling it how long the script may run. */ + const val TIMEOUT_VARIABLE = "COGO_TIMEOUT_SECONDS" + + fun spec( + wrapper: File, + script: ResolvedScript, + event: HookEvent, + ideVersion: String?, + timeoutSeconds: Long? = null, + ): CommandSpec.ShellCommand = + CommandSpec.ShellCommand( + executable = "sh", + arguments = listOf(wrapper.path, script.executable.path) + event.args, + // Null: the host's current project root, which can be the last project opened even + // after it closed. The wrapper then changes to COGO_PROJECT_DIR, which for + // project-closed the host would refuse, or to HOME when that is empty. + workingDirectory = null, + environment = environment(script, event, ideVersion) + listOfNotNull(timeoutSeconds?.let { TIMEOUT_VARIABLE to it.toString() }), + ) + + fun environment( + script: ResolvedScript, + event: HookEvent, + ideVersion: String?, + ): Map = variables(event.hook.id, event.projectDir, ideVersion, script.hooksDir, script.original, script.source) + + /** An action's: the same variables as a hook's, with `action` for the hook. Actions are global only. */ + fun actionEnvironment( + action: File, + actionsDir: File, + projectDir: File?, + ideVersion: String?, + ): Map = variables(HookRun.ACTION, projectDir, ideVersion, actionsDir, action, ScriptSource.GLOBAL) + + // The one list of what every script is told, hook or action; the docs list the same names. + private fun variables( + hook: String, + projectDir: File?, + ideVersion: String?, + hooksDir: File, + script: File, + source: ScriptSource, + ): Map = + buildMap { + put("COGO_HOOK", hook) + put("COGO_PROJECT_DIR", projectDir?.path ?: "") + ideVersion?.let { put("COGO_IDE_VERSION", it) } + put("COGO_HOOKS_DIR", hooksDir.path) + put("COGO_HOOK_SCRIPT", script.path) + put("COGO_HOOK_SOURCE", source.id) + } +} + +/** + * Runs hook scripts one at a time, in the order their 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, + * other events directly. Events wait in a bounded queue; when it is full the oldest is dropped. + * One at a time keeps the plugin far under the host's limit of three concurrent commands, and + * keeps a burst of saves from starting a burst of processes. + * + * A script gets the user's timeout three times over. The wrapper stops it, and every process it + * started, at the limit when the Terminal has GNU `timeout` ([timeoutAvailable]). The host is asked + * to stop it [WRAPPER_KILL_GRACE_MS] later, which a blocking wait in the host does not always + * honour. This runner gives up [TIMEOUT_GRACE_MS] after that and cancels the command. + * + * [clock] is wall time, for when a run started. How long a run took comes from [elapsedClock], + * which must not jump: a clock set back mid-run must not make a timeout look like an early exit. + */ +class HookRunner( + scope: CoroutineScope, + private val resolver: ScriptResolver, + private val commands: CommandRunner, + private val log: HookLog, + private val wrapper: () -> File?, + private val timeoutMs: () -> Long, + private val timeoutAvailable: () -> Boolean = { false }, + private val ideVersion: String? = null, + private val clock: () -> Long = System::currentTimeMillis, + private val elapsedClock: () -> Long = { System.nanoTime() / 1_000_000 }, + private val warn: (String) -> Unit = {}, + capacity: Int = DEFAULT_QUEUE_CAPACITY, +) { + private val queue = + Channel(capacity, BufferOverflow.DROP_OLDEST) { dropped -> + warn("Shell Hooks: queue full, dropped ${dropped.hook.id}") + } + + private val worker: Job = + scope.launch { + for (event in queue) process(event) + } + + /** Queues [event]; false once the runner is closed. */ + fun submit(event: HookEvent): Boolean = queue.trySend(event).isSuccess + + /** Stops taking events and cancels the script running now. */ + fun close() { + queue.close() + worker.cancel() + } + + private suspend fun process(event: HookEvent) { + val scripts = + try { + resolver.resolve(event) + } catch (e: CancellationException) { + throw e + } catch (e: Throwable) { + // An Error too (say OutOfMemoryError): it must not end the worker for the session. + warn("Shell Hooks: cannot list scripts for ${event.hook.id}: $e") + return + } + for (script in scripts) runOne(event, script) + } + + private suspend fun runOne( + event: HookEvent, + script: ResolvedScript, + ) { + val started = clock() + val startedElapsed = elapsedClock() + val limit = timeoutMs() + // Checked per run, as the wrapper checks: `timeout` can be installed or removed between runs. + val underTimeout = timeoutAvailable() + val wrapperFile = wrapper() + val tail = OutputTail() + val (outcome, exitCode, output) = + if (wrapperFile == null) { + Triple(Outcome.NOT_STARTED, null, "The hook runner script is missing") + } else { + val spec = HookInvocation.spec(wrapperFile, script, event, ideVersion, timeoutSeconds = (limit + 999) / 1000) + val hostLimit = limit + WRAPPER_KILL_GRACE_MS + try { + withTimeoutOrNull(hostLimit + TIMEOUT_GRACE_MS) { commands.run(spec, hostLimit, tail) } + ?.let { describe(it, elapsed = elapsedClock() - startedElapsed, limit = limit, underTimeout = underTimeout) } + ?: Triple(Outcome.TIMED_OUT, null, stopped(tail.text(), limit)) + } catch (e: CancellationException) { + throw e + } catch (e: Exception) { + // A refused start: the concurrency limit, or a permission the plugin lacks. + Triple(Outcome.NOT_STARTED, null, e.message ?: e.javaClass.simpleName) + } + } + log.record( + HookRun( + startedAtMillis = started, + hook = event.hook, + script = script.original, + source = script.source, + target = event.target, + outcome = outcome, + exitCode = exitCode, + durationMillis = elapsedClock() - startedElapsed, + output = output, + ), + ) + } + + private fun describe( + result: CommandResult, + elapsed: Long, + limit: Long, + underTimeout: Boolean, + ): Triple = + when (result) { + is CommandResult.Success -> Triple(Outcome.SUCCEEDED, result.exitCode, HookLog.combineOutput(result.stdout, result.stderr)) + is CommandResult.Failure -> { + val output = HookLog.combineOutput(result.stdout, result.stderr) + val error = result.error + when { + error != null && error.contains("timed out", ignoreCase = true) -> + Triple(Outcome.TIMED_OUT, null, listOf(output, error).filter { it.isNotBlank() }.joinToString("\n")) + // Mostly a start that failed, but the host reports an error after a start the + // same way, so whatever the script printed is kept. + error != null && result.exitCode == -1 -> + Triple(Outcome.NOT_STARTED, null, listOf(output, error).filter { it.isNotBlank() }.joinToString("\n")) + // GNU timeout: 124 after TERM, 137 when it had to KILL. Only when the wrapper ran + // the script under timeout, and only once the run reached its limit: otherwise a + // 124 or 137 is the script's own (passed on from an inner timeout, or a kill for + // memory), an ordinary failure. + (result.exitCode == TIMEOUT_EXIT || result.exitCode == TIMEOUT_KILL_EXIT) && underTimeout && elapsed >= limit -> + Triple(Outcome.TIMED_OUT, null, stopped(output, limit)) + else -> Triple(Outcome.FAILED, result.exitCode, output) + } + } + is CommandResult.Cancelled -> Triple(Outcome.CANCELLED, null, HookLog.combineOutput(result.partialStdout, result.partialStderr)) + } + + private fun stopped( + output: String, + limit: Long, + ): String = listOf(output.trimEnd(), "Stopped after ${limit / 1000} s").filter { it.isNotBlank() }.joinToString("\n") + + companion object { + const val DEFAULT_QUEUE_CAPACITY = 64 + + /** How much longer than the user's limit the host gets, so the wrapper's own stop comes first. */ + const val WRAPPER_KILL_GRACE_MS = 10_000L + + /** How much longer than that this runner waits for the host before cancelling the command. */ + const val TIMEOUT_GRACE_MS = 5_000L + + const val TIMEOUT_EXIT = 124 + const val TIMEOUT_KILL_EXIT = 137 + } +} + +/** + * Collapses a burst of events into the last one, delivered [delayMs] after the burst ends. + * Switching through five tabs runs file-activated once, for the tab the user stopped on. + */ +class Coalescer( + private val scope: CoroutineScope, + private val delayMs: Long, + private val emit: (HookEvent) -> Unit, +) { + private var pending: Job? = null + + fun offer(event: HookEvent) { + synchronized(this) { + pending?.cancel() + pending = + scope.launch { + delay(delayMs) + emit(event) + } + } + } + + fun cancel() { + synchronized(this) { pending?.cancel() } + } +} diff --git a/plugins/Shell-Hooks/src/main/kotlin/org/appdevforall/shellhooks/engine/HookRunners.kt b/plugins/Shell-Hooks/src/main/kotlin/org/appdevforall/shellhooks/engine/HookRunners.kt new file mode 100644 index 00000000..628d9627 --- /dev/null +++ b/plugins/Shell-Hooks/src/main/kotlin/org/appdevforall/shellhooks/engine/HookRunners.kt @@ -0,0 +1,38 @@ +package org.appdevforall.shellhooks.engine + +import kotlinx.coroutines.CoroutineScope +import java.io.File + +/** + * Builds the runner the plugin uses, so how its parts are wired can be tested: notably that the + * runner knows, per run, whether the Terminal has `timeout` ([HookPaths.hasTimeout]), without which + * an exit 124 or 137 is the script's own. + */ +object HookRunners { + fun create( + scope: CoroutineScope, + paths: HookPaths, + switches: HookSwitches, + trust: TrustStore, + log: HookLog, + verifiedDir: File, + commands: CommandRunner, + wrapper: () -> File?, + timeoutMs: () -> Long, + ideVersion: String?, + warn: (String) -> Unit, + elapsedClock: () -> Long = { System.nanoTime() / 1_000_000 }, + ): HookRunner = + HookRunner( + scope = scope, + resolver = HookResolver(paths, switches, trust, log, verifiedDir, warn), + commands = commands, + log = log, + wrapper = wrapper, + timeoutMs = timeoutMs, + timeoutAvailable = paths::hasTimeout, + ideVersion = ideVersion, + elapsedClock = elapsedClock, + warn = warn, + ) +} diff --git a/plugins/Shell-Hooks/src/main/kotlin/org/appdevforall/shellhooks/engine/LaunchGate.kt b/plugins/Shell-Hooks/src/main/kotlin/org/appdevforall/shellhooks/engine/LaunchGate.kt new file mode 100644 index 00000000..56de9ddc --- /dev/null +++ b/plugins/Shell-Hooks/src/main/kotlin/org/appdevforall/shellhooks/engine/LaunchGate.kt @@ -0,0 +1,39 @@ +package org.appdevforall.shellhooks.engine + +/** + * Decides whether ide-started belongs to this launch of the IDE. The host activates a plugin at + * every IDE start, but also when the user re-enables or updates it mid-session, so the plugin + * remembers the launch it last ran ide-started for. [launchId] names the IDE process, e.g. its + * pid and start time: it is the same for every activation within one launch, and differs after + * the IDE restarts. + */ +class LaunchGate( + private val store: KeyValueStore, +) { + /** True when ide-started has not yet run for [launchId]. */ + fun isNewLaunch(launchId: String): Boolean = store.getString(KEY) != launchId + + /** Records that ide-started ran for [launchId]. */ + fun record(launchId: String) = store.putString(KEY, launchId) + + companion object { + const val KEY = "ide_started.launch" + } +} + +/** + * What activate() does about ide-started: run it once per launch, the first time the plugin starts + * with it switched on. A start with hooks off records nothing, so turning them on and restarting + * the plugin later in the same launch still runs it. + */ +class IdeStartedTrigger( + private val gate: LaunchGate, + private val enabled: () -> Boolean, + private val submit: () -> Unit, +) { + fun onActivate(launchId: String) { + if (!enabled() || !gate.isNewLaunch(launchId)) return + submit() + gate.record(launchId) + } +} diff --git a/plugins/Shell-Hooks/src/main/kotlin/org/appdevforall/shellhooks/engine/SampleHooks.kt b/plugins/Shell-Hooks/src/main/kotlin/org/appdevforall/shellhooks/engine/SampleHooks.kt new file mode 100644 index 00000000..6faeb6e2 --- /dev/null +++ b/plugins/Shell-Hooks/src/main/kotlin/org/appdevforall/shellhooks/engine/SampleHooks.kt @@ -0,0 +1,71 @@ +package org.appdevforall.shellhooks.engine + +import java.io.File + +/** + * Writes one `.sample` per hook, and a sample action, into the user's hooks folder. As in + * git, a sample never runs: it is not executable and its name ends in `.sample`. Renaming it and + * marking it executable turns it on. + */ +object SampleHooks { + const val ACTION_SAMPLE = "word-count.sample" + + /** Writes the samples and returns how many files it wrote. */ + fun write(paths: HookPaths): Int { + paths.globalHooks.mkdirs() + paths.actions.mkdirs() + var written = 0 + for (hook in Hook.entries) { + sample(File(paths.globalHooks, hook.id + HookDiscovery.SAMPLE_SUFFIX), hookSample(hook)) + written++ + } + sample(File(paths.actions, ACTION_SAMPLE), ACTION_BODY) + return written + 1 + } + + private fun sample( + file: File, + body: String, + ) { + file.writeText(body) + file.setExecutable(false, false) + } + + fun hookSample(hook: Hook): String = + """ + |#!/usr/bin/env bash + |# Sample Shell Hooks script for "${hook.id}" (${hook.title}). + |# To use it, drop ".sample" from its name and make it executable: + |# cd ~/.config/codeonthego/hooks && mv ${hook.id}.sample ${hook.id} && chmod +x ${hook.id} + |# For several scripts on one hook, put them in ${hook.id}.d/ instead; they run in name order. + |# + |# Arguments: ${hook.argsDoc} + |# Environment: + |# COGO_HOOK ${hook.id} + |# COGO_PROJECT_DIR the IDE's current project folder, which can be the last one opened + |# even after it closes; empty for ide-started + |# COGO_HOOKS_DIR the hooks folder this script is in + |# COGO_HOOK_SCRIPT this script's path + |# COGO_HOOK_SOURCE global, or project for a script stored in a project + |# COGO_IDE_VERSION the IDE's version, when known + |# The script runs in COGO_PROJECT_DIR, or in HOME when that is empty or gone. Its output + |# appears in the Hooks tab when it ends. + |# Hooks only report what happened; a script cannot stop a save or a build. + | + |printf '%s %s %s\n' "${'$'}(date '+%F %T')" "${'$'}COGO_HOOK" "${'$'}*" >> "${'$'}HOME/codeonthego-hooks.log" + | + """.trimMargin() + + private val ACTION_BODY = + """ + |#!/usr/bin/env bash + |# Sample Shell Hooks action. Actions appear as "Run " when you long-press a file in + |# the file tree or an editor tab, and run in the Terminal so you see their output. + |# To use it: cd ~/.config/codeonthego/hooks/actions && mv $ACTION_SAMPLE word-count && chmod +x word-count + |# + |# Arguments: ${'$'}1 = the file + | + |wc -l -w -c "${'$'}1" + | + """.trimMargin() +} diff --git a/plugins/Shell-Hooks/src/main/kotlin/org/appdevforall/shellhooks/engine/ScriptHints.kt b/plugins/Shell-Hooks/src/main/kotlin/org/appdevforall/shellhooks/engine/ScriptHints.kt new file mode 100644 index 00000000..48422e2f --- /dev/null +++ b/plugins/Shell-Hooks/src/main/kotlin/org/appdevforall/shellhooks/engine/ScriptHints.kt @@ -0,0 +1,74 @@ +package org.appdevforall.shellhooks.engine + +/** + * A best-effort check, not a guarantee: marks the lines of a plain script ([ScriptReview]) that use + * shell syntax which can make a script do something other than it seems, so the review dialog can + * point at them. Plain text shows the reader every byte; it does not show how the shell parses them. + * + * Each line is judged on its own. Nothing is carried from one line to the next, and no quotes, + * comments, here-documents or arithmetic are tracked, so no line of a script can change how the + * lines after it are marked. A line is marked for each of these it contains, wherever it appears, + * in a comment or string too: + * - [Kind.HERE_DOCUMENT]: `<<`, which may start a here-document; + * - [Kind.CONTINUATION]: a backslash as its last character, which in code, and in the text of a + * here-document whose delimiter is not quoted, usually joins the next line to it (in bash the + * joined lines can then form the delimiter and end the here-document early); + * - [Kind.COMMAND]: a backtick or `$(`, which may run a command. + * + * That is the whole rule. It marks many lines that are harmless, and it says nothing about the many + * other ways a line can surprise a reader (an alias, `IFS`, a function named like a builtin): a line + * without a mark can still do anything. The dialog says so, and never states where a here-document + * ends or whether its text is expanded. + */ +object ScriptHints { + enum class Kind { HERE_DOCUMENT, CONTINUATION, COMMAND } + + /** Line numbers (1-based) listed in full for each kind; the rest are counted. */ + const val MAX_LISTED = 100 + + /** The marked lines of a script, by kind, each list in line order. */ + data class Marks( + val hereDocuments: List, + val continuations: List, + val commands: List, + ) { + val isEmpty: Boolean get() = hereDocuments.isEmpty() && continuations.isEmpty() && commands.isEmpty() + + /** Every marked line, for the `!` beside its number. */ + val lines: Set get() = (hereDocuments + continuations + commands).toSortedSet() + + fun of(kind: Kind): List = + when (kind) { + Kind.HERE_DOCUMENT -> hereDocuments + Kind.CONTINUATION -> continuations + Kind.COMMAND -> commands + } + } + + /** The kinds [line] is marked for: see [ScriptHints]. */ + fun kindsOf(line: String): Set = + buildSet { + if (line.contains("<<")) add(Kind.HERE_DOCUMENT) + if (line.endsWith('\\')) add(Kind.CONTINUATION) + if (line.contains('`') || line.contains("$(")) add(Kind.COMMAND) + } + + /** The marks for [lines], a script's lines without their newlines. */ + fun find(lines: List): Marks { + val byKind = Kind.entries.associateWith { mutableListOf() } + lines.forEachIndexed { index, line -> + for (kind in kindsOf(line)) byKind.getValue(kind).add(index + 1) + } + return Marks( + hereDocuments = byKind.getValue(Kind.HERE_DOCUMENT), + continuations = byKind.getValue(Kind.CONTINUATION), + commands = byKind.getValue(Kind.COMMAND), + ) + } + + /** The first [max] of [lines] to list, and how many more there are. */ + fun listed( + lines: List, + max: Int = MAX_LISTED, + ): Pair, Int> = lines.take(max) to (lines.size - max).coerceAtLeast(0) +} diff --git a/plugins/Shell-Hooks/src/main/kotlin/org/appdevforall/shellhooks/engine/ScriptReview.kt b/plugins/Shell-Hooks/src/main/kotlin/org/appdevforall/shellhooks/engine/ScriptReview.kt new file mode 100644 index 00000000..7f389993 --- /dev/null +++ b/plugins/Shell-Hooks/src/main/kotlin/org/appdevforall/shellhooks/engine/ScriptReview.kt @@ -0,0 +1,258 @@ +package org.appdevforall.shellhooks.engine + +import java.io.File +import java.io.IOException +import java.io.InputStream + +/** + * Whether a project script can be reviewed, and reading it to find out. + * + * The review dialog shows a project script so the user can see what will run, and only a plain + * script can be shown so that what it displays is what the shell reads. Each review of this plugin + * found another way to make a script read differently from how it runs: a no-break space bash + * takes as part of a word, a backslash before an invisible carriage return or trailing blank that + * reads as a line continuation, a run of spaces whose soft wrap looks like a new line, a tab that + * looks like a space where `<<-` tells them apart. Rather than display each such trick, a project + * script can be trusted only when it is plain: + * - at most [MAX_BYTES] bytes; + * - every byte printable ASCII (0x20-0x7E) or a newline: no tab, carriage return, other control + * byte or byte outside ASCII; + * - no line longer than [MAX_LINE] characters, and none ending in a space (a last line without a + * newline is fine); + * - a name inside the hooks folder of letters, digits, `.`, `_`, `-` and `/`, with no part starting + * with `.`. + * Anything else is listed with the reason it cannot be reviewed, and never runs. + * + * Plain text shows the reader every byte; it does not show how the shell parses them. A plain + * script can still read as inert and run a command. [ScriptHints] marks, as a best effort, lines that + * use syntax worth a closer look. + */ +object ScriptReview { + const val MAX_BYTES = 64 * 1024 + const val MAX_LINE = 100 + + private val SAFE_NAME = Regex("[A-Za-z0-9._/-]+") + + /** Why a script cannot be reviewed; [message] completes "Can't be reviewed: ". */ + sealed interface Reason { + val message: String + + data object TooLarge : Reason { + override val message = "it is larger than ${MAX_BYTES / 1024} KB" + } + + data object UnsafeName : Reason { + override val message = "its name uses characters other than letters, digits, '.', '_', '-' and '/'" + } + + data object HiddenName : Reason { + override val message = "its name has a part that starts with '.'" + } + + data class BadByte( + val line: Int, + val column: Int, + val value: Int, + ) : Reason { + override val message: String + get() { + val what = + when (value) { + 0x09 -> "a tab" + 0x0D -> "a carriage return" + in 0x00..0x1F, 0x7F -> "a control character (0x%02X)".format(value) + else -> "byte 0x%02X (not plain ASCII)".format(value) + } + return "line $line, column $column: $what" + } + } + + data class LongLine( + val line: Int, + ) : Reason { + override val message = "line $line is longer than $MAX_LINE characters" + } + + data class TrailingSpace( + val line: Int, + ) : Reason { + override val message = "line $line ends in a space" + } + } + + /** What [assess] found. */ + sealed interface Assessment { + /** A plain script: these [bytes] can be shown, as [lines], and trusted. */ + data class Reviewable( + val bytes: ByteArray, + val sha256: String, + ) : Assessment { + val lines: List get() = lines(bytes) + } + + data class NotReviewable( + val reason: Reason, + ) : Assessment + + /** + * The file could not be read. [cause] is for the log only: an IOException's message starts + * with the path, which the project chose, so it is never shown as it is. + */ + data class Unreadable( + val cause: String, + ) : Assessment + } + + /** + * Whether [file], at [relativePath] inside its hooks folder, can be reviewed. The name is + * checked before anything is read, and no more than [MAX_BYTES] + 1 bytes ever are. + */ + fun assess( + file: File, + relativePath: String, + ): Assessment { + checkName(relativePath)?.let { return Assessment.NotReviewable(it) } + val bytes = + try { + readAtMost(file, MAX_BYTES) + } catch (e: IOException) { + return Assessment.Unreadable(e.message ?: e.javaClass.simpleName) + } ?: return Assessment.NotReviewable(Reason.TooLarge) + checkBytes(bytes)?.let { return Assessment.NotReviewable(it) } + return Assessment.Reviewable(bytes, TrustStore.sha256(bytes)) + } + + /** Why [relativePath] and [bytes] cannot be reviewed, or null when they can. */ + fun check( + relativePath: String, + bytes: ByteArray, + ): Reason? = checkName(relativePath) ?: checkBytes(bytes) + + /** Why a script named [relativePath] inside its hooks folder cannot be reviewed, or null. */ + fun checkName(relativePath: String): Reason? { + if (!SAFE_NAME.matches(relativePath)) return Reason.UnsafeName + if (relativePath.split('/').any { it.startsWith(".") }) return Reason.HiddenName + return null + } + + /** The first reason [bytes] cannot be reviewed, by position, or null when they can. */ + fun checkBytes(bytes: ByteArray): Reason? { + if (bytes.size > MAX_BYTES) return Reason.TooLarge + var line = 1 + var column = 0 + var last = -1 + for (b in bytes) { + val value = b.toInt() and 0xFF + when { + value == 0x0A -> { + if (last == 0x20) return Reason.TrailingSpace(line) + line++ + column = 0 + } + value in 0x20..0x7E -> { + column++ + if (column > MAX_LINE) return Reason.LongLine(line) + } + else -> return Reason.BadByte(line, column + 1, value) + } + last = value + } + if (last == 0x20) return Reason.TrailingSpace(line) + return null + } + + /** The lines of a reviewable script, without their newlines; no empty last line for a final newline. */ + fun lines(bytes: ByteArray): List { + val text = String(bytes, Charsets.US_ASCII) + val lines = text.split('\n') + return if (text.endsWith('\n')) lines.dropLast(1) else lines + } + + /** + * [file]'s bytes, or null when it holds more than [max]. Checks the length first and never + * reads past [max] + 1, so a file that grows while it is read is still caught. + */ + @Throws(IOException::class) + fun readAtMost( + file: File, + max: Int, + ): ByteArray? = readAtMost(file.length(), { file.inputStream() }, max) + + /** [readAtMost] given the file's reported [length] and a way to [open] it. */ + @Throws(IOException::class) + internal fun readAtMost( + length: Long, + open: () -> InputStream, + max: Int, + ): ByteArray? { + if (length > max) return null + open().use { input -> + val buffer = ByteArray(max + 1) + var read = 0 + while (read < buffer.size) { + val n = input.read(buffer, read, buffer.size - read) + if (n < 0) break + read += n + } + return if (read > max) null else buffer.copyOf(read) + } + } + + /** + * A name as shown, how many characters in it were made visible, and where each `` it + * put in sits in [text], so a view can mark it apart from the same characters typed in a name. + */ + data class Revealed( + val text: String, + val hidden: Int, + val escapes: List = emptyList(), + ) + + /** + * Shows as `` every character of a name the project chose (a project folder, a file + * the run was about, a script that cannot be reviewed) that could make it read differently + * from what it is: everything outside plain ASCII (bidirectional controls, zero-width + * characters, no-break spaces), every control character including tab and newline, and every + * space at the end of the name or before a newline. Only printable ASCII is shown as it is: a + * name is one line, so a newline in one must not add a line of text to a dialog. Characters + * are taken one code point at a time, so a supplementary character shows as one escape and an + * unpaired surrogate is shown too. Scripts themselves are not revealed: one that would need it + * cannot be reviewed at all. + */ + fun reveal(text: String): Revealed { + val trailing = trailingBlanks(text) + val out = StringBuilder(text.length) + val escapes = mutableListOf() + var i = 0 + while (i < text.length) { + val cp = text.codePointAt(i) + if (isPlain(cp) && !trailing[i]) { + out.appendCodePoint(cp) + } else { + val start = out.length + out.append("') + escapes += start until out.length + } + i += Character.charCount(cp) + } + return Revealed(out.toString(), escapes.size, escapes) + } + + // Marks each space, tab or carriage return in the run that ends a line (before a newline, or + // at the end of the text). + private fun trailingBlanks(text: String): BooleanArray { + val marks = BooleanArray(text.length) + var inTrail = true + for (j in text.indices.reversed()) { + val c = text[j] + when { + c == '\n' -> inTrail = true + inTrail && (c == ' ' || c == '\t' || c == '\r') -> marks[j] = true + else -> inTrail = false + } + } + return marks + } + + private fun isPlain(cp: Int): Boolean = cp in 0x20..0x7E +} diff --git a/plugins/Shell-Hooks/src/main/kotlin/org/appdevforall/shellhooks/engine/ShellQuote.kt b/plugins/Shell-Hooks/src/main/kotlin/org/appdevforall/shellhooks/engine/ShellQuote.kt new file mode 100644 index 00000000..26767cdb --- /dev/null +++ b/plugins/Shell-Hooks/src/main/kotlin/org/appdevforall/shellhooks/engine/ShellQuote.kt @@ -0,0 +1,32 @@ +package org.appdevforall.shellhooks.engine + +/** + * Quoting for the one place a command must be a string: the Terminal takes a command line, not + * an argument list. Hooks run headless never pass through here; their values travel as argv. + */ +object ShellQuote { + /** + * [value] as one POSIX shell word. Inside single quotes nothing is special, so the only + * character to handle is the single quote itself: close the quote, emit an escaped quote, + * reopen. `$(...)`, backticks, `"` and newlines all stay literal. + */ + fun quote(value: String): String = "'" + value.replace("'", "'\\''") + "'" + + /** [words] as a command line in which each word reaches the program unchanged. */ + fun join(words: List): String = words.joinToString(" ") { quote(it) } + + /** + * `NAME='value' ... word ...`: [environment] set for this one command. Names are not quoted, + * so only names the plugin itself chose may be passed. + */ + fun command( + environment: Map, + words: List, + ): String { + environment.keys.forEach { require(NAME.matches(it)) { "Not an environment variable name: $it" } } + val assignments = environment.entries.joinToString(" ") { (name, value) -> name + "=" + quote(value) } + return listOf(assignments, join(words)).filter { it.isNotEmpty() }.joinToString(" ") + } + + private val NAME = Regex("[A-Za-z_][A-Za-z0-9_]*") +} diff --git a/plugins/Shell-Hooks/src/main/kotlin/org/appdevforall/shellhooks/engine/TimeoutSetting.kt b/plugins/Shell-Hooks/src/main/kotlin/org/appdevforall/shellhooks/engine/TimeoutSetting.kt new file mode 100644 index 00000000..941f806f --- /dev/null +++ b/plugins/Shell-Hooks/src/main/kotlin/org/appdevforall/shellhooks/engine/TimeoutSetting.kt @@ -0,0 +1,15 @@ +package org.appdevforall.shellhooks.engine + +/** The script timeout the user can set, in seconds. */ +object TimeoutSetting { + const val DEFAULT_SECONDS = 60 + const val MIN_SECONDS = 1 + const val MAX_SECONDS = 3600 + + /** + * What the user typed, as a timeout to store, or null when it is not a whole number of seconds + * from [MIN_SECONDS] to [MAX_SECONDS]. Nothing is clamped: a value the field shows is the + * value stored, or nothing is stored. + */ + fun parse(text: String): Int? = text.trim().toIntOrNull()?.takeIf { it in MIN_SECONDS..MAX_SECONDS } +} diff --git a/plugins/Shell-Hooks/src/main/kotlin/org/appdevforall/shellhooks/engine/TrustStore.kt b/plugins/Shell-Hooks/src/main/kotlin/org/appdevforall/shellhooks/engine/TrustStore.kt new file mode 100644 index 00000000..2740f094 --- /dev/null +++ b/plugins/Shell-Hooks/src/main/kotlin/org/appdevforall/shellhooks/engine/TrustStore.kt @@ -0,0 +1,118 @@ +package org.appdevforall.shellhooks.engine + +import java.io.File +import java.security.MessageDigest +import java.util.Base64 + +/** The few string operations [TrustStore] needs, so it runs on SharedPreferences or a map. */ +interface KeyValueStore { + fun getString(key: String): String? + + /** Stores [value] under [key]; null removes the key. */ + fun putString( + key: String, + value: String?, + ) + + fun keys(): Set +} + +/** + * Which project hooks the user approved. 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 script found there runs + * only once the user has read it and trusted that exact content: approval is keyed on the + * project, the script's path inside the hooks folder, and the SHA-256 of its bytes. Editing the + * script, or adding one, needs a new approval. Only a script [ScriptReview] can show as it runs can + * be trusted at all. + * + * This does not stop a plugin that can run commands or write files in-process: such a plugin can + * already write the global hooks folder, or these approvals, directly. + */ +class TrustStore( + private val store: KeyValueStore, +) { + fun isTrusted( + projectDir: File, + relativePath: String, + sha256: String, + ): Boolean = read(projectDir)[relativePath] == sha256 + + /** + * Trusts these [bytes] of [relativePath], replacing an approval of other content. Refuses, and + * stores nothing, when they cannot be reviewed: returns false. + */ + fun trust( + projectDir: File, + relativePath: String, + bytes: ByteArray, + ): Boolean { + if (ScriptReview.check(relativePath, bytes) != null) return false + put(projectDir, relativePath, sha256(bytes)) + return true + } + + /** Records an approval of [sha256] for [relativePath], unchecked. */ + internal fun put( + projectDir: File, + relativePath: String, + sha256: String, + ) { + synchronized(this) { + write(projectDir, read(projectDir) + (relativePath to sha256)) + } + } + + /** Forgets every approval for [projectDir]. */ + fun revoke(projectDir: File) { + synchronized(this) { store.putString(key(projectDir), null) } + } + + /** Projects with at least one trusted hook, as their canonical paths, sorted. */ + fun trustedProjects(): List = + store.keys().filter { it.startsWith(PREFIX) }.map { it.removePrefix(PREFIX) }.sorted() + + /** How many scripts are trusted in [projectDir]. */ + fun trustedCount(projectDir: File): Int = read(projectDir).size + + /** Every trusted content hash, across all projects. */ + fun trustedShas(): Set = + store.keys().filter { it.startsWith(PREFIX) }.flatMap { readKey(it).values }.toSet() + + private fun read(projectDir: File): Map = readKey(key(projectDir)) + + private fun readKey(key: String): Map { + val raw = store.getString(key) ?: return emptyMap() + return raw.lineSequence() + .mapNotNull { line -> + val tab = line.indexOf('\t') + if (tab <= 0) return@mapNotNull null + val path = runCatching { String(Base64.getDecoder().decode(line.substring(tab + 1)), Charsets.UTF_8) } + .getOrNull() ?: return@mapNotNull null + path to line.substring(0, tab) + }.toMap() + } + + // One line per script: "\t". Base64, because a file name may hold a tab + // or a newline. + private fun write( + projectDir: File, + entries: Map, + ) { + val value = + entries.entries.sortedBy { it.key }.joinToString("\n") { (path, sha) -> + sha + "\t" + Base64.getEncoder().encodeToString(path.toByteArray(Charsets.UTF_8)) + } + store.putString(key(projectDir), value.ifEmpty { null }) + } + + private fun key(projectDir: File) = PREFIX + canonical(projectDir) + + companion object { + private const val PREFIX = "trust:" + + fun canonical(dir: File): String = runCatching { dir.canonicalPath }.getOrDefault(dir.absolutePath) + + fun sha256(bytes: ByteArray): String = + MessageDigest.getInstance("SHA-256").digest(bytes).joinToString("") { "%02x".format(it) } + } +} diff --git a/plugins/Shell-Hooks/src/main/kotlin/org/appdevforall/shellhooks/ui/HooksPanelFragment.kt b/plugins/Shell-Hooks/src/main/kotlin/org/appdevforall/shellhooks/ui/HooksPanelFragment.kt new file mode 100644 index 00000000..596b6885 --- /dev/null +++ b/plugins/Shell-Hooks/src/main/kotlin/org/appdevforall/shellhooks/ui/HooksPanelFragment.kt @@ -0,0 +1,536 @@ +package org.appdevforall.shellhooks.ui + +import android.content.DialogInterface +import android.os.Bundle +import android.text.SpannableString +import android.text.SpannableStringBuilder +import android.text.Spanned +import android.text.format.DateFormat +import android.text.style.ForegroundColorSpan +import android.view.LayoutInflater +import android.view.View +import android.view.ViewGroup +import android.widget.Button +import android.widget.LinearLayout +import android.widget.TextView +import androidx.appcompat.app.AlertDialog +import androidx.fragment.app.Fragment +import androidx.lifecycle.Lifecycle +import androidx.lifecycle.lifecycleScope +import androidx.lifecycle.repeatOnLifecycle +import androidx.recyclerview.widget.LinearLayoutManager +import androidx.recyclerview.widget.ListAdapter +import androidx.recyclerview.widget.RecyclerView +import com.google.android.material.dialog.MaterialAlertDialogBuilder +import com.itsaky.androidide.plugins.base.PluginFragmentHelper +import com.itsaky.androidide.plugins.services.IdeTooltipService +import kotlinx.coroutines.Dispatchers +import kotlinx.coroutines.NonCancellable +import kotlinx.coroutines.flow.combine +import kotlinx.coroutines.launch +import kotlinx.coroutines.withContext +import org.appdevforall.shellhooks.R +import org.appdevforall.shellhooks.ShellHooksHelp +import org.appdevforall.shellhooks.ShellHooksPlugin +import org.appdevforall.shellhooks.engine.HookRun +import org.appdevforall.shellhooks.engine.Outcome +import org.appdevforall.shellhooks.engine.PendingTrust +import org.appdevforall.shellhooks.engine.ScriptHints +import org.appdevforall.shellhooks.engine.ScriptReview +import java.util.Date + +/** + * The Hooks bottom-sheet tab: project scripts awaiting review, then the recent runs. A run's + * output is hidden until its row is tapped. + */ +class HooksPanelFragment : Fragment() { + private var tooltips: IdeTooltipService? = null + private var reviewDialog: AlertDialog? = null + + /** A script is being read for review; further taps on Review wait for it. */ + private var reviewLoading = false + + /** Rows the user expanded, so a refresh keeps them open. */ + private val expanded = mutableSetOf() + + override fun onCreate(savedInstanceState: Bundle?) { + super.onCreate(savedInstanceState) + tooltips = + runCatching { + PluginFragmentHelper.getServiceRegistry(ShellHooksPlugin.PLUGIN_ID)?.get(IdeTooltipService::class.java) + }.getOrNull() + } + + override fun onGetLayoutInflater(savedInstanceState: Bundle?): LayoutInflater = + PluginFragmentHelper.getPluginInflater(ShellHooksPlugin.PLUGIN_ID, super.onGetLayoutInflater(savedInstanceState)) + + override fun onCreateView( + inflater: LayoutInflater, + container: ViewGroup?, + savedInstanceState: Bundle?, + ): View = inflater.inflate(R.layout.fragment_hooks_panel, container, false) + + override fun onViewCreated( + view: View, + savedInstanceState: Bundle?, + ) { + super.onViewCreated(view, savedInstanceState) + val plugin = ShellHooksPlugin.getInstance() ?: return + view.findViewById(R.id.hkList).apply { + layoutManager = LinearLayoutManager(requireContext()) + adapter = PanelAdapter(plugin) + } + + viewLifecycleOwner.lifecycleScope.launch { + viewLifecycleOwner.repeatOnLifecycle(Lifecycle.State.STARTED) { + combine(plugin.log.runs, plugin.log.pending) { runs, pending -> runs to pending } + .collect { (runs, pending) -> render(plugin, runs, pending) } + } + } + } + + override fun onResume() { + super.onResume() + // The master switch lives on another screen; pick up a change made there. + val plugin = ShellHooksPlugin.getInstance() ?: return + render(plugin, plugin.log.runs.value, plugin.log.pending.value) + } + + override fun onDestroyView() { + super.onDestroyView() + reviewDialog?.dismiss() + reviewDialog = null + } + + /** Hands the rows to the adapter, which works out off the main thread which ones changed. */ + private fun render( + plugin: ShellHooksPlugin, + runs: List, + pending: List, + ) { + val list = view?.findViewById(R.id.hkList) ?: return + val adapter = list.adapter as? PanelAdapter ?: return + // The list keeps its first visible row in place, so a row added above it, such as the + // first script awaiting review, would land out of sight even with the list at the top. + val atTop = !list.canScrollVertically(-1) + adapter.submitList(PanelRow.of(plugin.isOn(), runs, pending)) { + if (atTop) list.scrollToPosition(0) + } + } + + /** The tab's rows, inflated with the fragment's inflater, which reads the plugin's resources. */ + private inner class PanelAdapter( + private val plugin: ShellHooksPlugin, + ) : ListAdapter(PanelRowDiff) { + override fun getItemViewType(position: Int): Int = + when (getItem(position)) { + PanelRow.Off -> OFF + PanelRow.PendingTitle -> PENDING_TITLE + is PanelRow.Pending -> PENDING + is PanelRow.PendingMore -> PENDING_MORE + PanelRow.RunsHeader -> RUNS_HEADER + PanelRow.Empty -> EMPTY + is PanelRow.Run -> RUN + } + + override fun onCreateViewHolder( + parent: ViewGroup, + viewType: Int, + ): RecyclerView.ViewHolder { + val row = layoutInflater.inflate(LAYOUTS.getValue(viewType), parent, false) + when (viewType) { + PENDING -> return PendingHolder(row) + RUN -> return RunHolder(row) + PENDING_TITLE -> help(row, ShellHooksHelp.TAG_PROJECT_HOOKS) + PENDING_MORE -> help(row, ShellHooksHelp.TAG_REVIEW) + EMPTY -> (row as TextView).setText(R.string.hk_empty) + RUNS_HEADER -> { + help(row.findViewById(R.id.hkRunsTitle), ShellHooksHelp.TAG_TAB) + row.findViewById