Skip to content

Commit 71a4b57

Browse files
nathfavournathfavour
committed
docs: document single-command target hook distribution and add integration agent skill
1 parent 6273ed1 commit 71a4b57

3 files changed

Lines changed: 251 additions & 39 deletions

File tree

‎.agents/skills/integration/SKILL.md‎

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
---
2+
name: anyisland-integration
3+
description: Complete guide and reference for integrating any tool, binary, or repository with Anyisland. Covers single-command bootstrap hooks, manifest specification (anyisland.json), install adapter scripts, and live pulse/daemon auto-registration.
4+
---
5+
6+
# Anyisland Integration Skill
7+
8+
Use this skill when integrating any repository, service, or CLI tool with the **Anyisland** decentralized ecosystem.
9+
10+
---
11+
12+
## 1. Core Architecture Pattern
13+
14+
Anyisland enables a frictionless **one-command distribution model** for tools:
15+
16+
```bash
17+
curl -fsSL https://raw.githubusercontent.com/nathfavour/anyisland/master/install.sh | bash -s -- <owner/repo>
18+
```
19+
20+
When an end-user runs this command:
21+
1. `install.sh` downloads/builds Anyisland in `~/.local/bin` and registers it in `~/.anyisland/island.db` if not already present.
22+
2. `install.sh` immediately calls `anyisland install <owner/repo>`.
23+
3. Anyisland reads the tool's `anyisland.json` manifest, prepares dependencies, executes the build pipeline, and symlinks the binary into the user's `PATH`.
24+
25+
---
26+
27+
## 2. Manifest Schema (`anyisland.json`)
28+
29+
Every integrating tool must include an `anyisland.json` at its repository root:
30+
31+
```json
32+
{
33+
"name": "your-tool-name",
34+
"version": "1.0.0",
35+
"description": "Short summary of what the tool does.",
36+
"repository": "github.com/owner/your-tool-name",
37+
"source_dir": "~/.your-tool-name/source",
38+
"install_dir": "~/.local/bin",
39+
"build": {
40+
"steps": [
41+
"bash install.sh"
42+
],
43+
"bin": "your-tool-name",
44+
"toolchain": "go"
45+
},
46+
"runtime": {
47+
"dependencies": [
48+
"libtesseract-dev",
49+
"libleptonica-dev"
50+
],
51+
"daemon": false,
52+
"pulse": true
53+
}
54+
}
55+
```
56+
57+
### Manifest Fields
58+
- **`name`**: Tool binary and registry name (must match binary output).
59+
- **`version`**: Semantic version string (e.g. `1.0.0`).
60+
- **`build.steps`**: Sequential shell commands to compile or bundle the application.
61+
- **`build.bin`**: Name or relative path of the produced executable.
62+
- **`build.toolchain`**: Optional hint (`go`, `rust`, `node`, `python`, `flutter`, `c`).
63+
- **`runtime.dependencies`**: OS packages or libraries required at runtime.
64+
- **`runtime.pulse`**: Set `true` if the tool participates in Anyisland health/heartbeat pulses.
65+
66+
---
67+
68+
## 3. Tool `install.sh` Adapter Script
69+
70+
Include an `install.sh` in your repository root that handles both direct standalone execution and Anyisland invocation:
71+
72+
```bash
73+
#!/bin/bash
74+
set -e
75+
76+
# 1. Fallback: If run directly without Anyisland, delegate to Anyisland bootstrap
77+
if ! command -v anyisland &> /dev/null; then
78+
echo "🏝️ Bootstrapping via Anyisland..."
79+
curl -fsSL https://raw.githubusercontent.com/nathfavour/anyisland/master/install.sh | bash -s -- <owner/repo>
80+
exit 0
81+
fi
82+
83+
# 2. Host Dependency Verification (Linux/macOS)
84+
OS="$(uname -s | tr '[:upper:]' '[:lower:]')"
85+
86+
if [ "$OS" = "linux" ]; then
87+
if command -v apt-get >/dev/null 2>&1; then
88+
# Check and install system packages if needed
89+
echo "Verifying Linux libraries..."
90+
fi
91+
elif [ "$OS" = "darwin" ]; then
92+
echo "Verifying macOS Homebrew dependencies..."
93+
fi
94+
95+
# 3. Build Binary
96+
echo "Building binary..."
97+
go build -o your-tool-name ./cmd/your-tool-name
98+
```
99+
100+
---
101+
102+
## 4. Live Daemon Auto-Registration (UDP :1995)
103+
104+
Tools can broadcast their presence to the Anyisland background daemon on startup:
105+
106+
### Go Example
107+
```go
108+
package main
109+
110+
import (
111+
"encoding/json"
112+
"net"
113+
)
114+
115+
func RegisterWithIsland(name, version, repo string) {
116+
packet := map[string]string{
117+
"op": "REGISTER",
118+
"name": name,
119+
"source": repo,
120+
"version": version,
121+
"type": "binary",
122+
}
123+
data, err := json.Marshal(packet)
124+
if err != nil {
125+
return
126+
}
127+
conn, err := net.Dial("udp", "127.0.0.1:1995")
128+
if err == nil {
129+
defer conn.Close()
130+
_, _ = conn.Write(data)
131+
}
132+
}
133+
```
134+
135+
---
136+
137+
## 5. Standard README Installation Section
138+
139+
Document installation in your tool's `README.md` as follows:
140+
141+
```markdown
142+
## 📦 Installation
143+
144+
Install instantly with a single command (powered by [Anyisland](https://github.com/nathfavour/anyisland)):
145+
146+
\`\`\`bash
147+
# macOS / Linux
148+
curl -fsSL https://raw.githubusercontent.com/nathfavour/anyisland/master/install.sh | bash -s -- <owner/repo>
149+
\`\`\`
150+
151+
*Or if you already have Anyisland installed:*
152+
\`\`\`bash
153+
anyisland install <owner/repo>
154+
\`\`\`
155+
```

‎docs/docs/distribution.md‎

Lines changed: 82 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -4,76 +4,129 @@ sidebar_position: 3
44

55
# Distribution & Integration
66

7-
Anyisland allows developers to distribute their tools effortlessly and integrate them deeply into the user's sovereign environment.
7+
Anyisland provides a zero-friction, platform-agnostic distribution mechanism for modern CLI tools and sovereign software. Tools integrating with Anyisland can provide users with an instant single-command install experience without requiring separate package manager setup.
88

9-
## 1. Creating a Manifest (`anyisland.json`)
9+
---
10+
11+
## 1. Universal One-Command Bootstrap (Recommended Default)
12+
13+
The default and cleanest distribution method is the **Anyisland Universal Bootstrap Hook**. This allows end users to install your tool directly using a single curl command. The script bootstraps Anyisland (if not already present) and immediately delegates to building/installing your tool.
14+
15+
### User Install Snippet
16+
17+
Add this to your project's `README.md`:
18+
19+
```bash
20+
# macOS / Linux
21+
curl -fsSL https://raw.githubusercontent.com/nathfavour/anyisland/master/install.sh | bash -s -- <owner/repo>
22+
```
23+
24+
*Example for `nathfavour/threader`:*
25+
```bash
26+
curl -fsSL https://raw.githubusercontent.com/nathfavour/anyisland/master/install.sh | bash -s -- nathfavour/threader
27+
```
28+
29+
If the user already has Anyisland installed, they can also install your tool via:
30+
```bash
31+
anyisland install <owner/repo>
32+
```
33+
34+
---
1035

11-
The manifest is the source of truth for Anyisland. Placing this file in your repository's root allows Anyisland to skip AI analysis and follow your explicit instructions.
36+
## 2. Defining the Manifest (`anyisland.json`)
1237

13-
See the [**Manifest Specification**](./manifest-spec.md) for a detailed breakdown of all available fields and best practices.
38+
Placing an `anyisland.json` in your repository's root tells Anyisland how to resolve runtime dependencies and build your project deterministically.
1439

15-
### Basic Schema
40+
See the [**Manifest Specification**](./manifest-spec.md) for full field details.
41+
42+
### Standard Go / Rust / C / Native Schema
1643

1744
```json
1845
{
19-
"name": "tool-name",
46+
"name": "mytool",
2047
"version": "1.0.0",
48+
"description": "High performance marketing engine.",
49+
"repository": "github.com/owner/mytool",
50+
"source_dir": "~/.mytool/source",
51+
"install_dir": "~/.local/bin",
2152
"build": {
2253
"steps": [
23-
"go build -o mytool ."
54+
"bash install.sh"
2455
],
2556
"bin": "mytool",
26-
"install_dir": "/custom/path"
57+
"toolchain": "go"
58+
},
59+
"runtime": {
60+
"dependencies": [
61+
"libtesseract-dev",
62+
"libleptonica-dev"
63+
],
64+
"pulse": true
2765
}
2866
}
2967
```
3068

31-
#### Field Reference
32-
- **`name`**: The unique identifier for your tool.
33-
- **`version`**: The current semantic version.
34-
- **`build.steps`**: An array of shell commands executed sequentially in the source root.
35-
- **`build.bin`**: The relative path to the resulting executable after build steps finish.
36-
- **`build.install_dir`** *(Optional)*: An absolute path if you want to override the default `~/.anyisland/bin` location.
69+
---
70+
71+
## 3. Tool `install.sh` Adapter Pattern
72+
73+
To give users maximum flexibility, your repository's local `install.sh` can act as an adapter that bootstraps through Anyisland when run standalone, and builds the binary when called inside an Anyisland cycle:
74+
75+
```bash
76+
#!/bin/bash
77+
set -e
78+
79+
# If run directly outside Anyisland, bootstrap via Anyisland
80+
if ! command -v anyisland &> /dev/null; then
81+
echo "🏝️ Bootstrapping via Anyisland..."
82+
curl -fsSL https://raw.githubusercontent.com/nathfavour/anyisland/master/install.sh | bash -s -- <owner/repo>
83+
exit 0
84+
fi
85+
86+
# Build logic when invoked by Anyisland
87+
echo "Building binary..."
88+
go build -o mytool ./cmd/mytool
89+
```
3790

3891
---
3992

40-
## 2. Anyisland-Aware Tools
93+
## 4. Anyisland-Aware Tools (Pulse & Auto-Registration)
4194

42-
Tools can integrate with the Anyisland ecosystem to enable features like auto-discovery and state management.
95+
Tools can integrate with the local Anyisland daemon (`anyisland daemon`) to enable automatic discovery, telemetry, and live registration.
4396

44-
### Auto-Registration
45-
A tool can register itself with the local Anyisland daemon (`anyisland daemon`) by sending a UDP packet to port `1995`.
97+
### Auto-Registration via UDP
98+
A tool can register itself with the local Anyisland daemon by sending a UDP packet to port `1995`:
4699

47-
**Example (Go):**
48100
```go
49101
import (
50-
"net"
51102
"encoding/json"
103+
"net"
52104
)
53105

54-
func Register() {
106+
func RegisterWithIsland() {
55107
packet := map[string]string{
56108
"op": "REGISTER",
57-
"name": "my-tool",
58-
"source": "github.com/me/my-tool",
109+
"name": "mytool",
110+
"source": "github.com/owner/mytool",
59111
"version": "v1.0.0",
60112
"type": "binary",
61113
}
62114
data, _ := json.Marshal(packet)
63-
conn, _ := net.Dial("udp", "localhost:1995")
64-
conn.Write(data)
115+
conn, err := net.Dial("udp", "127.0.0.1:1995")
116+
if err == nil {
117+
defer conn.Close()
118+
conn.Write(data)
119+
}
65120
}
66121
```
67122

68123
---
69124

70-
## 3. Contributing Official Packages
125+
## 5. Contributing Official Packages
71126

72-
Anyisland maintains a set of "Official Packages" for common utilities. These manifests are stored in the core repository under `packages/official/`.
127+
Anyisland maintains a set of "Official Packages" for common utilities in `packages/official/`.
73128

74129
To contribute:
75130
1. Fork the Anyisland repository.
76131
2. Create `packages/official/<name>/anyisland.json`.
77132
3. Submit a Pull Request.
78-
79-
Official packages are prioritized by the `anyisland install` command and are verified for platform compatibility.

‎docs/docs/lifecycle/installation.md‎

Lines changed: 14 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,24 @@
11
# Installation & System Integration
22

3-
Anyisland is designed to be installed without root permissions, living entirely within the user's home directory.
3+
Anyisland is designed to be installed without root permissions, living entirely within the user's home directory. It supports standalone installation as well as unified single-command installation for target tools.
44

5-
## The Bootstrap Process
6-
7-
The standard installation uses a universal bootstrap script:
5+
## The Universal Bootstrap Process
86

7+
### 1. Standalone Anyisland Installation
98
```bash
10-
curl -fsSL https://anyisland.io/install.sh | bash
9+
curl -fsSL https://raw.githubusercontent.com/nathfavour/anyisland/master/install.sh | bash
1110
```
1211

13-
### 1. Platform Detection
14-
The script detects the host OS and architecture (e.g., `linux-arm64`) to select the correct binary package.
12+
### 2. Single-Command Tool Installation (Target Hook)
13+
Any tool can use Anyisland as its zero-friction installer by passing its GitHub repository slug as an argument to the bootstrap script:
14+
15+
```bash
16+
curl -fsSL https://raw.githubusercontent.com/nathfavour/anyisland/master/install.sh | bash -s -- <owner/repo>
17+
```
1518

16-
### 2. Binary Hand-off
17-
The script downloads the specific binary and executes it with the `self-install` flag. This transfers the installation logic from the ephemeral shell script to the robust Anyisland binary itself.
19+
When a target repo is passed:
20+
1. The script checks if Anyisland is installed/up-to-date and bootstraps it if necessary.
21+
2. The script immediately executes `anyisland install <owner/repo>` to resolve dependencies and build the tool.
1822

1923
## System Integration (`self-install`)
2024

@@ -32,4 +36,4 @@ export PATH="$PATH:$HOME/.local/bin"
3236

3337
## Security Initialization
3438

35-
During the first installation, Anyisland generates a unique **Master Key** used for E2EE shell history and local vault encryption. This key is stored securely using the platform's native keyring (via the [PAL](../internal/pal/README.md)).
39+
During the first installation, Anyisland generates a unique **Master Key** used for E2EE shell history and local vault encryption. This key is stored securely using the platform's native keyring (via the Platform Abstraction Layer).

0 commit comments

Comments
 (0)