jmfts-web 0.6.0__tar.gz

jmfts_web-0.6.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fight Fire with Fire Robotics, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

jmfts_web-0.6.0/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: jmfts-web
+Version: 0.6.0
+Summary: Browser front end for a JMFTS retrieval appliance
+Author: Fight Fire with Fire Robotics, LLC
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jmccardle/jmfts
+Project-URL: Repository, https://github.com/jmccardle/jmfts
+Keywords: jmfts,retrieval,ui,frontend
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# jmfts-web
+
+The browser front end for a [JMFTS](https://github.com/jmccardle/jmfts) retrieval appliance.
+
+```bash
+pip install 'jmfts[web]'
+uvicorn jmfts_core.rest.main:app --host 0.0.0.0 --port 8100
+# then open http://localhost:8100/app/
+```
+
+This wheel carries built static files and one module that says where they are. It has **no
+dependencies**: everything the front end does it does in the browser, over the same REST API
+any other client calls. Installing it adds no Python package to the appliance.
+
+It is not useful on its own — there is nothing to import and nothing to run. `jmfts[web]`
+depends on it, and `jmfts_core.rest.main` mounts it at `/app` when it is present. An
+appliance without it starts normally and serves no `/app`.
+
+## One generated client, and one event per call
+
+`jmfts_web/static/client/` is the only way this front end talks to an appliance. Four of its
+files are generated from the appliance's own `/openapi.json`, the way `jmfts-client`'s
+`_verbs.py` is generated from the route table:
+
+```bash
+python -m scripts.generate_ts_client            # in a jmfts source checkout
+python -m scripts.generate_ts_client --check    # exit 1 if the bundle is stale
+```
+
+The other six are the hand-written runtime — the request path, the three copy-out printers,
+and the entry point. `tests/test_ts_client_codegen.py` refuses a stale generated file and
+refuses a file that is in neither set.
+
+Every call emits one event: `{op_id, method, path, path_params, query, body, status,
+response, ms}`. Three things follow from that.
+
+* **Replay.** An event is a call plus its arguments, so `client.replay(event, {…})` re-sends
+  it with any of them edited.
+* **Verifiable thinness.** A view showing something the call log has no event for computed it
+  in the browser. That is readable from the log rather than arguable from the source.
+* **Copy-out.** `asCurl`, `asPython` and `asFetch` print any event three ways — and none of
+  them prints the credential. Each names the environment variable it lives in instead.
+
+There is no build step and no bundler: these are ES modules the browser runs as they stand,
+with `.d.ts` declarations beside them for TypeScript consumers. Nothing loads from a CDN, a
+font host or anywhere but the appliance's own origin, because this appliance is expected to
+run air-gapped.
+
+## Why a separate distribution
+
+An extra guards dependencies. Static files inside the server package would ship with the
+appliance whether or not an extra named them, so `jmfts[web]` over a bundle in the main wheel
+would have been a flag that guards nothing. `Dockerfile.worker` builds a worker that drains
+the ingest queue and never serves a page.
+
+## Versioning
+
+One number, three wheels, one tag — `jmfts`, `jmfts-client` and `jmfts-web` release in
+lockstep. The front end is written against the appliance's own route table, so a UI one
+release behind its server renders controls for operations that have moved.
+
+## Licence
+
+MIT. See `LICENSE`.

jmfts_web-0.6.0/README.md

@@ -0,0 +1,64 @@
+# jmfts-web
+
+The browser front end for a [JMFTS](https://github.com/jmccardle/jmfts) retrieval appliance.
+
+```bash
+pip install 'jmfts[web]'
+uvicorn jmfts_core.rest.main:app --host 0.0.0.0 --port 8100
+# then open http://localhost:8100/app/
+```
+
+This wheel carries built static files and one module that says where they are. It has **no
+dependencies**: everything the front end does it does in the browser, over the same REST API
+any other client calls. Installing it adds no Python package to the appliance.
+
+It is not useful on its own — there is nothing to import and nothing to run. `jmfts[web]`
+depends on it, and `jmfts_core.rest.main` mounts it at `/app` when it is present. An
+appliance without it starts normally and serves no `/app`.
+
+## One generated client, and one event per call
+
+`jmfts_web/static/client/` is the only way this front end talks to an appliance. Four of its
+files are generated from the appliance's own `/openapi.json`, the way `jmfts-client`'s
+`_verbs.py` is generated from the route table:
+
+```bash
+python -m scripts.generate_ts_client            # in a jmfts source checkout
+python -m scripts.generate_ts_client --check    # exit 1 if the bundle is stale
+```
+
+The other six are the hand-written runtime — the request path, the three copy-out printers,
+and the entry point. `tests/test_ts_client_codegen.py` refuses a stale generated file and
+refuses a file that is in neither set.
+
+Every call emits one event: `{op_id, method, path, path_params, query, body, status,
+response, ms}`. Three things follow from that.
+
+* **Replay.** An event is a call plus its arguments, so `client.replay(event, {…})` re-sends
+  it with any of them edited.
+* **Verifiable thinness.** A view showing something the call log has no event for computed it
+  in the browser. That is readable from the log rather than arguable from the source.
+* **Copy-out.** `asCurl`, `asPython` and `asFetch` print any event three ways — and none of
+  them prints the credential. Each names the environment variable it lives in instead.
+
+There is no build step and no bundler: these are ES modules the browser runs as they stand,
+with `.d.ts` declarations beside them for TypeScript consumers. Nothing loads from a CDN, a
+font host or anywhere but the appliance's own origin, because this appliance is expected to
+run air-gapped.
+
+## Why a separate distribution
+
+An extra guards dependencies. Static files inside the server package would ship with the
+appliance whether or not an extra named them, so `jmfts[web]` over a bundle in the main wheel
+would have been a flag that guards nothing. `Dockerfile.worker` builds a worker that drains
+the ingest queue and never serves a page.
+
+## Versioning
+
+One number, three wheels, one tag — `jmfts`, `jmfts-client` and `jmfts-web` release in
+lockstep. The front end is written against the appliance's own route table, so a UI one
+release behind its server renders controls for operations that have moved.
+
+## Licence
+
+MIT. See `LICENSE`.

jmfts_web-0.6.0/jmfts_web/__init__.py

@@ -0,0 +1,73 @@
+"""jmfts-web — the browser front end for a JMFTS appliance, as its own distribution.
+
+IC-5, ``docs/SPRINT_0_6_0.md`` Block F step 19. This package holds one thing: a directory of
+built static files, and the function that says where it is. There is no Python logic here and
+there is not meant to be — the appliance mounts :func:`static_dir` and serves it, and
+everything the front end does it does by calling the same REST API any other client calls.
+
+**Why this is a third distribution rather than a directory inside ``jmfts_core``.** An extra
+guards dependencies. Static files inside the server package ship with the appliance whether or
+not an extra names them, so ``jmfts[web]`` over a bundle in the main wheel would have been a
+flag that guards nothing. ``Dockerfile.worker`` builds a worker that drains the ingest queue
+and never serves a page; it should not carry a UI it cannot use. Question 4.8 of that sprint
+plan records the cost that was accepted for this: a third version in ``bump-version.sh``, a
+step in ``docs/RELEASING.md``, and a third case in ``.github/workflows/publish.yml``.
+
+**The version tracks the other two exactly.** One number, three wheels, one tag. The front end
+is generated against the appliance's own route table, so a client one release behind its server
+is a client that renders controls for operations that have moved.
+
+``jmfts_core.rest.main`` imports this package inside a ``try``: a base install has no
+``jmfts_web`` and must start anyway, with no ``/app`` route rather than a broken one.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+__version__ = "0.6.0"
+
+__all__ = ["static_dir", "index_path", "__version__"]
+
+#: The bundle, relative to this file. ``tests/test_web_distribution.py`` refuses a
+#: distribution whose bundle is missing.
+#:
+#: **There is no build step and that is not an omission.** Part of ``static/client/`` IS
+#: generated — ``scripts.generate_ts_client`` renders it from the appliance's
+#: ``/openapi.json`` (Block F step 23) — but it is generated as ES modules the browser runs
+#: as they stand, so nothing has to be compiled between here and a page. What a build step
+#: would add is a bundler and a TypeScript compiler, and Block F step 24 is where that
+#: decision belongs; until there is a source tree to compile, it would be a file that runs
+#: and does nothing.
+_STATIC = Path(__file__).resolve().parent / "static"
+
+
+def static_dir() -> Path:
+    """The directory to mount, as an absolute path.
+
+    Raises ``FileNotFoundError`` when the bundle is absent rather than returning a path that
+    does not exist. A ``StaticFiles`` mount over a missing directory raises at mount time in
+    some Starlette versions and answers 404 for every asset in others; neither is a state the
+    appliance should boot into quietly, because both look exactly like "the front end is
+    broken" to whoever opens it.
+    """
+    if not _STATIC.is_dir():
+        raise FileNotFoundError(
+            f"jmfts-web is installed but its bundle is missing at {_STATIC}. "
+            "This is a packaging fault, not a configuration one: reinstall the wheel, or in "
+            "a source checkout run python -m scripts.generate_ts_client."
+        )
+    return _STATIC
+
+
+def index_path() -> Path:
+    """The single-page entry document.
+
+    Named separately from :func:`static_dir` because the mount serves assets by path and the
+    application needs one document served for every unmatched route — a front end with client
+    -side routing answers ``/app/search`` from the same file as ``/app/``.
+    """
+    index = static_dir() / "index.html"
+    if not index.is_file():
+        raise FileNotFoundError(f"jmfts-web's bundle has no index.html at {index}.")
+    return index

jmfts_web-0.6.0/jmfts_web/static/client/copyout.d.ts

@@ -0,0 +1,23 @@
+// Types for the three copy-out renderers. Hand-written; `copyout.js` is the code.
+
+import type { CallEvent } from "./transport.js";
+
+export interface CopyOutOptions {
+  /**
+   * The appliance's origin to print. Empty keeps the URL relative, which is right for
+   * `fetch` from the same page and wrong for a `curl` somebody will paste into a terminal.
+   */
+  baseUrl?: string;
+}
+
+/** The event as a `curl` invocation, with the credential named and never printed. */
+export declare function asCurl(event: CallEvent, options?: CopyOutOptions): string;
+
+/**
+ * The event as a `jmfts_client.RemoteJmftsClient` call, or as the `httpx` call that is its
+ * honest equivalent for a route with no generated verb.
+ */
+export declare function asPython(event: CallEvent, options?: CopyOutOptions): string;
+
+/** The event as the browser `fetch` this client itself issued. */
+export declare function asFetch(event: CallEvent, options?: CopyOutOptions): string;

jmfts_web-0.6.0/jmfts_web/static/client/copyout.js

@@ -0,0 +1,226 @@
+// @ts-self-types="./copyout.d.ts"
+//
+// A call event, printed three ways. Hand-written.
+//
+// docs/SPRINT_0_6_0.md Block F step 23, third property: "an operation id maps to a
+// `_verbs.py` method name, so an event prints as curl with the token elided, as a
+// RemoteJmftsClient call, and as fetch. Worked examples stop being a thing anybody writes
+// by hand."
+//
+// That is the point. Every example in this appliance's documentation of how to call it is a
+// thing that can go stale; a printed event cannot, because it is a transcript of a request
+// that was actually made a moment ago, rendered from the same table the request was built
+// from.
+//
+// THE CREDENTIAL IS NEVER PRINTED. Each renderer names the environment variable or the
+// variable the reader is expected to supply. A copy button that put the appliance's token on
+// the clipboard, and from there into a chat window or a bug report, would be a credential
+// leak with a convenience feature around it.
+
+import { OPERATIONS } from "./operations.js";
+import { queryString } from "./transport.js";
+
+/** The shell/environment variable each credential is named by, never its value. */
+const CREDENTIAL_ENV = Object.freeze({
+  JMFTSToken: "JMFTS_API_TOKEN",
+  JMFTSRunnerKey: "JMFTS_RUNNER_KEY",
+});
+
+function operationFor(event) {
+  const op = OPERATIONS[event.op_id];
+  if (!op) throw new Error(`no such operation: ${event.op_id}`);
+  return op;
+}
+
+/** `'...'` for POSIX sh, with embedded single quotes closed and reopened. */
+function shellQuote(text) {
+  return `'${String(text).replace(/'/g, `'\\''`)}'`;
+}
+
+/** Continue a multi-line literal from the column it was written at. */
+function reindent(text, spaces) {
+  const pad = " ".repeat(spaces);
+  return text.split("\n").join(`\n${pad}`);
+}
+
+/** What a file part is, without its bytes: curl and fetch both need the name, not the data. */
+function partName(value) {
+  if (value && typeof value === "object" && typeof value.name === "string") return value.name;
+  return "FILE";
+}
+
+/**
+ * The event as a `curl` invocation.
+ *
+ * @param {object} event a call event
+ * @param {{baseUrl?: string}} [options] the appliance's origin; "" keeps the path relative
+ */
+export function asCurl(event, options = {}) {
+  const op = operationFor(event);
+  const base = (options.baseUrl ?? "").replace(/\/$/, "");
+  const url = base + event.path + queryString(event.query);
+  const lines = [`curl -sS -X ${op.method}`];
+
+  if (op.security_scheme) {
+    // Double quotes so the shell expands the variable; the value itself is never here.
+    lines.push(`  -H "Authorization: Bearer $${CREDENTIAL_ENV[op.security_scheme]}"`);
+  }
+  if (op.body_media_type === "multipart/form-data") {
+    for (const name of op.file_params) {
+      if (event.body?.[name] !== undefined) {
+        lines.push(`  -F ${shellQuote(`${name}=@${partName(event.body[name])}`)}`);
+      }
+    }
+    for (const name of op.form_params) {
+      if (event.body?.[name] !== undefined && event.body[name] !== null) {
+        lines.push(`  -F ${shellQuote(`${name}=${JSON.stringify(event.body[name])}`)}`);
+      }
+    }
+  } else if (op.body_param && event.body !== undefined) {
+    if (op.body_media_type === "application/json") {
+      lines.push(`  -H 'Content-Type: application/json'`);
+      lines.push(`  -d ${shellQuote(JSON.stringify(event.body))}`);
+    } else {
+      lines.push(`  -H ${shellQuote(`Content-Type: ${op.body_media_type}; charset=utf-8`)}`);
+      lines.push(`  -d ${shellQuote(event.body)}`);
+    }
+  }
+  if (op.binary) {
+    lines.push(`  -o out.${(op.response_media_type || "bin").split("/").pop()}`);
+  }
+  lines.push(`  ${shellQuote(url)}`);
+  return lines.join(" \\\n");
+}
+
+/** A JSON value as Python source. */
+function asPythonLiteral(value, indent = "") {
+  if (value === null || value === undefined) return "None";
+  if (value === true) return "True";
+  if (value === false) return "False";
+  if (typeof value === "number") return String(value);
+  if (typeof value === "string") return JSON.stringify(value);
+  if (Array.isArray(value)) {
+    if (value.length === 0) return "[]";
+    const inner = value.map((v) => `${indent}    ${asPythonLiteral(v, `${indent}    `)}`);
+    return `[\n${inner.join(",\n")},\n${indent}]`;
+  }
+  if (value instanceof Blob) return `open(${JSON.stringify(partName(value))}, "rb").read()`;
+  const entries = Object.entries(value);
+  if (entries.length === 0) return "{}";
+  const inner = entries.map(
+    ([k, v]) => `${indent}    ${JSON.stringify(k)}: ${asPythonLiteral(v, `${indent}    `)}`
+  );
+  return `{\n${inner.join(",\n")},\n${indent}}`;
+}
+
+/**
+ * The event as a `jmfts_client.RemoteJmftsClient` call.
+ *
+ * Seven of the appliance's routes are hand-written FastAPI routes rather than `@expose`'d
+ * service methods, so they have no generated verb. For those this prints the `httpx` call
+ * that is the honest equivalent, rather than a client method that does not exist.
+ */
+export function asPython(event, options = {}) {
+  const op = operationFor(event);
+  const base = options.baseUrl || "http://localhost:8100";
+  const env = op.security_scheme ? CREDENTIAL_ENV[op.security_scheme] : null;
+
+  if (!op.python_verb) {
+    const header = env ? `, headers={"Authorization": f"Bearer {os.environ['${env}']}"}` : "";
+    const body =
+      op.body_param && event.body !== undefined ? `, json=${asPythonLiteral(event.body)}` : "";
+    const url = `${base}${event.path}${queryString(event.query)}`;
+    return [
+      ...(env ? ["import os", ""] : []),
+      "import httpx",
+      "",
+      `# ${op.op_id} is a hand-written route: jmfts-client has no verb for it.`,
+      `httpx.request(${JSON.stringify(op.method)}, ${JSON.stringify(url)}${header}${body})`,
+    ].join("\n");
+  }
+
+  // Arguments are printed one per line at eight spaces, so nested literals continue from
+  // there: a pasted call has to be valid Python, not merely recognisable as one.
+  const inner = "        ";
+  const args = [];
+  for (const name of op.path_params) {
+    args.push(`${name}=${asPythonLiteral(event.path_params[name], inner)}`);
+  }
+  if (op.body_param && event.body !== undefined) {
+    args.push(`${op.body_param}=${asPythonLiteral(event.body, inner)}`);
+  }
+  for (const name of [...op.file_params, ...op.form_params]) {
+    if (event.body?.[name] !== undefined) {
+      args.push(`${name}=${asPythonLiteral(event.body[name], inner)}`);
+    }
+  }
+  for (const [name, value] of Object.entries(event.query)) {
+    args.push(`${name}=${asPythonLiteral(value, inner)}`);
+  }
+
+  const token = env ? `, token=os.environ[${JSON.stringify(env)}]` : "";
+  const imports = env ? ["import os", ""] : [];
+  return [
+    ...imports,
+    "from jmfts_client import RemoteJmftsClient",
+    "",
+    `with RemoteJmftsClient(${JSON.stringify(base)}${token}) as client:`,
+    `    result = client.${op.python_verb}(`,
+    ...args.map((arg) => `        ${arg},`),
+    "    )",
+  ].join("\n");
+}
+
+/** The event as a browser `fetch`, which is what this client itself did. */
+export function asFetch(event, options = {}) {
+  const op = operationFor(event);
+  const base = (options.baseUrl ?? "").replace(/\/$/, "");
+  const url = base + event.path + queryString(event.query);
+  const headers = [];
+  if (op.security_scheme) headers.push(`      "Authorization": \`Bearer \${token}\`,`);
+
+  const init = [`    method: ${JSON.stringify(op.method)},`];
+  let prelude = [];
+  if (op.body_media_type === "multipart/form-data") {
+    prelude = ["const form = new FormData();"];
+    for (const name of op.file_params) {
+      if (event.body?.[name] !== undefined) {
+        // The bytes are not printable, so this names where they come from and says which
+        // file was actually sent. Nothing here pretends to reproduce the upload.
+        prelude.push(
+          `form.append(${JSON.stringify(name)}, fileInput.files[0]); ` +
+            `// was: ${partName(event.body[name])}`
+        );
+      }
+    }
+    for (const name of op.form_params) {
+      if (event.body?.[name] !== undefined && event.body[name] !== null) {
+        prelude.push(
+          `form.append(${JSON.stringify(name)}, ${JSON.stringify(
+            JSON.stringify(event.body[name])
+          )});`
+        );
+      }
+    }
+    init.push("    body: form,");
+  } else if (op.body_param && event.body !== undefined) {
+    if (op.body_media_type === "application/json") {
+      headers.push(`      "Content-Type": "application/json",`);
+      init.push(`    body: JSON.stringify(${reindent(JSON.stringify(event.body, null, 2), 4)}),`);
+    } else {
+      const declared = JSON.stringify(`${op.body_media_type}; charset=utf-8`);
+      headers.push(`      "Content-Type": ${declared},`);
+      init.push(`    body: ${JSON.stringify(event.body)},`);
+    }
+  }
+  if (headers.length) init.splice(1, 0, "    headers: {", ...headers, "    },");
+
+  const read = op.binary ? "await response.blob()" : "await response.json()";
+  return [
+    ...prelude,
+    `const response = await fetch(${JSON.stringify(url)}, {`,
+    ...init,
+    "});",
+    `const result = ${read};`,
+  ].join("\n");
+}

jmfts_web-0.6.0/jmfts_web/static/client/index.d.ts

@@ -0,0 +1,18 @@
+// Types for the entry point. Hand-written; `index.js` is the code.
+
+export { JmftsClient } from "./verbs.js";
+export { OPERATIONS, OP_IDS } from "./operations.js";
+export type { Operation, OpId } from "./operations.js";
+export {
+  CALL_EVENT_FIELDS,
+  CREDENTIAL_KEYS,
+  TOKEN_KEY,
+  JmftsHttpError,
+  JmftsTransport,
+  JmftsTransportError,
+  credentialStorage,
+  detailOf,
+} from "./transport.js";
+export type { CallEvent, JmftsTransportOptions } from "./transport.js";
+export { asCurl, asFetch, asPython } from "./copyout.js";
+export type { CopyOutOptions } from "./copyout.js";

jmfts_web-0.6.0/jmfts_web/static/client/index.js

@@ -0,0 +1,26 @@
+// @ts-self-types="./index.d.ts"
+//
+// The one import a view needs. Hand-written.
+//
+// docs/SPRINT_0_6_0.md Block F step 23. Every view calls ONE client, and this is the door to
+// it — `import { JmftsClient } from "./client/index.js"`. Nothing here has behaviour; the
+// request path is transport.js, the operation table and the verbs are generated, and the
+// three printers are copyout.js.
+//
+// No build step and no bundler: this is an ES module the browser executes as it stands, and
+// it loads nothing from anywhere but this origin. The appliance is expected to run
+// air-gapped, and a page that renders blank without internet is worse than no page.
+
+export { JmftsClient } from "./verbs.js";
+export { OPERATIONS, OP_IDS } from "./operations.js";
+export {
+  CALL_EVENT_FIELDS,
+  CREDENTIAL_KEYS,
+  TOKEN_KEY,
+  JmftsHttpError,
+  JmftsTransport,
+  JmftsTransportError,
+  credentialStorage,
+  detailOf,
+} from "./transport.js";
+export { asCurl, asFetch, asPython } from "./copyout.js";