A structured procedural language w/ a Lisp runtime / Rust ATProto bridge, to build a working TUI Bsky client
Consolidate and align Superplan documentation
+130
-334
+6
docs/README.md
+6
docs/README.md
+10
-64
docs/bridge-abi.md
+10
-64
docs/bridge-abi.md
···
1
-
# AT Proto Bridge ABI
1
+
# Bridge ABI
2
2
3
-
## Overview
3
+
Communication via stdin/stdout using NDJSON.
4
4
5
-
Superplan runtime communicates with the bridge using:
6
-
- stdin/stdout
7
-
- newline-delimited JSON (NDJSON)
5
+
Request:
6
+
{"id":1,"op":"profile","actor":"handle"}
8
7
9
-
## Request Format
10
-
11
-
```json
12
-
{"id":1,"op":"timeline","cursor":""}
13
-
```
14
-
15
-
## Response Format
16
-
17
-
```json
8
+
Response:
18
9
{"id":1,"ok":true,"value":{...}}
19
-
```
20
-
21
-
Error:
22
-
```json
23
-
{"id":1,"ok":false,"error":"message"}
24
-
```
25
-
26
-
## Operations
27
-
28
-
### login
29
-
```json
30
-
{"op":"login","identifier":"user","password":"app-password"}
31
-
```
32
-
33
-
### timeline
34
-
```json
35
-
{"op":"timeline","cursor":""}
36
-
```
37
10
38
-
### profile
39
-
```json
40
-
{"op":"profile","actor":"did_or_handle"}
41
-
```
11
+
Operations:
12
+
login, timeline, profile, thread, post, notifications
42
13
43
-
### thread
44
-
```json
45
-
{"op":"thread","uri":"at://..."}
46
-
```
47
-
48
-
### post
49
-
```json
50
-
{"op":"post","text":"hello"}
51
-
```
52
-
53
-
### notifications
54
-
```json
55
-
{"op":"notifications"}
56
-
```
57
-
58
-
## Mapping to AT Proto
59
-
60
-
- login → com.atproto.server.createSession
61
-
- timeline → app.bsky.feed.getTimeline
62
-
- profile → app.bsky.actor.getProfile
63
-
- thread → app.bsky.feed.getPostThread
64
-
- post → com.atproto.repo.createRecord
65
-
66
-
## Notes
67
-
68
-
- Bridge handles auth + refresh tokens
69
-
- Superplan runtime never sees tokens
70
-
- JSON is returned as-is for runtime inspection
14
+
Notes:
15
+
- bridge handles auth + tokens
16
+
- Superplan runtime does not see credentials beyond login input
+21
-52
docs/grammar-ebnf.md
+21
-52
docs/grammar-ebnf.md
···
1
-
# Superplan-26 Grammar (EBNF)
1
+
# Superplan Grammar (EBNF)
2
2
3
-
program = "PROGRAM" ident decls "BEGIN" stmts "END" ;
3
+
program = "PROGRAM" ident decls "BEGIN" stmts "END" ;
4
4
5
-
decls = { decl } ;
6
-
decl = type ident | array_decl ;
5
+
decls = { decl } ;
6
+
decl = type ident | array_decl ;
7
7
8
-
array_decl = "ARRAY" type ident "[" number "]" ;
8
+
array_decl = "ARRAY" type ident "[" number "]" ;
9
9
10
-
type = "INTEGER" | "BOOLEAN" | "STRING" | "JSON" ;
10
+
type = "INTEGER" | "BOOLEAN" | "STRING" | "JSON" ;
11
11
12
-
stmts = { stmt } ;
12
+
stmts = { stmt } ;
13
13
14
-
stmt =
15
-
assign
16
-
| write
17
-
| read
18
-
| if_stmt
19
-
| while_stmt
20
-
| for_stmt
21
-
| call
22
-
| stop
23
-
| proc_decl ;
14
+
stmt =
15
+
ident "=" expr
16
+
| "WRITE" "(" expr ")"
17
+
| ident "=" "READLINE" "(" ")"
18
+
| "IF" expr "THEN" stmts "END"
19
+
| "WHILE" expr "DO" stmts "END"
20
+
| "CALL" ident "(" [ args ] ")"
21
+
| "STOP"
22
+
| proc ;
24
23
25
-
assign = ident "=" expr ;
24
+
proc = "PROCEDURE" ident "(" [ params ] ")" "BEGIN" stmts "END" ;
26
25
27
-
write = "WRITE" "(" expr ")" ;
28
-
29
-
read = ident "=" "READLINE" "(" ")" ;
30
-
31
-
if_stmt = "IF" expr "THEN" stmts "END" ;
32
-
33
-
while_stmt = "WHILE" expr "DO" stmts "END" ;
34
-
35
-
for_stmt = "FOR" ident "=" expr "TO" expr "STEP" expr "DO" stmts "END" ;
36
-
37
-
call = "CALL" ident "(" [ args ] ")" ;
38
-
39
-
args = expr { "," expr } ;
40
-
41
-
proc_decl = "PROCEDURE" ident "(" [ params ] ")" "BEGIN" stmts "END" ;
42
-
43
-
params = param { "," param } ;
44
-
param = type ident ;
26
+
expr = term { ("+"|"-") term } ;
27
+
term = factor { ("*"|"/") factor } ;
45
28
46
-
stop = "STOP" ;
47
-
48
-
expr = term { ("+" | "-") term } ;
49
-
term = factor { ("*" | "/") factor } ;
50
-
51
-
factor =
52
-
ident
53
-
| number
54
-
| string
55
-
| "(" expr ")"
56
-
| func_call ;
29
+
factor = ident | number | string | "(" expr ")" | func ;
57
30
58
-
func_call = ident "(" [ args ] ")" ;
59
-
60
-
ident = letter { letter | digit | "_" } ;
61
-
number = digit { digit } ;
62
-
string = '"' { any_char } '"' ;
31
+
func = ident "(" [ args ] ")" ;
-165
docs/superplan-26-spec.md
-165
docs/superplan-26-spec.md
···
1
-
# Superplan-26 Specification (v0)
2
-
3
-
## Overview
4
-
5
-
Superplan-26 is a modern reconstruction inspired by early high-level languages such as Superplan and ALGOL.
6
-
7
-
It is:
8
-
- procedural
9
-
- statically typed
10
-
- deterministic
11
-
- designed for terminal applications and system control
12
-
13
-
## Program Structure
14
-
15
-
```text
16
-
PROGRAM NAME
17
-
18
-
<declarations>
19
-
20
-
BEGIN
21
-
<statements>
22
-
END
23
-
```
24
-
25
-
## Types
26
-
27
-
### Primitive
28
-
- INTEGER
29
-
- BOOLEAN
30
-
- STRING
31
-
- JSON
32
-
33
-
### Composite
34
-
```text
35
-
ARRAY <TYPE> NAME[N]
36
-
```
37
-
38
-
Example:
39
-
```text
40
-
INTEGER I
41
-
STRING CMD
42
-
JSON TL
43
-
ARRAY STRING LINES[10]
44
-
```
45
-
46
-
## Statements
47
-
48
-
### Assignment
49
-
```text
50
-
X = 10
51
-
NAME = "hello"
52
-
```
53
-
54
-
### Output
55
-
```text
56
-
WRITE("TEXT")
57
-
WRITE(NAME)
58
-
```
59
-
60
-
### Input
61
-
```text
62
-
NAME = READLINE()
63
-
```
64
-
65
-
### Conditional
66
-
```text
67
-
IF X = 1 THEN
68
-
WRITE("ONE")
69
-
END
70
-
```
71
-
72
-
### Loop (WHILE)
73
-
```text
74
-
WHILE TRUE DO
75
-
CMD = READLINE()
76
-
END
77
-
```
78
-
79
-
### Loop (FOR)
80
-
```text
81
-
FOR I = 0 TO 10 STEP 1 DO
82
-
WRITE("ROW")
83
-
END
84
-
```
85
-
86
-
### Procedure
87
-
```text
88
-
PROCEDURE SHOW(JSON TL)
89
-
BEGIN
90
-
WRITE("DATA")
91
-
END
92
-
```
93
-
94
-
### Call
95
-
```text
96
-
CALL SHOW(TL)
97
-
```
98
-
99
-
### Stop
100
-
```text
101
-
STOP
102
-
```
103
-
104
-
## Expressions
105
-
106
-
### Arithmetic
107
-
- `+ - * /`
108
-
109
-
### Comparison
110
-
- `= <> < <= > >=`
111
-
112
-
### Boolean
113
-
- `AND OR NOT`
114
-
115
-
## Built-in Functions
116
-
117
-
### IO
118
-
- `WRITE(STRING)`
119
-
- `READLINE() -> STRING`
120
-
121
-
### JSON
122
-
- `JSON_PARSE(STRING) -> JSON`
123
-
- `JSON_STRINGIFY(JSON) -> STRING`
124
-
- `JSON_GET(JSON, STRING) -> JSON`
125
-
- `JSON_INDEX(JSON, INTEGER) -> JSON`
126
-
- `JSON_LEN(JSON) -> INTEGER`
127
-
- `JSON_TYPE(JSON) -> STRING`
128
-
- `JSON_STRING(JSON) -> STRING`
129
-
- `JSON_NUMBER(JSON) -> INTEGER`
130
-
- `JSON_BOOL(JSON) -> BOOLEAN`
131
-
- `JSON_IS_NULL(JSON) -> BOOLEAN`
132
-
133
-
### AT Proto Bridge
134
-
- `ATP_LOGIN(STRING, STRING) -> BOOLEAN`
135
-
- `ATP_TIMELINE(STRING) -> JSON`
136
-
- `ATP_PROFILE(STRING) -> JSON`
137
-
- `ATP_THREAD(STRING) -> JSON`
138
-
- `ATP_POST(STRING) -> BOOLEAN`
139
-
- `ATP_NOTIFICATIONS() -> JSON`
140
-
141
-
## Example
142
-
143
-
```text
144
-
PROGRAM DEMO
145
-
146
-
JSON TL
147
-
JSON FEED
148
-
JSON ITEM
149
-
STRING TEXT
150
-
151
-
BEGIN
152
-
TL = ATP_TIMELINE("")
153
-
FEED = JSON_GET(TL, "feed")
154
-
ITEM = JSON_INDEX(FEED, 0)
155
-
TEXT = JSON_STRING(JSON_GET(ITEM, "text"))
156
-
WRITE(TEXT)
157
-
END
158
-
```
159
-
160
-
## Notes
161
-
162
-
- No floating point in v0
163
-
- No recursion in v0
164
-
- JSON is opaque runtime value
165
-
- All networking is delegated to bridge
+71
docs/superplan-language-spec-v0.1.md
+71
docs/superplan-language-spec-v0.1.md
···
1
+
# Superplan Specification (v0.1)
2
+
3
+
## Overview
4
+
5
+
Superplan is a structured procedural language designed for system control and protocol-driven applications.
6
+
7
+
## Program Structure
8
+
9
+
PROGRAM NAME
10
+
11
+
<declarations>
12
+
<procedures>
13
+
14
+
BEGIN
15
+
<statements>
16
+
END
17
+
18
+
## Types
19
+
20
+
INTEGER, BOOLEAN, STRING, JSON
21
+
22
+
ARRAY TYPE NAME[N]
23
+
24
+
## Statements
25
+
26
+
Assignment:
27
+
X = expr
28
+
29
+
Output:
30
+
WRITE(expr)
31
+
32
+
Input:
33
+
X = READLINE()
34
+
35
+
Conditional:
36
+
IF expr THEN ... END
37
+
38
+
Loop:
39
+
WHILE expr DO ... END
40
+
41
+
Procedure:
42
+
PROCEDURE NAME(params)
43
+
44
+
Call:
45
+
CALL NAME(args)
46
+
47
+
Stop:
48
+
STOP
49
+
50
+
## Expressions
51
+
52
+
- literals
53
+
- variables
54
+
- function calls
55
+
- binary operators
56
+
57
+
## Built-ins
58
+
59
+
WRITE, READLINE
60
+
61
+
JSON:
62
+
JSON_GET, JSON_INDEX, JSON_STRING, JSON_PARSE, JSON_STRINGIFY
63
+
64
+
AT Proto:
65
+
ATP_LOGIN, ATP_TIMELINE, ATP_PROFILE, ATP_POST, ATP_WHOAMI
66
+
67
+
## Notes
68
+
69
+
- interpreter-based
70
+
- JSON opaque
71
+
- networking via bridge only
+22
-53
docs/vision.md
+22
-53
docs/vision.md
···
1
-
# Superplan AT Proto Project
1
+
# Superplan Project
2
2
3
3
## Vision
4
4
5
-
Build a working Bluesky / AT Protocol terminal client using a stack centered on **historical programming languages**, not modern frameworks.
5
+
Build a real, working terminal client for AT Protocol (Bluesky) using a stack centered on historical programming language ideas.
6
6
7
-
This is not nostalgia. This is a systems experiment:
7
+
This is a systems experiment:
8
8
9
-
- What happens when early-language design meets modern decentralized protocols?
10
-
- How far can we push pre-modern language models into real networked software?
9
+
- Can early language design scale into modern networked systems?
10
+
- How far can structured procedural languages go today?
11
11
12
-
## Core Stack
12
+
## Stack
13
13
14
-
- **Superplan-26** → primary user-facing language
15
-
- **Lisp** → compiler tooling, AST transforms, meta-layer
16
-
- **ALGOL influence** → structure, readability, block discipline
17
-
- **Plankalkül influence** → typed data and structured values
18
-
- **Rust/C bridge** → minimal AT Proto edge (HTTP, JSON, auth)
14
+
- Superplan → primary language
15
+
- Lisp → parser, AST, interpreter
16
+
- ALGOL influence → structure
17
+
- Plankalkül influence → typed thinking
18
+
- Rust bridge → network edge (AT Proto)
19
19
20
-
## Design Principles
20
+
## Principles
21
21
22
-
### 1. Old languages first
23
-
Push as much logic as possible into:
24
-
- Superplan
25
-
- Lisp
22
+
1. Keep logic in Superplan/Lisp
23
+
2. Use modern code only at the edge
24
+
3. Deterministic, explicit execution
25
+
4. Practical, not nostalgic
26
26
27
-
### 2. Modern code only at the edge
28
-
Rust/C is allowed only for:
29
-
- HTTPS / XRPC
30
-
- JSON parsing/serialization
31
-
- secure token handling
32
-
- IPC
27
+
## Target
33
28
34
-
### 3. Deterministic and simple
35
-
- no hidden magic
36
-
- no runtime surprises
37
-
- explicit flow
29
+
A working terminal client:
38
30
39
-
### 4. Historical but usable
40
-
This is not a museum recreation.
41
-
42
-
Superplan-26 is:
43
-
- inspired by history
44
-
- shaped for real execution
45
-
46
-
## Target
47
-
48
-
A working terminal client that can:
49
31
- login
50
-
- read timeline
51
-
- view profiles
52
-
- view threads
53
-
- post messages
32
+
- timeline
33
+
- profile
34
+
- post
54
35
55
-
All driven from Superplan programs.
56
-
57
-
## Philosophy
58
-
59
-
> The device speaks better than 100 slides.
60
-
61
-
This repo should demonstrate:
62
-
- a language
63
-
- a compiler
64
-
- a runtime
65
-
- a real protocol integration
66
-
67
-
All grounded in early computing ideas.
36
+
Driven entirely from Superplan programs.