de-shell 0.2.1__tar.gz → 0.4.0__tar.gz

{de_shell-0.2.1 → de_shell-0.4.0}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: de-shell
-Version: 0.2.1
+Version: 0.4.0
 Summary: The Electron + Python desktop-app shell Direct Electron's apps (SpyDE, Ground Crew, Autopilot) are assembled from
 Author-email: Carter Francis <cartsfrancis@gmail.com>
 License: MIT
 Project-URL: Homepage, https://github.com/directelectron/de-shell
 Project-URL: Repository, https://github.com/directelectron/de-shell
 Project-URL: Issues, https://github.com/directelectron/de-shell/issues
-Project-URL: Changelog, https://github.com/directelectron/de-shell/blob/main/CHANGELOG.md
+Project-URL: Changelog, https://github.com/directelectron/de-shell/blob/main/CHANGELOG.rst
 Keywords: electron,desktop,anyplotlib,electron-microscopy,direct-electron
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
@@ -26,7 +26,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: numpy>=1.20.0
-Requires-Dist: anyplotlib>=0.8.0
+Requires-Dist: anyplotlib>=0.10.0
 Requires-Dist: pyyaml
 Provides-Extra: tests
 Requires-Dist: pytest>=3.6; extra == "tests"
@@ -122,9 +122,10 @@ peer dependencies — react, electron, electron-updater, @playwright/test —
 are the app's to declare; every app already does. The e2e specs take the
 harness from `shell/testing/harness.cjs`.
 
-Autopilot and SpyDE ([directelectron/spyde#152](https://github.com/directelectron/spyde/pull/152))
-are wired this way, pinned `de-shell>=0.2,<0.3`; Ground Crew still carries a
-copy under its `packages/` and is next.
+All three apps are wired this way: Autopilot, SpyDE
+([directelectron/spyde#152](https://github.com/directelectron/spyde/pull/152))
+and Ground Crew ([directelectron/de_ground_crew#183](https://github.com/directelectron/de_ground_crew/pull/183)),
+pinned to the `0.2` line.
 
 ## Developing it
 
@@ -149,8 +150,20 @@ tests, and builds the wheel and checks what it carries.
 
 The version is written once, in `de_shell/__init__.py`. To release:
 
-1. Bump `__version__`, move the `CHANGELOG.md` entries under the new version.
-2. Commit, tag `vX.Y.Z`, push the tag.
+1. Run **Prepare Release** from the Actions tab and pick the bump (`minor`,
+   `bugfix`, `major`, `pre-release`, or `finalize` to drop a `bN` suffix). It
+   bumps `__version__`, assembles `CHANGELOG.rst` from the news fragments in
+   `upcoming_changes/`, runs the pre-flight checks, and opens a release PR that
+   names the one tag that will pass.
+2. Review and merge that PR, then tag the merge commit and push the tag — the
+   PR body has the exact commands.
+
+The tag has to match `__version__` exactly; going through the workflow makes
+them agree by construction, because the PR *is* the bump. To assemble the
+changelog by hand instead, `uv tool run towncrier build --version X.Y.Z` does
+the same thing — but stage `upcoming_changes/` with `git add -A`, because
+towncrier deletes the fragments it consumed and a plain `git add CHANGELOG.rst`
+leaves the deletions behind for the next release to re-publish.
 
 `.github/workflows/publish.yml` builds the distributions, refuses a tag that
 does not match `__version__`, and uploads to PyPI through trusted publishing
@@ -190,6 +203,9 @@ SpyDE commit the app copies were taken from:
 * **The protocol is the contract.** `PLOTAPP:` JSON lines and `PLOTBIN:`
   binary frames over the sidecar's stdio. Both halves of it live in this one
   package on purpose; keep it that way.
+* **Every pull request carries its own changelog entry**, as a news fragment
+  under [`upcoming_changes/`](upcoming_changes/README.rst) — one file per PR,
+  so two of them never conflict over the same lines of `CHANGELOG.rst`.
 * **LF line endings**, enforced by `.gitattributes`.
 
 ## License

{de_shell-0.2.1 → de_shell-0.4.0}/README.md

@@ -87,9 +87,10 @@ peer dependencies — react, electron, electron-updater, @playwright/test —
 are the app's to declare; every app already does. The e2e specs take the
 harness from `shell/testing/harness.cjs`.
 
-Autopilot and SpyDE ([directelectron/spyde#152](https://github.com/directelectron/spyde/pull/152))
-are wired this way, pinned `de-shell>=0.2,<0.3`; Ground Crew still carries a
-copy under its `packages/` and is next.
+All three apps are wired this way: Autopilot, SpyDE
+([directelectron/spyde#152](https://github.com/directelectron/spyde/pull/152))
+and Ground Crew ([directelectron/de_ground_crew#183](https://github.com/directelectron/de_ground_crew/pull/183)),
+pinned to the `0.2` line.
 
 ## Developing it
 
@@ -114,8 +115,20 @@ tests, and builds the wheel and checks what it carries.
 
 The version is written once, in `de_shell/__init__.py`. To release:
 
-1. Bump `__version__`, move the `CHANGELOG.md` entries under the new version.
-2. Commit, tag `vX.Y.Z`, push the tag.
+1. Run **Prepare Release** from the Actions tab and pick the bump (`minor`,
+   `bugfix`, `major`, `pre-release`, or `finalize` to drop a `bN` suffix). It
+   bumps `__version__`, assembles `CHANGELOG.rst` from the news fragments in
+   `upcoming_changes/`, runs the pre-flight checks, and opens a release PR that
+   names the one tag that will pass.
+2. Review and merge that PR, then tag the merge commit and push the tag — the
+   PR body has the exact commands.
+
+The tag has to match `__version__` exactly; going through the workflow makes
+them agree by construction, because the PR *is* the bump. To assemble the
+changelog by hand instead, `uv tool run towncrier build --version X.Y.Z` does
+the same thing — but stage `upcoming_changes/` with `git add -A`, because
+towncrier deletes the fragments it consumed and a plain `git add CHANGELOG.rst`
+leaves the deletions behind for the next release to re-publish.
 
 `.github/workflows/publish.yml` builds the distributions, refuses a tag that
 does not match `__version__`, and uploads to PyPI through trusted publishing
@@ -155,6 +168,9 @@ SpyDE commit the app copies were taken from:
 * **The protocol is the contract.** `PLOTAPP:` JSON lines and `PLOTBIN:`
   binary frames over the sidecar's stdio. Both halves of it live in this one
   package on purpose; keep it that way.
+* **Every pull request carries its own changelog entry**, as a news fragment
+  under [`upcoming_changes/`](upcoming_changes/README.rst) — one file per PR,
+  so two of them never conflict over the same lines of `CHANGELOG.rst`.
 * **LF line endings**, enforced by `.gitattributes`.
 
 ## License

{de_shell-0.2.1 → de_shell-0.4.0}/de_shell/__init__.py

@@ -20,6 +20,6 @@ from __future__ import annotations
 
 #: The package version — the one place it is written. pyproject.toml reads it
 #: (dynamic version) and the release workflow refuses a tag that disagrees.
-__version__ = "0.2.1"
+__version__ = "0.4.0"
 
 __all__ = ["ipc", "log_stream", "process_guard", "debug_flags", "compute"]

de_shell-0.4.0/de_shell/js/main/framing.test.ts

@@ -0,0 +1,125 @@
+/**
+ * framing.test.ts — the encoders against the existing demuxer: whatever
+ * framing.ts writes, stdoutDemux.ts must read back unchanged, whole or split
+ * one byte at a time.
+ *
+ * Run: `node --test de_shell/js/main/framing.test.ts`, or via `npm run test:unit`.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { encodeBinary, encodeMessage } from './framing.ts'
+import { createStdoutDemux } from './stdoutDemux.ts'
+
+type Event =
+  | { kind: 'message'; msg: Record<string, unknown> }
+  | { kind: 'stream'; text: string }
+  | { kind: 'binary'; header: Record<string, unknown>; payload: string }
+
+/** Feed `stream` to a fresh demuxer in `step`-byte slices; return the event trace. */
+function decode(stream: Buffer, step = stream.length || 1): Event[] {
+  const events: Event[] = []
+  const demux = createStdoutDemux({
+    onMessage: (msg) => events.push({ kind: 'message', msg }),
+    onStream: (text) => events.push({ kind: 'stream', text }),
+    onBinary: (header, payload) =>
+      events.push({ kind: 'binary', header, payload: payload.toString('hex') }),
+  })
+  for (let pos = 0; pos < stream.length; pos += step) {
+    demux.push(stream.subarray(pos, pos + step))
+  }
+  return events
+}
+
+/** A whole binary frame as it goes on the wire: prefix, header, then the caller's payload. */
+function frame(header: Record<string, unknown>, payload: Buffer): Buffer {
+  return Buffer.concat([...encodeBinary(header, payload), payload])
+}
+
+function patternPayload(n: number): Buffer {
+  const p = Buffer.allocUnsafe(n)
+  for (let i = 0; i < n; i++) p[i] = i & 0xff // includes 0x0a bytes
+  return p
+}
+
+test('a message is one PLOTAPP line and decodes to the same object', () => {
+  const msg = { type: 'state_update', key: 'clim', value: [0, 255], nested: { ok: true, none: null } }
+  const bytes = encodeMessage(msg)
+  assert.equal(bytes.subarray(0, 8).toString('ascii'), 'PLOTAPP:')
+  assert.equal(bytes.indexOf(0x0a), bytes.length - 1, 'exactly one newline, at the end')
+  assert.deepEqual(decode(bytes), [{ kind: 'message', msg }])
+})
+
+test('a newline inside a string stays escaped, so the message is still one line', () => {
+  const msg = { type: 'status', text: 'line one\nline two\r\n' }
+  const bytes = encodeMessage(msg)
+  assert.equal(bytes.indexOf(0x0a), bytes.length - 1)
+  assert.deepEqual(decode(bytes), [{ kind: 'message', msg }])
+})
+
+test('a frame with an empty payload decodes with an empty payload', () => {
+  assert.deepEqual(decode(frame({ fig_id: 'f3', key: 'spec' }, Buffer.alloc(0))), [
+    { kind: 'binary', header: { fig_id: 'f3', key: 'spec' }, payload: '' },
+  ])
+})
+
+test('a payload holding newlines and PLOTBIN:/PLOTAPP: lookalikes decodes whole, at any chunking', () => {
+  const nasty = Buffer.concat([
+    Buffer.from('\nPLOTBIN:9:9\nPLOTAPP:{}\n', 'ascii'),
+    patternPayload(3000),
+  ])
+  const stream = Buffer.concat([
+    frame({ fig_id: 'f1', key: 'image' }, nasty),
+    encodeMessage({ type: 'done' }),
+  ])
+  const expected: Event[] = [
+    { kind: 'binary', header: { fig_id: 'f1', key: 'image' }, payload: nasty.toString('hex') },
+    { kind: 'message', msg: { type: 'done' } },
+  ]
+  for (const step of [stream.length, 65536, 7, 1]) {
+    assert.deepEqual(decode(stream, step), expected, `diverged at ${step}-byte chunks`)
+  }
+})
+
+test('a non-ASCII header: hlen counts UTF-8 bytes, not characters', () => {
+  const header = { fig_id: 'f', key: 'k', label: 'εxx Å' }
+  const [prefix, head] = encodeBinary(header, Buffer.from([1, 2, 3]))
+  const json = JSON.stringify(header)
+  assert.notEqual(Buffer.byteLength(json, 'utf8'), json.length, 'the fixture must be multi-byte')
+  assert.equal(prefix.toString('ascii'), `PLOTBIN:${Buffer.byteLength(json, 'utf8')}:3\n`)
+  assert.equal(head.toString('utf8'), json)
+  assert.deepEqual(decode(frame(header, Buffer.from([1, 2, 3])), 1), [
+    { kind: 'binary', header, payload: '010203' },
+  ])
+})
+
+test('encodeBinary returns the prefix and header only; the payload is never copied', () => {
+  const payload = patternPayload(64)
+  const parts = encodeBinary({ fig_id: 'f', key: 'k' }, payload)
+  assert.equal(parts.length, 2)
+  assert.ok(!parts.includes(payload))
+  assert.match(parts[0].toString('ascii'), /^PLOTBIN:\d+:64\n$/)
+})
+
+test('the layout is the documented wire format, byte for byte', () => {
+  // PLOTBIN:<hlen>:<plen>\n<header json><payload>, as anyplotlib's
+  // _binary_frame.encode_frame writes it and stdoutDemux.ts parses it.
+  const header = { fig_id: 'f', key: 'k', dims: [2, 2] }
+  const payload = Buffer.from([0, 10, 255, 10])
+  const json = JSON.stringify(header)
+  assert.deepEqual(frame(header, payload), Buffer.concat([
+    Buffer.from(`PLOTBIN:${Buffer.byteLength(json)}:4\n${json}`, 'utf8'),
+    payload,
+  ]))
+  assert.deepEqual(encodeMessage({ type: 'done' }), Buffer.from('PLOTAPP:{"type":"done"}\n', 'utf8'))
+})
+
+test('a non-finite number is refused rather than framed', () => {
+  for (const bad of [NaN, Infinity, -Infinity]) {
+    assert.throws(() => encodeMessage({ type: 'fit', value: bad }), RangeError)
+    assert.throws(
+      () => encodeBinary({ fig_id: 'f', key: 'k', clim: [0, bad] }, Buffer.alloc(0)),
+      RangeError,
+    )
+  }
+  assert.throws(() => encodeMessage({ a: { b: [1, NaN] } }), /non-finite/)
+})

de_shell-0.4.0/de_shell/js/main/framing.ts

@@ -0,0 +1,34 @@
+/**
+ * framing.ts — encoders for the backend wire format; the inverse of
+ * stdoutDemux.ts.
+ *
+ *   PLOTAPP:<json>\n                                  a message
+ *   PLOTBIN:<hlen>:<plen>\n<header json><payload>     a binary frame
+ *
+ * The layout ipc.emit and anyplotlib's _binary_frame.encode_frame write on the
+ * Python side. hlen and plen are byte counts. The JSON text is JSON.stringify's
+ * own (compact, raw UTF-8); every decoder of the format accepts it. Imports
+ * nothing.
+ */
+
+/** JSON.stringify replacer: a non-finite number is not JSON, so refuse it rather than emit null or NaN. */
+function refuseNonFinite(key: string, value: unknown): unknown {
+  if (typeof value === 'number' && !Number.isFinite(value)) {
+    throw new RangeError(`cannot frame the non-finite number ${value}${key ? ` at key "${key}"` : ''}`)
+  }
+  return value
+}
+
+/** `PLOTAPP:<json>\n`. JSON escapes every newline inside a string, so the message is one line. */
+export function encodeMessage(obj: Record<string, unknown>): Buffer {
+  return Buffer.from(`PLOTAPP:${JSON.stringify(obj, refuseNonFinite)}\n`, 'utf8')
+}
+
+/**
+ * The prefix line and the header bytes of a PLOTBIN frame. The payload is the
+ * caller's Buffer, written as its own chunk after these two, never copied.
+ */
+export function encodeBinary(header: Record<string, unknown>, payload: Buffer): [Buffer, Buffer] {
+  const head = Buffer.from(JSON.stringify(header, refuseNonFinite), 'utf8')
+  return [Buffer.from(`PLOTBIN:${head.length}:${payload.length}\n`, 'ascii'), head]
+}

{de_shell-0.2.1 → de_shell-0.4.0}/de_shell/js/main/index.ts

@@ -22,6 +22,10 @@ export {
 export { recordProblem, recordedProblems } from './problemLog'
 export type { Problem } from './problemLog'
 
+export { createRelay } from './relay'
+export type { Relay, RelayConnection, RelayCloseReason, RelayOptions } from './relay'
+export { encodeMessage, encodeBinary } from './framing'
+
 export {
   initErrorReporting, reportingConfigured, collectDiagnostics, submitReport,
 } from './errorReport'

{de_shell-0.2.1 → de_shell-0.4.0}/de_shell/js/main/pythonEnv.test.ts

@@ -10,9 +10,9 @@
  * Run: `node --test src/pythonEnv.test.ts` (from packages/shell-main/), or via
  * the `test:unit` npm script.
  */
-import { test } from 'node:test'
+import { test, after } from 'node:test'
 import assert from 'node:assert/strict'
-import { mkdtempSync, writeFileSync, mkdirSync } from 'fs'
+import { mkdtempSync, writeFileSync, mkdirSync, rmSync } from 'fs'
 import { join } from 'path'
 import { tmpdir } from 'os'
 import { configureShell } from './config.ts'
@@ -24,17 +24,29 @@ configureShell({
   pythonModule: 'testapp',
 })
 
+/** Every temp directory these tests make, removed when the file is done. */
+const tempDirs: string[] = []
+after(() => {
+  for (const dir of tempDirs) rmSync(dir, { recursive: true, force: true })
+})
+
+function tempDir(prefix: string): string {
+  const dir = mkdtempSync(join(tmpdir(), prefix))
+  tempDirs.push(dir)
+  return dir
+}
+
 /** A directory containing a uv stub under both spellings, so these tests do not
  *  fork on the host platform. */
 function dirWithUv(): string {
-  const dir = mkdtempSync(join(tmpdir(), 'uv-stub-'))
+  const dir = tempDir('uv-stub-')
   writeFileSync(join(dir, 'uv'), '')
   writeFileSync(join(dir, 'uv.exe'), '')
   return dir
 }
 
 function emptyDir(): string {
-  return mkdtempSync(join(tmpdir(), 'uv-none-'))
+  return tempDir('uv-none-')
 }
 
 /** An env whose PATH and every fallback root point somewhere we control. */