@1agh/maude 0.42.0 → 0.43.0

package/apps/studio/footage-store.ts

@@ -0,0 +1,235 @@
+/**
+ * @file       footage-store.ts — Footage-analysis + EDL sidecar persistence
+ *             (feature-footage-analysis-director, Task 2).
+ * @scope      apps/studio/footage-store.ts
+ * @purpose    Read / write the two VERSIONED sidecars behind the footage
+ *             "director" pipeline (DDR-115 taxonomy):
+ *               • `assets/<sha8>.footage.json` — a `FootageAnalysis` (per clip)
+ *               • `<designRoot>/<slug>.edl.json` — an `Edl` (per cut)
+ *             Mirrors `photo-store.ts`'s `createX(ctx)` factory + `Bun.write`/
+ *             `Bun.file` shape. Server-side only — imports the DEPENDENCY-FREE
+ *             `footage/schema.ts`.
+ *
+ * @security   UNLIKE `/_api/photo-edit`, the `/_api/footage` route is
+ *             MAIN-ORIGIN ONLY (privileged — NOT in either canvas allowlist).
+ *             It is written by the `footage-analyst` / `footage-director` agents
+ *             over loopback, never by the untrusted canvas iframe (DDR-054), so
+ *             a `GET → 405` assertion from the canvas origin guards it
+ *             (canvas-origin-gate.test.ts). The write path is still derived from
+ *             caller-supplied params, so the DDR-088 cap stack is preserved:
+ *               1. strict sha8 / slug extraction (hex or kebab, bounded) —
+ *                  rejects `..`, `/`, `%2f`, absolute paths by construction;
+ *               2. explicit containment assert (poisoned-designRoot backstop);
+ *               3. structural `validateFootageAnalysis` / `validateEdl`;
+ *               4. body/file size cap (256 KB — generous for analysis JSON).
+ */
+
+import path from 'node:path';
+
+import type { Context } from './context.ts';
+import {
+  EDL_VERSION,
+  type Edl,
+  FOOTAGE_ANALYSIS_VERSION,
+  type FootageAnalysis,
+  validateEdl,
+  validateFootageAnalysis,
+} from './footage/schema.ts';
+
+/** Max bytes for either sidecar (read + write). Analysis JSON is small; slack. */
+export const FOOTAGE_MAX_BYTES = 256 * 1024;
+
+const SHA_RE = /^[0-9a-f]{8,64}$/;
+// A cut slug: lowercase kebab, bounded. Matches the `slug.sh` normalization
+// shape — no path segment, no dot, so `..`/`/`/absolute can never survive.
+const SLUG_RE = /^[a-z0-9][a-z0-9-]{0,80}$/;
+
+/**
+ * Extract + validate the content-address sha8 from an `asset` param, in any of
+ * the forms a caller might hold (`assets/<sha8>.<ext>`, `/assets/<sha8>.png`,
+ * `<sha8>.png`, bare `<sha8>`). The hex regex is the traversal defense.
+ * (Copied from photo-store.assetSha8 — same contract, kept local so the two
+ * stores stay independent.)
+ */
+export function assetSha8(param: string | null | undefined): string | null {
+  if (typeof param !== 'string') return null;
+  let s = param.trim();
+  if (!s) return null;
+  s = s.replace(/^\/+/, '');
+  s = s.replace(/^assets\//, '');
+  s = s.replace(/\.[A-Za-z0-9]+$/, '');
+  return SHA_RE.test(s) ? s : null;
+}
+
+/** Validate a cut slug (already-normalized kebab), or null. */
+export function edlSlug(param: string | null | undefined): string | null {
+  if (typeof param !== 'string') return null;
+  const s = param.trim();
+  return SLUG_RE.test(s) ? s : null;
+}
+
+export interface FootageStore {
+  analysisPathForSha8(sha8: string): string;
+  edlPathForSlug(slug: string): string;
+  getAnalysis(assetParam: string | null | undefined): Promise<FootageAnalysis | null>;
+  saveAnalysis(
+    assetParam: string | null | undefined,
+    analysis: unknown
+  ): Promise<
+    | { ok: true; path: string; analysis: FootageAnalysis }
+    | { ok: false; status: number; error: string }
+  >;
+  getEdl(slugParam: string | null | undefined): Promise<Edl | null>;
+  saveEdl(
+    slugParam: string | null | undefined,
+    edl: unknown
+  ): Promise<{ ok: true; path: string; edl: Edl } | { ok: false; status: number; error: string }>;
+}
+
+export function createFootageStore(ctx: Context): FootageStore {
+  const designRoot = ctx.paths.designRoot;
+  const assetsDir = path.join(designRoot, 'assets');
+
+  function analysisPathForSha8(sha8: string): string {
+    if (!SHA_RE.test(sha8)) throw new Error(`invalid sha8: ${sha8}`);
+    const abs = path.join(assetsDir, `${sha8}.footage.json`);
+    const rel = path.relative(assetsDir, abs);
+    if (rel !== `${sha8}.footage.json` || rel.startsWith('..') || path.isAbsolute(rel)) {
+      throw new Error(`footage path escaped assets/: ${abs}`);
+    }
+    return abs;
+  }
+
+  function edlPathForSlug(slug: string): string {
+    if (!SLUG_RE.test(slug)) throw new Error(`invalid slug: ${slug}`);
+    const abs = path.join(designRoot, `${slug}.edl.json`);
+    const rel = path.relative(designRoot, abs);
+    if (rel !== `${slug}.edl.json` || rel.startsWith('..') || path.isAbsolute(rel)) {
+      throw new Error(`edl path escaped designRoot: ${abs}`);
+    }
+    return abs;
+  }
+
+  async function readSidecar<T>(
+    abs: string,
+    validate: (v: unknown) => { ok: boolean }
+  ): Promise<T | null> {
+    try {
+      const file = Bun.file(abs);
+      if (!(await file.exists())) return null;
+      if (file.size > FOOTAGE_MAX_BYTES) return null;
+      const parsed = JSON.parse(await file.text());
+      return validate(parsed).ok ? (parsed as T) : null;
+    } catch {
+      return null;
+    }
+  }
+
+  async function getAnalysis(
+    assetParam: string | null | undefined
+  ): Promise<FootageAnalysis | null> {
+    const sha8 = assetSha8(assetParam);
+    if (!sha8) return null;
+    return readSidecar<FootageAnalysis>(analysisPathForSha8(sha8), validateFootageAnalysis);
+  }
+
+  async function saveAnalysis(
+    assetParam: string | null | undefined,
+    analysis: unknown
+  ): Promise<
+    | { ok: true; path: string; analysis: FootageAnalysis }
+    | { ok: false; status: number; error: string }
+  > {
+    const sha8 = assetSha8(assetParam);
+    if (!sha8) return { ok: false, status: 400, error: 'invalid or missing asset (expected sha8)' };
+
+    let serialized: string;
+    try {
+      serialized = JSON.stringify(analysis ?? {});
+    } catch {
+      return { ok: false, status: 400, error: 'body is not serializable JSON' };
+    }
+    if (Buffer.byteLength(serialized, 'utf8') > FOOTAGE_MAX_BYTES) {
+      return {
+        ok: false,
+        status: 413,
+        error: `footage analysis exceeds ${FOOTAGE_MAX_BYTES} bytes`,
+      };
+    }
+
+    const check = validateFootageAnalysis(analysis);
+    if (!check.ok) {
+      return {
+        ok: false,
+        status: 400,
+        error: `invalid FootageAnalysis: ${check.errors.join('; ')}`,
+      };
+    }
+
+    // Stamp version only; the sidecar filename (<sha8>.footage.json) is the
+    // authoritative source key. `asset` is already validated as a well-formed
+    // relative path — keep the client's value verbatim.
+    const toWrite: FootageAnalysis = {
+      ...(analysis as FootageAnalysis),
+      version: FOOTAGE_ANALYSIS_VERSION,
+    };
+
+    let abs: string;
+    try {
+      abs = analysisPathForSha8(sha8);
+    } catch (e) {
+      return { ok: false, status: 400, error: e instanceof Error ? e.message : 'bad path' };
+    }
+    try {
+      await Bun.write(abs, JSON.stringify(toWrite, null, 2));
+    } catch (e) {
+      return { ok: false, status: 500, error: e instanceof Error ? e.message : 'write failed' };
+    }
+    return { ok: true, path: path.posix.join('assets', `${sha8}.footage.json`), analysis: toWrite };
+  }
+
+  async function getEdl(slugParam: string | null | undefined): Promise<Edl | null> {
+    const slug = edlSlug(slugParam);
+    if (!slug) return null;
+    return readSidecar<Edl>(edlPathForSlug(slug), validateEdl);
+  }
+
+  async function saveEdl(
+    slugParam: string | null | undefined,
+    edl: unknown
+  ): Promise<{ ok: true; path: string; edl: Edl } | { ok: false; status: number; error: string }> {
+    const slug = edlSlug(slugParam);
+    if (!slug) return { ok: false, status: 400, error: 'invalid or missing slug (expected kebab)' };
+
+    let serialized: string;
+    try {
+      serialized = JSON.stringify(edl ?? {});
+    } catch {
+      return { ok: false, status: 400, error: 'body is not serializable JSON' };
+    }
+    if (Buffer.byteLength(serialized, 'utf8') > FOOTAGE_MAX_BYTES) {
+      return { ok: false, status: 413, error: `edl exceeds ${FOOTAGE_MAX_BYTES} bytes` };
+    }
+
+    const check = validateEdl(edl);
+    if (!check.ok) {
+      return { ok: false, status: 400, error: `invalid Edl: ${check.errors.join('; ')}` };
+    }
+
+    const toWrite: Edl = { ...(edl as Edl), version: EDL_VERSION };
+    let abs: string;
+    try {
+      abs = edlPathForSlug(slug);
+    } catch (e) {
+      return { ok: false, status: 400, error: e instanceof Error ? e.message : 'bad path' };
+    }
+    try {
+      await Bun.write(abs, JSON.stringify(toWrite, null, 2));
+    } catch (e) {
+      return { ok: false, status: 500, error: e instanceof Error ? e.message : 'write failed' };
+    }
+    return { ok: true, path: `${slug}.edl.json`, edl: toWrite };
+  }
+
+  return { analysisPathForSha8, edlPathForSlug, getAnalysis, saveAnalysis, getEdl, saveEdl };
+}

package/apps/studio/fs-watch.ts

@@ -34,6 +34,16 @@ export function createFsWatch(ctx: Context): FsWatch {
 
   function start() {
     if (watcher) return;
+    // Capture/CI opt-out (MAUDE_NO_WATCH=1): a headless render server has no
+    // interactive editor to hot-reload, so it never needs the watcher. It's a
+    // DEFENSIVE measure for long video exports — an HMR hard-reload broadcast
+    // fired mid-capture (from a concurrent write to designRoot, e.g. a peer edit
+    // or a runtime-state save NOT in the skip-list below) destroys the Playwright
+    // page's execution context. (NB: in the 2026-07-10 cinematic-cut dogfood the
+    // ACTUAL cause of the "Execution context was destroyed" crashes turned out to
+    // be renderer compositing pressure — too many full-frame mix-blend-mode /
+    // filter layers per frame — not the watcher; this guard is belt-and-braces.)
+    if (process.env.MAUDE_NO_WATCH === '1') return;
     try {
       watcher = watch(ctx.paths.designRoot, { recursive: true }, (_event, filename) => {
         if (!filename) return;

package/apps/studio/git/endpoints.ts

@@ -14,6 +14,8 @@
 // echoed, or persisted (it is stripped from the JSON we return on error).
 
 import type { Context } from '../context.ts';
+import { parseGitHubRemote } from '../github/endpoints.ts';
+import { createPullRequest, GitHubApiError } from '../github/service.ts';
 import { getGithubToken } from '../github/token.ts';
 import {
   type GitFileStatus,
@@ -284,19 +286,64 @@ export function createGitEndpoints(ctx: Context): GitEndpoints {
   }
 
   async function fold(body: unknown): Promise<GitEndpointResult> {
-    // Token resolution mirrors push (it publishes the Shared version): body token →
-    // keychain bridge → undefined → authRequired.
+    // Token resolution mirrors push: body token → keychain bridge → undefined. Needed
+    // for the GitHub PR API call; an ssh draft-push authenticates with the user's key.
     const token = readToken(body) ?? (await getGithubToken()) ?? undefined;
     const b = (body ?? {}) as { name?: unknown; remote?: unknown };
     const name = safeGitArg(b.name);
     if (name === undefined) return bad('Invalid draft name.');
     if (b.remote != null && safeRemoteArg(b.remote) === undefined) return bad('Invalid remote.');
     const res = await gitFoldDraft(dir, name, token, { remote: safeRemoteArg(b.remote) });
-    if (res.ok) return { status: 200, json: { ok: true, shared: res.shared } };
-    if (res.authRequired)
-      return { status: 401, json: { ok: false, authRequired: true, error: res.error } };
-    if (res.conflict) return { status: 409, json: { ok: false, conflict: true, error: res.error } };
-    return { status: 502, json: { ok: false, error: res.error ?? 'Could not add the draft.' } };
+    if (!res.ok) {
+      if (res.authRequired)
+        return { status: 401, json: { ok: false, authRequired: true, error: res.error } };
+      if (res.conflict)
+        return { status: 409, json: { ok: false, conflict: true, error: res.error } };
+      return { status: 502, json: { ok: false, error: res.error ?? 'Could not add the draft.' } };
+    }
+    // Local-merge path (no GitHub remote): the draft is already in the Shared version.
+    if (!res.prReady) return { status: 200, json: { ok: true, shared: res.shared } };
+    // PR path: the draft branch is pushed — open a pull request draft→shared. The merge
+    // itself happens on GitHub after review (this is how a protected `main` is added to).
+    const gh = res.remoteUrl ? parseGitHubRemote(res.remoteUrl) : null;
+    if (!gh)
+      return draftPublishedNoPr(
+        res.shared,
+        res.head,
+        'Draft published. Open a pull request on your Git host to add it to the Shared version.'
+      );
+    if (!token)
+      return draftPublishedNoPr(
+        res.shared,
+        res.head,
+        'Draft published. Sign in with GitHub in Maude to open the pull request.'
+      );
+    try {
+      const pr = await createPullRequest(token, gh.owner, gh.repo, {
+        head: res.head as string,
+        base: res.base as string,
+        title: `Add draft “${res.head}” to ${res.base}`,
+        body: 'Opened from Maude — “Add to Shared version”.',
+      });
+      return {
+        status: 200,
+        // Surface the resolved destination repo (F2): the user should SEE which
+        // owner/repo their draft was pushed to / PR'd against, not just "the Shared
+        // version" — a poisoned `origin` would otherwise silently target another repo.
+        json: {
+          ok: true,
+          shared: res.shared,
+          prUrl: pr.html_url,
+          prNumber: pr.number,
+          repo: `${gh.owner}/${gh.repo}`,
+        },
+      };
+    } catch (e) {
+      // The draft IS pushed — a PR-creation failure is a partial success, not a hard
+      // fail. Surface the reason and keep the draft so the user can retry / open it.
+      const msg = e instanceof GitHubApiError ? e.message : 'Could not open the pull request.';
+      return draftPublishedNoPr(res.shared, res.head, msg);
+    }
   }
 
   async function fetchRemote(body: unknown): Promise<GitEndpointResult> {
@@ -335,6 +382,20 @@ function readToken(body: unknown): string | null {
   return typeof t === 'string' && t.length > 0 ? t : null;
 }
 
+/** Fold partial-success: the draft branch was pushed but no PR could be opened (no
+ *  sign-in, a non-GitHub remote, or the PR call failed). `ok:true` because the work IS
+ *  published; the UI shows `error` as a heads-up and keeps the draft for a retry. */
+function draftPublishedNoPr(
+  shared: string | undefined,
+  head: string | undefined,
+  error: string
+): GitEndpointResult {
+  return {
+    status: 200,
+    json: { ok: true, shared, published: head, prUnavailable: true, error },
+  };
+}
+
 /** DDR-112 — expand each selected path to include any DIRTY same-directory,
  *  same-stem sidecar (`<stem>.meta.json`, `<stem>.annotations.svg`, …). The `.`
  *  delimiter prevents `ui/Pricing` from grabbing `ui/Pricing v3.*`. */