A structured procedural language w/ a Lisp runtime / Rust ATProto bridge, to build a working TUI Bsky client
Rewrite README for public launch
+158
-33
+158
-33
README.md
+158
-33
README.md
···
1
-
# Superplan AT Proto Project
1
+
# Superplan
2
2
3
-
Historical-language systems lab for a terminal Bluesky / AT Protocol client.
3
+
Superplan is a structured, procedural programming language inspired by early high-level languages such as ALGOL, Plankalkül, and Superplan — reimagined for modern systems experimentation.
4
4
5
-
## Stack
5
+
This repository contains a working system where Superplan programs interact with the AT Protocol (Bluesky) through a Lisp runtime and a Rust bridge.
6
6
7
-
- Superplan-26: main visible language
8
-
- Lisp: parser, interpreter, meta-tooling
9
-
- ALGOL influence: syntax and block structure
10
-
- Plankalkül influence: typed data model ideas
11
-
- Rust bridge: protocol edge only
7
+
---
12
8
13
-
## Current state
9
+
## Why Superplan
14
10
15
-
This repo currently includes:
11
+
This project explores a simple question:
16
12
17
-
- vision and language docs
18
-
- Superplan example program
19
-
- Common Lisp lexer, parser, AST, pretty printer, interpreter
20
-
- fake Lisp bridge process over stdin/stdout
21
-
- fake Rust bridge preserving the same ABI
13
+
> What if early structured languages evolved directly into modern networked systems?
22
14
23
-
## Quick start
15
+
Instead of building everything in contemporary languages, this stack is deliberately split:
24
16
25
-
### 1. Install prerequisites
17
+
* **Superplan** — visible application layer
18
+
* **Common Lisp** — parser, AST, interpreter
19
+
* **Rust** — protocol edge (AT Proto / Bluesky)
26
20
27
-
- SBCL
28
-
- Rust / Cargo
21
+
The result is a real system capable of:
22
+
23
+
* login
24
+
* profile lookup
25
+
* home timeline fetch
26
+
* posting content
27
+
28
+
---
29
+
30
+
## Architecture
31
+
32
+
```
33
+
Superplan (.spl)
34
+
↓
35
+
Lisp lexer / parser / AST / interpreter
36
+
↓
37
+
Bridge client (JSON over stdio)
38
+
↓
39
+
Rust AT Proto bridge
40
+
↓
41
+
Bluesky / AT Protocol
42
+
```
43
+
44
+
---
45
+
46
+
## Example
47
+
48
+
```superplan
49
+
PROGRAM HELLO
50
+
51
+
BEGIN
52
+
WRITE("HELLO SUPERPLAN")
53
+
END
54
+
```
55
+
56
+
---
57
+
58
+
## Real Example (Bluesky)
59
+
60
+
```superplan
61
+
PROGRAM PROFILE
62
+
63
+
STRING ACTOR
64
+
JSON PROFILE
65
+
66
+
PROCEDURE SHOW_PROFILE(JSON PROFILE)
67
+
BEGIN
68
+
WRITE("HANDLE:")
69
+
WRITE(JSON_STRING(JSON_GET(PROFILE, "handle")))
70
+
END
71
+
72
+
BEGIN
73
+
WRITE("ACTOR:")
74
+
ACTOR = READLINE()
75
+
PROFILE = ATP_PROFILE(ACTOR)
76
+
CALL SHOW_PROFILE(PROFILE)
77
+
END
78
+
```
79
+
80
+
---
81
+
82
+
## Getting Started
83
+
84
+
### Requirements
85
+
86
+
* SBCL (Common Lisp)
87
+
* Rust / Cargo
29
88
30
-
### 2. Run the Rust fake bridge directly
89
+
### Build the bridge
31
90
32
91
```bash
33
-
cd bridge
34
-
cargo run
92
+
cargo build --manifest-path bridge/Cargo.toml
35
93
```
36
94
37
-
### 3. Run the Lisp parser + interpreter
38
-
39
-
From repo root:
95
+
### Run the Superplan program
40
96
41
97
```bash
42
98
sbcl --script lisp-tools/parser/run.lisp
43
99
```
44
100
45
-
By default, the interpreter tries to launch the Rust bridge first and falls back to the Lisp bridge if Rust is unavailable.
101
+
---
102
+
103
+
## Example Programs
104
+
105
+
Located in:
106
+
107
+
```
108
+
superplan/examples/
109
+
```
110
+
111
+
Included:
112
+
113
+
* `home.spl` — interactive client (timeline, profile, post, whoami)
114
+
* `profile.spl` — profile lookup
115
+
* `post.spl` — post creation
116
+
117
+
---
118
+
119
+
## File Extension
120
+
121
+
Superplan source files use:
122
+
123
+
```
124
+
.spl
125
+
```
126
+
127
+
(`.sp` is avoided due to GitHub Linguist mapping to SourcePawn)
128
+
129
+
---
130
+
131
+
## Project Status
132
+
133
+
Early but functional.
134
+
135
+
Currently working:
136
+
137
+
* Superplan parsing and execution
138
+
* terminal client written in Superplan
139
+
* real Bluesky profile lookup
140
+
* real authenticated timeline fetch
141
+
* real post creation
142
+
143
+
Not yet implemented:
144
+
145
+
* automatic token refresh
146
+
* static type checking
147
+
* compiled backend
148
+
149
+
---
150
+
151
+
## Repo Layout
152
+
153
+
* `docs/` — vision, spec, grammar, bridge ABI
154
+
* `superplan/examples/` — `.spl` programs
155
+
* `lisp-tools/parser/` — lexer, parser, AST, runner
156
+
* `lisp-tools/interpreter/` — runtime + bridge client
157
+
* `bridge/` — Rust AT Proto bridge
158
+
* `editors/vscode/superplan/` — VS Code language support
159
+
160
+
---
161
+
162
+
## Design Influences
163
+
164
+
* ALGOL — structure and control flow
165
+
* Plankalkül — typed data model thinking
166
+
* Lisp — language tooling and meta-layer
167
+
* modern API systems — practical integration
168
+
169
+
---
170
+
171
+
## License
172
+
173
+
MIT
174
+
175
+
---
46
176
47
-
## Repo layout
177
+
## Author
48
178
49
-
- `docs/` — vision, language spec, grammar, ABI
50
-
- `superplan/examples/` — `.sp` examples
51
-
- `lisp-tools/parser/` — lexer, parser, AST, pretty printer, runner
52
-
- `lisp-tools/interpreter/` — environment, bridge client, interpreter
53
-
- `lisp-tools/bridge/` — fake Lisp bridge
54
-
- `bridge/` — fake Rust bridge
179
+
Former Lab