npm - @terminus-ai/cli - Versions diffs - 0.0.1 - Mend

@terminus-ai/cli 0.0.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.

Files changed (60) hide show

package/LICENSE +21 -0
package/README.md +1055 -0
package/bin/agent-discovery.mjs +71 -0
package/bin/agent-icon.mjs +77 -0
package/bin/agent-models.mjs +77 -0
package/bin/agent-type.mjs +51 -0
package/bin/agentdev.mjs +657 -0
package/bin/app-route-script.mjs +59 -0
package/bin/app-runtime-contract.mjs +2 -0
package/bin/appdev-remote.mjs +346 -0
package/bin/appdev.mjs +4446 -0
package/bin/apps.mjs +5512 -0
package/bin/capability-calls.mjs +437 -0
package/bin/capsule-data.mjs +260 -0
package/bin/client.mjs +189 -0
package/bin/commands.mjs +1194 -0
package/bin/dev-capsules.mjs +1599 -0
package/bin/dev-contract.mjs +262 -0
package/bin/dev-data.mjs +287 -0
package/bin/dev-members.mjs +18 -0
package/bin/dev-net.mjs +316 -0
package/bin/dev-notification-popup.mjs +628 -0
package/bin/dev-ports.mjs +567 -0
package/bin/dev-server-binding.mjs +35 -0
package/bin/dev-server-ops.mjs +1086 -0
package/bin/dev-ui/IoskeleyMono-400.woff2 +0 -0
package/bin/dev-ui/IoskeleyMono-600.woff2 +0 -0
package/bin/dev-ui/OFL.txt +92 -0
package/bin/dev-ui/agent-robot.webp +0 -0
package/bin/dev-ui/app.js +5217 -0
package/bin/dev-ui/highlight.js +195 -0
package/bin/dev-ui/index.html +34 -0
package/bin/dev-ui/style.css +3640 -0
package/bin/devlint.mjs +112 -0
package/bin/devserver.mjs +2127 -0
package/bin/devtriggers.mjs +367 -0
package/bin/endpoints.mjs +156 -0
package/bin/errors.mjs +61 -0
package/bin/files.mjs +169 -0
package/bin/horizontal-capabilities/v1/contract.json +280 -0
package/bin/http.mjs +500 -0
package/bin/lint-manifests/justbash-commands.json +88 -0
package/bin/lint-manifests/python-stdlib.json +295 -0
package/bin/login-page.mjs +488 -0
package/bin/schedules.mjs +664 -0
package/bin/server-sandbox.mjs +204 -0
package/bin/servicedev.mjs +425 -0
package/bin/sync.mjs +357 -0
package/bin/terminus.js +3666 -0
package/bin/toolchain.mjs +125 -0
package/bin/vendor/app-runtime-v1/app-host.json +124 -0
package/bin/vendor/app-runtime-v1/capability-calls.json +412 -0
package/bin/vendor/app-runtime-v1/doors.json +2867 -0
package/bin/vendor/appd/node-harness.mjs +209 -0
package/bin/vendor/appd/python-harness.py +12 -0
package/bin/vendor/appd/server-protocol.json +84 -0
package/bin/vendor/where.mjs +541 -0
package/bin/versioning.mjs +72 -0
package/bin/write-rules.mjs +398 -0
package/package.json +41 -0

package/bin/app-route-script.mjs ADDED Viewed

@@ -0,0 +1,59 @@
+/*
+ * Routes into an app that is already open.
+ *
+ * The desk asks an open app window to go somewhere by changing its frame's
+ * fragment to `#terminus-route=<encodeURIComponent(path)>`, where the path is
+ * same-origin: it starts with "/", its second character is not "/", and it
+ * holds no "\". The app host puts this one inline classic script in every
+ * HTML document it serves for an app, as the first child of <head>, before any
+ * app script runs:
+ *
+ * - on a fresh load the fragment simply becomes the page's own URL, so an app
+ *   that reads `location` at startup opens at the route;
+ * - on a live `hashchange` it dispatches a cancelable `terminus:route` event on
+ *   `window` (the SDK's `routes.onRoute`); an app that handles routes calls
+ *   `preventDefault()`, and any other app reloads at the route.
+ *
+ * `terminus dev` serves app documents the way the host does, so this is the
+ * host's script, word for word — keep it in step with the app host
+ * (terminus-frontend `workers/app-host.ts`). The dev servers set no
+ * Content-Security-Policy and put no nonce on scripts, so it carries none.
+ */
+/** The script, exactly as the app host injects it. */
+export const APP_ROUTE_SCRIPT = String.raw`(function () {
+  var P = "#terminus-route=";
+  function read() {
+    if (location.hash.indexOf(P) !== 0) return null;
+    var route;
+    try { route = decodeURIComponent(location.hash.slice(P.length)); } catch (error) { return null; }
+    return route.charAt(0) === "/" && route.charAt(1) !== "/" && route.indexOf("\\") < 0 ? route : null;
+  }
+  if (location.hash.indexOf(P) === 0) {
+    history.replaceState(history.state, "", read() || location.pathname + location.search);
+  }
+  addEventListener("hashchange", function () {
+    if (location.hash.indexOf(P) !== 0) return;
+    var route = read();
+    history.replaceState(history.state, "", route || location.pathname + location.search);
+    if (!route) return;
+    var event = new CustomEvent("terminus:route", { detail: { route: route }, cancelable: true });
+    if (dispatchEvent(event)) location.reload();
+  });
+})();`;
+const HEAD_OPENING = /<head(?=[\s/>])[^>]*>/i;
+const LEADING_DOCTYPE = /^\s*<!doctype[^>]*>/i;
+/**
+ * Put the route script in an app's HTML document: the first child of <head>,
+ * or — a document with no <head> — the very top, after the doctype when there
+ * is one (anything ahead of a doctype drops the page into quirks mode).
+ */
+export function injectAppRouteScript(html) {
+  const head = HEAD_OPENING.exec(html);
+  const at = head
+    ? head.index + head[0].length
+    : (LEADING_DOCTYPE.exec(html)?.[0].length ?? 0);
+  return `${html.slice(0, at)}<script>${APP_ROUTE_SCRIPT}</script>${html.slice(at)}`;
+}

package/bin/app-runtime-contract.mjs ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ /** Sole public app-runtime major shared by the dev host and SDK metadata command. */
2	+ export const APP_RUNTIME_API_VERSION = 1;

package/bin/appdev-remote.mjs ADDED Viewed

@@ -0,0 +1,346 @@
+/**
+ * `terminus dev --remote`: the local ui/ bundle against the PRODUCTION
+ * app runtime instead of the SQLite harness.
+ *
+ * The handshake is the one the wildcard app host performs: the CLI's login
+ * session mints a one-time browser authorization for the published app
+ * (`POST /v1/app-runtime/authorizations`), exchanges it for an app session
+ * token (`POST /v1/app-runtime/session`), and then proxies `/_terminus/*`
+ * to the platform with that bearer.
+ *
+ * The routing is the app host's own, read from its contract (app-host.json,
+ * vendored under bin/vendor/app-runtime-v1/ from the SDK's conformance
+ * bundle) rather than copied by hand: the first-segment allowlist, the
+ * bootstrap and capability rewrites, the header allowlists both ways, the
+ * doors the host answers itself (icon, logout and sign-in; callback, open and
+ * guest are the browser's way in, which a CLI session never goes through),
+ * and the error codes. SSE streams through untouched.
+ *
+ * The CLI's own calls here (the handshake, the sign-out) are doors of
+ * bin/endpoints.mjs like any other; what it forwards for the app goes
+ * through bin/http.mjs's `openResponse`, routed by that contract.
+ */
+import { createServer } from "node:http";
+import path from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { readDevPackage, requireBuiltDevBundle, serveUiAsset } from "./appdev.mjs";
+import { CliError } from "./errors.mjs";
+import { Api, openResponse } from "./http.mjs";
+import { APP_HOST, DOORS, returnToPath, runtimeError, sendRuntimeError } from "./dev-contract.mjs";
+import {
+  answerDevAbout,
+  assertDevPortRangeAvailable,
+  closeDevServer,
+  DEV_ABOUT_PATH,
+  devPortUnavailableError,
+  isLoopbackHost,
+  isLoopbackOrigin,
+  listenDevServer,
+  refuseCrossSite,
+  refuseForeignHost,
+  resolveDevPortRange,
+} from "./dev-ports.mjs";
+const SAFE_METHODS = new Set(["GET", "HEAD"]);
+const ALLOWED_SEGMENTS = new Set(APP_HOST.allowed_segments);
+const WORKER_HANDLED = new Set(APP_HOST.worker_handled);
+/** What a worker-handled door answers to, by name: its door's method, read
+ * from doors.json (a GET door answers HEAD too). A door app-host.json names
+ * that doors.json does not have is a contract that disagrees with itself. */
+const WORKER_METHODS = Object.fromEntries(APP_HOST.worker_handled.map((name) => {
+  const door = DOORS.doors.find((candidate) => candidate.worker_handled && candidate.path === `/${name}`);
+  if (!door) throw new Error(`app-host.json's worker door '${name}' is not in doors.json`);
+  return [name, door.method === "GET" ? ["GET", "HEAD"] : [door.method]];
+}));
+/** Mint an app session exactly the way the production app host does: the
+ * login (`api`) authorizes the app, and the code is exchanged with no
+ * credential at all, as the host's callback exchanges it. */
+export async function mintRemoteAppSession({ api, appId }) {
+  const authorization = await api.json("POST /v1/app-runtime/authorizations", { body: { app_id: appId } });
+  if (!authorization?.code || !authorization?.web_host) {
+    throw new CliError("the Terminus API returned an incomplete app authorization");
+  }
+  const session = await new Api({ base: api.base }).json("POST /v1/app-runtime/session", {
+    body: { code: authorization.code, host: authorization.web_host },
+  });
+  if (!session?.token) throw new CliError("the Terminus API returned no app session token");
+  return {
+    token: session.token,
+    expiresAt: session.expires_at ?? null,
+    webHost: authorization.web_host,
+    appName: authorization.app_name ?? null,
+    kind: authorization.kind ?? null,
+  };
+}
+/**
+ * Where the app host sends `method` `pathname` (a `/_terminus/...` path):
+ * `{ upstream, headers }` for a platform door (upstream in the route
+ * contract's `/v1/...` spelling), `{ worker }` for a door the host answers
+ * itself, or `{ error: { code, message } }`.
+ */
+export function remoteRuntimeRoute(pathname, method = "GET") {
+  const prefix = `${APP_HOST.prefix}/`;
+  if (!pathname.startsWith(prefix)) return { error: { code: "not_found", message: "Unknown app API route" } };
+  const suffix = pathname.slice(prefix.length);
+  const segments = suffix.split("/");
+  const refused = { error: { code: "not_found", message: "Unknown app API route" } };
+  if (!suffix || suffix.length > 1024) return refused;
+  try {
+    for (const encoded of segments) {
+      const segment = decodeURIComponent(encoded);
+      if (!segment || segment === "." || segment === ".." || /[/\\\p{Cc}]/u.test(segment)) return refused;
+    }
+  } catch {
+    return refused;
+  }
+  if (segments.length === 1 && WORKER_HANDLED.has(segments[0])) {
+    if (!WORKER_METHODS[segments[0]].includes(method)) {
+      return { error: { code: "method_not_allowed", message: `${pathname} does not answer ${method}` } };
+    }
+    return { worker: segments[0] };
+  }
+  if (`/${suffix}` === APP_HOST.bootstrap.path) {
+    if (!APP_HOST.bootstrap.methods.includes(method)) {
+      return { error: { code: "method_not_allowed", message: "bootstrap answers GET and HEAD" } };
+    }
+    return { upstream: APP_HOST.bootstrap.upstream, headers: {} };
+  }
+  if (!ALLOWED_SEGMENTS.has(segments[0])) return refused;
+  for (const rewrite of APP_HOST.rewrites) {
+    if (`/${suffix}` === rewrite.prefix || `/${suffix}`.startsWith(`${rewrite.prefix}/`)) {
+      return {
+        upstream: `${rewrite.upstream_prefix}${`/${suffix}`.slice(rewrite.prefix.length)}`,
+        headers: { ...rewrite.request_headers },
+      };
+    }
+  }
+  return { upstream: `${APP_HOST.default_upstream_prefix}/${suffix}`, headers: {} };
+}
+/** A `/v1/...` route on the platform whose API base is `apiBase` (`…/v1`). */
+function upstreamUrl(apiBase, upstream, search = "") {
+  const base = apiBase.replace(/\/+$/u, "");
+  const root = base.endsWith("/v1") && upstream.startsWith("/v1/") ? base.slice(0, -3) : base;
+  return `${root}${upstream}${search}`;
+}
+/** The response headers the app host passes through for `pathname`. */
+function passedHeaders(upstreamHeaders, pathname) {
+  const headers = { ...APP_HOST.added_response_headers };
+  for (const name of APP_HOST.response_headers) {
+    const value = upstreamHeaders.get(name);
+    if (value) headers[name] = value;
+  }
+  const suffix = pathname.slice(APP_HOST.prefix.length);
+  for (const override of APP_HOST.response_header_overrides) {
+    if (suffix.startsWith(override.prefix)) Object.assign(headers, override.headers);
+  }
+  return headers;
+}
+/** Forward one request to the platform with a bearer (none for a
+ * sessionless door), streaming the upstream body straight back. Shared with
+ * the local harness, whose capability plane is the same platform proxy. */
+export async function forwardPlatformRequest(target, bearer, method, request, response, artifactContext = null, { pathname = null } = {}) {
+  const headers = bearer ? { authorization: `Bearer ${bearer}` } : {};
+  if (artifactContext) headers["x-terminus-artifact-context"] = artifactContext;
+  for (const name of APP_HOST.request_headers) {
+    const value = request.headers[name];
+    if (value) headers[name] = Array.isArray(value) ? value.join(", ") : value;
+  }
+  let body;
+  if (!SAFE_METHODS.has(method)) {
+    const chunks = [];
+    for await (const chunk of request) chunks.push(chunk);
+    body = Buffer.concat(chunks);
+  }
+  const abort = new AbortController();
+  response.on("close", () => abort.abort());
+  let upstream;
+  try {
+    // The app host passes redirects through rather than following them, and
+    // the platform's own deadlines answer a slow door.
+    upstream = await openResponse(target, {
+      method,
+      headers,
+      body,
+      bodyBytes: body?.length ?? 0,
+      redirect: "manual",
+      timeoutMs: null,
+      signal: abort.signal,
+    });
+  } catch (error) {
+    if (abort.signal.aborted) return response.end();
+    return sendRuntimeError(response, runtimeError("service_unavailable", error.message));
+  }
+  response.writeHead(upstream.status, passedHeaders(upstream.headers, pathname ?? new URL(target).pathname));
+  if (!upstream.body || method === "HEAD") return response.end();
+  response.flushHeaders();
+  try {
+    await pipeline(Readable.fromWeb(upstream.body), response);
+  } catch {
+    // The browser went away mid-stream (EventSource reconnects, tab closed):
+    // the abort above already cancelled the upstream request.
+    if (!response.writableEnded) response.end();
+  }
+  return undefined;
+}
+/**
+ * Forward one `/_terminus/*` request the way the app host does. `remote`
+ * holds the session; the host answers icon, logout and sign-in itself, and a
+ * signed-out session refuses every other door until the app is opened again
+ * or signs in (`signIn` mints the session anew, as opening the app does).
+ */
+export async function proxyRemoteRuntime(remote, url, request, response, { signIn = null } = {}) {
+  const method = (request.method ?? "GET").toUpperCase();
+  const route = remoteRuntimeRoute(url.pathname, method);
+  if (route.error) {
+    if (route.error.code === "method_not_allowed") {
+      response.setHeader("allow", (url.pathname.endsWith(APP_HOST.bootstrap.path)
+        ? APP_HOST.bootstrap.methods
+        : WORKER_METHODS[url.pathname.split("/").at(-1)] ?? []).join(", "));
+    }
+    return sendRuntimeError(response, runtimeError(route.error.code, route.error.message));
+  }
+  if (route.worker === "icon") {
+    // Sessionless, by the app's own host name, as the app host asks for it.
+    return forwardPlatformRequest(
+      upstreamUrl(remote.apiBase, "/v1/app-runtime/icon", `?host=${encodeURIComponent(remote.webHost ?? "")}`),
+      null,
+      method,
+      request,
+      response,
+      null,
+      { pathname: url.pathname },
+    );
+  }
+  if (route.worker === "logout") {
+    // Revoke the session, as the host does; the browser's next open of the
+    // app mints a new one (the host would send it to the sign-in page).
+    const revoked = remote.token;
+    remote.token = null;
+    if (revoked) {
+      await new Api({ base: remote.apiBase, token: revoked })
+        .request("DELETE /v1/app-runtime/session/current", { as: "none" })
+        .catch(() => undefined);
+    }
+    response.writeHead(303, { location: "/" });
+    return response.end();
+  }
+  if (route.worker === "signin" && signIn) {
+    // Sign in, then come back: the app session is the CLI login's, so a live
+    // one goes straight back to the place, and a signed-out page signs in
+    // anew first. The place is a path on this origin, or `/`.
+    if (!remote.token) await signIn();
+    response.writeHead(303, { location: returnToPath(url.searchParams.get("return_to")) });
+    return response.end();
+  }
+  if (route.worker) {
+    return sendRuntimeError(response, runtimeError(
+      "unsupported_in_dev",
+      `terminus dev --remote holds the app session itself; the browser's /_terminus/${route.worker} is the app host's`,
+    ));
+  }
+  if (!remote.token) {
+    return sendRuntimeError(response, runtimeError("unauthorized", "signed out: open the app again to sign in"));
+  }
+  return forwardPlatformRequest(
+    upstreamUrl(remote.apiBase, route.upstream, url.search),
+    remote.token,
+    method,
+    request,
+    response,
+    route.headers["x-terminus-artifact-context"] ?? null,
+    { pathname: url.pathname },
+  );
+}
+/** One origin: the local ui/ bundle plus the proxied production runtime.
+ * `remote` is `{ login, token, appId, webHost }`: the login's client (which
+ * mints a new app session when a signed-out page is opened again) and the
+ * app session in hand. */
+export async function startRemoteDevServer(dir, options = {}) {
+  const pkg = options.pkg ?? await readDevPackage(dir);
+  requireBuiltDevBundle(pkg);
+  const remote = options.remote ? { ...options.remote } : null;
+  if (!remote?.login || !remote?.token) throw new CliError("dev --remote needs an app session");
+  remote.apiBase = remote.login.base;
+  const mint = options.mint ?? (() => mintRemoteAppSession({ api: remote.login, appId: remote.appId }));
+  /** A new app session, as the app host's sign-in ends in one. */
+  const signIn = async () => {
+    const minted = await mint();
+    remote.token = minted.token;
+    remote.webHost = minted.webHost ?? remote.webHost;
+  };
+  const port = resolveDevPortRange(options.port, 1);
+  await assertDevPortRangeAvailable({
+    basePort: port,
+    commandArgs: options.commandArgs,
+    count: 1,
+    directory: dir,
+    viteProxy: true,
+  });
+  const uiDir = path.join(dir, pkg.uiDirectory);
+  const server = createServer(async (request, response) => {
+    // Every /_terminus call here acts on real data under the app session.
+    if (!isLoopbackHost(request)) return refuseForeignHost(request, response);
+    const url = new URL(request.url ?? "/", `http://localhost:${request.socket.localPort}`);
+    // Nor may a page on another site fire those calls blind (see
+    // isLoopbackOrigin); the bundle's pages stay open to any link.
+    const runtime = url.pathname === "/_terminus" || url.pathname.startsWith("/_terminus/")
+      || url.pathname.startsWith("/__terminus_dev/");
+    if (runtime && !isLoopbackOrigin(request)) return refuseCrossSite(response);
+    try {
+      if (url.pathname === DEV_ABOUT_PATH) {
+        answerDevAbout(request, response, {
+          kind: "app",
+          app: pkg.id ?? pkg.manifest.slug,
+          directory: path.resolve(dir),
+          remote: true,
+        });
+        return;
+      }
+      if (url.pathname === "/_terminus" || url.pathname.startsWith("/_terminus/")) {
+        await proxyRemoteRuntime(remote, url, request, response, { signIn });
+        return;
+      }
+      // Opening the app signs a signed-out session back in.
+      if (!remote.token && String(request.headers.accept ?? "").includes("text/html")) await signIn();
+      await serveUiAsset(pkg, uiDir, url, request, response);
+    } catch (error) {
+      if (response.headersSent) return response.end();
+      sendRuntimeError(response, error);
+    }
+  });
+  try {
+    await listenDevServer(server, port);
+  } catch (error) {
+    if (error?.code === "EADDRINUSE" && port !== 0) {
+      throw await devPortUnavailableError({
+        basePort: port,
+        commandArgs: options.commandArgs,
+        count: 1,
+        directory: dir,
+        failures: [{ port, error }],
+        viteProxy: true,
+      });
+    }
+    throw error;
+  }
+  return {
+    manifest: pkg.manifest,
+    hasUi: pkg.hasUi,
+    uiDirectory: pkg.uiDirectory,
+    port: server.address().port,
+    webHost: remote.webHost ?? null,
+    async close() {
+      await closeDevServer(server);
+    },
+  };
+}