@miadi/tide 0.2.0 → 0.2.1
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/README.md +10 -6
- package/package.json +2 -2
- package/src/client.ts +2 -2
- package/src/herdr.ts +66 -19
package/README.md
CHANGED
|
@@ -55,20 +55,24 @@ prompt for a human to review and submit. `buildSendKeysPlan(...)` returns the ex
|
|
|
55
55
|
pair without executing — used for the cockpit's inline command preview. The tmux binary is
|
|
56
56
|
resolved via `TIDE_TMUX_BIN` -> `tmux` on `PATH`.
|
|
57
57
|
|
|
58
|
-
### herdr transport — `multiplexer: "herdr"` (
|
|
58
|
+
### herdr transport — `multiplexer: "herdr"` (live-verified)
|
|
59
59
|
|
|
60
60
|
`sendKeys(pane, message, { multiplexer: "herdr" })` dispatches to the herdr CLI transport
|
|
61
61
|
(`src/herdr.ts`): `herdr pane send-text` types the text, `herdr pane send-keys … Enter` submits
|
|
62
62
|
(`submit: false` skips it, same toggle as tmux). The result is the herdr variant of the
|
|
63
63
|
`TideSendKeysResult` union from `@miadi/tide-contract` (`multiplexer: "herdr"`, herdr CLI argv).
|
|
64
|
-
herdr pane ids (`"1-2"`) are
|
|
65
|
-
|
|
64
|
+
herdr pane ids (`"w1:p2"` as of herdr 0.7; legacy `"1-2"` accepted) are **session-scoped** —
|
|
65
|
+
they reset on herdr restart, and a stale id fails loudly with `pane_not_found`. Pass `paneLabel`
|
|
66
|
+
(set via `herdr pane rename`) and the client re-resolves label → current id via
|
|
67
|
+
`herdr pane list` before **every** action. Additional verbs:
|
|
66
68
|
`runInHerdrPane`, `readHerdrPane` (recent-unwrapped text), `waitForHerdrOutput`,
|
|
67
69
|
`waitForHerdrAgentStatus`, `listHerdrPanes/Workspaces/Tabs`. Binary resolution:
|
|
68
70
|
`TIDE_HERDR_BIN` → `herdr` on `PATH`.
|
|
69
71
|
|
|
70
|
-
> **Readiness: `
|
|
71
|
-
>
|
|
72
|
+
> **Readiness: `live-verified`.** Smoked against a real herdr 0.7.4 instance (EP137
|
|
73
|
+
> herdr-smoke lane, 2026-07-16) — inventory parsing, send-text/send-keys, pane run, read,
|
|
74
|
+
> wait output (hit + timeout exit codes), agent-status, and label→id resolution — in
|
|
75
|
+
> addition to the injected-runner tests in `test/herdr.test.ts`.
|
|
72
76
|
|
|
73
77
|
`getTerminals` and `detect` are the read-only surface behind `GET /api/tide/terminals`
|
|
74
78
|
and `GET /api/tide/detect` — the typed half of operator-terminal triage and manual
|
|
@@ -81,7 +85,7 @@ is deferred to the runtime + a guarded route.
|
|
|
81
85
|
|---|---|
|
|
82
86
|
| One-shot CLI (`tide … --format json`, `execFile` arg-arrays, no shell) | **implemented** |
|
|
83
87
|
| Daemon + Unix-domain-socket transport (`miadi.tide.daemon.v2`) | **implemented** (`src/socket.ts`) |
|
|
84
|
-
| herdr CLI transport (`src/herdr.ts`, `multiplexer: "herdr"`) | **
|
|
88
|
+
| herdr CLI transport (`src/herdr.ts`, `multiplexer: "herdr"`) | **live-verified** (herdr 0.7.4, EP137 smoke + runner-mocked tests) |
|
|
85
89
|
| Schema-first contract (`tide-api.schema.json` → generated types) | planned |
|
|
86
90
|
|
|
87
91
|
### How transport selection works
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@miadi/tide",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.1",
|
|
4
4
|
"description": "Typed client boundary for the ironsilk `tide` runtime. Daemon Unix-socket transport with CLI fallback.",
|
|
5
5
|
"publishConfig": {
|
|
6
6
|
"access": "public"
|
|
@@ -15,7 +15,7 @@
|
|
|
15
15
|
"src"
|
|
16
16
|
],
|
|
17
17
|
"dependencies": {
|
|
18
|
-
"@miadi/tide-contract": "0.2.
|
|
18
|
+
"@miadi/tide-contract": "0.2.1"
|
|
19
19
|
},
|
|
20
20
|
"scripts": {
|
|
21
21
|
"test": "d=$(mktemp -d \"${TMPDIR:-/tmp}/miadi-tide-test.XXXXXX\") && trap 'rm -rf \"$d\"' EXIT && ../../node_modules/.bin/tsc -p tsconfig.test.json --outDir \"$d\" && node --test \"$d\"/packages/tide/test/*.test.js"
|
package/src/client.ts
CHANGED
|
@@ -267,12 +267,12 @@ export interface SendKeysOptions extends TideRunOptions {
|
|
|
267
267
|
/**
|
|
268
268
|
* Terminal multiplexer to drive. Absent or "tmux" keeps the historical
|
|
269
269
|
* direct `tmux send-keys` path unchanged; "herdr" dispatches to the herdr
|
|
270
|
-
* CLI transport (herdr.ts — READINESS:
|
|
270
|
+
* CLI transport (herdr.ts — READINESS: live-verified on herdr 0.7.4).
|
|
271
271
|
*/
|
|
272
272
|
multiplexer?: Multiplexer
|
|
273
273
|
/**
|
|
274
274
|
* herdr only: durable pane label, re-resolved to the current pane id at
|
|
275
|
-
* action time (herdr ids are
|
|
275
|
+
* action time (herdr ids are session-scoped and reset on herdr restart).
|
|
276
276
|
*/
|
|
277
277
|
paneLabel?: string
|
|
278
278
|
/** herdr only: injected command runner (tests). */
|
package/src/herdr.ts
CHANGED
|
@@ -14,13 +14,18 @@
|
|
|
14
14
|
// wait agent-status <id> --status … --timeout ms (JSON)
|
|
15
15
|
// workspace list | tab list --workspace <id> | pane list (JSON)
|
|
16
16
|
//
|
|
17
|
-
// herdr pane ids ("
|
|
18
|
-
//
|
|
19
|
-
//
|
|
20
|
-
//
|
|
17
|
+
// herdr pane ids are "w<N>:p<M>" (e.g. "w1:p2") as of herdr 0.7; the legacy
|
|
18
|
+
// dashed "1-2" form is still accepted for older releases. Live smoke against
|
|
19
|
+
// herdr 0.7.4 (EP137) showed ids are monotonic within a session — they do NOT
|
|
20
|
+
// compact or get reused when panes close, and a stale id fails loudly with
|
|
21
|
+
// {"error":{"code":"pane_not_found"}}. They are still session-scoped (a herdr
|
|
22
|
+
// restart resets them), so every action re-resolves `paneLabel` → current pane
|
|
23
|
+
// id at action time (never cached) when a label is provided; `pane rename`
|
|
24
|
+
// sets the `label` field that resolution matches on.
|
|
21
25
|
//
|
|
22
|
-
// READINESS:
|
|
23
|
-
//
|
|
26
|
+
// READINESS: live-verified — smoked against a real herdr 0.7.4 instance
|
|
27
|
+
// (EP137 herdr-smoke lane, 2026-07-16) in addition to the injected-runner
|
|
28
|
+
// tests in test/herdr.test.ts.
|
|
24
29
|
|
|
25
30
|
import { execFile } from "node:child_process"
|
|
26
31
|
import { promisify } from "node:util"
|
|
@@ -64,14 +69,37 @@ function makeRunner(opts: HerdrRunOptions): HerdrCommandRunner {
|
|
|
64
69
|
}
|
|
65
70
|
}
|
|
66
71
|
|
|
72
|
+
/**
|
|
73
|
+
* Detail line for a failed runner call WITHOUT echoing argv values: node's
|
|
74
|
+
* execFile error message embeds the full command line ("Command failed: herdr
|
|
75
|
+
* pane send-text <id> <text> …") — the very values these TideError messages
|
|
76
|
+
* redact (live EP137 finding; mocks never hit this because injected errors
|
|
77
|
+
* carry custom messages). Prefer the child's stderr (herdr's own diagnostic,
|
|
78
|
+
* e.g. its {"error":…} JSON), then the message with any "Command failed: …"
|
|
79
|
+
* line stripped, then exit metadata.
|
|
80
|
+
*/
|
|
81
|
+
function describeRunnerError(err: unknown): string {
|
|
82
|
+
const e = err as Partial<{ stderr: unknown; code: unknown; signal: unknown }> | null
|
|
83
|
+
const stderr = typeof e?.stderr === "string" ? e.stderr.trim() : ""
|
|
84
|
+
if (stderr) return stderr
|
|
85
|
+
const raw = err instanceof Error ? err.message : String(err)
|
|
86
|
+
const stripped = raw.replace(/^Command failed:[^\n]*\n?/, "").trim()
|
|
87
|
+
if (stripped) return stripped
|
|
88
|
+
const meta = [
|
|
89
|
+
e?.code != null ? `exit code ${String(e.code)}` : null,
|
|
90
|
+
typeof e?.signal === "string" && e.signal ? `killed by ${e.signal}` : null,
|
|
91
|
+
].filter(Boolean)
|
|
92
|
+
return meta.length ? meta.join(", ") : "command failed"
|
|
93
|
+
}
|
|
94
|
+
|
|
67
95
|
/** Run one herdr CLI command, wrapping failures in TideError. */
|
|
68
96
|
async function runHerdr(args: string[], opts: HerdrRunOptions): Promise<HerdrCommandResult> {
|
|
69
97
|
const runner = makeRunner(opts)
|
|
70
98
|
try {
|
|
71
99
|
return await runner(resolveHerdrBin(), args)
|
|
72
100
|
} catch (err) {
|
|
73
|
-
const
|
|
74
|
-
throw new TideError(`herdr ${
|
|
101
|
+
const verb = args.length >= 2 ? `${args[0]} ${args[1]}` : "operation"
|
|
102
|
+
throw new TideError(`herdr ${verb} failed: ${describeRunnerError(err)}`, err)
|
|
75
103
|
}
|
|
76
104
|
}
|
|
77
105
|
|
|
@@ -85,26 +113,36 @@ function parseHerdrJson<T>(stdout: string, what: string): T {
|
|
|
85
113
|
|
|
86
114
|
// ── Pane targets and label→id resolution ────────────────────────────────────
|
|
87
115
|
|
|
88
|
-
|
|
116
|
+
// "w1:p2" is the live herdr 0.7 format; the dashed "1-2" form is legacy.
|
|
117
|
+
export const HERDR_PANE_ID_PATTERN = /^(w[0-9]+:p[0-9]+|[0-9]+-[0-9]+)$/
|
|
89
118
|
|
|
90
|
-
/** Validate a herdr pane id (e.g. "
|
|
119
|
+
/** Validate a herdr pane id (e.g. "w1:p2"). Unlike tmux there is no `%` prefix to add. */
|
|
91
120
|
export function normalizeHerdrPaneTarget(pane: string): string {
|
|
92
121
|
const trimmed = pane.trim()
|
|
93
122
|
if (!HERDR_PANE_ID_PATTERN.test(trimmed)) {
|
|
94
123
|
throw new TideError(
|
|
95
|
-
`invalid herdr pane id "${pane}" (expected "<workspace
|
|
124
|
+
`invalid herdr pane id "${pane}" (expected "w<workspace>:p<pane>", e.g. "w1:p2"); herdr ids are session-scoped — pass paneLabel to resolve by label instead`,
|
|
96
125
|
)
|
|
97
126
|
}
|
|
98
127
|
return trimmed
|
|
99
128
|
}
|
|
100
129
|
|
|
101
|
-
/**
|
|
130
|
+
/**
|
|
131
|
+
* One row from `herdr pane list`. Loosely typed; the named fields below are
|
|
132
|
+
* the ones observed live on herdr 0.7.4. `label` only appears after
|
|
133
|
+
* `herdr pane rename`; `title` is tolerated for other herdr builds.
|
|
134
|
+
*/
|
|
102
135
|
export interface HerdrPaneInfo {
|
|
103
136
|
pane_id?: string
|
|
104
137
|
label?: string
|
|
105
138
|
title?: string
|
|
106
139
|
focused?: boolean
|
|
107
140
|
agent_status?: TideAgentStatus | string
|
|
141
|
+
workspace_id?: string
|
|
142
|
+
tab_id?: string
|
|
143
|
+
cwd?: string
|
|
144
|
+
terminal_title?: string
|
|
145
|
+
terminal_title_stripped?: string
|
|
108
146
|
[key: string]: unknown
|
|
109
147
|
}
|
|
110
148
|
|
|
@@ -156,8 +194,10 @@ export async function listHerdrTabs(workspace: string, opts: HerdrRunOptions = {
|
|
|
156
194
|
|
|
157
195
|
/**
|
|
158
196
|
* Resolve a durable pane label to the CURRENT herdr pane id via `pane list`.
|
|
159
|
-
* Runs before every action when a label is given — herdr ids
|
|
160
|
-
*
|
|
197
|
+
* Runs before every action when a label is given — herdr ids are
|
|
198
|
+
* session-scoped (a herdr restart resets them), so a cached id can go stale.
|
|
199
|
+
* Live 0.7.4: a stale id fails loudly with pane_not_found (ids are never
|
|
200
|
+
* reused within a session); `pane rename` sets the `label` field matched here.
|
|
161
201
|
*/
|
|
162
202
|
export async function resolveHerdrPaneId(paneLabel: string, opts: HerdrRunOptions = {}): Promise<string> {
|
|
163
203
|
const label = paneLabel.trim()
|
|
@@ -233,16 +273,17 @@ export async function sendKeysViaHerdr(
|
|
|
233
273
|
try {
|
|
234
274
|
await runner(bin, plan.literal_command)
|
|
235
275
|
} catch (err) {
|
|
236
|
-
|
|
237
|
-
|
|
276
|
+
throw new TideError(
|
|
277
|
+
`herdr pane send-text to ${plan.target} failed (typing literal text): ${describeRunnerError(err)}`,
|
|
278
|
+
err,
|
|
279
|
+
)
|
|
238
280
|
}
|
|
239
281
|
if (plan.submit_command) {
|
|
240
282
|
try {
|
|
241
283
|
await runner(bin, plan.submit_command)
|
|
242
284
|
} catch (err) {
|
|
243
|
-
const msg = err instanceof Error ? err.message : String(err)
|
|
244
285
|
throw new TideError(
|
|
245
|
-
`herdr pane send-keys to ${plan.target} failed (submitting Enter; literal text was typed but left unsubmitted): ${
|
|
286
|
+
`herdr pane send-keys to ${plan.target} failed (submitting Enter; literal text was typed but left unsubmitted): ${describeRunnerError(err)}`,
|
|
246
287
|
err,
|
|
247
288
|
)
|
|
248
289
|
}
|
|
@@ -303,7 +344,13 @@ export async function waitForHerdrOutput(
|
|
|
303
344
|
return parseHerdrJson<unknown>(stdout, "wait output")
|
|
304
345
|
}
|
|
305
346
|
|
|
306
|
-
/**
|
|
347
|
+
/**
|
|
348
|
+
* `herdr wait agent-status <id> --status … --timeout …` — blocks until the
|
|
349
|
+
* agent reaches the status. On a hit, herdr 0.7.4 prints an EVENT envelope
|
|
350
|
+
* ({"event":"pane.agent_status_changed","data":{pane_id, workspace_id,
|
|
351
|
+
* agent_status}}), not a result envelope; on timeout it exits 1 with plain
|
|
352
|
+
* text on stderr, which surfaces here as a TideError.
|
|
353
|
+
*/
|
|
307
354
|
export async function waitForHerdrAgentStatus(
|
|
308
355
|
pane: string,
|
|
309
356
|
status: TideAgentStatus,
|