@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 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"` (unverified-live)
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 compact and **non-durable** — pass `paneLabel` and the client
65
- re-resolves label → current id via `herdr pane list` before **every** action. Additional verbs:
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: `unverified-live`.** The herdr transport is proven against injected command
71
- > runners in `test/herdr.test.ts` only; no live smoke inside a herdr instance has run yet.
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"`) | **unverified-live** (runner-mocked tests only) |
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.0",
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.0"
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: unverified-live).
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 compact and non-durable).
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 ("1-2") are compact and NON-DURABLE — they can change when
18
- // panes, tabs, or workspaces close. Every action therefore re-resolves
19
- // `paneLabel` → current pane id at action time (never cached) when a label is
20
- // provided.
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: unverified-live — exercised against injected runners in
23
- // test/herdr.test.ts only; no live smoke inside a herdr instance has run yet.
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 msg = err instanceof Error ? err.message : String(err)
74
- throw new TideError(`herdr ${args.join(" ")} failed: ${msg}`, err)
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
- export const HERDR_PANE_ID_PATTERN = /^[0-9]+-[0-9]+$/
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. "1-2"). Unlike tmux there is no `%` prefix to add. */
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>-<pane>", e.g. "1-2"); herdr ids are non-durable — pass paneLabel to resolve by label instead`,
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
- /** One row from `herdr pane list`. Loosely typed pending a herdr JSON schema. */
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 compact when
160
- * panes close, so a cached id may silently point at a different pane.
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
- const msg = err instanceof Error ? err.message : String(err)
237
- throw new TideError(`herdr pane send-text to ${plan.target} failed (typing literal text): ${msg}`, err)
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): ${msg}`,
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
- /** `herdr wait agent-status <id> --status … --timeout …` — blocks until the agent reaches the status. JSON result. */
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,