@m-kopa/launchpad-cli 0.23.0

package/skills/marquee-share/src/config.ts

@@ -0,0 +1,101 @@
+// Runtime configuration for the Marquee share skill.
+//
+// Adapted from @m-kopa/launchpad-cli src/config.ts — see
+// auth/PROVENANCE.md. Two values determine where the skill talks to:
+//
+//   * `resourceUrl` — base URL of the Marquee app (the
+//     Cloudflare-Access-protected Pages deployment). Discovery walks
+//     the well-known docs under this host; the upload task POSTs to
+//     `${resourceUrl}/api/uploads`.
+//   * `sessionPath` — where the OAuth session is persisted.
+//
+// Defaults come from the bundled prod constants. Overrides come from
+// environment variables — useful for local dev against a preview
+// deployment, or for the test harness.
+//
+// Environment overrides:
+//   * `MARQUEE_RESOURCE_URL` — overrides `resourceUrl`. Trailing
+//     slashes are trimmed so callers can do `${resourceUrl}/api/...`
+//     without worrying about double slashes. Validated at load time:
+//     must be a well-formed absolute URL that is either `https:` (any
+//     host) or `http:` restricted to loopback hosts (local dev only).
+//   * `MARQUEE_SESSION_PATH` — overrides `sessionPath`. Used by tests
+//     to point at a temp directory.
+//
+// A blank or whitespace-only value for either variable is treated as
+// unset — the bundled default applies — rather than as a real
+// override that would yield empty config.
+
+import * as os from "node:os";
+import * as path from "node:path";
+
+/** Production Marquee app URL (Cloudflare-Access-protected). */
+export const DEFAULT_RESOURCE_URL = "https://marquee.launchpad.m-kopa.us";
+
+export interface SkillConfig {
+  readonly resourceUrl: string;
+  readonly sessionPath: string;
+}
+
+/**
+ * Reads an environment override, treating a blank or whitespace-only
+ * value as unset. Returns the trimmed value, or `undefined` when the
+ * variable is absent or empty — so the caller's default applies.
+ */
+function readOverride(value: string | undefined): string | undefined {
+  if (value === undefined) return undefined;
+  const trimmed = value.trim();
+  return trimmed.length === 0 ? undefined : trimmed;
+}
+
+/**
+ * True when `host` is a loopback host: `localhost`, an explicit
+ * loopback IP (`127.0.0.1`, `::1`), or a `*.localhost` subdomain.
+ * `http:` is only permitted for these, to keep the OAuth bearer token
+ * off plaintext links to arbitrary hosts.
+ */
+function isLoopbackHost(host: string): boolean {
+  const h = host.toLowerCase();
+  return (
+    h === "localhost" ||
+    h.endsWith(".localhost") ||
+    h === "127.0.0.1" ||
+    h === "::1" ||
+    h === "[::1]"
+  );
+}
+
+export function loadConfig(env: NodeJS.ProcessEnv = process.env): SkillConfig {
+  const resourceUrl =
+    readOverride(env.MARQUEE_RESOURCE_URL)?.replace(/\/+$/, "") ??
+    DEFAULT_RESOURCE_URL;
+  let parsedResourceUrl: URL;
+  try {
+    parsedResourceUrl = new URL(resourceUrl);
+  } catch {
+    throw new Error(
+      `MARQUEE_RESOURCE_URL must be a valid absolute URL (got: ${resourceUrl})`,
+    );
+  }
+  // `https:` is allowed for any host. `http:` is allowed only for
+  // loopback hosts (local dev) — a non-loopback plaintext URL risks
+  // leaking the OAuth bearer token on the wire, so it is rejected.
+  if (parsedResourceUrl.protocol === "http:") {
+    if (!isLoopbackHost(parsedResourceUrl.hostname)) {
+      throw new Error(
+        `MARQUEE_RESOURCE_URL must use https: for non-loopback hosts; ` +
+          `http: is permitted only for localhost / 127.0.0.1 / ::1 ` +
+          `(got: ${resourceUrl})`,
+      );
+    }
+  } else if (parsedResourceUrl.protocol !== "https:") {
+    throw new Error(
+      `MARQUEE_RESOURCE_URL must use https: (or http: for loopback hosts); ` +
+        `got: ${parsedResourceUrl.protocol}`,
+    );
+  }
+  const sessionPath =
+    readOverride(env.MARQUEE_SESSION_PATH) ??
+    path.join(os.homedir(), ".marquee", "session.json");
+  return { resourceUrl, sessionPath };
+}

package/skills/marquee-share/src/render/template.ts

@@ -0,0 +1,171 @@
+// The single M-KOPA-branded HTML template for the Marquee share skill.
+//
+// DESIGN INTENT
+//   This is ONE template, not a template system. The skill is a thin
+//   uploader: an AI chat produces the inner content as HTML (per the
+//   SKILL.md guidance written in Task 5), and this module wraps that
+//   content in a clean, branded, self-contained document shell. If a
+//   different look is ever needed, the right move is to edit the
+//   `STYLE` / `SHELL_*` constants below — not to grow a theming layer.
+//
+// SELF-CONTAINED
+//   The produced document references no external CSS, JS, or fonts.
+//   All styling is in one inline <style> block. Marquee renders
+//   uploaded HTML inside a sandboxed iframe on a separate origin with
+//   no credentials; a document that needs the network would render
+//   broken there. System fonts only.
+//
+// ESCAPING
+//   Two slots are filled:
+//     * `title`       — a PLAIN STRING. It is HTML-escaped before
+//                       injection. A hostile title therefore cannot
+//                       break out of the <title>/<h1> text context to
+//                       inject markup or script into the shell.
+//     * `contentHtml` — already-rendered HTML, inserted verbatim into
+//                       <body>. Treating it as HTML is the contract
+//                       (the AI produces real HTML). It cannot subvert
+//                       the SHELL: the shell prefix is a fixed string
+//                       built before the slot, so no payload can reach
+//                       back and alter the shell's own structure. The
+//                       trust boundary for the content itself is
+//                       Marquee's sandboxed-iframe render isolation
+//                       (see the marquee repo ARCHITECTURE.md), not
+//                       this skill.
+
+/**
+ * M-KOPA brand accent. M-KOPA's brand colour is a vivid green; this is
+ * a reasonable stand-in. HUMAN: confirm the exact brand hex and tweak
+ * this one constant — everything else derives from it.
+ */
+const BRAND_GREEN = "#00b140";
+/** Near-black used for body text and the footer rule. */
+const INK = "#1a1a1a";
+/** Default title when the caller supplies an empty string. */
+const DEFAULT_TITLE = "Shared via Marquee";
+
+/**
+ * Escape the five HTML-significant characters so a string is safe to
+ * place in element text OR a double-quoted attribute. `&` first so we
+ * never double-encode an entity we just produced.
+ */
+function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+
+/** Inputs for the branded document. */
+export interface BrandedDocumentInput {
+  /** Human-readable title — plain text, HTML-escaped on injection. */
+  readonly title: string;
+  /** Already-rendered inner HTML — inserted verbatim into <body>. */
+  readonly contentHtml: string;
+}
+
+/**
+ * Inline brand stylesheet. White background, green + black accents,
+ * deliberately simple. System font stack so the document is fully
+ * self-contained.
+ */
+const STYLE = `
+  :root { --brand-green: ${BRAND_GREEN}; --ink: ${INK}; }
+  * { box-sizing: border-box; }
+  html, body { margin: 0; padding: 0; }
+  body {
+    background: #ffffff;
+    color: var(--ink);
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto,
+      Helvetica, Arial, sans-serif;
+    line-height: 1.6;
+    -webkit-text-size-adjust: 100%;
+  }
+  .marquee-shell {
+    max-width: 760px;
+    margin: 0 auto;
+    padding: 40px 24px 64px;
+  }
+  .marquee-header {
+    border-bottom: 3px solid var(--brand-green);
+    padding-bottom: 16px;
+    margin-bottom: 32px;
+  }
+  .marquee-eyebrow {
+    font-size: 12px;
+    font-weight: 700;
+    letter-spacing: 0.08em;
+    text-transform: uppercase;
+    color: var(--brand-green);
+    margin: 0 0 6px;
+  }
+  .marquee-title {
+    font-size: 28px;
+    font-weight: 700;
+    color: var(--ink);
+    margin: 0;
+  }
+  .marquee-content {
+    font-size: 16px;
+  }
+  .marquee-content a { color: var(--brand-green); }
+  .marquee-content pre,
+  .marquee-content code {
+    font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  }
+  .marquee-content pre {
+    background: #f5f5f5;
+    border-left: 3px solid var(--brand-green);
+    padding: 12px 16px;
+    overflow-x: auto;
+  }
+  .marquee-footer {
+    margin-top: 48px;
+    padding-top: 16px;
+    border-top: 1px solid #e6e6e6;
+    font-size: 12px;
+    color: #6b6b6b;
+  }
+`.trim();
+
+/**
+ * Wrap already-rendered content HTML into the branded, self-contained
+ * M-KOPA document. The title is escaped; the content is inserted
+ * verbatim. Returns one complete HTML document as a string.
+ */
+export function renderBrandedDocument(input: BrandedDocumentInput): string {
+  const safeTitle = escapeHtml(
+    input.title.trim().length > 0 ? input.title : DEFAULT_TITLE,
+  );
+
+  // SHELL_PREFIX is a fixed string assembled entirely from the escaped
+  // title + static markup BEFORE the content slot. Because it is built
+  // first and the content is appended after, no content payload can
+  // alter the shell's structure — it is only ever bytes inside <body>.
+  const shellPrefix =
+    `<!DOCTYPE html>\n` +
+    `<html lang="en">\n` +
+    `<head>\n` +
+    `<meta charset="utf-8">\n` +
+    `<meta name="viewport" content="width=device-width, initial-scale=1">\n` +
+    `<title>${safeTitle}</title>\n` +
+    `<style>${STYLE}</style>\n` +
+    `</head>\n` +
+    `<body>\n` +
+    `<main class="marquee-shell">\n` +
+    `<header class="marquee-header">\n` +
+    `<p class="marquee-eyebrow">M-KOPA</p>\n` +
+    `<h1 class="marquee-title">${safeTitle}</h1>\n` +
+    `</header>\n` +
+    `<article class="marquee-content">\n`;
+
+  const shellSuffix =
+    `\n</article>\n` +
+    `<footer class="marquee-footer">Shared via Marquee</footer>\n` +
+    `</main>\n` +
+    `</body>\n` +
+    `</html>\n`;
+
+  return shellPrefix + input.contentHtml + shellSuffix;
+}

package/skills/marquee-share/src/upload/index.ts

@@ -0,0 +1,11 @@
+// Public upload surface for the Marquee share skill.
+//
+// This is the ONLY module later tasks (the SKILL.md entrypoint in
+// Task 5, distribution in Task 6) should import from for the
+// wrap + upload capability. It re-exports `shareToMarquee` — wrap
+// content into the branded M-KOPA template, POST it to Marquee's
+// `/api/uploads`, return the `view_url` — plus its types and the
+// typed `MarqueeUploadError`.
+
+export { shareToMarquee, MarqueeUploadError } from "./upload.js";
+export type { ShareInput, ShareResult, ShareOptions } from "./upload.js";

package/skills/marquee-share/src/upload/upload.ts

@@ -0,0 +1,191 @@
+// Wrap + upload — the core of Task 4 of the Marquee share skill.
+//
+// `shareToMarquee` is the one operation a caller needs:
+//   1. Wrap already-rendered content HTML into the branded,
+//      self-contained M-KOPA document (see `../render/template.ts`).
+//   2. Acquire a valid Cloudflare Access bearer token via the auth
+//      layer's `getValidToken` (Task 3) — silent reuse / refresh /
+//      re-login is handled there.
+//   3. POST the document to `${resourceUrl}/api/uploads` with
+//      `Content-Type: text/html` and `Authorization: Bearer <token>`.
+//   4. Parse and return the `view_url` from the JSON response.
+//
+// SECURITY POSTURE
+//   * The bearer token is placed ONLY in the `Authorization` header
+//     of the HTTPS request to Marquee. It is never logged, never put
+//     in an error message, never returned to the caller.
+//   * `MarqueeUploadError` carries the HTTP status and a generic
+//     message — never the token, never the request body.
+//
+// All side-effecting dependencies (`fetch`, the token provider) are
+// injectable so the unit tests can run against a fake server without
+// the real auth layer / browser — matching the auth `flow.test.ts`
+// injection style.
+
+import { loadConfig, type SkillConfig } from "../config.js";
+import { getValidToken } from "../auth/index.js";
+import { renderBrandedDocument } from "../render/template.js";
+
+/** What to share: a title plus already-rendered inner HTML. */
+export interface ShareInput {
+  /** Human-readable title — plain text, escaped into the template. */
+  readonly title: string;
+  /** Already-rendered inner HTML produced by the AI chat. */
+  readonly contentHtml: string;
+}
+
+/** The result of a successful share. */
+export interface ShareResult {
+  /** The shareable URL Marquee returned. */
+  readonly viewUrl: string;
+  /** Marquee's generated upload id, when present in the response. */
+  readonly id?: string;
+}
+
+/** Default upload-request timeout — a stalled network must not hang
+ *  `share` forever. */
+export const DEFAULT_UPLOAD_TIMEOUT_MS = 30_000;
+
+/** Options for {@link shareToMarquee}. All injectables default. */
+export interface ShareOptions {
+  /** Override resolved config. Defaults to `loadConfig()`. */
+  readonly config?: SkillConfig;
+  /** Injected for tests. Defaults to the global `fetch`. */
+  readonly fetcher?: typeof fetch;
+  /**
+   * Upload-request timeout in milliseconds. After this elapses the
+   * request is aborted and a `MarqueeUploadError` is thrown. Defaults
+   * to {@link DEFAULT_UPLOAD_TIMEOUT_MS}.
+   */
+  readonly timeoutMs?: number;
+  /**
+   * Supplies the bearer token. Defaults to the auth layer's
+   * `getValidToken` (silent reuse / refresh / re-login). Injected in
+   * tests so they never touch the real auth layer.
+   */
+  readonly tokenProvider?: () => Promise<string>;
+}
+
+/**
+ * A failed Marquee upload. Carries the HTTP status when the failure
+ * was an HTTP error response; `status` is 0 for transport / parsing
+ * failures. The message is deliberately generic — it never embeds the
+ * bearer token or the upload body.
+ */
+export class MarqueeUploadError extends Error {
+  /** HTTP status of the failing response, or 0 if there was none. */
+  public readonly status: number;
+
+  public constructor(message: string, status: number) {
+    super(message);
+    this.name = "MarqueeUploadError";
+    this.status = status;
+  }
+}
+
+/** The subset of the upload response this skill consumes. */
+interface UploadResponseShape {
+  readonly view_url?: unknown;
+  readonly id?: unknown;
+}
+
+/**
+ * Wrap content into the branded template, upload it to Marquee, and
+ * return the shareable `view_url`.
+ *
+ * @throws {MarqueeUploadError} on a non-2xx response, a non-JSON
+ *   response, or a 2xx response missing a usable `view_url`.
+ */
+export async function shareToMarquee(
+  input: ShareInput,
+  options: ShareOptions = {},
+): Promise<ShareResult> {
+  const config = options.config ?? loadConfig();
+  const fetcher = options.fetcher ?? fetch;
+  const tokenProvider = options.tokenProvider ?? (() => getValidToken());
+  const timeoutMs = options.timeoutMs ?? DEFAULT_UPLOAD_TIMEOUT_MS;
+
+  // 1. Wrap into the branded, self-contained document.
+  const document = renderBrandedDocument({
+    title: input.title,
+    contentHtml: input.contentHtml,
+  });
+
+  // 2. Acquire the bearer token. Held in a local only; never logged.
+  const token = await tokenProvider();
+
+  // 3. POST to `${resourceUrl}/api/uploads`.
+  const endpoint = `${config.resourceUrl}/api/uploads`;
+  let response: Response;
+  // Abort the request once `timeoutMs` elapses so a stalled network
+  // can't hang `share` indefinitely. The timer is always cleared in
+  // the `finally` so it never keeps the event loop alive.
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    response = await fetcher(endpoint, {
+      method: "POST",
+      headers: {
+        // Marquee stores/serves text/html; the body is the wrapped
+        // branded document. `charset=utf-8` matches what Marquee pins.
+        "content-type": "text/html; charset=utf-8",
+        // The ONLY place the token travels. HTTPS to Marquee.
+        authorization: `Bearer ${token}`,
+      },
+      body: document,
+      signal: controller.signal,
+    });
+  } catch (_e) {
+    // Transport failure (DNS, TLS, offline) or an abort fired by the
+    // timeout above. `_e` may itself reference the request — do NOT
+    // fold it into the message; surface a generic, token-free error.
+    throw new MarqueeUploadError("upload request failed (network error)", 0);
+  } finally {
+    clearTimeout(timer);
+  }
+
+  // 4a. Non-2xx → typed error carrying the status (no body, no token).
+  if (!response.ok) {
+    throw new MarqueeUploadError(
+      `Marquee upload failed with HTTP ${response.status}`,
+      response.status,
+    );
+  }
+
+  // 4b. Parse the JSON response and extract `view_url`.
+  let parsed: unknown;
+  try {
+    parsed = await response.json();
+  } catch (_e) {
+    throw new MarqueeUploadError(
+      "Marquee upload returned a non-JSON response",
+      response.status,
+    );
+  }
+
+  // A successful `JSON.parse` still admits `null`, an array, or a bare
+  // primitive (`42`, `"ok"`). Reading `.view_url` off any of those would
+  // throw a raw `TypeError` (for `null`) or silently yield `undefined`.
+  // Narrow to a non-null, non-array object FIRST so every malformed
+  // response surfaces as a typed `MarqueeUploadError`, never a stray
+  // `TypeError`.
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new MarqueeUploadError(
+      "Marquee upload response was not a JSON object",
+      response.status,
+    );
+  }
+
+  const shape = parsed as UploadResponseShape;
+  if (typeof shape.view_url !== "string" || shape.view_url.length === 0) {
+    throw new MarqueeUploadError(
+      "Marquee upload response did not include a view_url",
+      response.status,
+    );
+  }
+
+  return {
+    viewUrl: shape.view_url,
+    ...(typeof shape.id === "string" ? { id: shape.id } : {}),
+  };
+}