@pithy-sh/ui-react-native 0.0.0-stage → 0.2.0

package/src/templates.ts

@@ -0,0 +1,92 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * The React Native templates `pithy ui add react-native` copies into an Expo app.
+ *
+ * A template library, not a runtime library: it ships text, and nothing imports it at runtime except the CLI's
+ * scaffolder. The screens need React Native's toolchain to be checked — its types, a program with no DOM lib, and
+ * `react-native-web` to render them under test — so they live here with it rather than in the CLI.
+ *
+ * The tree mirrors the scaffolded layout exactly, so a template's relative imports resolve here as they will in
+ * the app, and the whole library typechecks in place.
+ */
+
+/** Absolute path to the template tree. Resolved from this module, so it holds in a workspace and once published. */
+export const TEMPLATE_DIR: string = join(dirname(fileURLToPath(import.meta.url)), "..", "templates");
+
+/**
+ * The named file groups this library offers, each keyed by path within {@link TEMPLATE_DIR}, grouped as
+ * `@pithy-sh/ui-react`'s are so a screen set maps one to one.
+ *
+ * `base` is written on every scaffold: the Expo app's entry and config, the router, the transport, the locale and
+ * the theme. Every other group is a screen set that rides on a capability being composed, with the helpers only
+ * those screens use. The home screen is not in a group: {@link HOME_SCREEN} picks one of its two variants.
+ *
+ * Tests for these files live in this package's `src/`, not in the tree, so nothing here is a test.
+ */
+export const TEMPLATE_GROUPS = {
+  base: [
+    "app.config.ts",
+    "metro.config.js",
+    "metro-proxy.cjs",
+    "tsconfig.json",
+    "app/_layout.tsx",
+    "app/index.tsx",
+    "app/[...pithy].tsx",
+    "src/theme.ts",
+    "src/platform.ts",
+    "src/pithy-config.ts",
+    "src/pithy-config.generated.ts",
+    "src/pithy-locale.tsx",
+    "src/router.tsx",
+    "src/route-modules.ts",
+    "src/transport.ts",
+  ],
+  auth: [
+    "src/session.tsx",
+    "src/turnstile.tsx",
+    "src/useTurnstileWeb.ts",
+    "src/routes/pithy/sign-in.tsx",
+    "src/routes/pithy/otp.tsx",
+    "src/routes/pithy/callback.tsx",
+    "src/routes/pithy/account-suspended.tsx",
+    "src/routes/pithy/account-deleted.tsx",
+    "src/routes/pithy/organization-suspended.tsx",
+  ],
+  organization: ["src/routes/pithy/choose-organization.tsx", "src/routes/pithy/invitation.tsx"],
+  mcp: ["src/routes/pithy/agent-consent.tsx", "src/routes/pithy/connected-applications.tsx"],
+  payments: [
+    "src/payments.tsx",
+    "src/payments-store.ts",
+    "src/payments-store.native.ts",
+    "src/useStoreTransactions.ts",
+    "src/useAppFocus.ts",
+    "src/routes/pithy/paywall.tsx",
+    "src/routes/pithy/pricing.tsx",
+    "src/routes/pithy/subscription.tsx",
+  ],
+  consent: ["src/routes/pithy/consent.tsx"],
+} as const satisfies Record<string, readonly string[]>;
+
+/** One of {@link TEMPLATE_GROUPS}. */
+export type TemplateGroup = keyof typeof TEMPLATE_GROUPS;
+
+/**
+ * The adopter's own home screen, in two variants: the auth one carries the signed-in guard and a sign-out, the
+ * bare one asks the Worker's health route. Exactly one is written, always to the same place.
+ */
+export const HOME_SCREEN = {
+  target: "src/routes/app/home.tsx",
+  auth: "src/routes/app/home.tsx",
+  bare: "src/routes/app/home.bare.tsx",
+} as const;
+
+/** The token the templates use where the name of the Worker the app calls belongs. */
+export const WORKER_TOKEN = "__PITHY_WORKER__";
+
+/** The token `app.config.ts` uses where the app's own name belongs: its `apps/<name>` directory. */
+export const APP_TOKEN = "__PITHY_APP__";

package/src/version.ts

@@ -0,0 +1,13 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** This package's own version, read from its manifest beside `src/` and `dist/` alike. Node only: the scaffolder reads it. */
+export const UI_REACT_NATIVE_VERSION: string = (
+  JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf8")) as {
+    version: string;
+  }
+).version;

package/templates/app/[...pithy].tsx

@@ -0,0 +1,7 @@
+import type { ReactNode } from "react";
+import { Router, useExpoRouterAdapter } from "../src/router";
+
+/** Every path but `/`, handed to the kit's router. `src/router.tsx` reads the path and the query through the adapter. */
+export default function Pithy(): ReactNode {
+  return <Router adapter={useExpoRouterAdapter()} />;
+}

package/templates/app/_layout.tsx

@@ -0,0 +1,31 @@
+import { Slot } from "expo-router";
+import { type ReactNode, StrictMode } from "react";
+import { PithyLocale } from "../src/pithy-locale";
+import { storeTransactions } from "../src/route-modules";
+
+/**
+ * The app's root: one language over every screen, and the route `expo-router` resolved. Every path lands on
+ * `[...pithy].tsx` or `index.tsx`, which hand it to the kit's router, so screens register by dropping a file into
+ * `src/routes/`, exactly as they do in the React app.
+ *
+ * With the payments screens written, the store's listener runs here for the whole launch, so a purchase the store
+ * hands back at launch reaches the account before any screen asks for it.
+ *
+ * Your own catalogs go on `<PithyLocale messages={{ fr: … }}>`.
+ */
+export default function Layout(): ReactNode {
+  return (
+    <StrictMode>
+      {storeTransactions && <StoreTransactions listen={storeTransactions} />}
+      <PithyLocale>
+        <Slot />
+      </PithyLocale>
+    </StrictMode>
+  );
+}
+
+/** Runs the store listener. A component of its own, so the layout calls the hook only when it was written. */
+function StoreTransactions(props: { listen: () => void }): ReactNode {
+  props.listen();
+  return null;
+}

package/templates/app/index.tsx

@@ -0,0 +1,4 @@
+import Pithy from "./[...pithy]";
+
+/** `/`, which a catch-all route does not match, handed to the same router. */
+export default Pithy;

package/templates/app.config.ts

@@ -0,0 +1,56 @@
+import type { ExpoConfig } from "expo/config";
+import generated from "./src/pithy-config.generated";
+
+/** The host whose https links open the app, once `universalLinkOrigin` names one. */
+const universalHost = generated.universalLinkOrigin?.replace(/^https:\/\//, "") ?? null;
+
+/** Google's iOS sign-in returns on the reversed client id, as a URL scheme. */
+const googleIosScheme = generated.google.iosClientId
+  ? generated.google.iosClientId.split(".").reverse().join(".")
+  : null;
+
+/**
+ * The Expo app's config, read from the same file the screens read. The scheme a sign-in returns to and the origin
+ * a checkout returns through are stated once, in `src/pithy-config.generated.ts`, so the app cannot answer to a
+ * link the config does not name.
+ *
+ * The name and the bundle identifiers are yours: set `ios.bundleIdentifier` and `android.package` before a store
+ * build, and give Apple sign-in the same identifier the Worker's `appBundleIdentifier` names.
+ */
+export default (): ExpoConfig => ({
+  name: "__PITHY_APP__",
+  slug: "__PITHY_APP__",
+  scheme: generated.appScheme,
+  version: "0.1.0",
+  orientation: "portrait",
+  userInterfaceStyle: "automatic",
+  ios: {
+    supportsTablet: true,
+    usesAppleSignIn: true,
+    associatedDomains: universalHost ? [`applinks:${universalHost}`] : [],
+  },
+  android: {
+    intentFilters: universalHost
+      ? [
+          {
+            action: "VIEW",
+            autoVerify: true,
+            data: [{ scheme: "https", host: universalHost }],
+            category: ["BROWSABLE", "DEFAULT"],
+          },
+        ]
+      : [],
+  },
+  web: { output: "single" },
+  plugins: [
+    "expo-router",
+    "expo-secure-store",
+    "expo-localization",
+    "expo-web-browser",
+    "expo-apple-authentication",
+    "expo-iap",
+    ...(googleIosScheme
+      ? [["@react-native-google-signin/google-signin", { iosUrlScheme: googleIosScheme }] as [string, unknown]]
+      : []),
+  ],
+});

package/templates/metro-proxy.cjs

@@ -0,0 +1,289 @@
+// The web build's way to the Worker under `pithy dev`.
+//
+// The web build calls the Worker by relative path, and in production that is right: the build is served from the
+// Worker's own origin. Under `pithy dev` it is served by Metro, on Metro's own port, so a relative call reaches
+// Metro. This sends the requests under the Worker's paths on to `origins.dev` in `src/pithy-config.generated.ts`,
+// and hands Metro everything else.
+//
+// A request goes on as it came: method, headers and body, with its path and query resolved the way the Worker
+// resolves them, so a path is matched where it lands. Its `Host` stays the page's, so the Worker answers it as
+// same-origin with the page that sent it and sets its cookies there. The answer comes back as the Worker gave it:
+// status, every header and every `Set-Cookie`, and the body.
+//
+// Metro runs this middleware only while it serves. `expo export` builds without it. Metro reads the config when it
+// starts, so restart it after `pithy ui sync --app` rewrites the file.
+//
+// Node's own modules only: Metro loads this file before anything is bundled.
+
+const fs = require("node:fs");
+const http = require("node:http");
+const https = require("node:https");
+const path = require("node:path");
+const { pipeline } = require("node:stream");
+
+/** Where the generated config sits, relative to the app. */
+const GENERATED_CONFIG = "src/pithy-config.generated.ts";
+
+/** Where the kit's clients call each capability by default, for a generated config that lists no paths. */
+const KIT_PATHS = {
+  organization: "/organizations",
+  consent: "/consent",
+  mcp: "/mcp",
+  health: "/health",
+  turnstile: "/turnstile",
+};
+
+/** Where an MCP client discovers the Worker's authorization server. Auth serves them. */
+const OAUTH_DISCOVERY = ["/.well-known/oauth-authorization-server", "/.well-known/oauth-protected-resource"];
+
+/**
+ * The app's own screens whose path is also a capability's base path. Metro serves the screen; the routes under
+ * it are the Worker's.
+ */
+const SCREEN_PATHS = ["/consent"];
+
+/** The line the generated value starts on. The value runs from there to `export default config`. */
+const OPEN = "const config: GeneratedPithyConfig = ";
+const CLOSE = /;\s*export default config;\s*$/;
+
+/** A literal this reader cannot read. */
+class Unreadable extends Error {}
+
+/**
+ * The object literal in `text`: JSON, plus what a formatter or a hand edit leaves in a TypeScript literal, which is
+ * a key without quotes, a single-quoted string, a trailing comma and a comment. Anything else, such as an
+ * expression, throws: the file is read, never run.
+ */
+function parseLiteral(text) {
+  let at = 0;
+  const skip = () => {
+    for (;;) {
+      while (at < text.length && /\s/.test(text[at])) at += 1;
+      if (text.startsWith("//", at)) {
+        const end = text.indexOf("\n", at);
+        at = end === -1 ? text.length : end + 1;
+      } else if (text.startsWith("/*", at)) {
+        const end = text.indexOf("*/", at + 2);
+        if (end === -1) throw new Unreadable();
+        at = end + 2;
+      } else return;
+    }
+  };
+  const consume = (char) => {
+    skip();
+    if (text[at] !== char) throw new Unreadable();
+    at += 1;
+  };
+  const string = () => {
+    const quote = text[at];
+    let end = at + 1;
+    let raw = "";
+    while (end < text.length && text[end] !== quote) {
+      const char = text[end];
+      if (char === "\n") throw new Unreadable();
+      if (char === "\\") {
+        const next = text[end + 1] ?? "";
+        raw += next === "'" ? "'" : char + next;
+        end += 2;
+        continue;
+      }
+      raw += char === '"' ? '\\"' : char;
+      end += 1;
+    }
+    if (end >= text.length) throw new Unreadable();
+    at = end + 1;
+    try {
+      return JSON.parse(`"${raw}"`);
+    } catch {
+      throw new Unreadable();
+    }
+  };
+  const value = () => {
+    skip();
+    const char = text[at];
+    if (char === "{") {
+      at += 1;
+      const object = {};
+      for (;;) {
+        skip();
+        if (text[at] === "}") {
+          at += 1;
+          return object;
+        }
+        let key;
+        if (text[at] === '"' || text[at] === "'") key = string();
+        else {
+          const name = /^[A-Za-z_$][A-Za-z0-9_$]*/.exec(text.slice(at))?.[0];
+          if (name === undefined) throw new Unreadable();
+          key = name;
+          at += name.length;
+        }
+        consume(":");
+        Object.defineProperty(object, key, { value: value(), enumerable: true, writable: true, configurable: true });
+        skip();
+        if (text[at] === ",") at += 1;
+        else if (text[at] !== "}") throw new Unreadable();
+      }
+    }
+    if (char === "[") {
+      at += 1;
+      const array = [];
+      for (;;) {
+        skip();
+        if (text[at] === "]") {
+          at += 1;
+          return array;
+        }
+        array.push(value());
+        skip();
+        if (text[at] === ",") at += 1;
+        else if (text[at] !== "]") throw new Unreadable();
+      }
+    }
+    if (char === '"' || char === "'") return string();
+    const word = /^(?:true|false|null|-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?)(?![A-Za-z0-9_$.])/.exec(
+      text.slice(at),
+    )?.[0];
+    if (word === undefined) throw new Unreadable();
+    at += word.length;
+    return JSON.parse(word);
+  };
+  const parsed = value();
+  skip();
+  if (at !== text.length) throw new Unreadable();
+  return parsed;
+}
+
+/**
+ * The value in a generated config's text, or `null` when the text is not one Pithy wrote. A file the project's
+ * formatter has reformatted, or an adopter has edited by hand, still reads.
+ */
+function readGeneratedConfig(text) {
+  const start = text.indexOf(OPEN);
+  const close = CLOSE.exec(text);
+  if (start === -1 || close === null || close.index < start) return null;
+  try {
+    const value = parseLiteral(text.slice(start + OPEN.length, close.index));
+    return value && typeof value === "object" && value.origins && typeof value.origins.dev === "string" ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The paths the Worker answers. The generated config lists every base path the Worker's route table serves, as the
+ * CLI composed it; a config written before it carried the list falls back to what each capability's `dev`
+ * projection composes, since `pithy dev` serves `dev`, and the kit's defaults for the rest.
+ */
+function proxiedPaths(config) {
+  if (Array.isArray(config.workerPaths) && config.workerPaths.every((path) => typeof path === "string")) {
+    return config.workerPaths;
+  }
+  const dev = (field) => config[field]?.dev;
+  const consent = dev("consent")?.enabled ? dev("consent").basePath : KIT_PATHS.consent;
+  const paths = [KIT_PATHS.organization, consent, KIT_PATHS.mcp, KIT_PATHS.health];
+  if (dev("auth")?.enabled) paths.push(dev("auth").basePath, ...OAUTH_DISCOVERY);
+  if (dev("payments")?.enabled) paths.push(dev("payments").basePath);
+  if (dev("turnstile")?.enabled) paths.push(KIT_PATHS.turnstile);
+  return paths;
+}
+
+/** The base a request target is resolved against. A target that names any other origin is not a path. */
+const LOCAL = "http://metro.invalid";
+
+/**
+ * The path and query to send the Worker for `url`, a request's target, or `null` when it stays with Metro. The
+ * target is resolved the way the Worker resolves it, dot segments and backslashes included, so a path that climbs
+ * out of a base path is matched where it lands.
+ */
+function workerPath(url, paths) {
+  let resolved;
+  try {
+    resolved = new URL(url, LOCAL);
+  } catch {
+    return null;
+  }
+  if (resolved.origin !== LOCAL) return null;
+  const { pathname, search } = resolved;
+  if (SCREEN_PATHS.includes(pathname)) return null;
+  const under = paths.some((base) => pathname === base || pathname.startsWith(`${base}/`));
+  return under ? `${pathname}${search}` : null;
+}
+
+/** Whether `url`, a request's target, goes to the Worker: under one of `paths`, and not one of the app's screens. */
+function isProxied(url, paths) {
+  return workerPath(url, paths) !== null;
+}
+
+/** A middleware that sends a request under `paths` to `target`, and any other to the next middleware. */
+function createDevProxy({ target, paths }) {
+  const upstream = new URL(target);
+  const send = upstream.protocol === "https:" ? https.request : http.request;
+  return (req, res, next) => {
+    const forward = workerPath(req.url || "/", paths);
+    if (forward === null) {
+      next();
+      return;
+    }
+    const outgoing = send(
+      {
+        protocol: upstream.protocol,
+        hostname: upstream.hostname.replace(/^\[|\]$/g, ""),
+        port: upstream.port,
+        method: req.method,
+        path: forward,
+        headers: req.headers,
+      },
+      (answer) => {
+        res.writeHead(answer.statusCode || 502, answer.statusMessage, answer.rawHeaders);
+        pipeline(answer, res, () => undefined);
+      },
+    );
+    res.on("close", () => {
+      if (!res.writableFinished) outgoing.destroy();
+    });
+    outgoing.on("error", (error) => {
+      if (res.headersSent) {
+        res.destroy(error);
+        return;
+      }
+      res.writeHead(502, { "content-type": "text/plain; charset=utf-8" });
+      res.end(`The Worker did not answer at ${target}. Start it with pithy dev. ${error.message}\n`);
+    });
+    req.pipe(outgoing);
+  };
+}
+
+/**
+ * `config` with the dev proxy in front of Metro's middleware, and of any enhancer already there. A generated
+ * config it cannot read leaves `config` as it was, and says why.
+ */
+function withDevProxy(config, appDir, warn = console.warn) {
+  let generated = null;
+  try {
+    generated = readGeneratedConfig(fs.readFileSync(path.join(appDir, GENERATED_CONFIG), "utf8"));
+  } catch {
+    generated = null;
+  }
+  if (generated === null) {
+    warn(
+      `The web build cannot reach the Worker under Metro: ${GENERATED_CONFIG} is not a file Pithy wrote. Run pithy ui sync --app.`,
+    );
+    return config;
+  }
+  const proxy = createDevProxy({ target: generated.origins.dev, paths: proxiedPaths(generated) });
+  const server = config.server || {};
+  const earlier = server.enhanceMiddleware;
+  return {
+    ...config,
+    server: {
+      ...server,
+      enhanceMiddleware: (middleware, metro) => {
+        const inner = earlier ? earlier(middleware, metro) : middleware;
+        return (req, res, next) => proxy(req, res, () => inner(req, res, next));
+      },
+    },
+  };
+}
+
+module.exports = { KIT_PATHS, readGeneratedConfig, proxiedPaths, isProxied, createDevProxy, withDevProxy };

package/templates/metro.config.js

@@ -0,0 +1,6 @@
+// Expo's Metro config, with the web build's way to the Worker under `pithy dev`: Metro serves the web build on its
+// own port, and `metro-proxy.cjs` sends the calls meant for the Worker on to it.
+const { getDefaultConfig } = require("expo/metro-config");
+const { withDevProxy } = require("./metro-proxy.cjs");
+
+module.exports = withDevProxy(getDefaultConfig(__dirname), __dirname);

package/templates/src/payments-store.native.ts

@@ -0,0 +1,20 @@
+import type * as ExpoIap from "expo-iap";
+
+/**
+ * The platform's store, StoreKit or Play Billing, through `expo-iap`: the file Metro resolves `./payments-store` to
+ * on a phone. The module loads on the first store call, so an app that never sells through a store never loads it.
+ */
+
+/** `expo-iap`, as the store calls reach it. */
+export type StoreModule = typeof ExpoIap;
+
+let loading: Promise<StoreModule | null> | null = null;
+
+/** The store on this platform, loaded once. A failed load is forgotten, so the next call tries again. */
+export function loadStore(): Promise<StoreModule | null> {
+  loading ??= import("expo-iap").catch(() => {
+    loading = null;
+    return null;
+  });
+  return loading;
+}

package/templates/src/payments-store.ts

@@ -0,0 +1,16 @@
+import type * as ExpoIap from "expo-iap";
+
+/**
+ * The platform's store, StoreKit or Play Billing, through `expo-iap`.
+ *
+ * Metro resolves `./payments-store` to `payments-store.native.ts` on a phone and to this file on the web, so the
+ * web bundle never carries `expo-iap`: the web sells on a hosted page and has no store to reach.
+ */
+
+/** `expo-iap`, as the store calls reach it. */
+export type StoreModule = typeof ExpoIap;
+
+/** The store on this platform. The web has none. */
+export function loadStore(): Promise<StoreModule | null> {
+  return Promise.resolve(null);
+}