@field/cascade 0.10.0 → 0.12.0

package/dist/cli/runtime/image.ts

@@ -0,0 +1,302 @@
+/**
+ * `cascade/image` — the one image API a node body uses, in every host.
+ *
+ * A node that draws used to have two honest choices and one dishonest one.
+ * `new OffscreenCanvas` worked in Studio and under `cascade run` (the CLI
+ * installs Skia's canvas as that global), but the bytes in and out went
+ * through `cascade/io`'s project paths, and fonts had no portable door at all.
+ * So the nodes that needed fonts or files reached for `@napi-rs/canvas` and
+ * `node:fs` directly, declared `runsOn: 'server'`, and could never be exported
+ * as a browser editor — the commons plotter-social job was blocked on exactly
+ * that ("Cascade has no browser image contract").
+ *
+ * The contract, in full:
+ *
+ *  - **Surface.** `createCanvas(w, h)` is an `OffscreenCanvas`: the browser's
+ *    own in a page or a worker, Skia's (`@napi-rs/canvas`, installed by the
+ *    headless host) under `cascade run`/`render`/MCP. `context2d(canvas)` asks
+ *    for a CPU-backed 2D context (`willReadFrequently`), which is what keeps
+ *    Chrome on the same software Skia rasteriser the headless host uses, and
+ *    is the right hint anyway for nodes that read pixels back.
+ *  - **Pixels in.** `readImage(context, ref)` reads an `ImageRef`, `AssetRef`
+ *    or project path through the node's declared `assets` capability and
+ *    decodes it with `decodeImage` (`createImageBitmap` in both hosts).
+ *  - **Pixels out.** `writeImage(context, canvas, name)` encodes PNG through
+ *    `encodeImage` and stores it with `assets.write`, returning the `ImageRef`
+ *    to set on an `image` output. The host decides where it lands
+ *    (`.cascade-cache/<name>.<hash>.png` headless, an in-memory generated
+ *    asset in an exported editor), so a node never names a path.
+ *  - **Fonts.** `registerFont(family, bytes)` makes a face drawable by
+ *    `ctx.font` in this host: `FontFace` added to the page's or worker's font
+ *    set in a browser, Skia's `GlobalFonts` headless. Bytes come from the same
+ *    `assets` capability, so a font is a project file like any other.
+ *  - **Refusal, not fallback.** No canvas in this host, or no `assets`
+ *    capability declared, is an error with one sentence saying which, never a
+ *    silent blank image.
+ *
+ * A node using it declares `runsOn: 'portable'` and `capabilities: ['assets']`
+ * and imports nothing host-specific (`node:*`, `@napi-rs/canvas`, `document`).
+ * Then the same body cooks in Studio, in `cascade run`, and in an exported
+ * editor's worker.
+ *
+ * The headless host installs its font door under a global key, like
+ * `cascade/io`'s bridge, because the node's copy of this module and the CLI's
+ * copy are not always the same module instance.
+ */
+
+import { canvasPixels, pixelsBitmap, type ImagePixels } from './io.js';
+
+export type { ImagePixels } from './io.js';
+
+/** An image port value. Mirrors Cascade's core `ImageRef`. */
+export interface ImageRef {
+  path: string;
+  size: [number, number];
+  channels: 'r' | 'a' | 'rg' | 'rgb' | 'rgba';
+  depth: 'u8' | 'u16' | 'f16' | 'f32';
+  space: 'srgb' | 'linear';
+}
+
+/** Anything naming stored bytes: an `ImageRef`, an `AssetRef`, or a project path. */
+export type ImageSourceRef = string | { readonly path: string };
+
+/** The part of the `assets` capability these helpers use. */
+export interface ImageAssets {
+  read(ref: { path: string }, options: { signal: unknown }): Promise<Uint8Array>;
+  write(
+    data: Uint8Array,
+    metadata: { mediaType?: string; suggestedName?: string },
+    options: { signal: unknown },
+  ): Promise<{ path: string; mediaType?: string }>;
+  /** Optional: store an intermediate from its pixels (see core `AssetCapability.keepImage`). */
+  keepImage?(
+    pixels: ImagePixels,
+    metadata: { suggestedName?: string },
+    options: { signal: unknown },
+  ): Promise<{ path: string; mediaType?: string }>;
+  /** Optional: the pixels behind a stored image while the host holds them in memory. */
+  imagePixels?(ref: { path: string }): ImagePixels | undefined;
+}
+
+/**
+ * The slice of a definition-v1 `NodeExecutionContext` these helpers need, so
+ * a node passes its own `context`. Typed loosely on purpose: a node that did
+ * not declare `assets` still type-checks here and gets a sentence at run time
+ * naming the missing declaration rather than a type error about generics.
+ */
+export interface ImageNodeContext {
+  readonly capabilities: object;
+  readonly signal?: unknown;
+}
+
+export type ImageType = 'image/png' | 'image/webp' | 'image/jpeg';
+
+/** What a host gives `registerFont`. A browser realm needs none. */
+export interface ImageHost {
+  /** For a `--verbose` line and for errors. */
+  readonly renderer: string;
+  registerFont(family: string, bytes: Uint8Array, descriptors: FontDescriptors): void | Promise<void>;
+}
+
+export interface FontDescriptors {
+  /** CSS weight, `'400'`, `'bold'`. Headless reads the weight from the file. */
+  weight?: string;
+  /** `'normal'` or `'italic'`. Headless reads the style from the file. */
+  style?: string;
+}
+
+const HOST_KEY = '__cascadeImageHost';
+
+const NO_CANVAS =
+  'cascade/image: this host has no canvas. In a browser this needs OffscreenCanvas; headless, Cascade installs ' +
+  '@napi-rs/canvas before a run (install it with "npm install @napi-rs/canvas" if it is missing).';
+
+/** Install the headless host's font door. Returns the disposer. */
+export function installImageHost(host: ImageHost | null): () => void {
+  const globals = globalThis as Record<string, unknown>;
+  const previous = globals[HOST_KEY];
+  globals[HOST_KEY] = host ?? undefined;
+  return () => {
+    globals[HOST_KEY] = previous;
+  };
+}
+
+function installedHost(): ImageHost | null {
+  const host = (globalThis as Record<string, unknown>)[HOST_KEY] as ImageHost | undefined;
+  return host && typeof host.registerFont === 'function' ? host : null;
+}
+
+type CanvasConstructor = new (width: number, height: number) => OffscreenCanvas;
+
+function canvasConstructor(): CanvasConstructor | undefined {
+  return (globalThis as { OffscreenCanvas?: CanvasConstructor }).OffscreenCanvas;
+}
+
+/** Whether this host can draw. Never throws. */
+export function canvasAvailable(): boolean {
+  return typeof canvasConstructor() === 'function';
+}
+
+/** A drawing surface of whole pixels, at least 1x1. */
+export function createCanvas(width: number, height: number): OffscreenCanvas {
+  const Canvas = canvasConstructor();
+  if (!Canvas) throw new Error(NO_CANVAS);
+  return new Canvas(Math.max(1, Math.round(width)), Math.max(1, Math.round(height)));
+}
+
+/**
+ * The canvas's 2D context, CPU-backed. `willReadFrequently` keeps a browser
+ * off the GPU rasteriser, so a node draws with the same software Skia in Chrome
+ * as headless, and `getImageData` does not stall on a readback.
+ */
+export function context2d(canvas: OffscreenCanvas): OffscreenCanvasRenderingContext2D {
+  const context = canvas.getContext('2d', { willReadFrequently: true }) as OffscreenCanvasRenderingContext2D | null;
+  if (!context) throw new Error('cascade/image: the canvas has no 2D context');
+  return context;
+}
+
+/** `createCanvas` and `context2d` in one: `const { canvas, context } = surface(w, h)`. */
+export function surface(width: number, height: number): {
+  canvas: OffscreenCanvas;
+  context: OffscreenCanvasRenderingContext2D;
+} {
+  const canvas = createCanvas(width, height);
+  return { canvas, context: context2d(canvas) };
+}
+
+/** Encoded bytes (PNG, JPEG, WebP) to something `drawImage` accepts. */
+export async function decodeImage(bytes: Uint8Array | ArrayBuffer | Blob): Promise<ImageBitmap> {
+  const create = (globalThis as { createImageBitmap?: (source: Blob) => Promise<ImageBitmap> }).createImageBitmap;
+  if (typeof create !== 'function') throw new Error(NO_CANVAS);
+  const blob = bytes instanceof Blob ? bytes : new Blob([bytes as BlobPart]);
+  const image = await create(blob);
+  if (!image?.width || !image?.height) throw new Error('cascade/image: could not decode the image data');
+  return image;
+}
+
+/** A canvas's pixels as encoded bytes, PNG unless asked otherwise. */
+export async function encodeImage(
+  canvas: OffscreenCanvas,
+  options: { type?: ImageType; quality?: number } = {},
+): Promise<Uint8Array> {
+  const type = options.type ?? 'image/png';
+  if (typeof canvas.convertToBlob !== 'function') throw new Error('cascade/image: this canvas cannot encode (no convertToBlob)');
+  const blob = await canvas.convertToBlob({ type, ...(options.quality === undefined ? {} : { quality: options.quality }) });
+  return new Uint8Array(await blob.arrayBuffer());
+}
+
+// One record per realm, so a font registered once is not added again on every
+// cook. Keyed by family and content: new bytes under a family name register.
+// The headless realm is keyed by its renderer name rather than the host
+// object, because a long-lived process (MCP) installs a fresh host per run
+// while Skia's font registry lives for the whole process.
+const registered = new Map<unknown, Set<string>>();
+
+function fingerprint(bytes: Uint8Array): string {
+  let hash = 0x811c9dc5;
+  for (let index = 0; index < bytes.length; index += 1) {
+    hash ^= bytes[index]!;
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return `${bytes.length}:${(hash >>> 0).toString(16)}`;
+}
+
+interface BrowserFontSet { add(face: unknown): unknown }
+type FontFaceConstructor = new (family: string, source: ArrayBuffer | Uint8Array, descriptors?: FontDescriptors) => {
+  load(): Promise<unknown>;
+};
+
+/**
+ * Make `family` drawable by `ctx.font` here. Idempotent per family and bytes.
+ * A browser realm (page or worker) uses `FontFace`; the headless host
+ * registers with Skia. A host with neither refuses.
+ */
+export async function registerFont(
+  family: string,
+  bytes: Uint8Array | ArrayBuffer,
+  descriptors: FontDescriptors = {},
+): Promise<void> {
+  if (!family.trim()) throw new Error('cascade/image: registerFont needs a family name');
+  const data = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+  if (!data.byteLength) throw new Error(`cascade/image: the font for ${family} is empty`);
+  const host = installedHost();
+  const globals = globalThis as { FontFace?: FontFaceConstructor; fonts?: BrowserFontSet; document?: { fonts?: BrowserFontSet } };
+  const fonts = host ? null : globals.fonts ?? globals.document?.fonts;
+  const realm: unknown = host ? `headless:${host.renderer}` : fonts ?? globalThis;
+  const key = `${family}\u0000${descriptors.weight ?? ''}\u0000${descriptors.style ?? ''}\u0000${fingerprint(data)}`;
+  const seen = registered.get(realm) ?? new Set<string>();
+  if (seen.has(key)) return;
+  if (host) {
+    await host.registerFont(family, data, descriptors);
+  } else if (typeof globals.FontFace === 'function' && fonts) {
+    // A copy: FontFace may detach or keep the buffer it is given.
+    const face = new globals.FontFace(family, data.slice().buffer, descriptors);
+    fonts.add(await face.load());
+  } else {
+    throw new Error('cascade/image: this host cannot register fonts (no FontFace and no headless canvas host)');
+  }
+  seen.add(key);
+  registered.set(realm, seen);
+}
+
+function assetsOf(context: ImageNodeContext): ImageAssets {
+  const assets = (context.capabilities as { assets?: ImageAssets }).assets;
+  if (!assets || typeof assets.read !== 'function' || typeof assets.write !== 'function') {
+    throw new Error("cascade/image: this node reads or writes images, so its definition must declare capabilities: ['assets']");
+  }
+  return assets;
+}
+
+function refOf(ref: ImageSourceRef): { path: string } {
+  const path = typeof ref === 'string' ? ref : ref?.path;
+  if (typeof path !== 'string' || !path) throw new Error('cascade/image: no image to read (an empty path or an unset image input)');
+  return { path };
+}
+
+const NEVER = { aborted: false, addEventListener() {}, removeEventListener() {} };
+
+/** A stored file's bytes through the node's `assets` capability: an image, a font, anything. */
+export async function readBytes(context: ImageNodeContext, ref: ImageSourceRef): Promise<Uint8Array> {
+  return assetsOf(context).read(refOf(ref), { signal: context.signal ?? NEVER });
+}
+
+/** Read and decode an image input, an asset, or a project file. */
+export async function readImage(context: ImageNodeContext, ref: ImageSourceRef): Promise<ImageBitmap> {
+  // An image the host still holds in memory skips the read and the decode.
+  const pixels = assetsOf(context).imagePixels?.(refOf(ref));
+  if (pixels) return pixelsBitmap(pixels);
+  return decodeImage(await readBytes(context, ref));
+}
+
+/**
+ * Encode a canvas and store it; set the result on an `image` output. `name`
+ * is a suggestion (`context.nodeId + '.png'` keeps instances apart); the host
+ * picks the stored path.
+ */
+export async function writeImage(
+  context: ImageNodeContext,
+  canvas: OffscreenCanvas,
+  name: string,
+  options: { type?: ImageType; quality?: number; space?: 'srgb' | 'linear' } = {},
+): Promise<ImageRef> {
+  const type = options.type ?? 'image/png';
+  const assets = assetsOf(context);
+  const signal = context.signal ?? NEVER;
+  // A PNG intermediate goes to the host as pixels when it can take them: a
+  // fast lossless write, or no encode at all until something needs the file.
+  const pixels = type === 'image/png' && assets.keepImage ? canvasPixels(canvas) : null;
+  const stored = pixels && assets.keepImage
+    ? await assets.keepImage(pixels, { suggestedName: name }, { signal })
+    : await assets.write(
+      await encodeImage(canvas, { type, ...(options.quality === undefined ? {} : { quality: options.quality }) }),
+      { mediaType: type, suggestedName: name },
+      { signal },
+    );
+  return {
+    path: stored.path,
+    size: [canvas.width, canvas.height],
+    channels: 'rgba',
+    depth: 'u8',
+    space: options.space ?? 'srgb',
+  };
+}

package/dist/cli/runtime/io.ts

@@ -51,6 +51,25 @@ export interface IoBridge {
   write(path: string, data: Uint8Array): Promise<string>;
   /** Host-owned display URL, valid until the host releases its stored asset. */
   url?(path: string, options?: MediaOptions): string;
+  /**
+   * Store an intermediate image from its pixels and return the stored path,
+   * as `write` would. Optional. The headless host has it: it writes a fast
+   * lossless PNG, and in a run that keeps pixels it holds them in memory and
+   * writes behind (`pixels` below). Without it `saveImage` encodes and writes.
+   */
+  keep?(path: string, pixels: ImagePixels): Promise<string>;
+  /** The pixels behind a path `keep` returned, while the host holds them. */
+  pixels?(path: string): ImagePixels | undefined;
+}
+
+/**
+ * An image's pixels in memory. Mirrors Cascade's core `ImagePixels`: 8-bit
+ * RGBA, sRGB, unpremultiplied, top row first — `ImageData`'s layout.
+ */
+export interface ImagePixels {
+  readonly width: number;
+  readonly height: number;
+  readonly data: Uint8ClampedArray;
 }
 
 const IO_BRIDGE_KEY = '__cascadeIoBridge';
@@ -96,6 +115,8 @@ export async function loadBytes(path: string, options: MediaOptions = { raw: tru
  * to hand it. Pass a width explicitly to work at a smaller size on purpose.
  */
 export async function loadImage(path: string, options: MediaOptions = { raw: true }): Promise<HTMLImageElement> {
+  const held = heldBitmap(path);
+  if (held) return held as unknown as HTMLImageElement;
   const image = new Image();
   const bridge = localIo();
   let temporaryUrl: string | undefined;
@@ -123,8 +144,41 @@ export async function loadImage(path: string, options: MediaOptions = { raw: tru
   }
 }
 
+/**
+ * Pixels the host still holds in memory for `path` (a path `keep` returned),
+ * as something `drawImage` takes, or null to read the file. Bypasses the read
+ * and the decode; the image is the same either way (`ImagePixels` is what a
+ * PNG decodes to).
+ */
+function heldBitmap(path: string): ImageBitmap | null {
+  if (/^(https?:|data:|blob:)/.test(path)) return null;
+  const pixels = localIo()?.pixels?.(path.replace(/^\.?\//, ''));
+  return pixels ? pixelsBitmap(pixels) : null;
+}
+
+/**
+ * `ImagePixels` as a drawable: a canvas holding them, with an `ImageBitmap`'s
+ * `width`, `height` and `close()` (and an image's `naturalWidth`/`naturalHeight`).
+ */
+export function pixelsBitmap(pixels: ImagePixels): ImageBitmap {
+  const Canvas = (globalThis as { OffscreenCanvas?: new (w: number, h: number) => OffscreenCanvas }).OffscreenCanvas;
+  if (!Canvas) throw new Error('cascade/io: this host has no OffscreenCanvas to hold the image');
+  const canvas = new Canvas(pixels.width, pixels.height);
+  const context = canvas.getContext('2d') as OffscreenCanvasRenderingContext2D | null;
+  if (!context) throw new Error('cascade/io: the canvas has no 2D context');
+  const data = new ImageData(pixels.data as Uint8ClampedArray<ArrayBuffer>, pixels.width, pixels.height);
+  context.putImageData(data, 0, 0);
+  const drawable = canvas as unknown as Record<string, unknown>;
+  drawable.close = () => {};
+  drawable.naturalWidth = pixels.width;
+  drawable.naturalHeight = pixels.height;
+  return canvas as unknown as ImageBitmap;
+}
+
 /** Same, as an ImageBitmap — the right input for `texImage2D`. */
 export async function loadBitmap(path: string, options: MediaOptions = { raw: true }): Promise<ImageBitmap> {
+  const held = heldBitmap(path);
+  if (held) return held;
   const bridge = localIo();
   if (bridge?.url) return createImageBitmap(await loadImage(path, options));
   if (bridge) return createImageBitmap(new Blob([await loadBytes(path, options)]));
@@ -177,6 +231,15 @@ export async function saveImage(
   const type = `image/${format}`;
   let blob: Blob;
 
+  // A host that keeps intermediates gets the pixels, not an encode: the
+  // headless host writes a fast PNG (or holds them in memory), where the
+  // canvas's own encoder would spend six times as long.
+  const bridge = localIo();
+  if (format === 'png' && bridge?.keep) {
+    const pixels = canvasPixels(source);
+    if (pixels) return bridge.keep(path.replace(/^\.?\//, ''), pixels);
+  }
+
   if (source instanceof Blob) {
     blob = source;
   } else if (typeof (source as OffscreenCanvas).convertToBlob === 'function') {
@@ -200,6 +263,21 @@ export async function saveImage(
   return saveBytes(blob, path);
 }
 
+/**
+ * A canvas's pixels as `ImagePixels`, or null for anything that is not a 2D
+ * canvas (a Blob, an encoder-only source, a WebGL canvas, whose `getContext('2d')`
+ * is null).
+ */
+export function canvasPixels(source: unknown): ImagePixels | null {
+  const canvas = source as { width?: unknown; height?: unknown; getContext?: (kind: '2d') => CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D | null };
+  if (typeof canvas?.getContext !== 'function' || typeof canvas.width !== 'number' || typeof canvas.height !== 'number') return null;
+  if (!canvas.width || !canvas.height) return null;
+  const context = canvas.getContext('2d');
+  if (!context || typeof context.getImageData !== 'function') return null;
+  const image = context.getImageData(0, 0, canvas.width, canvas.height);
+  return { width: image.width, height: image.height, data: image.data };
+}
+
 /** Write any bytes into the project cache and return the path. */
 export async function saveBytes(data: Blob | ArrayBuffer | Uint8Array, path: string): Promise<string> {
   const clean = path.replace(/^\.?\//, '');

package/dist/cli/runtime/stage.ts

@@ -115,7 +115,10 @@ async function overHttp<T>(stage: string, args: Record<string, unknown>, signal?
   const postStage = async () => fetch('/api/exec', {
     method: 'POST',
     headers: { 'Content-Type': 'application/json', 'X-Cascade-Exec-Capability': await capability() },
-    body: JSON.stringify({ stage, args }),
+    // `cook`: a node's cook is a pure function of its inputs, so the server's
+    // default stage cache may serve it (see StageCachePolicy). A panel posts
+    // through its own api.runStage, without this, and is never cached unasked.
+    body: JSON.stringify({ stage, args, caller: 'cook' }),
     signal,
   });
 

package/dist/cli/share-MHF6TNRK.js

@@ -0,0 +1,166 @@
+import {
+  deployVercel,
+  exportEditor,
+  scanForLeaks,
+  vercelConfig
+} from "./chunk-3RXL5GHB.js";
+import "./chunk-OM6BEME6.js";
+import "./chunk-MP653A5O.js";
+import "./chunk-MI5JLQYA.js";
+import "./chunk-GRIN2DDP.js";
+import "./chunk-X4WKAOQP.js";
+import "./chunk-DEQSEFFH.js";
+import "./chunk-RXDIMXN5.js";
+import "./chunk-QQPA2ZHH.js";
+import "./chunk-KH4MUBKF.js";
+import "./chunk-HSNOBIVT.js";
+import "./chunk-L6B6FUQP.js";
+import "./chunk-HFHWYL55.js";
+import "./chunk-KBGUO27Q.js";
+import "./chunk-ICH7N5PN.js";
+import "./chunk-CO22XHNG.js";
+import "./chunk-LTXWBXOM.js";
+import "./chunk-BZ63XQ3I.js";
+import "./chunk-YH637PDL.js";
+import "./chunk-X566FWBV.js";
+import "./chunk-WD62JIP6.js";
+import "./chunk-5ORUQ6ES.js";
+import "./chunk-2JEU3MGB.js";
+import "./chunk-NJFMDXHR.js";
+import "./chunk-J7VK7MNF.js";
+import "./chunk-FWMSGKEH.js";
+import "./chunk-JVOCK5W4.js";
+
+// src/cli/share.ts
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+var SHARE_USAGE = "cascade share <graph-file | site-directory> [--name <slug>] [--scope <team>] [--protected] [--json]";
+function shareSlug(text) {
+  const slug = text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").replace(/^cascade-/, "").slice(0, 80).replace(/-+$/, "");
+  if (!slug) throw new Error(`"${text}" makes no usable name; pass --name <slug>`);
+  return slug;
+}
+async function share(target, options = {}) {
+  const log = options.log ?? ((line) => console.log(line));
+  const source = path.resolve(target);
+  const stat = await fs.stat(source).catch(() => void 0);
+  if (!stat) throw new Error(`${target} does not exist`);
+  const isGraph = stat.isFile() && source.endsWith(".cascade");
+  if (!isGraph && !stat.isDirectory()) throw new Error(`cascade share takes a .cascade graph or a directory with an index.html (got ${target})`);
+  const scratch = await fs.mkdtemp(path.join(os.tmpdir(), "cascade-share-"));
+  try {
+    const site = path.join(scratch, "site");
+    let name;
+    let projectRoot;
+    if (isGraph) {
+      const { plan } = await exportEditor(source, { out: site, log });
+      name = shareSlug(options.name ?? plan.editor.id);
+      projectRoot = path.dirname(source);
+    } else {
+      if (!(await fs.stat(path.join(source, "index.html")).catch(() => void 0))?.isFile())
+        throw new Error(`${target} has no index.html to share`);
+      await copySite(source, site);
+      if (!await fs.stat(path.join(site, "vercel.json")).catch(() => void 0))
+        await fs.writeFile(path.join(site, "vercel.json"), `${JSON.stringify(vercelConfig(), null, 2)}
+`);
+      projectRoot = await findProjectRoot(source);
+      await scanForLeaks(site, projectRoot ?? source);
+      name = shareSlug(options.name ?? path.basename(source));
+    }
+    const project = `cascade-${name}`;
+    const deploy = options.deploy ?? deployVercel;
+    const deployed = await deploy(site, { project, scope: options.scope, public: options.protected !== true, log });
+    const record = {
+      source: projectRoot ? path.relative(projectRoot, source).split(path.sep).join("/") || "." : path.basename(source),
+      name,
+      project,
+      url: deployed.url,
+      deployment: deployed.deployment,
+      sharedAt: (options.now?.() ?? /* @__PURE__ */ new Date()).toISOString()
+    };
+    const shares = projectRoot ? await recordShare(projectRoot, record) : void 0;
+    return { ...record, ...shares ? { shares } : {} };
+  } finally {
+    await fs.rm(scratch, { recursive: true, force: true });
+  }
+}
+async function recordShare(projectRoot, record) {
+  const file = path.join(projectRoot, "shares.json");
+  const existing = await readShares(projectRoot);
+  const shares = [...existing.shares.filter((item) => item.source !== record.source), record].sort((a, b) => a.source.localeCompare(b.source));
+  const next = { format: "cascade.shares", version: 1, shares };
+  await fs.writeFile(file, `${JSON.stringify(next, null, 2)}
+`);
+  return file;
+}
+async function readShares(projectRoot) {
+  const text = await fs.readFile(path.join(projectRoot, "shares.json"), "utf8").catch(() => void 0);
+  if (!text) return { format: "cascade.shares", version: 1, shares: [] };
+  const parsed = JSON.parse(text);
+  if (parsed.format !== "cascade.shares" || !Array.isArray(parsed.shares)) throw new Error(`${path.join(projectRoot, "shares.json")} is not a cascade.shares file`);
+  return { format: "cascade.shares", version: 1, shares: parsed.shares };
+}
+async function findProjectRoot(start) {
+  for (let directory = start; ; directory = path.dirname(directory)) {
+    if (await fs.stat(path.join(directory, "cascade.json")).catch(() => void 0)) return directory;
+    if (path.dirname(directory) === directory) return void 0;
+  }
+}
+async function copySite(from, to) {
+  await fs.cp(from, to, {
+    recursive: true,
+    dereference: true,
+    filter: (file) => {
+      const relative = path.relative(from, file);
+      return !relative || relative.split(path.sep).every((part) => !part.startsWith(".") && part !== "licensed");
+    }
+  });
+}
+async function runShareCommand(args) {
+  const rest = args.slice(1);
+  const json = rest.includes("--json");
+  let target;
+  const values = {};
+  let isProtected = false;
+  for (let index = 0; index < rest.length; index++) {
+    const arg = rest[index];
+    if (arg === "--json") continue;
+    if (arg === "--protected") {
+      isProtected = true;
+      continue;
+    }
+    if (arg === "--name" || arg === "--scope") {
+      const value = rest[++index];
+      if (!value || value.startsWith("--")) throw new Error(`${arg} needs a value`);
+      values[arg.slice(2)] = value;
+      continue;
+    }
+    if (arg.startsWith("--")) throw new Error(`Unknown option ${arg}
+Usage: ${SHARE_USAGE}`);
+    if (target) throw new Error(`cascade share takes one graph or directory
+Usage: ${SHARE_USAGE}`);
+    target = arg;
+  }
+  if (!target) throw new Error(`Usage: ${SHARE_USAGE}`);
+  const result = await share(target, {
+    ...values.name ? { name: values.name } : {},
+    ...values.scope ? { scope: values.scope } : {},
+    protected: isProtected,
+    log: json ? () => {
+    } : (line) => console.log(line)
+  });
+  if (json) console.log(JSON.stringify(result));
+  else console.log(`
+Shared: ${result.url}${result.shares ? `
+Recorded in ${result.shares}` : ""}`);
+}
+export {
+  SHARE_USAGE,
+  readShares,
+  recordShare,
+  runShareCommand,
+  share,
+  shareSlug
+};
+//# sourceMappingURL=share-MHF6TNRK.js.map

package/dist/cli/stageCache-TY2BFZJR.js

@@ -0,0 +1,15 @@
+import {
+  callStage,
+  cascadeVersion,
+  formatStageTrace,
+  stageCacheKey,
+  stageSources
+} from "./chunk-5ORUQ6ES.js";
+export {
+  callStage,
+  cascadeVersion,
+  formatStageTrace,
+  stageCacheKey,
+  stageSources
+};
+//# sourceMappingURL=stageCache-TY2BFZJR.js.map

package/dist/cli/stageRunner-KY2EJP7X.js

@@ -0,0 +1,10 @@
+import {
+  readStageConfig,
+  runProjectStage
+} from "./chunk-X566FWBV.js";
+import "./chunk-WD62JIP6.js";
+export {
+  readStageConfig,
+  runProjectStage
+};
+//# sourceMappingURL=stageRunner-KY2EJP7X.js.map