@m-kopa/launchpad-cli 0.23.0

package/skills/marquee-share/src/auth/session.ts

@@ -0,0 +1,205 @@
+// Persisted skill session — file-backed.
+//
+// Vendored from @m-kopa/launchpad-cli src/auth/session.ts — see
+// PROVENANCE.md. Marquee adaptations: comments refer to
+// `~/.marquee/session.json` and `MARQUEE_SESSION_PATH`; and
+// `readSession` rejects non-finite / non-positive
+// `accessTokenExpiresAt` values rather than type-checking alone.
+// The storage logic itself is otherwise identical.
+//
+// Storage is a single JSON file at `~/.marquee/session.json`
+// (overridable via `MARQUEE_SESSION_PATH`). The file is created with
+// mode `0o600` and the parent directory with `0o700` so other users
+// on a shared box can't read the access token.
+//
+// Why a file rather than the OS keychain (e.g. `keytar`):
+//   * `keytar` is a native module — adds a build-time dependency
+//     and cross-platform packaging headaches the skill doesn't need.
+//   * The threat model already trusts files in `$HOME` (same posture
+//     as `~/.aws/credentials`, `~/.config/gh/hosts.yml`). Mode
+//     `0o600` is the standard mitigation.
+// If the keychain story matters later we can swap the implementation
+// behind `readSession` / `writeSession` without touching callers.
+//
+// Schema versioning: `version: 1` is stamped into every file. A
+// future migration bumps the integer; readers reject unknown
+// versions rather than guessing.
+//
+// SECURITY: the access + refresh tokens live in this struct. They
+// must never be logged or echoed. This module only ever writes them
+// to the 0600 session file; nothing here goes to stdout/stderr.
+
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { randomBytes } from "node:crypto";
+
+export const SESSION_VERSION = 1;
+
+export interface MarqueeSession {
+  readonly version: typeof SESSION_VERSION;
+  /** OAuth `access_token`. Sent to Marquee as
+   *  `Authorization: Bearer <accessToken>`. */
+  readonly accessToken: string;
+  /** OAuth `refresh_token` — used to silently mint a fresh
+   *  access token when the current one expires. */
+  readonly refreshToken: string;
+  /** Epoch milliseconds at which `accessToken` ceases to be valid.
+   *  Computed at write-time as `Date.now() + (expires_in * 1000)`. */
+  readonly accessTokenExpiresAt: number;
+  /** OAuth client id from dynamic-client-registration. Cached so
+   *  refreshes don't re-register. There is NO client secret — this
+   *  is a public client. */
+  readonly clientId: string;
+  /** Token endpoint discovered at login. Cached for refreshes so
+   *  refresh doesn't re-walk discovery. */
+  readonly tokenEndpoint: string;
+  /** RFC 8707 resource indicator (Marquee's canonical URL). Cached
+   *  so silent refresh can re-include it without re-discovering —
+   *  Cf Access binds the access_token's audience to this and the
+   *  refresh grant must match. Optional in the on-disk schema so a
+   *  session written without it still parses (those callers fall
+   *  through to a forced re-login on the next refresh attempt). */
+  readonly resource?: string;
+  /** ISO-8601 UTC timestamp of when this session was written. Used
+   *  for diagnostic display only. */
+  readonly issuedAt: string;
+}
+
+export class SessionParseError extends Error {
+  readonly code = "session_parse_error" as const;
+}
+
+/**
+ * Read the session file. Returns `null` if the file doesn't exist
+ * (the user hasn't logged in yet — a normal state). Throws
+ * `SessionParseError` for a corrupt file: better to fail loudly
+ * than to silently re-prompt for login when the storage is
+ * actually broken.
+ */
+export async function readSession(
+  sessionPath: string,
+): Promise<MarqueeSession | null> {
+  let raw: string;
+  try {
+    raw = await fs.readFile(sessionPath, "utf8");
+  } catch (e) {
+    if (isErrno(e) && e.code === "ENOENT") return null;
+    throw e;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (e) {
+    throw new SessionParseError(
+      `session file at ${sessionPath} is not valid JSON: ${describe(e)}`,
+    );
+  }
+  if (typeof parsed !== "object" || parsed === null) {
+    throw new SessionParseError(
+      `session file at ${sessionPath} is not an object`,
+    );
+  }
+  const obj = parsed as Record<string, unknown>;
+  if (obj.version !== SESSION_VERSION) {
+    throw new SessionParseError(
+      `unsupported session version ${String(obj.version)} at ${sessionPath}; expected ${SESSION_VERSION}`,
+    );
+  }
+  for (const k of [
+    "accessToken",
+    "refreshToken",
+    "clientId",
+    "tokenEndpoint",
+    "issuedAt",
+  ] as const) {
+    if (typeof obj[k] !== "string") {
+      throw new SessionParseError(
+        `session file at ${sessionPath}: missing or non-string ${k}`,
+      );
+    }
+  }
+  // `accessTokenExpiresAt` gates silent-refresh behaviour, so a
+  // type-only check is too weak: `NaN`, `±Infinity`, and non-positive
+  // values would all slip through and break the expiry comparison in
+  // `getValidAccessToken`. Reject anything that is not a positive
+  // finite number.
+  if (
+    typeof obj.accessTokenExpiresAt !== "number" ||
+    !Number.isFinite(obj.accessTokenExpiresAt) ||
+    obj.accessTokenExpiresAt <= 0
+  ) {
+    throw new SessionParseError(
+      `session file at ${sessionPath}: missing or invalid accessTokenExpiresAt`,
+    );
+  }
+  // `resource` is optional in the on-disk schema. Reject only
+  // obviously-wrong shapes (non-string) — absent is fine.
+  if (obj.resource !== undefined && typeof obj.resource !== "string") {
+    throw new SessionParseError(
+      `session file at ${sessionPath}: resource present but not a string`,
+    );
+  }
+  return obj as unknown as MarqueeSession;
+}
+
+/**
+ * Atomic-ish write: writes to `<path>.<unique>.tmp` then renames
+ * into place. The whole-directory chmod is best-effort (Windows
+ * ignores mode bits) — the per-file mode is the load-bearing one.
+ */
+export async function writeSession(
+  sessionPath: string,
+  session: MarqueeSession,
+): Promise<void> {
+  const dir = path.dirname(sessionPath);
+  await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+  // chmod the directory in case it pre-existed at a wider mode.
+  // Best-effort — surface no error on Windows.
+  try {
+    await fs.chmod(dir, 0o700);
+  } catch {
+    /* ignore — Windows etc. */
+  }
+  // Per-write unique tmp filename. Two concurrent processes both
+  // refreshing tokens at the same time could otherwise stomp each
+  // other's `.tmp` file mid-write. pid+ts+random makes collisions
+  // inconceivable.
+  const tmp = `${sessionPath}.${process.pid}.${Date.now()}.${randomBytes(4).toString("hex")}.tmp`;
+  try {
+    await fs.writeFile(tmp, JSON.stringify(session, null, 2), {
+      encoding: "utf8",
+      mode: 0o600,
+    });
+    await fs.rename(tmp, sessionPath);
+  } catch (e) {
+    // Best-effort tmp cleanup so a failed write doesn't leak
+    // increasingly-stale `.tmp` files into ~/.marquee/.
+    await fs.unlink(tmp).catch(() => undefined);
+    throw e;
+  }
+}
+
+/**
+ * `logout`: zero out the session file. Idempotent — already-absent
+ * file is a no-op success. Returns whether a session actually
+ * existed (so the caller can render the right message).
+ */
+export async function clearSession(sessionPath: string): Promise<boolean> {
+  try {
+    await fs.unlink(sessionPath);
+    return true;
+  } catch (e) {
+    if (isErrno(e) && e.code === "ENOENT") return false;
+    throw e;
+  }
+}
+
+function isErrno(e: unknown): e is NodeJS.ErrnoException {
+  return (
+    e instanceof Error && typeof (e as NodeJS.ErrnoException).code === "string"
+  );
+}
+
+function describe(e: unknown): string {
+  return e instanceof Error ? e.message : String(e);
+}

package/skills/marquee-share/src/auth/token.ts

@@ -0,0 +1,162 @@
+// Token-endpoint exchanges: code-for-token (login) and
+// refresh-token-for-token (silent refresh).
+//
+// Vendored from @m-kopa/launchpad-cli src/auth/token.ts — see
+// PROVENANCE.md. The grant exchange is generic OAuth and not
+// Marquee-specific. Marquee divergence: a non-2xx response surfaces
+// only the HTTP status plus the standard OAuth `error` code — the
+// raw response body is never embedded in the error (leak hardening).
+//
+// Cloudflare Access's token endpoint speaks application/x-www-form-
+// urlencoded for both grants, returns JSON. The two callers care
+// about the same set of response fields (access_token,
+// refresh_token, expires_in), so we centralise parsing here.
+//
+// Note: there is NO `client_secret` form field anywhere below. This
+// is a PKCE public client — `code_verifier` is the proof.
+
+export interface TokenResponse {
+  readonly accessToken: string;
+  readonly refreshToken: string;
+  /** Seconds until `accessToken` expiry, as returned by the
+   *  server. Caller converts to absolute epoch when persisting. */
+  readonly expiresInSec: number;
+}
+
+export class TokenError extends Error {
+  readonly code = "token_error" as const;
+  /** Optional HTTP status — present only for non-2xx responses, not
+   *  for network errors. Lets the login flow distinguish "user
+   *  denied at the IdP" from "network is down". */
+  readonly httpStatus?: number;
+  constructor(message: string, httpStatus?: number) {
+    super(message);
+    this.name = "TokenError";
+    if (httpStatus !== undefined) this.httpStatus = httpStatus;
+  }
+}
+
+export async function exchangeCodeForTokens(
+  params: {
+    readonly tokenEndpoint: string;
+    readonly clientId: string;
+    readonly code: string;
+    readonly codeVerifier: string;
+    readonly redirectUri: string;
+    /** RFC 8707 resource indicator. Cf Access binds the resulting
+     *  access_token's audience to this value; Marquee's JWT
+     *  validation MUST see a matching `aud` claim. */
+    readonly resource: string;
+  },
+  fetcher: typeof fetch = fetch,
+): Promise<TokenResponse> {
+  const form = new URLSearchParams({
+    grant_type: "authorization_code",
+    client_id: params.clientId,
+    code: params.code,
+    code_verifier: params.codeVerifier,
+    redirect_uri: params.redirectUri,
+    resource: params.resource,
+  });
+  return postTokenForm(params.tokenEndpoint, form, fetcher);
+}
+
+export async function refreshTokens(
+  params: {
+    readonly tokenEndpoint: string;
+    readonly clientId: string;
+    readonly refreshToken: string;
+    /** RFC 8707 resource indicator — same posture as
+     *  exchangeCodeForTokens. The refreshed access_token's audience
+     *  must match what the upload call targets. */
+    readonly resource: string;
+  },
+  fetcher: typeof fetch = fetch,
+): Promise<TokenResponse> {
+  const form = new URLSearchParams({
+    grant_type: "refresh_token",
+    client_id: params.clientId,
+    refresh_token: params.refreshToken,
+    resource: params.resource,
+  });
+  return postTokenForm(params.tokenEndpoint, form, fetcher);
+}
+
+async function postTokenForm(
+  tokenEndpoint: string,
+  form: URLSearchParams,
+  fetcher: typeof fetch,
+): Promise<TokenResponse> {
+  let res: Response;
+  try {
+    res = await fetcher(tokenEndpoint, {
+      method: "POST",
+      headers: {
+        "content-type": "application/x-www-form-urlencoded",
+        accept: "application/json",
+      },
+      body: form.toString(),
+    });
+  } catch (e) {
+    throw new TokenError(`token endpoint: network error: ${describe(e)}`);
+  }
+  if (!res.ok) {
+    // Do NOT fold the raw response body into the error message. An
+    // upstream / proxy that reflects request data could otherwise
+    // leak secrets into user-visible errors. Surface the HTTP status
+    // plus, when the body is well-formed OAuth JSON, only the short
+    // standard `error` code (RFC 6749 §5.2) — never free-form text.
+    const detail = await res.text().catch(() => "");
+    let oauthError = "";
+    try {
+      const parsed = JSON.parse(detail) as { error?: unknown };
+      if (typeof parsed.error === "string") {
+        oauthError = ` (${parsed.error})`;
+      }
+    } catch {
+      // Non-JSON body — ignore it entirely.
+    }
+    throw new TokenError(
+      `token endpoint ${tokenEndpoint} returned HTTP ${res.status}${oauthError}`,
+      res.status,
+    );
+  }
+  let parsed: unknown;
+  try {
+    parsed = await res.json();
+  } catch (e) {
+    throw new TokenError(`token endpoint: non-JSON response: ${describe(e)}`);
+  }
+  if (parsed === null || typeof parsed !== "object") {
+    throw new TokenError(`token endpoint: response is not an object`);
+  }
+  const obj = parsed as Record<string, unknown>;
+  if (typeof obj.access_token !== "string") {
+    throw new TokenError(`token endpoint: response missing access_token`);
+  }
+  if (typeof obj.refresh_token !== "string") {
+    throw new TokenError(`token endpoint: response missing refresh_token`);
+  }
+  // `Number.isFinite(NaN)` and `Number.isFinite(±Infinity)` both
+  // return false, so this single guard covers all the pathological
+  // numeric shapes. ≤ 0 would mean "already expired".
+  const expiresIn = obj.expires_in;
+  if (
+    typeof expiresIn !== "number" ||
+    !Number.isFinite(expiresIn) ||
+    expiresIn <= 0
+  ) {
+    throw new TokenError(
+      `token endpoint: response missing positive finite numeric expires_in (got ${String(expiresIn)})`,
+    );
+  }
+  return {
+    accessToken: obj.access_token,
+    refreshToken: obj.refresh_token,
+    expiresInSec: expiresIn,
+  };
+}
+
+function describe(e: unknown): string {
+  return e instanceof Error ? e.message : String(e);
+}

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

@@ -0,0 +1,246 @@
+#!/usr/bin/env node
+// CLI entrypoint for the Marquee share skill — Task 5 of M-960.
+//
+// SHEBANG / RUNTIME — this is a TypeScript source file. It is never
+// executed directly: the dev loop runs it through `tsx` via the npm
+// scripts (`tsx` is invoked explicitly and ignores this shebang), and
+// the distributed/installed skill runs the bundled `dist/cli.js`
+// (produced by `npm run build`) under plain Node. The `#!/usr/bin/env
+// node` line is carried verbatim by `bun build` into `dist/cli.js`,
+// where it is the operative shebang — so `dist/cli.js` is directly
+// executable with only Node 22+ on PATH, no `tsx`, no `node_modules`.
+//
+// This module WIRES the auth layer (`src/auth`) and the wrap+upload
+// layer (`src/upload`) into a single command with three subcommands:
+//
+//   * `login`  — run the auth layer's interactive browser PKCE login.
+//   * `logout` — clear the cached session.
+//   * `share`  — read a complete inner-content HTML document (from a
+//                file argument or stdin), wrap+upload it to Marquee,
+//                and print ONLY the resulting `view_url` to stdout so
+//                the calling Claude Code skill can capture it.
+//
+// DESIGN — TESTABLE CORE
+//   `run()` is a pure-ish dispatcher: every side-effecting dependency
+//   (argv, stdin, the filesystem, the auth/upload operations, and the
+//   two output streams) is injected via `RunDeps`. `main()` at the
+//   bottom supplies the real implementations and is the only part that
+//   touches the process. Tests drive `run()` with fakes — they never
+//   open a browser, touch the network, or read the real session file.
+//   This mirrors the injection style of `tests/flow.test.ts` and
+//   `tests/upload.test.ts`.
+//
+// SECURITY POSTURE
+//   * The bearer token never appears here. `share` calls
+//     `shareToMarquee`, which holds the token in-process and puts it
+//     ONLY in an Authorization header. This CLI prints exactly one
+//     thing on the success path: the `view_url`.
+//   * Diagnostics (auth URLs, status lines) go to STDERR. stdout is
+//     reserved for the `view_url` alone, so a caller doing
+//     `marquee-share share < doc.html` gets a clean, capturable URL.
+//   * Errors are surfaced as a short generic message on stderr plus a
+//     non-zero exit code — never the token, never a raw stack.
+
+import * as fs from "node:fs/promises";
+import { pathToFileURL } from "node:url";
+import { login, logout } from "./auth/index.js";
+import { shareToMarquee } from "./upload/index.js";
+
+/** A line sink — stdout or stderr. Injected so tests can capture. */
+export type LineSink = (line: string) => void;
+
+/** Reads the whole of stdin as a UTF-8 string. Injected for tests. */
+export type StdinReader = () => Promise<string>;
+
+/**
+ * The injectable surface of {@link run}. `main()` supplies the real
+ * implementations; tests supply fakes.
+ */
+export interface RunDeps {
+  /** Argument vector WITHOUT `node` / script path — i.e. the
+   *  equivalent of `process.argv.slice(2)`. */
+  readonly argv: readonly string[];
+  /** Writes a line to stdout. The `view_url` is the only thing the
+   *  success path ever sends here. */
+  readonly stdout: LineSink;
+  /** Writes a diagnostic line to stderr. */
+  readonly stderr: LineSink;
+  /** Reads all of stdin — used by `share` when no file arg is given. */
+  readonly readStdin: StdinReader;
+  /** Reads a UTF-8 file — used by `share` with a path argument.
+   *  Defaults to `node:fs` in `main()`. */
+  readonly readFile: (path: string) => Promise<string>;
+  /** The auth login operation. Defaults to the real `login`. */
+  readonly login: typeof login;
+  /** The auth logout operation. Defaults to the real `logout`. */
+  readonly logout: typeof logout;
+  /** Wrap+upload. Defaults to the real `shareToMarquee`. */
+  readonly shareToMarquee: typeof shareToMarquee;
+}
+
+const USAGE = `marquee-share — share an AI-chat result to Marquee.
+
+Usage:
+  marquee-share login              Authenticate with Marquee (one-time browser login).
+  marquee-share logout             Clear the cached Marquee session.
+  marquee-share share [file]       Wrap an HTML document, upload it, print the view URL.
+                                   Reads the document from [file], or from stdin if omitted.
+    --title <text>                 Title for the branded document (default: "Shared via Marquee").
+
+The 'share' command prints ONLY the resulting view URL to stdout.`;
+
+/**
+ * Parsed form of the `share` subcommand's arguments.
+ */
+interface ShareArgs {
+  /** Path to read the inner HTML from, or `undefined` for stdin. */
+  readonly file?: string;
+  /** Document title. */
+  readonly title: string;
+}
+
+/**
+ * Parse the args that follow `share`. Recognises `--title <text>`
+ * (anywhere) and at most one positional file path. Throws a plain
+ * `Error` with a usage-friendly message on misuse.
+ */
+function parseShareArgs(args: readonly string[]): ShareArgs {
+  let title = "Shared via Marquee";
+  let file: string | undefined;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i] as string;
+    if (arg === "--title") {
+      const value = args[i + 1];
+      if (value === undefined) {
+        throw new Error("--title requires a value");
+      }
+      title = value;
+      i++;
+      continue;
+    }
+    if (arg.startsWith("--title=")) {
+      title = arg.slice("--title=".length);
+      continue;
+    }
+    if (arg.startsWith("-")) {
+      throw new Error(`unknown option: ${arg}`);
+    }
+    if (file !== undefined) {
+      throw new Error("share accepts at most one file argument");
+    }
+    file = arg;
+  }
+  return file !== undefined ? { file, title } : { title };
+}
+
+/**
+ * Run the `share` subcommand: read the inner content HTML, wrap +
+ * upload it, and print the `view_url`.
+ *
+ * The auth layer's `getValidToken` (used inside `shareToMarquee`)
+ * handles a missing session by running an interactive browser login
+ * itself, so a first run with no session "just works" — no special
+ * orchestration needed here.
+ */
+async function runShare(
+  deps: RunDeps,
+  rest: readonly string[],
+): Promise<number> {
+  const { file, title } = parseShareArgs(rest);
+
+  const contentHtml =
+    file !== undefined ? await deps.readFile(file) : await deps.readStdin();
+
+  if (contentHtml.trim().length === 0) {
+    deps.stderr("error: no HTML content to share (input was empty)");
+    return 1;
+  }
+
+  const result = await deps.shareToMarquee({ title, contentHtml });
+  // The ONLY thing the success path writes to stdout — a clean,
+  // capturable URL. No token, no surrounding prose.
+  deps.stdout(result.viewUrl);
+  return 0;
+}
+
+/**
+ * Dispatch a parsed argv to a subcommand. Returns a process exit code
+ * (0 success, non-zero failure). Never throws for an expected failure
+ * — failures are reported on `stderr` and reflected in the code.
+ */
+export async function run(deps: RunDeps): Promise<number> {
+  const [subcommand, ...rest] = deps.argv;
+
+  if (subcommand === undefined || subcommand === "--help" || subcommand === "-h") {
+    deps.stderr(USAGE);
+    // No subcommand at all is a misuse; an explicit --help is not.
+    return subcommand === undefined ? 1 : 0;
+  }
+
+  try {
+    switch (subcommand) {
+      case "login": {
+        await deps.login({ onDiagnostic: deps.stderr });
+        return 0;
+      }
+      case "logout": {
+        await deps.logout({ onDiagnostic: deps.stderr });
+        return 0;
+      }
+      case "share": {
+        return await runShare(deps, rest);
+      }
+      default: {
+        deps.stderr(`error: unknown command "${subcommand}"`);
+        deps.stderr(USAGE);
+        return 1;
+      }
+    }
+  } catch (e) {
+    // Surface a short, generic message — never a raw stack, never a
+    // token. `shareToMarquee` already strips secrets from its errors;
+    // for anything else we print only `error.message`.
+    const message = e instanceof Error ? e.message : String(e);
+    deps.stderr(`error: ${message}`);
+    return 1;
+  }
+}
+
+/**
+ * Real entrypoint: wires the production dependencies and exits the
+ * process with the resolved code. Kept tiny and untested — all logic
+ * lives in `run()`.
+ */
+async function main(): Promise<void> {
+  const code = await run({
+    argv: process.argv.slice(2),
+    stdout: (line) => process.stdout.write(`${line}\n`),
+    stderr: (line) => process.stderr.write(`${line}\n`),
+    readStdin: async () => {
+      const chunks: Buffer[] = [];
+      for await (const chunk of process.stdin) {
+        chunks.push(Buffer.from(chunk));
+      }
+      return Buffer.concat(chunks).toString("utf8");
+    },
+    readFile: (path) => fs.readFile(path, "utf8"),
+    login,
+    logout,
+    shareToMarquee,
+  });
+  process.exitCode = code;
+}
+
+// Run only when invoked as a program (not when imported by a test).
+// `import.meta.url` ends with the script path; `process.argv[1]` is
+// the invoked script. Comparing them keeps the module import-safe.
+// `pathToFileURL` builds a correct file:// URL across platforms — it
+// percent-encodes special characters and handles Windows drive paths
+// and backslashes, which a hand-built `file://${path}` string does not.
+const invokedDirectly =
+  process.argv[1] !== undefined &&
+  import.meta.url === pathToFileURL(process.argv[1]).href;
+
+if (invokedDirectly) {
+  void main();
+}