Skip to content

Commit 2be9546

Browse files
aygp-draygp-dr
committed
docs: Add shell archive pattern documentation
- Explain self-contained installer design - Document why this approach succeeded - Provide examples and best practices - Update build docs with shell archive details
1 parent d72af36 commit 2be9546

File tree

3 files changed

+233
-4
lines changed

3 files changed

+233
-4
lines changed

‎BUILD_TEST_DEPLOY.md‎

Lines changed: 21 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -21,19 +21,36 @@ sefaca status
2121
## Components
2222

2323
### 1. Core Script (`scripts/sefaca.sh`)
24-
- Main SEFACA functionality
24+
- Main SEFACA functionality
2525
- Updated with Git SHA for tracking
2626
- Sourced by installer
2727

2828
### 2. Installer (`scripts/install-standalone.sh`)
29-
- Self-contained shell archive
30-
- Embeds entire sefaca.sh
31-
- No external downloads
29+
- Self-contained shell archive (see [Shell Archive Pattern](SHELL_ARCHIVE_PATTERN.md))
30+
- Embeds entire sefaca.sh using heredoc
31+
- No external downloads after initial curl
32+
- ~350 lines including embedded content
3233

3334
### 3. Deployment
3435
- GitHub Gist for testing
3536
- Future: sefaca.dev CDN
3637

38+
## How the Shell Archive Works
39+
40+
The installer contains:
41+
```bash
42+
cat > "${INSTALL_DIR}/sefaca.sh" << 'SEFACA_EOF'
43+
#!/bin/bash
44+
# ... entire sefaca.sh script embedded here ...
45+
SEFACA_EOF
46+
```
47+
48+
This creates a self-extracting installer that:
49+
1. Downloads as a single file
50+
2. Extracts embedded content when run
51+
3. Sets up the complete SEFACA installation
52+
4. No network calls after initial download
53+
3754
## Build Process
3855

3956
1. **Update Version/SHA**

‎RELEASE_NOTES_v0.1.0.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# SEFACA v0.1.0 - Minimal Implementation
2+
3+
## 🎉 First Release
4+
5+
SEFACA (Safe Execution Framework for Autonomous Coding Agents) v0.1.0 provides core functionality for tracking and auditing AI agent command execution.
6+
7+
## ✨ Features
8+
9+
- **Context Tracking**: Every command is tagged with `[persona:agent:user@host(repo:branch)]`
10+
- **Audit Logging**: Full command history with timestamps and exit codes
11+
- **Execution Modes**: minimal, logging, controlled, forensic (v0 implements basic versions)
12+
- **Self-Contained Installation**: Single-command deployment via `curl|sh`
13+
- **Cross-Platform**: Tested on macOS, Linux, FreeBSD, ARM64
14+
15+
## 📦 Installation
16+
17+
```bash
18+
curl -sSL https://gist.github.com/aygp-dr/1cc80b2e8156c599f357786b552e462d/raw | sh
19+
source ~/.sefaca/bin/load-sefaca
20+
```
21+
22+
## 🚀 Quick Start
23+
24+
```bash
25+
# Track a command
26+
sefaca run make build
27+
28+
# View logs
29+
sefaca logs --tail 20
30+
31+
# Check status
32+
sefaca status
33+
```
34+
35+
## 📋 Web Team Deployment Instructions
36+
37+
To deploy SEFACA on sefaca.dev:
38+
39+
1. **Host the installer script** at `https://sefaca.dev/install.sh`
40+
- Use the content from `scripts/install-standalone.sh`
41+
- Ensure Content-Type: text/plain
42+
- Enable CORS for curl access
43+
44+
2. **Update installation command** in docs to:
45+
```bash
46+
curl -sSL https://sefaca.dev/install.sh | sh
47+
```
48+
49+
3. **Optional CDN setup**:
50+
- Cache for 5 minutes max (allows quick updates)
51+
- Log download metrics
52+
- Consider geographic distribution
53+
54+
4. **Testing checklist**:
55+
- [ ] Verify curl command works from various networks
56+
- [ ] Test on Linux, macOS, FreeBSD
57+
- [ ] Confirm no HTTPS certificate issues
58+
- [ ] Check download speed globally
59+
60+
## 🧪 Tested On
61+
62+
- ✅ FreeBSD 14.3
63+
- ✅ macOS Darwin 20.6.0
64+
- ✅ Linux ARM64 (Raspberry Pi)
65+
- ✅ Debian 12
66+
67+
## 📝 Documentation
68+
69+
- [Build/Test/Deploy Workflow](BUILD_TEST_DEPLOY.md)
70+
- [Deployment Experiment Report](DEPLOYMENT_EXPERIMENT.md)
71+
- [Quick Test Guide](TEST_SEFACA_NOW.md)
72+
73+
## 🔮 Future Plans
74+
75+
- Enhanced forensic mode with process tree tracking
76+
- Resource limit enforcement
77+
- Integration with CI/CD pipelines
78+
- Web dashboard for audit log visualization
79+
80+
## 🙏 Acknowledgments
81+
82+
Thanks to @aygp-dr for testing and deployment validation on pi.lan.
83+
84+
---
85+
86+
**Git SHA**: d72af36
87+
**Release Date**: 2025-07-31
88+
**Maintainer**: @defrecord

‎SHELL_ARCHIVE_PATTERN.md‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
# Shell Archive Pattern for SEFACA
2+
3+
## What is a Shell Archive?
4+
5+
A shell archive (shar) is a self-extracting script that contains embedded files. When executed, it creates the necessary files and directories on the target system. SEFACA uses this pattern for reliable, single-file distribution.
6+
7+
## How SEFACA Uses This Pattern
8+
9+
### 1. Structure of `install-standalone.sh`
10+
11+
```bash
12+
#!/bin/sh
13+
# Installation script header
14+
# - Sets up variables
15+
# - Creates directories
16+
# - Shows banner
17+
18+
# Embedded file using heredoc
19+
cat > "${INSTALL_DIR}/sefaca.sh" << 'SEFACA_EOF'
20+
#!/bin/bash
21+
# This is the entire sefaca.sh script
22+
# ... hundreds of lines of code ...
23+
SEFACA_EOF
24+
25+
# Post-installation
26+
# - Set permissions
27+
# - Create loader script
28+
# - Show instructions
29+
```
30+
31+
### 2. Key Benefits
32+
33+
- **Single Download**: One `curl` command gets everything
34+
- **No Network Dependencies**: After initial download, no more network calls
35+
- **No 404 Errors**: Can't fail to find secondary files
36+
- **Self-Contained**: Everything needed is in one file
37+
- **Version Locked**: The embedded content matches the installer version
38+
39+
### 3. The Installation Flow
40+
41+
```
42+
User runs curl
43+
↓
44+
Downloads install-standalone.sh (350+ lines)
45+
↓
46+
Shell executes the script
47+
↓
48+
Script creates ~/.sefaca/bin/
49+
↓
50+
Script writes sefaca.sh (embedded content)
51+
↓
52+
Script creates load-sefaca wrapper
53+
↓
54+
Installation complete!
55+
```
56+
57+
### 4. Why Not Download sefaca.sh Separately?
58+
59+
Our failed attempts taught us:
60+
- GitHub raw URLs can 404
61+
- Gist URLs need exact formatting
62+
- Multiple downloads = multiple failure points
63+
- Caching delays cause version mismatches
64+
65+
### 5. The Heredoc Technique
66+
67+
```bash
68+
cat > "output_file" << 'END_MARKER'
69+
This content is written exactly as-is.
70+
No variable expansion because marker is quoted.
71+
Perfect for embedding shell scripts.
72+
END_MARKER
73+
```
74+
75+
Using `'SEFACA_EOF'` (quoted) prevents the shell from interpreting variables in the embedded script.
76+
77+
## Creating Your Own Shell Archive
78+
79+
1. **Start with your installer template**:
80+
```bash
81+
#!/bin/sh
82+
set -e
83+
echo "Installing..."
84+
mkdir -p "$HOME/.myapp"
85+
```
86+
87+
2. **Embed your application**:
88+
```bash
89+
cat > "$HOME/.myapp/app.sh" << 'APP_EOF'
90+
#!/bin/bash
91+
# Your entire application here
92+
echo "Hello from embedded app!"
93+
APP_EOF
94+
chmod +x "$HOME/.myapp/app.sh"
95+
```
96+
97+
3. **Test the archive**:
98+
```bash
99+
sh your-installer.sh
100+
```
101+
102+
## Real-World Examples
103+
104+
- **Rustup**: Rust's installer uses this pattern
105+
- **nvm**: Node Version Manager installation
106+
- **rbenv-installer**: Ruby version management
107+
- **SEFACA**: Our implementation for AI agent safety
108+
109+
## Best Practices
110+
111+
1. **Use quoted heredocs** to prevent variable expansion
112+
2. **Include version info** in both installer and embedded content
113+
3. **Make scripts executable** with `chmod +x`
114+
4. **Provide clear post-install instructions**
115+
5. **Test on minimal shells** (sh, not just bash)
116+
117+
## The SEFACA Success
118+
119+
From our deployment experiment:
120+
- ❌ Multi-file download approach: Failed with 404s
121+
- ❌ GitHub raw URLs: Caching and availability issues
122+
- ✅ Shell archive pattern: Worked first time on pi.lan!
123+
124+
This pattern enabled our "curl|sh" installation to work reliably across platforms.

0 commit comments

Comments
 (0)