@joystack/cli 0.0.0-stage → 0.1.43

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,22 @@
-# Temporary Holding Version
+# @joystack/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Joystack game-development CLI: bootstrap, run, and publish multiplayer games.
+A published game is served from its own address, `https://<slug>.joystack.games/`.
+
+```bash
+npx joystack create my-game
+cd my-game
+npx joystack dev
+```
+
+New here? Point your AI agent at **https://docs.joystack.ai/setup.md** and say
+"set me up to make Joystack games."
+
+## License
+
+This CLI is licensed under **Apache-2.0** (see `LICENSE`) — **the CLI only**.
+
+The **Joystack engine** that the CLI downloads for you (after `joystack login`) is a
+separate, proprietary work and is NOT covered by this package's license. It is
+governed by the [Joystack Engine License](https://docs.joystack.ai/engine-license.md),
+which you accept when connecting your computer to your Joystack account.

package/bin/joystack.mjs

@@ -0,0 +1,300 @@
+#!/usr/bin/env node
+// joystack — the Joystack game-development CLI.
+//
+// Runs inside a standalone game folder (its own repo). The agent is the
+// primary user: keep output plain, actionable, and machine-legible.
+import { dev } from '../lib/dev.mjs';
+import { agentSessionFromEnv } from '../lib/agent-session.mjs';
+import { lane } from '../lib/lane.mjs';
+import { login, logout, whoami } from '../lib/login.mjs';
+import { publish } from '../lib/publish.mjs';
+import { create } from '../lib/create.mjs';
+import { parseTestArgs, TEST_HELP } from '../lib/test-policy.mjs';
+import { testCmd } from '../lib/test-cmd.mjs';
+import { lintCmd } from '../lib/lint.mjs';
+import { update } from '../lib/update.mjs';
+import { changelog } from '../lib/changelog.mjs';
+import { sendFeedback } from '../lib/feedback.mjs';
+import { syncFeedback } from '../lib/feedback-sync.mjs';
+import { printableLines } from '../lib/printable.mjs';
+
+const [, , cmd, ...rest] = process.argv;
+
+function flag(name) {
+  const i = rest.indexOf(`--${name}`);
+  return i === -1 ? undefined : rest[i + 1];
+}
+
+const HELP = `joystack — build and run Joystack games
+
+Usage:
+  joystack create <name>        Bootstrap a new game folder (multiplayer works out of the box)
+  joystack dev [--port <n>]     Run the full dev stack (game + multiplayer + services)
+  joystack dev --share          ...and print a public link testers can play (needs cloudflared)
+  joystack dev --no-reload      ...frozen as it is now: saves reach nobody until you restart it
+  joystack assets [<id>]       Browse and drive your models, sounds and assets on their own
+  joystack assets <id> --sheet  Draw a view sheet of a 3D asset to .joystack/sheets/ (--help: options)
+  joystack assets --json [<id>…]  Print each asset's parameters, measured stats and flags as JSON
+  joystack lane <name>          Open an isolated copy of the game to experiment in, safely
+  joystack test [aspect]        Run targeted checks (no aspect: conservative full run)
+  joystack test --since <base>  Submission: ordinary + triggered extended checks
+  joystack test --all           Explicit full audit; add --list to preview selection
+  joystack test --help          Everything about running and reading tests
+  joystack lint [--fix]         Check the game against the Joystack rules (runs inside 'joystack test')
+  joystack changelog [<v>]      What changed in the engine (default: everything newer than your pin)
+  joystack update [--rc <v>]    Move this game to the latest engine release (--rc <v> takes a specific pre-release)
+  joystack model bake <glb>     Re-bake a 3D model's server-side hit data now (normally automatic)
+  joystack publish [--slug <s>] [--dev-tools]
+                              Publish this game to <slug>.joystack.games (--slug for an A/B copy;
+                              --dev-tools makes that copy a review build with Tweaks on)
+  joystack build-id             The id of this game's code as it is now, with its git commit
+  joystack replay list          Every recorded session: when, how long, on what device, which build
+  joystack replay export [<id>]  Turn a recorded session into tables you can query (Parquet)
+  joystack replay profile [<id>] --ticks <a-b>
+                              Which functions ran in those ticks, as a table
+  joystack feedback             Send reports + replies under notes/feedback/; pull outcomes back in
+  joystack inbox reply <id> "<text>"  Answer a report a dev tool sent your agent; the text shows in the tool
+  joystack login                Authenticate this machine as your Joystack player account
+  joystack logout [--all]       Sign out: revoke the token (--all: on every machine)
+  joystack whoami               Show who this machine publishes as
+  joystack help                 This message
+
+The dev stack serves your game at http://localhost:8000/games/<name>/index.html
+with local multiplayer on :1999. Run several at once (a lane, another game) and
+each picks its own free ports — 'joystack dev' never disturbs a stack that isn't
+its own.
+`;
+
+try {
+  switch (cmd) {
+    case 'dev': {
+      const handle = await dev({ port: flag('port') ? Number(flag('port')) : undefined, share: rest.includes('--share'), reload: !rest.includes('--no-reload'), agentSession: agentSessionFromEnv() });
+      const shutdown = () => {
+        handle.stop();
+        process.exit(0);
+      };
+      process.on('SIGINT', shutdown);
+      process.on('SIGTERM', shutdown);
+      // Keep the process alive; servers + children hold the loop open.
+      break;
+    }
+    case 'assets': {
+      // `--json`: print what each asset is, measured by the page headless,
+      // instead of opening it (assets-json.mjs). stdout carries the JSON and
+      // nothing else, so it can be piped; everything else goes to stderr.
+      if (rest.includes('--json')) {
+        const { assetsJson, parseJsonArgs, safeJson, JSON_HELP } = await import('../lib/assets-json.mjs');
+        const { printable } = await import('../lib/printable.mjs');
+        if (rest.includes('--help')) {
+          console.log(JSON_HELP);
+          break;
+        }
+        const progress = process.stderr.isTTY
+          ? (i, n, id) => process.stderr.write(`\r  measuring ${i + 1}/${n} ${[...printable(id)].slice(0, 40).join('').padEnd(40)}`)
+          : () => {};
+        // A stack started for the listing is stopped on Ctrl-C too.
+        let started = null;
+        const interrupt = async () => {
+          await started?.stop();
+          process.exit(130);
+        };
+        process.on('SIGINT', interrupt);
+        process.on('SIGTERM', interrupt);
+        let out;
+        try {
+          out = await assetsJson({ ...parseJsonArgs(rest), startDev: dev, progress, onStarted: (s) => { started = s; } });
+        } catch (err) {
+          // An error here may quote the game's own text, so every line of it
+          // is made printable before it reaches the terminal.
+          if (process.stderr.isTTY) process.stderr.write('\r\x1b[K');
+          console.error(`joystack assets: ${printableLines(err?.message ?? err)}`);
+          process.exit(1);
+        }
+        if (process.stderr.isTTY) process.stderr.write('\r\x1b[K');
+        process.off('SIGINT', interrupt);
+        process.off('SIGTERM', interrupt);
+        const failed = out.assets.filter((a) => a.error);
+        for (const a of failed) console.error(`joystack assets: ${printable(a.id)} could not be measured: ${printable(a.error)}`);
+        // An exit code, not process.exit(): stdout to a pipe is written
+        // asynchronously, and exiting at once cuts a long listing off at the
+        // pipe's buffer (64 KB on macOS), which leaves invalid JSON.
+        process.exitCode = failed.length ? 1 : 0;
+        process.stdout.write(`${safeJson(out)}\n`);
+        break;
+      }
+      // `--sheet`: draw a view sheet headless and write it to disk, instead
+      // of opening the page (assets-sheet.mjs).
+      if (rest.includes('--sheet')) {
+        const { assetsSheet, parseSheetArgs, printable, SHEET_HELP } = await import('../lib/assets-sheet.mjs');
+        if (rest.includes('--help')) {
+          console.log(SHEET_HELP);
+          break;
+        }
+        let missingRefs;
+        try {
+          ({ missingRefs } = await assetsSheet({ ...parseSheetArgs(rest), startDev: dev }));
+        } catch (err) {
+          // An error here may quote the game's own text, so every line of it
+          // is made printable before it reaches the terminal.
+          console.error(`joystack assets: ${printableLines(err?.message ?? err)}`);
+          process.exit(1);
+        }
+        if (missingRefs.length) {
+          console.error(`joystack assets: ${missingRefs.length === 1 ? 'a reference image' : 'reference images'} declared in assets.js could not be shown: ${missingRefs.map((m) => printable(m.src)).join(', ')}`);
+          process.exit(1);
+        }
+        process.exit(0);
+      }
+      // The same dev stack `joystack dev` runs, opened on the assets page. Not a
+      // second server: the assets page is a page under /shared/, which this one
+      // already mounts. A healthy `joystack dev` already running for this game is
+      // reused rather than replaced (assets-page.mjs, openAssets).
+      const { openAssets, openBrowser, itemArg } = await import('../lib/assets-page.mjs');
+      const { reused, target, handle, agentUnreachable } = await openAssets({
+        port: flag('port') ? Number(flag('port')) : undefined,
+        item: itemArg(rest),
+        agentSession: agentSessionFromEnv(),
+        startDev: dev,
+      });
+      if (reused) console.log('\n  → using the dev stack already running for this game');
+      if (agentUnreachable) {
+        console.log('  ⚠ that stack was not started by a coding agent, so notes sent from the Assets page are only filed.');
+        console.log('    To have them reach you, stop it and run `joystack dev` (or `joystack assets`) from your agent.');
+      }
+      console.log(`\n  🔎 Assets → ${target}\n`);
+      if (!rest.includes('--no-open')) openBrowser(target);
+      // A reused stack belongs to the `joystack dev` that started it; there is
+      // nothing here to keep alive or to stop.
+      if (!handle) break;
+      const shutdown = () => {
+        handle.stop();
+        process.exit(0);
+      };
+      process.on('SIGINT', shutdown);
+      process.on('SIGTERM', shutdown);
+      break;
+    }
+    case 'inbox': {
+      const { inboxReply, INBOX_HELP } = await import('../lib/inbox-cmd.mjs');
+      const dirAt = rest.indexOf('--dir');
+      if (dirAt !== -1 && (!rest[dirAt + 1] || rest[dirAt + 1].startsWith('--'))) throw new Error(`--dir needs a folder. Usage: ${INBOX_HELP}`);
+      const args = dirAt === -1 ? rest : [...rest.slice(0, dirAt), ...rest.slice(dirAt + 2)];
+      if (args[0] !== 'reply') throw new Error(`Usage: ${INBOX_HELP}`);
+      await inboxReply({ dir: flag('dir'), id: args[1], text: args.slice(2).join(' ') });
+      break;
+    }
+    case 'lane': {
+      const name = rest.find((a) => !a.startsWith('--'));
+      if (!name) throw new Error('Name the lane: joystack lane <name>  (e.g. joystack lane judder)');
+      const { dir } = await lane(name);
+      console.log(`\nWork in it:\n  cd ${dir} && npx joystack dev\n`);
+      break;
+    }
+    case 'create':
+      await create({ name: rest.find((a) => !a.startsWith('--')) });
+      break;
+    case 'test': {
+      const options = parseTestArgs(rest);
+      if (options.help) {
+        console.log(TEST_HELP);
+        break;
+      }
+      const { ok } = await testCmd(options);
+      process.exit(ok ? 0 : 1);
+    }
+    case 'lint': {
+      const { ok } = await lintCmd({ fix: rest.includes('--fix') });
+      process.exit(ok ? 0 : 1);
+    }
+    case 'changelog':
+      await changelog({
+        version: rest.find((a) => !a.startsWith('--')),
+        all: rest.includes('--all'),
+      });
+      break;
+    case 'update': {
+      // `--rc <version>` takes an exact release candidate by reference (a
+      // pre-release you were handed); no flag → the normal newest-stable update.
+      const rcIdx = rest.indexOf('--rc');
+      const target = rcIdx >= 0 ? rest[rcIdx + 1] : null;
+      if (rcIdx >= 0 && !target) throw new Error('`--rc` needs a version, e.g. `joystack update --rc 0.2.0-rc.1`');
+      await update({ target });
+      break;
+    }
+    case 'model': {
+      // `model` is the accessor for 3D-model tooling; `bake` is its first verb.
+      // Baking is normally automatic (dev/test/publish re-bake changed models);
+      // this is the explicit escape hatch.
+      const [verb, glb] = rest.filter((a) => !a.startsWith('--'));
+      if (verb !== 'bake') throw new Error(`Unknown model command: ${verb ?? '(none)'} — try: joystack model bake <file.glb>`);
+      if (!glb) throw new Error('Name the model: joystack model bake <file.glb>');
+      const { bakeModel } = await import('../lib/model-bake.mjs');
+      await bakeModel(glb);
+      break;
+    }
+    case 'build-id': {
+      const { buildIdCommand } = await import('../lib/build-id.mjs');
+      buildIdCommand({ json: rest.includes('--json') });
+      break;
+    }
+    case 'replay': {
+      // `replay` is the accessor for a recorded session; `export` is its first
+      // verb. Watching one back needs no command at all — it is `?replay=<id>`
+      // on the game's URL, or the toolbox's Sessions panel.
+      const { REPLAY_HELP, replayExport, replayProfile, replayList, parseReplayArgs } = await import('../lib/replay-cmd.mjs');
+      // Parsed in the lib so the argv split is under test — a flag's value must
+      // never slide into the session slot, and --help must be answered before
+      // anything is read as an id.
+      const { verb, id, out, ticks, json, repeat, help } = parseReplayArgs(rest);
+      if (help) {
+        console.log(REPLAY_HELP);
+        break;
+      }
+      if (verb === 'list') {
+        await replayList({ json });
+        break;
+      }
+      if (verb === 'profile') {
+        await replayProfile({ stream: id, ticks, out, repeat });
+        break;
+      }
+      if (verb !== 'export') {
+        throw new Error(`Unknown replay command: ${verb} — try: joystack replay list, joystack replay export, or joystack replay profile`);
+      }
+      await replayExport({ stream: id, out });
+      break;
+    }
+    case 'publish':
+      await publish({ slug: flag('slug'), devTools: rest.includes('--dev-tools') });
+      break;
+    case 'feedback':
+      // Send first, then sync: a report filed this run is already stamped with
+      // its id, so the same invocation can pull any outcome waiting for it.
+      await sendFeedback();
+      await syncFeedback();
+      break;
+    case 'login':
+      await login();
+      break;
+    case 'logout':
+      await logout({ all: rest.includes('--all') });
+      break;
+    case 'whoami':
+      await whoami();
+      break;
+    case undefined:
+    case 'help':
+    case '--help':
+    case '-h':
+      console.log(HELP);
+      break;
+    default:
+      console.error(`Unknown command: ${printableLines(cmd)}\n\n${HELP}`);
+      process.exit(2);
+  }
+} catch (err) {
+  // Printable, line by line: a message can quote a file from the game folder
+  // or text a page returned, and a terminal must not act on either.
+  console.error(`joystack ${printableLines(cmd)}: ${printableLines(err?.message ?? err)}`);
+  process.exit(1);
+}

package/lib/agent-session.mjs

@@ -0,0 +1,52 @@
+// The coding-agent session that started this dev server, if one did.
+//
+// Claude Code exports the address of each session's inbox socket to every
+// command that session runs (CLAUDE_CODE_MESSAGING_SOCKET, with a per-session
+// CLAUDE_CODE_MESSAGING_TOKEN). A `joystack dev` the agent started therefore
+// inherits the address of exactly the conversation that started it, and a
+// message posted there reaches that conversation, starting a new turn if it
+// is idle. No flag, plugin or setting is involved, and a dev server started
+// from a plain terminal inherits nothing, so it never guesses at a session.
+//
+// The socket protocol is newline-delimited JSON: an optional auth line, then
+// one frame per message. The auth line lets Claude Code verify the sender as
+// one of the session's own child processes, which it delivers without asking.
+import { existsSync } from 'node:fs';
+import { createConnection } from 'node:net';
+import { randomUUID } from 'node:crypto';
+
+export function agentSessionFromEnv(env = process.env) {
+  const address = env.CLAUDE_CODE_MESSAGING_SOCKET;
+  if (!address) return null;
+  return { agent: 'Claude Code', socket: address.replace(/^uds:/, ''), token: env.CLAUDE_CODE_MESSAGING_TOKEN || null };
+}
+
+// The environment with the session's address and token removed, for the
+// processes the dev server starts itself (the room server, the tunnel): none
+// of them may post into the agent's conversation.
+export function withoutAgentSession(env = process.env) {
+  const { CLAUDE_CODE_MESSAGING_SOCKET: _socket, CLAUDE_CODE_MESSAGING_TOKEN: _token, ...rest } = env;
+  return rest;
+}
+
+// The socket file is removed when its session exits. On native Windows the
+// address is a named pipe, which has no file to check, so it counts as live.
+export function sessionAlive(session) {
+  if (!session) return false;
+  return session.socket.startsWith('\\\\.\\pipe\\') || existsSync(session.socket);
+}
+
+// Resolves once the session has accepted the message; rejects if it cannot
+// be reached within five seconds.
+export function postToSession(session, content) {
+  return new Promise((resolve, reject) => {
+    const conn = createConnection(session.socket, () => {
+      if (session.token) conn.write(`${JSON.stringify({ type: 'auth', token: session.token })}\n`);
+      conn.end(`${JSON.stringify({ msgV: 1, msg_id: randomUUID(), type: 'user', message: { role: 'user', content }, priority: 'next' })}\n`);
+    });
+    conn.setTimeout(5000, () => conn.destroy(new Error('the agent session did not accept the message')));
+    conn.on('error', reject);
+    conn.on('close', (hadError) => { if (!hadError) resolve(); });
+    conn.resume();
+  });
+}