@foldspace_npm/harness 0.1.32 → 0.1.33

package/bin/share.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+// foldspace share <inspect|upload> [<video.mp4>] [--poster <file.jpg>] [--targets '<json>']
+//
+//   inspect - sizes and checks the MP4 and its poster here; uploads nothing.
+//             Its video.bytes and poster.bytes go into the MCP tool
+//             create_video_share.
+//   upload  - sends both files to Foldspace's video storage with the one-time
+//             targets create_video_share returned (its upload command), then
+//             the agent calls publish_video_share for the link.
+//
+// The CLI holds no Foldspace sign-in: creating and publishing a share are MCP
+// tools, only the bytes go through here. The targets are never printed.
+// Sharing is always the human's call: run upload only after they said yes.
+
+import path from "node:path";
+
+import { parseArgs, printJson } from "../src/cdp-client.mjs";
+import { recordEvent } from "../src/session-events.mjs";
+import { resolveProjectDir } from "../src/upgrade.mjs";
+import { ShareError, defaultVideo, inspectForShare, parseTargets, posterFor, resumableUpload } from "../src/video/share.mjs";
+
+const { flags, rest } = parseArgs(process.argv.slice(2), ["poster", "targets"]);
+const [action, videoArg] = rest;
+const projectDir = path.resolve(resolveProjectDir());
+
+try {
+  if (action !== "inspect" && action !== "upload") {
+    throw new ShareError("USAGE", "Usage: foldspace share <inspect|upload> [<video.mp4>] [--poster <file.jpg>] [--targets '<json>']");
+  }
+  const videoPath = videoArg ? path.resolve(projectDir, videoArg) : defaultVideo(projectDir);
+  const posterPath = flags.poster ? path.resolve(projectDir, String(flags.poster)) : posterFor(videoPath);
+  const files = inspectForShare({ videoPath, posterPath });
+
+  if (action === "inspect") {
+    printJson({
+      ok: true,
+      video: { path: path.relative(projectDir, files.video.path), bytes: files.video.bytes, durationS: round(files.video.durationS) },
+      poster: { path: path.relative(projectDir, files.poster.path), bytes: files.poster.bytes },
+      next: "Only if the human agreed to share it: call create_video_share with a title, video_bytes and poster_bytes, then run the upload command it returns.",
+    });
+  } else {
+    if (!flags.targets) throw new ShareError("BAD_TARGETS", "--targets is required: run the upload command create_video_share returned.");
+    const targets = parseTargets(flags.targets);
+    await resumableUpload(targets.video, files.video.path, { label: "video" });
+    await resumableUpload(targets.poster, files.poster.path, { label: "poster" });
+    recordEvent(projectDir, "share-upload", { videoBytes: files.video.bytes });
+    printJson({
+      ok: true,
+      status: "uploaded",
+      videoBytes: files.video.bytes,
+      posterBytes: files.poster.bytes,
+      next: "Call publish_video_share with the share_id from create_video_share; it returns the public link.",
+    });
+  }
+} catch (error) {
+  const code = error instanceof ShareError ? error.code : "UNEXPECTED";
+  printJson({ ok: false, code, message: error instanceof Error ? error.message : String(error) });
+  process.exitCode = 1;
+}
+
+function round(seconds) {
+  return Math.round(seconds * 10) / 10;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foldspace_npm/harness",
-  "version": "0.1.32",
+  "version": "0.1.33",
   "description": "Build and verify portable Foldspace action artifacts against a live app.",
   "type": "module",
   "bin": {

package/src/cli-registry.mjs

@@ -490,6 +490,48 @@ export const CLI_COMMANDS = Object.freeze([
       "To change a scene's capabilities or line: edit the scenes file, then `npx foldspace record --from <recordDir>`",
     ],
   }),
+  Object.freeze({
+    name: "share",
+    entry: "share.mjs",
+    group: "share",
+    summary: "Size and check a video for a Foldspace share link, then upload it with the targets create_video_share returned",
+    usage: "foldspace share <inspect|upload> [<video.mp4>] [--poster <file.jpg>] [--targets '<json>']",
+    risk: "remote-upload",
+    environment: "node",
+    environmentVariables: ["FOLDSPACE_PROJECT_DIR"],
+    capabilities: ["video.upload"],
+    positionals: [
+      Object.freeze({
+        name: "action",
+        required: true,
+        description:
+          "inspect: size and check the MP4 and its poster here, uploading nothing | upload: send both to Foldspace's video storage with the targets create_video_share returned",
+      }),
+      Object.freeze({
+        name: "video",
+        required: false,
+        description: "The MP4; default the newest video/*.mp4 that `record` made",
+      }),
+    ],
+    options: [
+      value("--poster", "file.jpg", "The JPEG poster", { default: "the MP4's name with .jpg" }),
+      value("--targets", "json", "upload only: the targets JSON exactly as the upload command from create_video_share has it"),
+    ],
+    prerequisites: [
+      "An H.264 MP4 with its moov box first (what `record` makes) and a JPEG poster",
+      "upload: the human said yes to a public link, and the Foldspace MCP tool create_video_share returned the upload command (its targets last 30 minutes)",
+    ],
+    effects: [
+      "inspect reads the two files and nothing else",
+      "upload sends the MP4 and the poster to Foldspace's video storage, and only there; it reads no Foldspace sign-in",
+      "Never prints the upload targets: each is a one-time credential for one file",
+      "Anyone with the link publish_video_share returns can watch the video, which shows real data from the account",
+    ],
+    next: [
+      "After inspect, with the human's yes: create_video_share with a title, video_bytes and poster_bytes, then run its upload command",
+      "After upload: publish_video_share with the share_id; give the human the link",
+    ],
+  }),
   Object.freeze({
     name: "deploy",
     // Foldspace-internal: it uploads to Foldspace's own storage, which no
@@ -542,12 +584,14 @@ export const CAPABILITY_CATALOGUE = Object.freeze([
   ["page.evaluate", "Inspect bounded SDK and registration state"],
   ["page.mutate", "Prepare and restore a matching development page"],
   ["artifact.publish", "Write the built artifact to remote storage"],
+  ["video.upload", "Upload a video and its poster for a Foldspace share link, with targets the Foldspace MCP issued"],
 ]);
 
 export const RISK_CATALOGUE = Object.freeze([
   ["local-write", "Writes only inside the consuming project"],
   ["browser-session", "Launches or temporarily mutates a local browser session"],
   ["remote-publish", "Writes the action artifact to remote storage"],
+  ["remote-upload", "Uploads files the human chose to share to Foldspace's video storage"],
 ]);
 
 export const ENVIRONMENT_CATALOGUE = Object.freeze([

package/src/video/share.mjs

@@ -0,0 +1,284 @@
+// foldspace share - the bytes half of sharing a video by a Foldspace link.
+//
+// The CLI holds no Foldspace sign-in (the editor's MCP does), so sharing is
+// three steps the agent takes, only after the human said yes:
+//   1. `npx foldspace share inspect` - sizes and checks the MP4 and poster here
+//   2. MCP `create_video_share` - returns one-time signed upload targets
+//      (`upload_command`), then `npx foldspace share upload` sends the files
+//      straight to Foldspace's video storage with them
+//   3. MCP `publish_video_share` - the server checks the files and returns
+//      the public link
+// Nothing here talks to Foldspace except the upload targets the MCP issued,
+// and nothing prints them: a target is a bearer credential for one object.
+
+import fs from "node:fs";
+import path from "node:path";
+
+/** GCS requires every chunk but the last to be a multiple of 256 KiB. */
+export const CHUNK_UNIT_BYTES = 256 * 1024;
+export const DEFAULT_CHUNK_BYTES = 32 * CHUNK_UNIT_BYTES; // 8 MiB
+const MAX_ATTEMPTS_PER_CHUNK = 4;
+
+/**
+ * The only hosts an upload may go to: Google Cloud Storage, where Foldspace's video bucket is, and
+ * this machine for the local demo. A target anywhere else is refused, so a tampered or injected
+ * upload command cannot send the human's recording somewhere else.
+ */
+export function isAllowedUploadUrl(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    return false;
+  }
+  if (url.protocol === "https:" && url.hostname === "storage.googleapis.com") return true;
+  return url.protocol === "http:" && (url.hostname === "localhost" || url.hostname === "127.0.0.1");
+}
+
+/** Mirrors the server's caps (share-service SHARE_MAX_*): checked here so a too-big file fails before any upload. */
+export const MAX_VIDEO_BYTES = 500 * 1024 * 1024;
+export const MAX_POSTER_BYTES = 5 * 1024 * 1024;
+
+export class ShareError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}
+
+/** The newest video/*.mp4 that `record` made, with its poster beside it. */
+export function defaultVideo(projectDir) {
+  const dir = path.join(projectDir, "video");
+  let names = [];
+  try {
+    names = fs.readdirSync(dir).filter((name) => name.endsWith(".mp4"));
+  } catch {
+    // no video folder
+  }
+  if (!names.length) {
+    throw new ShareError("NO_VIDEO", "No video/*.mp4 in this project. Make one with `npx foldspace record`, or pass the MP4's path.");
+  }
+  const newest = names
+    .map((name) => ({ name, mtime: fs.statSync(path.join(dir, name)).mtimeMs }))
+    .sort((a, b) => b.mtime - a.mtime)[0].name;
+  return path.join(dir, newest);
+}
+
+export function posterFor(videoPath) {
+  return videoPath.replace(/\.mp4$/i, ".jpg");
+}
+
+/**
+ * Sizes the two files and runs the same structural checks the server's publish
+ * check runs (MP4 with ftyp, moov before mdat; JPEG poster), so the agent hears
+ * "re-encode with faststart" before uploading 500 MB rather than after.
+ */
+export function inspectForShare({ videoPath, posterPath }) {
+  const video = statFile(videoPath, "NO_VIDEO", "video");
+  const poster = statFile(posterPath, "NO_POSTER", "poster");
+  if (video.bytes > MAX_VIDEO_BYTES) throw new ShareError("TOO_LARGE", `The video is ${mb(video.bytes)} MB; the limit is ${mb(MAX_VIDEO_BYTES)} MB.`);
+  if (poster.bytes > MAX_POSTER_BYTES) throw new ShareError("TOO_LARGE", `The poster is ${mb(poster.bytes)} MB; the limit is ${mb(MAX_POSTER_BYTES)} MB.`);
+
+  const head = readSlice(posterPath, 0, 3);
+  if (!(head[0] === 0xff && head[1] === 0xd8 && head[2] === 0xff)) {
+    throw new ShareError("NOT_JPEG", "The poster must be a JPEG image.");
+  }
+  const durationS = readMp4Duration(videoPath, video.bytes);
+  return { video: { ...video, durationS }, poster };
+}
+
+/** Walks top-level boxes: ftyp first, moov before mdat; returns mvhd duration in seconds. */
+function readMp4Duration(file, size) {
+  const first = boxAt(file, 0, size);
+  if (!first || first.type !== "ftyp") throw new ShareError("NOT_MP4", "The video is not an MP4 file.");
+  let offset = first.size;
+  for (let i = 0; i < 64 && offset < size; i++) {
+    const box = boxAt(file, offset, size);
+    if (!box) throw new ShareError("NOT_MP4", "The MP4 is truncated or damaged.");
+    if (box.type === "mdat") {
+      throw new ShareError("NOT_FAST_START", "The MP4 is not fast-start (its moov box comes after the video data). Re-encode it with `-movflags +faststart`.");
+    }
+    if (box.type === "moov") {
+      const body = readSlice(file, offset + box.header, Math.min(box.size - box.header, 16 * 1024 * 1024));
+      return mvhdDurationSeconds(body);
+    }
+    offset += box.size;
+  }
+  throw new ShareError("NOT_MP4", "The MP4 has no moov box.");
+}
+
+function mvhdDurationSeconds(moov) {
+  let offset = 0;
+  while (offset + 8 <= moov.length) {
+    const size = moov.readUInt32BE(offset);
+    const type = moov.toString("latin1", offset + 4, offset + 8);
+    if (size < 8) break;
+    if (type === "mvhd") {
+      const body = moov.subarray(offset + 8, offset + size);
+      if (body[0] === 1) return Number(body.readBigUInt64BE(24)) / body.readUInt32BE(20);
+      return body.readUInt32BE(16) / body.readUInt32BE(12);
+    }
+    offset += size;
+  }
+  throw new ShareError("NOT_MP4", "The MP4 has no movie header.");
+}
+
+function boxAt(file, offset, fileSize) {
+  if (offset + 8 > fileSize) return null;
+  const head = readSlice(file, offset, 16);
+  let size = head.readUInt32BE(0);
+  let header = 8;
+  if (size === 1) {
+    size = Number(head.readBigUInt64BE(8));
+    header = 16;
+  } else if (size === 0) {
+    size = fileSize - offset;
+  }
+  if (size < header || offset + size > fileSize) return null;
+  return { type: head.toString("latin1", 4, 8), size, header };
+}
+
+/**
+ * Parses the `--targets` JSON that `create_video_share` put in the upload
+ * command: { video: {url, method, headers}, poster: {...} }.
+ */
+export function parseTargets(text) {
+  let parsed;
+  try {
+    parsed = JSON.parse(String(text || ""));
+  } catch {
+    throw new ShareError("BAD_TARGETS", "--targets is not valid JSON. Copy the upload command from create_video_share exactly.");
+  }
+  for (const name of ["video", "poster"]) {
+    const target = parsed?.[name];
+    if (!target || typeof target.url !== "string" || target.method !== "POST" || typeof target.headers !== "object") {
+      throw new ShareError("BAD_TARGETS", `--targets has no valid ${name} target. Copy the upload command from create_video_share exactly.`);
+    }
+    if (!isAllowedUploadUrl(target.url)) {
+      throw new ShareError("BAD_TARGETS", `The ${name} upload target is not Foldspace's video storage (https://storage.googleapis.com). Use only the command create_video_share returned.`);
+    }
+  }
+  return parsed;
+}
+
+/**
+ * GCS resumable upload: POST the signed URL to start a session, then PUT the
+ * file in chunks with Content-Range. On a dropped connection it asks the
+ * session how much arrived (`bytes * /total`) and resumes from there.
+ * Errors name the HTTP status and GCS's error code, never the URL.
+ */
+export async function resumableUpload(target, filePath, { fetchImpl = fetch, chunkBytes = DEFAULT_CHUNK_BYTES, label = "file" } = {}) {
+  if (chunkBytes % CHUNK_UNIT_BYTES !== 0) throw new Error("chunkBytes must be a multiple of 256 KiB");
+  const total = fs.statSync(filePath).size;
+  if (total === 0) throw new ShareError("UPLOAD_FAILED", `The ${label} is empty.`);
+  // redirect: "manual" everywhere, never "error": GCS answers every unfinished chunk with 308 "Resume
+  // Incomplete", which fetch would turn into a network error. A 3xx that names a Location is a real
+  // redirect, and is refused (rejectRedirect): storage never sends an upload somewhere else.
+  const start = rejectRedirect(await fetchImpl(target.url, { method: "POST", headers: target.headers, body: "", redirect: "manual" }), label);
+  if (start.status !== 200 && start.status !== 201) {
+    throw new ShareError("UPLOAD_REFUSED", `Starting the ${label} upload failed: ${await describe(start)}. The upload targets last 30 minutes; if they expired, call create_video_share again.`);
+  }
+  const session = start.headers.get("location");
+  if (!session || !isAllowedUploadUrl(session)) throw new ShareError("UPLOAD_REFUSED", `Starting the ${label} upload returned no usable session.`);
+
+  let offset = 0;
+  let attempts = 0;
+  const handle = fs.openSync(filePath, "r");
+  const buffer = Buffer.alloc(Math.min(chunkBytes, total)); // one buffer, reused for every chunk
+  try {
+    while (offset < total) {
+      const end = Math.min(offset + chunkBytes, total) - 1;
+      const length = end - offset + 1;
+      fs.readSync(handle, buffer, 0, length, offset);
+      const chunk = buffer.subarray(0, length);
+      let response;
+      try {
+        response = await fetchImpl(session, {
+          method: "PUT",
+          headers: { "content-range": `bytes ${offset}-${end}/${total}` },
+          body: chunk,
+          redirect: "manual",
+        });
+      } catch (error) {
+        if (++attempts >= MAX_ATTEMPTS_PER_CHUNK) throw new ShareError("UPLOAD_FAILED", `The ${label} upload kept failing: ${error.message}`);
+        offset = await committedBytes(fetchImpl, session, total);
+        continue;
+      }
+      rejectRedirect(response, label);
+      if (response.status === 200 || response.status === 201) return { bytes: total };
+      if (response.status === 308) {
+        // Progress resets the retry count; a 308 whose committed range did not move counts as a failed
+        // attempt, so a session that never advances ends instead of looping forever.
+        const next = rangeEnd(response.headers.get("range"));
+        if (next > offset) attempts = 0;
+        else if (++attempts >= MAX_ATTEMPTS_PER_CHUNK) throw new ShareError("UPLOAD_FAILED", `The ${label} upload stopped moving: storage kept the same ${next} bytes.`);
+        offset = next;
+        continue;
+      }
+      if (response.status >= 500 && ++attempts < MAX_ATTEMPTS_PER_CHUNK) {
+        offset = await committedBytes(fetchImpl, session, total);
+        continue;
+      }
+      throw new ShareError("UPLOAD_FAILED", `The ${label} upload failed: ${await describe(response)}.`);
+    }
+  } finally {
+    fs.closeSync(handle);
+  }
+  throw new ShareError("UPLOAD_FAILED", `The ${label} upload did not finish.`);
+}
+
+async function committedBytes(fetchImpl, session, total) {
+  const status = rejectRedirect(await fetchImpl(session, { method: "PUT", headers: { "content-range": `bytes */${total}` }, body: "", redirect: "manual" }), "file");
+  if (status.status === 200 || status.status === 201) return total;
+  return rangeEnd(status.headers.get("range"));
+}
+
+/** A 3xx with a Location is a redirect away from storage: refused. (GCS's 308 Resume Incomplete has none.) */
+function rejectRedirect(response, label) {
+  if (response.status >= 300 && response.status < 400 && response.headers.get("location")) {
+    throw new ShareError("UPLOAD_REFUSED", `The ${label} upload was redirected; uploads go only to Foldspace's video storage.`);
+  }
+  return response;
+}
+
+/** "bytes=0-1048575" → 1048576 (the next byte to send); no header → 0. */
+function rangeEnd(header) {
+  const match = /bytes=0-(\d+)/.exec(header || "");
+  return match ? Number(match[1]) + 1 : 0;
+}
+
+async function describe(response) {
+  let code = "";
+  try {
+    const text = await response.text();
+    code = /<Code>([^<]{1,64})<\/Code>/.exec(text)?.[1] ?? "";
+  } catch {
+    // no body
+  }
+  return `HTTP ${response.status}${code ? ` ${code}` : ""}`;
+}
+
+function statFile(file, code, label) {
+  try {
+    const stat = fs.statSync(file);
+    if (!stat.isFile()) throw new Error("not a file");
+    return { path: file, bytes: stat.size };
+  } catch {
+    throw new ShareError(code, `No ${label} at ${file}.`);
+  }
+}
+
+function readSlice(file, offset, length) {
+  const handle = fs.openSync(file, "r");
+  try {
+    const buffer = Buffer.alloc(length);
+    const read = fs.readSync(handle, buffer, 0, length, offset);
+    return buffer.subarray(0, read);
+  } finally {
+    fs.closeSync(handle);
+  }
+}
+
+function mb(bytes) {
+  return Math.round(bytes / (1024 * 1024));
+}

package/templates/agent-starter/skills/share-a-video/SKILL.md

@@ -22,7 +22,8 @@ nothing to set.
 
 - **Real data from their account.** The signed-in app as it is: their records,
   their numbers, their name wherever the app or the panel shows it. Nothing is
-  blurred, nothing is made up, nothing is uploaded.
+  blurred, nothing is made up, and nothing is uploaded unless the human asks
+  for a share link (step 7).
 - **Sharing it is their call** - whether, and where. Like a screen recording
   they made themselves.
 - Never create demo data for the video, never blur or crop parts of it, and
@@ -199,8 +200,43 @@ another question for that use case, prove it, record again. If there is a
   goes is their call.
 
 **Sharing:** upload the MP4 itself to LinkedIn or X - that is also how it
-plays inline in the feed. A Foldspace share link (a page anyone can open to
-watch it) is coming; until then, the file.
+plays inline in the feed. Or a Foldspace share link (step 7): a page anyone
+with the link can open to watch it, with a "Build yours" button, and an email
+to them when it is watched.
+
+## 7. A Foldspace share link - only when they ask for one
+
+Offer it as one option next to "send me the file", never as the default.
+The link is public: anyone who has it can watch, with no sign-in. So before
+anything leaves this computer, ask once, as a choice: *"A share link is public
+to anyone who has it, and the video shows [what is on screen]. Create one?"*
+Only on a yes:
+
+1. `npx foldspace share inspect` (the newest `video/*.mp4` and its poster, or
+   pass the path). It uploads nothing. If it says the MP4 is not fast-start,
+   that file did not come from `record`: say so and stop.
+2. The Foldspace tool `create_video_share` with a title in their words (the
+   product and what the agent does, up to 200 characters), and `video_bytes`
+   and `poster_bytes` from step 1.
+3. Run the upload command it returns, exactly - it carries one-time upload
+   targets for 30 minutes. Pass `upload` the same video path and `--poster`
+   you gave `inspect`, if any, so it uploads the files `inspect` sized. Never
+   paste the targets into chat, a file or a commit. In Codex (or any editor
+   that runs commands in a sandbox), this command needs the network: run it
+   outside the sandbox through the editor's own approval, with one plain line
+   on why.
+4. When it prints `"status": "uploaded"`, the tool `publish_video_share` with
+   the `share_id`. It returns the link: give it to them as it is.
+5. Tell them in one line that they get an email at the first view and a daily
+   summary on days it is watched, and that you can show the numbers
+   (`get_video_share_stats`) or delete the link (`delete_video_share`) whenever
+   they ask.
+
+The tools refuse with a reason you pass on as it is: an EU account (share
+links are not offered there yet - send the file instead), a cap (shares per
+day, or a trial's monthly limit), or a sign-in by API key rather than as a
+person. The CLI never signs in to Foldspace and never reaches the Foldspace
+tools itself: steps 2 and 4 are tool calls you make.
 
 The video holds real data, so it is never saved with the code: `record` writes
 `video/.gitignore` (`*.mp4`, `*.jpg`) in every project. `video/scenes.json`