npm - @openparachute/app - Versions diffs - 0.2.0-rc.4 - Mend

@openparachute/app 0.2.0-rc.4

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 (29) hide show

package/.parachute/config/schema +62 -0
package/.parachute/info +14 -0
package/.parachute/module.json +14 -0
package/CHANGELOG.md +405 -0
package/LICENSE +661 -0
package/bin/parachute-app.ts +525 -0
package/dist/admin/assets/index-BXlRNPxk.js +60 -0
package/dist/admin/assets/index-DaGP1hmw.css +1 -0
package/dist/admin/index.html +14 -0
package/package.json +51 -0
package/src/admin-routes.ts +884 -0
package/src/auth.ts +212 -0
package/src/bootstrap.ts +153 -0
package/src/cache-headers.ts +106 -0
package/src/config.ts +289 -0
package/src/dcr.ts +334 -0
package/src/dev-injection.ts +166 -0
package/src/dev-mode.ts +205 -0
package/src/dev-routes.ts +380 -0
package/src/dev-watcher.ts +479 -0
package/src/http-server.ts +533 -0
package/src/index.ts +394 -0
package/src/meta-schema.ts +662 -0
package/src/npm-fetch.ts +320 -0
package/src/operator-token.ts +95 -0
package/src/provision-schema.ts +180 -0
package/src/self-register.ts +155 -0
package/src/services-manifest.ts +104 -0
package/src/ui-registry.ts +202 -0

package/src/dev-injection.ts ADDED Viewed

@@ -0,0 +1,166 @@
+/**
+ * Dev-mode reload-script injection — Phase 1.3.
+ *
+ * When a UI is in dev mode AND its `index.html` is served, we inject a
+ * small `<script>` that opens an EventSource against the SSE reload
+ * endpoint and reloads the tab on a `reload` event. The script is
+ * idempotent — re-injection doesn't duplicate because we tag it with a
+ * known `id` and skip if that id is already present.
+ *
+ * Why string scanning instead of cheerio:
+ *
+ *   We considered `cheerio` (the brief explicitly invites it), but a
+ *   500KB+ HTML-parser dep for ONE conservative insertion is the wrong
+ *   shape. The injection point is well-defined: just before `</head>`.
+ *   The regex is case-insensitive and tolerates whitespace. The
+ *   fallback chain (head → first `<script>` → first `<body>` → append)
+ *   handles the unusual cases the brief calls out.
+ *
+ *   Cheerio also serializes the document on output, which would re-emit
+ *   the operator's HTML in cheerio's canonical form. For a dev-mode
+ *   shim we want the document untouched apart from one inserted line.
+ *
+ *   If we ever need richer manipulation (CSP rewrites, link-prefetch
+ *   stripping, etc.) we revisit. For now, regex.
+ *
+ * Idempotency contract:
+ *
+ *   - `id="parachute-app-dev-reload"` is the marker. Any earlier
+ *     injection sets it, so a re-render finds it and skips.
+ *   - The marker check is regex-based; we don't parse the HTML to find
+ *     it. False positives (a comment containing the exact marker)
+ *     would suppress injection harmlessly — dev mode would still work,
+ *     it just wouldn't re-inject. Conservative.
+ */
+/**
+ * Marker id used to deduplicate the injected `<script>`. Exported because
+ * tests assert on it.
+ */
+export const DEV_RELOAD_SCRIPT_ID = "parachute-app-dev-reload" as const;
+/**
+ * Marker regex matching the script tag's `id` attribute. We accept both
+ * quote styles (`id="..."` and `id='...'`).
+ */
+const ID_MARKER_REGEX = new RegExp(
+  `id\\s*=\\s*['"]${DEV_RELOAD_SCRIPT_ID.replace(/[-/\\^$*+?.()|[\]{}]/g, "\\$&")}['"]`,
+  "i",
+);
+/** Find `</head>` (case-insensitive, whitespace-tolerant). */
+const HEAD_CLOSE_REGEX = /<\/\s*head\s*>/i;
+/** Find the first `<script ...>` tag. */
+const FIRST_SCRIPT_REGEX = /<script\b/i;
+/** Find the opening `<body ...>` tag. */
+const BODY_OPEN_REGEX = /<body\b[^>]*>/i;
+/**
+ * Build the dev-reload script tag. The script:
+ *   - Opens an EventSource against `<endpoint>` (mount-relative path).
+ *   - On `reload`, schedules a `window.location.reload()` 200ms out
+ *     (debounce — covers the case where a Phase 2 watcher fires the same
+ *     event twice in quick succession).
+ *   - Silently ignores errors; EventSource auto-reconnects on transient
+ *     drops by default.
+ *
+ * `endpoint` is relative to the UI's mount path (e.g. `/app/notes/_dev/reload`)
+ * — passed in so we can build absolute URLs the browser will navigate to
+ * correctly regardless of the document's `<base>` tag.
+ */
+export function buildDevReloadScript(endpoint: string): string {
+  // The endpoint is interpolated as a string literal; escape any embedded
+  // quote / backslash so a hostile mount path can't break out. Mount
+  // paths are constrained by PATH_PATTERN so this is belt-and-braces.
+  const safeEndpoint = JSON.stringify(endpoint);
+  return `<script id="${DEV_RELOAD_SCRIPT_ID}">
+(() => {
+  try {
+    const es = new EventSource(${safeEndpoint});
+    let pending = false;
+    es.addEventListener("reload", () => {
+      if (pending) return;
+      pending = true;
+      setTimeout(() => { window.location.reload(); }, 200);
+    });
+    es.addEventListener("error", () => {
+      /* EventSource auto-reconnects; nothing to do */
+    });
+  } catch (e) {
+    console.warn("[parachute-app dev-reload] failed to start:", e);
+  }
+})();
+</script>`;
+}
+/**
+ * Inject the dev-reload script into `html`. If the marker is already
+ * present, return `html` unchanged (idempotent). Otherwise insert the
+ * `<script>` immediately before `</head>`. Fallback chain when there's
+ * no `</head>`:
+ *
+ *   1. Before the first `<script>` tag.
+ *   2. After the opening `<body>` tag.
+ *   3. Append to end (with a `console.warn` from the script itself —
+ *      callers also log a warning so operators see the affordance).
+ *
+ * Returns `{ html, injected, fallback }`:
+ *   - `html`: the (maybe-modified) document.
+ *   - `injected`: did we change anything?
+ *   - `fallback`: which fallback branch fired (or `undefined` for the
+ *     happy path). Tests + log surface this.
+ */
+export function injectDevReloadScript(
+  html: string,
+  endpoint: string,
+): {
+  html: string;
+  injected: boolean;
+  fallback?: "before-script" | "after-body" | "append";
+} {
+  // Idempotent: bail if the marker is already in the doc.
+  if (ID_MARKER_REGEX.test(html)) {
+    return { html, injected: false };
+  }
+  const script = `${buildDevReloadScript(endpoint)}\n`;
+  // Happy path: just before </head>.
+  const headMatch = HEAD_CLOSE_REGEX.exec(html);
+  if (headMatch) {
+    const idx = headMatch.index;
+    return {
+      html: `${html.slice(0, idx)}${script}${html.slice(idx)}`,
+      injected: true,
+    };
+  }
+  // Fallback 1: before the first <script>.
+  const scriptMatch = FIRST_SCRIPT_REGEX.exec(html);
+  if (scriptMatch) {
+    const idx = scriptMatch.index;
+    return {
+      html: `${html.slice(0, idx)}${script}${html.slice(idx)}`,
+      injected: true,
+      fallback: "before-script",
+    };
+  }
+  // Fallback 2: after the opening <body>.
+  const bodyMatch = BODY_OPEN_REGEX.exec(html);
+  if (bodyMatch) {
+    const idx = bodyMatch.index + bodyMatch[0].length;
+    return {
+      html: `${html.slice(0, idx)}\n${script}${html.slice(idx)}`,
+      injected: true,
+      fallback: "after-body",
+    };
+  }
+  // Fallback 3: append. Operators with a malformed document still get
+  // the affordance.
+  return {
+    html: `${html}\n${script}`,
+    injected: true,
+    fallback: "append",
+  };
+}

package/src/dev-mode.ts ADDED Viewed

@@ -0,0 +1,205 @@
+/**
+ * Per-UI dev-mode state — Phase 1.3.
+ *
+ * Solves the "edit code, build, browser still shows old" frustration
+ * (parachute-notes#151) at the platform level. Each registered UI carries
+ * an optional dev-mode flag the operator toggles via `parachute-app dev
+ * <name>` (Phase 1.3) or the admin SPA. When dev mode is on:
+ *
+ *   1. The HTTP server emits `Cache-Control: no-cache, no-store,
+ *      must-revalidate` on every response from that UI (overrides smart
+ *      caching for hashed assets + 1h-default for non-hashed).
+ *   2. The UI's `index.html` gets an injected `<script>` tag that opens
+ *      an EventSource against `/app/<name>/_dev/reload`. Operator-triggered
+ *      reload events broadcast on the stream cause the tab to reload.
+ *   3. The operator-flow trigger is manual at MVP — `parachute-app dev
+ *      <name> --trigger`. Phase 2 will wire a file watcher to fire the
+ *      same broadcast on dist/ change.
+ *
+ * State design choices:
+ *
+ *   - Process-local, in-memory. A daemon restart returns every UI to
+ *     production cache headers. This is deliberate — dev mode is an
+ *     interactive operator concern, not a persisted property of the UI
+ *     itself. If an operator wants persistence later, meta.json could
+ *     grow a `dev_mode_default` field (Phase 2+).
+ *   - One map module-wide. Lookup is O(name) on every request, but the
+ *     map is at most a handful of entries (operator iterating on UIs).
+ *   - SSE controllers live in a separate `Set` per-UI; broadcast iterates
+ *     and tolerates per-client errors (disconnects are normal).
+ *
+ * Concurrency notes: Bun runs the event loop single-threaded, so the
+ * mutations here (Map.set, Set.add) are atomic relative to one another;
+ * no locking needed.
+ */
+export type DevModeState = {
+  enabled: boolean;
+  /** ms since epoch when `enabled` was last flipped to `true`. 0 when disabled. */
+  enabledAt: number;
+  /** Phase 2 — file watcher source dir override. Stored for forward-compat. */
+  watchDir?: string;
+  /** Phase 2 — auto-rebuild command override. Stored for forward-compat. */
+  buildCmd?: string;
+};
+/**
+ * SSE subscriber — a connected browser tab listening on
+ * `/app/<name>/_dev/reload`. We keep both the controller (for `enqueue`)
+ * and the encoder (we always emit utf8) so the broadcast path stays
+ * allocation-light.
+ *
+ * Per-subscriber `closed` flag short-circuits the broadcast loop if a
+ * `controller.enqueue` already threw on this client — we mark it dead
+ * and reap on the next pass instead of re-throwing on every event.
+ */
+export type DevReloadSubscriber = {
+  controller: ReadableStreamDefaultController<Uint8Array>;
+  closed: boolean;
+};
+const STATE = new Map<string, DevModeState>();
+const SUBSCRIBERS = new Map<string, Set<DevReloadSubscriber>>();
+/** Return the dev-mode state for a UI, or the default (disabled). */
+export function getDevMode(name: string): DevModeState {
+  return STATE.get(name) ?? { enabled: false, enabledAt: 0 };
+}
+/** Pure predicate, used everywhere the cache + injection branches read. */
+export function isDevMode(name: string): boolean {
+  return STATE.get(name)?.enabled === true;
+}
+/** List every UI currently in dev mode (for the `dev list` CLI). */
+export function listDevMode(): Array<{ name: string; state: DevModeState }> {
+  const out: Array<{ name: string; state: DevModeState }> = [];
+  for (const [name, state] of STATE) {
+    if (state.enabled) out.push({ name, state });
+  }
+  out.sort((a, b) => a.name.localeCompare(b.name));
+  return out;
+}
+/**
+ * Enable dev mode for `name`. Idempotent — calling twice doesn't reset
+ * the timestamp. Returns the resulting state.
+ */
+export function enableDevMode(
+  name: string,
+  opts: { watchDir?: string; buildCmd?: string } = {},
+): DevModeState {
+  const existing = STATE.get(name);
+  if (existing?.enabled) {
+    // Idempotent — preserve the earlier `enabledAt`.
+    return existing;
+  }
+  const next: DevModeState = {
+    enabled: true,
+    enabledAt: Date.now(),
+    watchDir: opts.watchDir,
+    buildCmd: opts.buildCmd,
+  };
+  STATE.set(name, next);
+  return next;
+}
+/**
+ * Disable dev mode for `name`. Also closes every connected SSE subscriber
+ * so the next page load resumes production cache headers cleanly. Returns
+ * the resulting state (always `enabled: false`).
+ */
+export function disableDevMode(name: string): DevModeState {
+  STATE.set(name, { enabled: false, enabledAt: 0 });
+  // Close any active SSE streams so the browser's EventSource auto-reconnect
+  // doesn't keep retrying against a UI that's no longer in dev mode.
+  closeAllSubscribers(name);
+  return STATE.get(name)!;
+}
+/** Reset all dev-mode state. Tests use this. */
+export function resetDevMode(): void {
+  for (const name of [...SUBSCRIBERS.keys()]) {
+    closeAllSubscribers(name);
+  }
+  STATE.clear();
+  SUBSCRIBERS.clear();
+}
+/** Register a new SSE subscriber. The caller holds the controller. */
+export function addSubscriber(name: string, subscriber: DevReloadSubscriber): void {
+  let set = SUBSCRIBERS.get(name);
+  if (!set) {
+    set = new Set();
+    SUBSCRIBERS.set(name, set);
+  }
+  set.add(subscriber);
+}
+/** Drop a subscriber (called from the stream's `cancel` hook). */
+export function removeSubscriber(name: string, subscriber: DevReloadSubscriber): void {
+  const set = SUBSCRIBERS.get(name);
+  if (!set) return;
+  set.delete(subscriber);
+  if (set.size === 0) SUBSCRIBERS.delete(name);
+}
+/** Count of currently-connected subscribers (used by the trigger response). */
+export function subscriberCount(name: string): number {
+  return SUBSCRIBERS.get(name)?.size ?? 0;
+}
+/**
+ * Broadcast a `reload` event to every subscriber of `name`. Returns the
+ * number of subscribers we successfully enqueued to — a controller that
+ * errors mid-broadcast (disconnect) is marked closed + removed.
+ *
+ * SSE wire format:
+ *
+ *     event: reload\n
+ *     data: {"timestamp": 1716345600000}\n
+ *     \n
+ *
+ * The empty line terminates the event; without it most browsers buffer
+ * the event without dispatching.
+ */
+export function broadcastReload(name: string, timestamp = Date.now()): number {
+  const set = SUBSCRIBERS.get(name);
+  if (!set) return 0;
+  const encoder = new TextEncoder();
+  const payload = encoder.encode(`event: reload\ndata: ${JSON.stringify({ timestamp })}\n\n`);
+  let notified = 0;
+  const dead: DevReloadSubscriber[] = [];
+  for (const sub of set) {
+    if (sub.closed) {
+      dead.push(sub);
+      continue;
+    }
+    try {
+      sub.controller.enqueue(payload);
+      notified++;
+    } catch {
+      sub.closed = true;
+      dead.push(sub);
+    }
+  }
+  for (const d of dead) set.delete(d);
+  if (set.size === 0) SUBSCRIBERS.delete(name);
+  return notified;
+}
+/** Close + drop every subscriber for a UI. Used on disableDevMode + tests. */
+export function closeAllSubscribers(name: string): void {
+  const set = SUBSCRIBERS.get(name);
+  if (!set) return;
+  for (const sub of set) {
+    if (sub.closed) continue;
+    sub.closed = true;
+    try {
+      sub.controller.close();
+    } catch {
+      // already closed by the runtime — fine
+    }
+  }
+  SUBSCRIBERS.delete(name);
+}