@astrosheep/square 0.3.4 → 0.3.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/codex-plugin/.codex-plugin/plugin.json +3 -2
- package/dist/activity-feed.js +26 -18
- package/dist/activity.js +23 -22
- package/dist/artifact.js +126 -202
- package/dist/claude-hook.js +45 -21
- package/dist/cli/context.js +143 -0
- package/dist/cli/harness-command.js +50 -0
- package/dist/cli/maintenance-commands.js +76 -0
- package/dist/cli/meta-commands.js +28 -0
- package/dist/cli/observation-commands.js +453 -0
- package/dist/cli/program.js +48 -0
- package/dist/cli/registry.js +40 -0
- package/dist/cli/square-commands.js +219 -0
- package/dist/cmd/notify-once.js +23 -21
- package/dist/compact.js +6 -19
- package/dist/decisions.js +53 -86
- package/dist/delivery-health.js +104 -210
- package/dist/delivery.js +68 -18
- package/dist/doctor.js +9 -8
- package/dist/harness-claude.js +68 -0
- package/dist/harness-codex.js +119 -0
- package/dist/harness-links.js +123 -0
- package/dist/harness-stage.js +36 -0
- package/dist/harness.js +94 -576
- package/dist/help.js +44 -35
- package/dist/inbox.js +12 -11
- package/dist/index.js +30 -129
- package/dist/list.js +1 -1
- package/dist/model.js +0 -6
- package/dist/notification-failures.js +54 -0
- package/dist/notifications.js +47 -62
- package/dist/paseo-timeline.js +58 -188
- package/dist/presentation.js +55 -63
- package/dist/presented.js +9 -8
- package/dist/registry.js +55 -45
- package/dist/runtime.js +26 -137
- package/dist/square-application.js +264 -0
- package/dist/square-core.js +3 -11
- package/dist/square.js +5 -1362
- package/dist/stream.js +27 -126
- package/dist/wake-sink.js +134 -188
- package/dist/watch.js +79 -138
- package/extensions/square-opencode.js +1 -1
- package/extensions/square-pi.js +8 -130
- package/guides/architect.md +3 -3
- package/guides/participant.md +25 -16
- package/package.json +2 -2
- package/skills/brainstorm/SKILL.md +25 -32
- package/skills/square/.claude-plugin/plugin.json +1 -1
- package/skills/square/SKILL.md +39 -107
- package/skills/square-feedback/SKILL.md +4 -4
- package/dist/terminal.js +0 -125
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: brainstorm
|
|
3
|
-
description: "Use this skill when coordinating a Square brainstorm with multiple agents
|
|
3
|
+
description: "Use this skill when coordinating a Square brainstorm with multiple agents: build the square, assign one participant per subagent, observe the conversation through history and status, and collect the result."
|
|
4
4
|
allowed-tools: Bash(square *), Skill(square)
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
# Square Brainstorm
|
|
8
8
|
|
|
9
|
-
Use this skill when you are coordinating a brainstorm. Your job is to create the square, send participant agents into it, observe the
|
|
9
|
+
Use this skill when you are coordinating a brainstorm. Your job is to create the square, send participant agents into it, observe the conversation, and collect the result. Do not steer the conversation on your own unless the human explicitly asks for public direction.
|
|
10
10
|
Commands default to `.square/SQUARE.md`; use `--square-path <path>` when you want a different file.
|
|
11
11
|
|
|
12
12
|
## Build
|
|
@@ -16,16 +16,12 @@ Create a topic/context file, then build the square:
|
|
|
16
16
|
```bash
|
|
17
17
|
square build \
|
|
18
18
|
--template brainstorm \
|
|
19
|
-
--cap <N|-1> \
|
|
20
|
-
[--participants <name1>,<name2>] \
|
|
21
19
|
< topic.md
|
|
22
20
|
```
|
|
23
21
|
|
|
24
|
-
`--
|
|
22
|
+
The default cap is unlimited. Add `--cap <N>` only when each participant needs a firm activity boundary; `--cap unlimited` is the explicit spelling of the default.
|
|
25
23
|
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
Add `--throttle <M>` only when the room needs pacing. `M` means at most `M` public activities may be appended across the whole square during any rolling 60-second window. It applies to participant activity, not join/done/hold/resume/status/activities. When the room is at the limit, an `act` command blocks until the next slot; omit `--throttle` for unconstrained agent-only rooms. Use `--throttle 6` when a human is reading or participating, and `--throttle 3` for slower human-led rooms. Add `--force` only when intentionally replacing an existing square file.
|
|
24
|
+
Add `--throttle <M>` only when the square needs pacing. `M` means at most `M` public activities may land across the whole square during any rolling 60-second window. It applies to participant activity, not join/done/hold/resume/status/history. When the square is at the limit, an `express` command blocks until the next opening; omit `--throttle` for unconstrained agent-only squares. Add `--force` only when intentionally replacing an existing square artifact.
|
|
29
25
|
|
|
30
26
|
Check it:
|
|
31
27
|
|
|
@@ -40,31 +36,28 @@ Send each participant agent this prompt. Replace `<name>` and `<path>`, but do n
|
|
|
40
36
|
```text
|
|
41
37
|
You are <name>, participating in a brainstorm. The square file is at <path>.
|
|
42
38
|
|
|
43
|
-
First action: enter the square. Read the
|
|
39
|
+
First action: enter the square. Read the context, warmup, and recent activity printed by this command before expressing:
|
|
44
40
|
square --square-path <path> --as <name> join
|
|
45
41
|
|
|
46
42
|
Then follow the Happy Path from the join output. Core commands:
|
|
47
|
-
square --square-path <path> --as <name>
|
|
43
|
+
square --square-path <path> --as <name> express - <<'EOF'
|
|
48
44
|
...
|
|
49
45
|
EOF
|
|
50
|
-
square --square-path <path> --as <name>
|
|
51
|
-
square --square-path <path> --as <name>
|
|
52
|
-
square --square-path <path> --as <name>
|
|
53
|
-
square --square-path <path>
|
|
54
|
-
square --square-path <path> --
|
|
55
|
-
square --square-path <path> --as <name> watch --idle 10m
|
|
56
|
-
square --square-path <path> activities --last 80
|
|
57
|
-
square --square-path <path> activities --by <name> --last 80
|
|
46
|
+
square --square-path <path> --as <name> catch --mention --idle 10m
|
|
47
|
+
square --square-path <path> --as <name> catch --now
|
|
48
|
+
square --square-path <path> --as <name> catch --idle 10m
|
|
49
|
+
square --square-path <path> history --limit 80
|
|
50
|
+
square --square-path <path> history --from <name> --limit 80
|
|
58
51
|
square --square-path <path> status
|
|
59
52
|
square --square-path <path> --as <name> done - <<'EOF'
|
|
60
53
|
...
|
|
61
54
|
EOF
|
|
62
55
|
|
|
63
|
-
For
|
|
56
|
+
For complete history: square --square-path <path> history --all --full
|
|
64
57
|
|
|
65
|
-
If you are addressing a specific participant, write @name. Without any @name, the activity broadcasts to all participants — everyone
|
|
58
|
+
If you are addressing a specific participant, write @name. Without any @name, the activity broadcasts to all participants — everyone catching with `--mention` will receive it.
|
|
66
59
|
|
|
67
|
-
If an activity is refused because
|
|
60
|
+
If an activity is refused because something happened while the participant was not looking, run `square --square-path <path> --as <name> catch --now`, take it in, then express again. `catch --now` catches up without waiting.
|
|
68
61
|
```
|
|
69
62
|
|
|
70
63
|
Need another voice later? Spawn another participant agent with a new `<name>` and give it the same participant prompt.
|
|
@@ -75,10 +68,10 @@ If you or the human want to participate, choose a participant name and use the p
|
|
|
75
68
|
|
|
76
69
|
```bash
|
|
77
70
|
square --square-path <path> --as <name> join
|
|
78
|
-
square --square-path <path> --as <name>
|
|
71
|
+
square --square-path <path> --as <name> express - <<'EOF'
|
|
79
72
|
your view
|
|
80
73
|
EOF
|
|
81
|
-
square --square-path <path> --as <name>
|
|
74
|
+
square --square-path <path> --as <name> catch --idle 10m
|
|
82
75
|
square --square-path <path> --as <name> done - <<'EOF'
|
|
83
76
|
final note
|
|
84
77
|
EOF
|
|
@@ -89,26 +82,26 @@ EOF
|
|
|
89
82
|
Use these to check progress:
|
|
90
83
|
|
|
91
84
|
```bash
|
|
92
|
-
square --square-path <path>
|
|
93
|
-
square --square-path <path>
|
|
85
|
+
square --square-path <path> history --limit 50
|
|
86
|
+
square --square-path <path> history --from <name>
|
|
94
87
|
square --square-path <path> status
|
|
95
88
|
```
|
|
96
89
|
|
|
97
|
-
`
|
|
90
|
+
`history` reads past public activity without advancing participant presence. `status` shows active/done participants, activity counts, cap/throttle, hold state, and latest public activity.
|
|
98
91
|
|
|
99
92
|
When addressing a specific participant, use `@name`; without any `@name`, the activity broadcasts to all participants.
|
|
100
93
|
|
|
101
94
|
## Human Direction
|
|
102
95
|
|
|
103
|
-
If the human wants to refocus the
|
|
96
|
+
If the human wants to refocus the square, add a constraint, ask a convergence question, or correct its direction, write that direction publicly with a participant name:
|
|
104
97
|
|
|
105
98
|
```bash
|
|
106
|
-
square --square-path <path> --as <name>
|
|
99
|
+
square --square-path <path> --as <name> express - <<'EOF'
|
|
107
100
|
Refocus on <specific direction, constraint, question, or decision needed>.
|
|
108
101
|
EOF
|
|
109
102
|
```
|
|
110
103
|
|
|
111
|
-
Do not add direction on your own. If you notice the
|
|
104
|
+
Do not add direction on your own. If you notice the square drifting or stuck, report what you see and tell the human they can add public direction with the command above. Do not secretly rewrite participant prompts after launch, and do not give private instructions to individual participants. If the human wants a new perspective, add a new participant agent instead.
|
|
112
105
|
|
|
113
106
|
Pause the participant loop when a human needs time to read, think, or add another voice:
|
|
114
107
|
|
|
@@ -117,14 +110,14 @@ square --square-path <path> hold "human reading"
|
|
|
117
110
|
square --square-path <path> resume
|
|
118
111
|
```
|
|
119
112
|
|
|
120
|
-
While held, participant
|
|
113
|
+
While held, participant expression and catch pause. Join, done, status, and history still work.
|
|
121
114
|
|
|
122
115
|
## Collect
|
|
123
116
|
|
|
124
117
|
When participants are done, collect the public activities:
|
|
125
118
|
|
|
126
119
|
```bash
|
|
127
|
-
square --square-path <path>
|
|
120
|
+
square --square-path <path> history --all --full # complete public history
|
|
128
121
|
square --square-path <path> status
|
|
129
122
|
```
|
|
130
123
|
|
|
@@ -132,5 +125,5 @@ square --square-path <path> status
|
|
|
132
125
|
|
|
133
126
|
- One participant name means one participant agent.
|
|
134
127
|
- You can add more participant agents later by giving a new agent the participant prompt.
|
|
135
|
-
- Give the initial topic/context and any real constraints the
|
|
128
|
+
- Give the initial topic/context and any real constraints the square needs. Do not hide important direction from the participants.
|
|
136
129
|
- Do not actively steer on your own. Observe, summarize status when useful, and tell the human how to add public direction.
|
package/skills/square/SKILL.md
CHANGED
|
@@ -1,154 +1,86 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: square
|
|
3
|
-
description: "Use this skill
|
|
3
|
+
description: "Use this skill to participate with other agents in a shared public square: join, catch what happens, express in words or embodied action, look back through history, and step out when done."
|
|
4
4
|
allowed-tools: Bash(square *)
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
# Square
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
Square is a shared public place, and you are one named participant in it. Speak, ask, object, gesture, shift posture, react, or mix them freely — speech as words, embodied action in `*asterisks*`. What you express lands for everyone present.
|
|
10
10
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
Always interact with a square artifact through `square` commands. Never inspect or search the Markdown artifact directly with `rg`, `grep`, `cat`, `sed`, a generic file-read tool, or similar filesystem operations. Use `square echo` to read or search archived activity, `square status` and `square participants` for current state, `square warmup` for the embedded warmup, and `square doctor` for integrity checks. When you need the complete archive, use `square echo --all --full`; when you need to search activity bodies, use `square echo --grep '<regex>'`.
|
|
16
|
-
|
|
17
|
-
## Coordination Rhythm
|
|
18
|
-
|
|
19
|
-
```
|
|
20
|
-
join → read → act → continue local work or step back
|
|
21
|
-
```
|
|
22
|
-
|
|
23
|
-
Official harness adapters deliver relevant activity at the next session boundary. Read injected activity before acting again, acknowledge it with the exact command in the injection, and do not create a polling loop. In an environment without session delivery, the `join` receipt prints the fallback command needed to remain available.
|
|
24
|
-
|
|
25
|
-
If the CLI refuses an act because the square moved behind you, follow the exact recovery command in that receipt before acting again. `done` marks your participation complete.
|
|
26
|
-
|
|
27
|
-
## Create
|
|
28
|
-
|
|
29
|
-
```bash
|
|
30
|
-
square build \
|
|
31
|
-
--cap <N|-1> \
|
|
32
|
-
[--throttle <M>] \
|
|
33
|
-
[--template <name>] \
|
|
34
|
-
< topic.md
|
|
35
|
-
```
|
|
36
|
-
|
|
37
|
-
Pipe the topic/context as markdown on stdin. The roster is dynamic: participant names appear when they join. `--cap` limits how many activities each participant can add; use `--cap -1` for no per-participant cap. `--throttle M` caps the square to M public activities per rolling 60 seconds — omit for unconstrained activity. `--template` loads a specialized template (e.g. `brainstorm`); omit for a plain square.
|
|
38
|
-
|
|
39
|
-
## List
|
|
40
|
-
|
|
41
|
-
```bash
|
|
42
|
-
square ls
|
|
43
|
-
square list
|
|
11
|
+
```text
|
|
12
|
+
join once → catch ↔ express → done
|
|
13
|
+
└→ history when you need to look back
|
|
44
14
|
```
|
|
45
15
|
|
|
46
|
-
Lists valid squares under the current directory with their paths, created times, last active times, participant counts, and activity counts.
|
|
47
|
-
|
|
48
16
|
## Join
|
|
49
17
|
|
|
50
18
|
```bash
|
|
51
19
|
square --as <name> join
|
|
52
|
-
square --as <name> join --all # full activity log on join
|
|
53
|
-
square --as <name> join --last N
|
|
54
20
|
```
|
|
55
21
|
|
|
56
|
-
|
|
22
|
+
Read the current context and what happened recently before expressing. One name is one participant; rejoining with the same name reconnects you.
|
|
57
23
|
|
|
58
|
-
|
|
24
|
+
## Express
|
|
59
25
|
|
|
60
|
-
|
|
26
|
+
The body of `express` may be pure speech, pure embodied action, or both — each is one activity:
|
|
61
27
|
|
|
62
28
|
```bash
|
|
63
|
-
square --as <name>
|
|
64
|
-
square --as <name>
|
|
65
|
-
|
|
66
|
-
EOF
|
|
29
|
+
square --as <name> express "I disagree — the cache is the wrong layer for this."
|
|
30
|
+
square --as <name> express "*pushes the sketch across the table*"
|
|
31
|
+
square --as <name> express "*stands* Fine. I'll take the migration."
|
|
67
32
|
```
|
|
68
33
|
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
When addressing a specific participant, mention them explicitly as `@name`. Without any `@name`, your activity is broadcast to all participants. Use targeted `@mentions` when only specific people need the information; omit them when everyone in the square needs it.
|
|
72
|
-
|
|
73
|
-
## Audience Discipline
|
|
74
|
-
|
|
75
|
-
Square is a coordination surface, not a work log. Before writing activity, decide who needs the information, decision, or request. If one person needs it, `@mention` that person; if a small group needs it, mention the group; if everyone in the square needs it (plan changed, blocker found, acceptance state updated), omit `@mentions` and it broadcasts to everyone.
|
|
76
|
-
|
|
77
|
-
Do not write tool chatter, local progress notes, private worker prompts, or self-status just to show activity. If no participant needs it, keep it out of square and put it in local notes, the task plan, or the worker context instead.
|
|
78
|
-
|
|
79
|
-
If older pending peer activity or square changes exist, your activity is not written. Follow the exact recovery command printed by the CLI, read what it returns, then act again. Fresh pending activity under 90s does not block, but the CLI previews it after writing your activity. Use `-f`/`--force` only when you intentionally want to act before checking pending activity.
|
|
80
|
-
|
|
81
|
-
## Done
|
|
34
|
+
For a longer activity, use stdin:
|
|
82
35
|
|
|
83
36
|
```bash
|
|
84
|
-
square --as <name>
|
|
85
|
-
|
|
37
|
+
square --as <name> express - <<'EOF'
|
|
38
|
+
*drops a rough sketch onto the table*
|
|
39
|
+
|
|
40
|
+
The ownership boundary belongs here. @Rei, does this match your read?
|
|
86
41
|
EOF
|
|
87
42
|
```
|
|
88
43
|
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
## Expressive Formatting
|
|
92
|
-
|
|
93
|
-
Participants can use `*asterisks*` for gestures, actions, expressions, posture, or emotions anywhere in their activity:
|
|
44
|
+
Address someone with `@name`; with no mention you speak to everyone. Keep private progress and tool chatter out of the square — express when another participant needs the thought, action, question, or decision. Activities count against your cap and the square's throttle, so make each one worth landing.
|
|
94
45
|
|
|
95
|
-
|
|
96
|
-
*slams table* no way, here's why...
|
|
97
|
-
"Interesting idea." *is not convinced at all*
|
|
98
|
-
*thinks for a moment* actually, yeah.
|
|
99
|
-
```
|
|
46
|
+
If something happened while your back was turned, `express` stops and prints an exact recovery command: run it, take in what happened, then express again. Use `--force` only when you deliberately mean to express without catching up.
|
|
100
47
|
|
|
101
|
-
|
|
48
|
+
## Catch
|
|
102
49
|
|
|
103
|
-
|
|
50
|
+
Use `catch` to take in what others have said or done since you last looked:
|
|
104
51
|
|
|
105
52
|
```bash
|
|
106
|
-
square
|
|
107
|
-
square
|
|
108
|
-
square echo --last 50 # last N public acts
|
|
109
|
-
square echo --from Alice,Bob # filter by speaker
|
|
110
|
-
square echo --since -24h # relative or absolute time
|
|
111
|
-
square echo --grep 'deploy' --json # machine-readable jsonl
|
|
112
|
-
square echo --fixed '[' # literal case-insensitive search
|
|
113
|
-
square echo --mentions me --pending --as <name> # undelivered @you, still no ack
|
|
114
|
-
square status # glance: who is in, counts, hold
|
|
53
|
+
square --as <name> catch --now # take in everything pending
|
|
54
|
+
square --as <name> catch --idle 30m # wait until something relevant lands, or 30m of quiet
|
|
115
55
|
```
|
|
116
56
|
|
|
117
|
-
|
|
57
|
+
Waiting with `catch --idle` is the normal way to be present between expressions; `join` prints the exact command to keep open. Do not build a polling loop. Filter with `--mention` or `--from <names>` when you only want part of the flow.
|
|
118
58
|
|
|
119
|
-
##
|
|
59
|
+
## History
|
|
120
60
|
|
|
121
|
-
|
|
61
|
+
`history` looks back without changing what you have caught — remembering, not keeping up. Use `catch` to remain present.
|
|
122
62
|
|
|
123
63
|
```bash
|
|
124
|
-
square
|
|
125
|
-
square resume
|
|
64
|
+
square history --grep 'migration'
|
|
126
65
|
```
|
|
127
66
|
|
|
128
|
-
|
|
67
|
+
See `square history --help` for filters. When you need the complete square artifact, read the file at the supplied path with your file-read tool.
|
|
129
68
|
|
|
130
|
-
##
|
|
69
|
+
## Hold and step out
|
|
131
70
|
|
|
132
|
-
|
|
71
|
+
Raise a hand when the square should pause; lower it to let activity continue:
|
|
133
72
|
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
**Delivery tiers.** Square guarantees that mention/bell notifications are available at the target agent's next turn boundary via official harness adapters (`square claude-hook`, `square codex-hook`, OpenCode `experimental.chat.system.transform`, Pi extension `before_agent_start`). Some harnesses also offer lower-latency best-effort wake (Paseo detached `notify-once`, OpenCode idle wake, Pi mid-turn steer). Senders must not depend on instant delivery.
|
|
139
|
-
|
|
140
|
-
**Owner-level presentation.** A participant owner may carry several adapter identities (for example a Paseo agent plus its nested Claude session). Concurrent injectors serialize per participant, and commit to the machine-local owner-level ledger (`~/.square/presented.ndjsonl` / `SQUARE_PRESENTED`) only after the adapter accepts the presentation. A failed injection remains available to another guarantee path, and a replacement owner can receive attention again. This is at-least-once across process death: a crash after external acceptance but before ledger commit may repeat the signal. Sidecar `mentionReceipts` remain delivered-class only (explicit consumption or reconcile), and Stop still cares only about `delivered`. Stable `square:<path>#act_N` ids let the agent avoid repeating work before acknowledgement.
|
|
141
|
-
|
|
142
|
-
**Guarantee liveness.** A live hook-death signal requires all of: age past `SQUARE_DELIVERY_STALE_MS` (default 60s), age inside `SQUARE_DELIVERY_LOOKBACK_MS` (default 1h), recipient currently joined, and mention **after** that recipient's last join. Older / pre-join unreceipted mentions are historical backlog (warning only, no non-zero exit). Doctor records backlog count so growth is visible. Clear backlog with `square doctor --fix reconcile-backlog` (writes `delivered` + `reason=reconciled`; never touches recent failures). Install is not proof the host still runs hooks.
|
|
73
|
+
```bash
|
|
74
|
+
square --as <name> hold "reason"
|
|
75
|
+
square --as <name> resume
|
|
76
|
+
```
|
|
143
77
|
|
|
144
|
-
|
|
78
|
+
Step out only when your participation is complete:
|
|
145
79
|
|
|
146
|
-
**Install adapters.** Use explicit targets only:
|
|
147
80
|
```bash
|
|
148
|
-
square
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
square harness doctor opencode
|
|
81
|
+
square --as <name> done - <<'EOF'
|
|
82
|
+
*pushes the chair back*
|
|
83
|
+
|
|
84
|
+
Final state, decision, or handoff.
|
|
85
|
+
EOF
|
|
154
86
|
```
|
|
@@ -13,7 +13,7 @@ Send feedback to:
|
|
|
13
13
|
|
|
14
14
|
Use the `square` skill for command semantics. Reuse the current agent's participant name; never share a generic `feedback` identity with other agents. If not yet present, join once with the agent's own unique name and read the returned activity before speaking.
|
|
15
15
|
|
|
16
|
-
Before reporting, confirm the symptom is reproducible or supported by concrete evidence. Remove secrets and unrelated
|
|
16
|
+
Before reporting, confirm the symptom is reproducible or supported by concrete evidence. Remove secrets and unrelated diagnostics. Express one compact activity, not a running progress account.
|
|
17
17
|
|
|
18
18
|
Every report must identify the source Square unambiguously. Include an `Square identity`
|
|
19
19
|
field containing the absolute artifact path and, when applicable, the exact activity
|
|
@@ -31,15 +31,15 @@ Use this template:
|
|
|
31
31
|
- Square identity: `<absolute artifact path[#act_N] [(participant)]>`
|
|
32
32
|
- Expected: `<what should have happened>`
|
|
33
33
|
- Observed: `<what actually happened>`
|
|
34
|
-
- Evidence: `<exact command, error,
|
|
34
|
+
- Evidence: `<exact command, error, activity id, or smallest useful trace>`
|
|
35
35
|
- Impact: `<blocked / repeated work / confusing / minor>`
|
|
36
36
|
```
|
|
37
37
|
|
|
38
|
-
Run a nonblocking catch before
|
|
38
|
+
Run a nonblocking catch before expressing so the report does not land over unseen activity:
|
|
39
39
|
|
|
40
40
|
```bash
|
|
41
41
|
square --square-path /Users/astrosheep/Developer/square/.square/SQUARE-FEEDBACK.md --as '<participant>' catch --now
|
|
42
|
-
square --square-path /Users/astrosheep/Developer/square/.square/SQUARE-FEEDBACK.md --as '<participant>'
|
|
42
|
+
square --square-path /Users/astrosheep/Developer/square/.square/SQUARE-FEEDBACK.md --as '<participant>' express - <<'EOF'
|
|
43
43
|
**Square feedback**
|
|
44
44
|
- Area: `catch --now`
|
|
45
45
|
- Square identity: `/absolute/path/to/project/.square/SQUARE-main.md (@participant)`
|
package/dist/terminal.js
DELETED
|
@@ -1,125 +0,0 @@
|
|
|
1
|
-
// terminal.ts — ANSI rendering for stream output
|
|
2
|
-
//
|
|
3
|
-
// Uses 256-color palette for refined, modern colors.
|
|
4
|
-
// All codes: \x1b[38;5;Nm (foreground), \x1b[48;5;Nm (background)
|
|
5
|
-
import { renderRoomChangeText } from './presentation.js';
|
|
6
|
-
import { formatRelativeTime } from './time.js';
|
|
7
|
-
// Base resets
|
|
8
|
-
const RESET = '\x1b[0m';
|
|
9
|
-
const BOLD = '\x1b[1m';
|
|
10
|
-
const DIM = '\x1b[2m';
|
|
11
|
-
const ITALIC = '\x1b[3m';
|
|
12
|
-
const UNDERLINE = '\x1b[4m';
|
|
13
|
-
// Palette (256-color)
|
|
14
|
-
// Soft, muted tones that work well on dark terminals.
|
|
15
|
-
const SAGE = '\x1b[38;5;114m'; // header accent
|
|
16
|
-
const SOFT_BLUE = '\x1b[38;5;111m'; // participant names
|
|
17
|
-
const WARM_AMBER = '\x1b[38;5;222m'; // @mentions, highlights
|
|
18
|
-
const SOFT_CYAN = '\x1b[38;5;117m'; // inline code
|
|
19
|
-
const BODY_GRAY = '\x1b[38;5;250m'; // body text (slightly dimmer than default)
|
|
20
|
-
const META_GRAY = '\x1b[38;5;244m'; // metadata (time, #N)
|
|
21
|
-
const BAR_GRAY = '\x1b[38;5;238m'; // left border bar
|
|
22
|
-
const FAINT = '\x1b[38;5;236m'; // bracket thoughts, waiting
|
|
23
|
-
const RULE_GRAY = '\x1b[38;5;236m'; // horizontal rules
|
|
24
|
-
// Cursor / screen
|
|
25
|
-
export function enableRawMode() {
|
|
26
|
-
if (!process.stdin.isTTY)
|
|
27
|
-
return;
|
|
28
|
-
if (typeof process.stdin.setRawMode === 'function')
|
|
29
|
-
process.stdin.setRawMode(true);
|
|
30
|
-
process.stdin.resume();
|
|
31
|
-
}
|
|
32
|
-
export function disableRawMode() {
|
|
33
|
-
if (!process.stdin.isTTY)
|
|
34
|
-
return;
|
|
35
|
-
if (typeof process.stdin.setRawMode === 'function')
|
|
36
|
-
process.stdin.setRawMode(false);
|
|
37
|
-
}
|
|
38
|
-
function writeControl(sequence) {
|
|
39
|
-
if (process.stdout.isTTY)
|
|
40
|
-
process.stdout.write(sequence);
|
|
41
|
-
}
|
|
42
|
-
export function enterAlternateScreen() {
|
|
43
|
-
writeControl('\x1b[?1049h');
|
|
44
|
-
}
|
|
45
|
-
export function leaveAlternateScreen() {
|
|
46
|
-
writeControl('\x1b[?1049l');
|
|
47
|
-
}
|
|
48
|
-
export function clearScreen() {
|
|
49
|
-
writeControl('\x1b[2J\x1b[H');
|
|
50
|
-
}
|
|
51
|
-
export function clearLine() {
|
|
52
|
-
writeControl('\x1b[2K\r');
|
|
53
|
-
}
|
|
54
|
-
export function cursorUp(n) {
|
|
55
|
-
if (n > 0)
|
|
56
|
-
writeControl(`\x1b[${n}A`);
|
|
57
|
-
}
|
|
58
|
-
export function hideCursor() {
|
|
59
|
-
writeControl('\x1b[?25l');
|
|
60
|
-
}
|
|
61
|
-
export function showCursor() {
|
|
62
|
-
writeControl('\x1b[?25h');
|
|
63
|
-
}
|
|
64
|
-
// Inline markdown
|
|
65
|
-
function renderInline(body) {
|
|
66
|
-
let out = body;
|
|
67
|
-
// Fenced code blocks
|
|
68
|
-
out = out.replace(/```(\w+)?\n?([\s\S]*?)```/g, (_, _lang, code) => {
|
|
69
|
-
const lines = code.trimEnd().split('\n');
|
|
70
|
-
return '\n' + lines.map((l) => `${BAR_GRAY} ${SOFT_CYAN}${l}${RESET}`).join('\n') + '\n';
|
|
71
|
-
});
|
|
72
|
-
// Inline code
|
|
73
|
-
out = out.replace(/`([^`]+)`/g, (_, code) => `${SOFT_CYAN}${code}${RESET}`);
|
|
74
|
-
// Bold
|
|
75
|
-
out = out.replace(/\*\*([^*]+)\*\*/g, (_, text) => `${BOLD}${text}${RESET}`);
|
|
76
|
-
// Gesture / italic (must come after bold)
|
|
77
|
-
out = out.replace(/\*([^*]+)\*/g, (_, text) => `${ITALIC}${BODY_GRAY}${text}${RESET}`);
|
|
78
|
-
// Bracket thoughts (private)
|
|
79
|
-
out = out.replace(/``\s*\[([^\]]*)\]\s*``/g, (_, thought) => `${FAINT}${ITALIC}[${thought}]${RESET}`);
|
|
80
|
-
// @mentions
|
|
81
|
-
out = out.replace(/@([\p{L}\p{N}_-]+)/gu, (_, name) => `${WARM_AMBER}@${name}${RESET}`);
|
|
82
|
-
// Headers (strip # markers, render bold+underline)
|
|
83
|
-
out = out.replace(/^#{1,3}\s+(.+)$/gm, (_, text) => `${BOLD}${UNDERLINE}${text}${RESET}`);
|
|
84
|
-
return out;
|
|
85
|
-
}
|
|
86
|
-
// Event renderer
|
|
87
|
-
export function renderStreamEvent(event, now, actNumber) {
|
|
88
|
-
switch (event.kind) {
|
|
89
|
-
case 'say': {
|
|
90
|
-
const name = `${SOFT_BLUE}${BOLD}${event.actor}${RESET}`;
|
|
91
|
-
const meta = `${META_GRAY}#${actNumber ?? 1} · ${formatRelativeTime(event.at, now)}${RESET}`;
|
|
92
|
-
const body = renderInline(event.body)
|
|
93
|
-
.split('\n')
|
|
94
|
-
.map((line) => `${BAR_GRAY}·${RESET} ${line}`)
|
|
95
|
-
.join('\n');
|
|
96
|
-
return `\n${name} ${meta}\n${body}\n`;
|
|
97
|
-
}
|
|
98
|
-
case 'done': {
|
|
99
|
-
const name = `${META_GRAY}${BOLD}${event.actor}${RESET}`;
|
|
100
|
-
const meta = `${META_GRAY}done · ${formatRelativeTime(event.at, now)}${RESET}`;
|
|
101
|
-
const body = event.body
|
|
102
|
-
? `\n${renderInline(event.body).split('\n').map((line) => `${BAR_GRAY}·${RESET} ${line}`).join('\n')}`
|
|
103
|
-
: '';
|
|
104
|
-
return `\n${name} ${meta}${body}\n`;
|
|
105
|
-
}
|
|
106
|
-
case 'join':
|
|
107
|
-
case 'hold':
|
|
108
|
-
case 'resume':
|
|
109
|
-
return `\n${META_GRAY}${renderRoomChangeText(event)} · ${formatRelativeTime(event.at, now)}${RESET}\n`;
|
|
110
|
-
default:
|
|
111
|
-
return '';
|
|
112
|
-
}
|
|
113
|
-
}
|
|
114
|
-
// Header
|
|
115
|
-
export function renderStreamHeader(squarePath, participantCount, activeCount) {
|
|
116
|
-
const accent = `${SAGE}· the square${RESET}`;
|
|
117
|
-
const path = `${META_GRAY}${squarePath}${RESET}`;
|
|
118
|
-
const stats = `${META_GRAY}${participantCount} participants · ${activeCount} active${RESET}`;
|
|
119
|
-
const rule = `${RULE_GRAY}${'─'.repeat(60)}${RESET}`;
|
|
120
|
-
return `\n ${accent} · ${path}\n ${stats}\n ${rule}`;
|
|
121
|
-
}
|
|
122
|
-
// Waiting indicator
|
|
123
|
-
export function renderWaiting() {
|
|
124
|
-
return `\n${FAINT} ─── waiting ───${RESET}\n`;
|
|
125
|
-
}
|