@deskwork/studio 0.9.5

package/dist/routes/api.js

@@ -0,0 +1,175 @@
+/**
+ * API route handlers for the studio. Each route is a thin wrapper over a
+ * `lib/review/handlers.ts` function — it parses the HTTP request, calls
+ * the handler with `(projectRoot, config, body)`, and serializes the
+ * `{status, body}` result as JSON.
+ *
+ * Mirrors the audiocontrol Astro routes byte-for-byte so the existing
+ * client code (editorial-review-client.ts, editorial-studio-client.ts)
+ * keeps working without changes.
+ */
+import { Hono } from 'hono';
+import { handleAnnotate, handleListAnnotations, handleDecision, handleGetWorkflow, handleCreateVersion, handleStartLongform, } from '@deskwork/core/review/handlers';
+import { handleStartShortform } from '@deskwork/core/review/start-handlers';
+import { renderMarkdownToHtml } from '@deskwork/core/review/render';
+/**
+ * Narrow a `HandlerResult.body` (typed as `unknown`) to extract the
+ * workflow id. Returns null when the shape doesn't match — phase 21c's
+ * start-shortform route uses this to decide whether to augment the
+ * response with a reviewUrl. Avoids `as`-casts on the body.
+ */
+function extractWorkflowId(body) {
+    if (typeof body !== 'object' || body === null)
+        return null;
+    const workflow = Reflect.get(body, 'workflow');
+    if (typeof workflow !== 'object' || workflow === null)
+        return null;
+    const id = Reflect.get(workflow, 'id');
+    return typeof id === 'string' && id.length > 0 ? id : null;
+}
+/**
+ * Build a fresh response object that preserves every field from the
+ * original handler body and adds `reviewUrl`. Iterates own keys via
+ * `Object.entries` so the result is a plain `Record<string, unknown>`
+ * rather than carrying the input's unknown-typed shape.
+ */
+function withReviewUrl(body, workflowId) {
+    const out = {};
+    if (typeof body === 'object' && body !== null) {
+        for (const [k, v] of Object.entries(body)) {
+            out[k] = v;
+        }
+    }
+    out.reviewUrl = `/dev/editorial-review/${workflowId}`;
+    return out;
+}
+export function createApiRouter(ctx) {
+    const app = new Hono();
+    // POST /api/dev/editorial-review/annotate
+    app.post('/annotate', async (c) => {
+        let body;
+        try {
+            body = await c.req.json();
+        }
+        catch {
+            return c.json({ error: 'invalid JSON body' }, 400);
+        }
+        const r = handleAnnotate(ctx.projectRoot, ctx.config, body);
+        return c.json(r.body, r.status);
+    });
+    // GET /api/dev/editorial-review/annotations?workflowId=...&version=...
+    app.get('/annotations', (c) => {
+        const r = handleListAnnotations(ctx.projectRoot, ctx.config, {
+            workflowId: c.req.query('workflowId') ?? null,
+            version: c.req.query('version') ?? null,
+        });
+        return c.json(r.body, r.status);
+    });
+    // POST /api/dev/editorial-review/decision
+    app.post('/decision', async (c) => {
+        let body;
+        try {
+            body = await c.req.json();
+        }
+        catch {
+            return c.json({ error: 'invalid JSON body' }, 400);
+        }
+        const r = handleDecision(ctx.projectRoot, ctx.config, body);
+        return c.json(r.body, r.status);
+    });
+    // GET /api/dev/editorial-review/workflow?id=... or ?site=...&slug=...&...
+    app.get('/workflow', (c) => {
+        const r = handleGetWorkflow(ctx.projectRoot, ctx.config, {
+            id: c.req.query('id') ?? null,
+            site: c.req.query('site') ?? null,
+            slug: c.req.query('slug') ?? null,
+            contentKind: c.req.query('contentKind') ?? null,
+            platform: c.req.query('platform') ?? null,
+            channel: c.req.query('channel') ?? null,
+        });
+        return c.json(r.body, r.status);
+    });
+    // POST /api/dev/editorial-review/version
+    app.post('/version', async (c) => {
+        let body;
+        try {
+            body = await c.req.json();
+        }
+        catch {
+            return c.json({ error: 'invalid JSON body' }, 400);
+        }
+        const r = handleCreateVersion(ctx.projectRoot, ctx.config, body);
+        return c.json(r.body, r.status);
+    });
+    // POST /api/dev/editorial-review/start-longform
+    app.post('/start-longform', async (c) => {
+        let body;
+        try {
+            body = await c.req.json();
+        }
+        catch {
+            return c.json({ error: 'invalid JSON body' }, 400);
+        }
+        const r = handleStartLongform(ctx.projectRoot, ctx.config, body);
+        return c.json(r.body, r.status);
+    });
+    // POST /api/dev/editorial-review/start-shortform
+    //
+    // Phase 21c: Mirrors start-longform but for shortform workflows.
+    // Augments the handler's success body with a `reviewUrl` so the
+    // dashboard's matrix-cell start button can fetch + redirect in one
+    // round-trip. The handler scaffolds the disk file (frontmatter +
+    // initial body) when missing and is idempotent on
+    // (entryId|site+slug, contentKind, platform, channel).
+    app.post('/start-shortform', async (c) => {
+        let body;
+        try {
+            body = await c.req.json();
+        }
+        catch {
+            return c.json({ error: 'invalid JSON body' }, 400);
+        }
+        const r = handleStartShortform(ctx.projectRoot, ctx.config, body);
+        const workflowId = extractWorkflowId(r.body);
+        if (r.status === 200 && workflowId !== null) {
+            const augmented = withReviewUrl(r.body, workflowId);
+            return c.json(augmented, 200);
+        }
+        return c.json(r.body, r.status);
+    });
+    // POST /api/dev/editorial-review/render
+    //
+    // Replaces the upstream client-side dynamic import of
+    // `scripts/lib/editorial-review/render.js`. The preview pane in
+    // `editorial-review-client.ts` POSTs the markdown source here and
+    // gets HTML back. Centralising the render keeps the unified pipeline
+    // (remark-parse + remark-strip-first-h1 + remark-image-figure +
+    // remark-rehype + rehype-stringify) on the server, where it already
+    // runs for the initial review-page render — one source of truth.
+    app.post('/render', async (c) => {
+        let body;
+        try {
+            body = await c.req.json();
+        }
+        catch {
+            return c.json({ error: 'invalid JSON body' }, 400);
+        }
+        if (!body || typeof body !== 'object') {
+            return c.json({ error: 'expected JSON object body' }, 400);
+        }
+        const markdown = body.markdown;
+        if (typeof markdown !== 'string') {
+            return c.json({ error: 'markdown (string) is required' }, 400);
+        }
+        try {
+            const html = await renderMarkdownToHtml(markdown);
+            return c.json({ html });
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            return c.json({ error: `render failed: ${reason}` }, 500);
+        }
+    });
+    return app;
+}
+//# sourceMappingURL=api.js.map

package/dist/routes/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../../src/routes/api.ts"],"names":[],"mappings":"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"}

package/dist/routes/scrapbook-file.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Read-only binary endpoint for scrapbook files.
+ *
+ * `GET /api/dev/scrapbook-file?site=<slug>&path=<scrapbook path>&name=<filename>[&secret=1]`
+ *
+ * Returns the raw bytes of a single scrapbook file with a sensible
+ * Content-Type header. Read-only — no write/rename/delete here. The
+ * shared scrapbook-item renderer uses this for image thumbnails,
+ * PDF iframes, and download links on the review-drawer + content-view
+ * surfaces.
+ *
+ * Validation runs through `@deskwork/core/scrapbook`'s own
+ * `assertSlug` / `assertFilename` (via `readScrapbookFile`), so path
+ * traversal attempts are caught at the core boundary, not here.
+ */
+import type { Context } from 'hono';
+import type { StudioContext } from './api.ts';
+export declare function serveScrapbookFile(c: Context, ctx: StudioContext): Promise<Response>;
+//# sourceMappingURL=scrapbook-file.d.ts.map

package/dist/routes/scrapbook-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scrapbook-file.d.ts","sourceRoot":"","sources":["../../src/routes/scrapbook-file.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAGpC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAwB9C,wBAAsB,kBAAkB,CACtC,CAAC,EAAE,OAAO,EACV,GAAG,EAAE,aAAa,GACjB,OAAO,CAAC,QAAQ,CAAC,CA2CnB"}

package/dist/routes/scrapbook-file.js

@@ -0,0 +1,77 @@
+/**
+ * Read-only binary endpoint for scrapbook files.
+ *
+ * `GET /api/dev/scrapbook-file?site=<slug>&path=<scrapbook path>&name=<filename>[&secret=1]`
+ *
+ * Returns the raw bytes of a single scrapbook file with a sensible
+ * Content-Type header. Read-only — no write/rename/delete here. The
+ * shared scrapbook-item renderer uses this for image thumbnails,
+ * PDF iframes, and download links on the review-drawer + content-view
+ * surfaces.
+ *
+ * Validation runs through `@deskwork/core/scrapbook`'s own
+ * `assertSlug` / `assertFilename` (via `readScrapbookFile`), so path
+ * traversal attempts are caught at the core boundary, not here.
+ */
+import { extname } from 'node:path';
+import { readScrapbookFile } from '@deskwork/core/scrapbook';
+const MIME_TYPES = {
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.svg': 'image/svg+xml',
+    '.pdf': 'application/pdf',
+    '.json': 'application/json; charset=utf-8',
+    '.jsonl': 'application/jsonl; charset=utf-8',
+    '.txt': 'text/plain; charset=utf-8',
+    '.log': 'text/plain; charset=utf-8',
+    '.md': 'text/markdown; charset=utf-8',
+    '.markdown': 'text/markdown; charset=utf-8',
+    '.mdx': 'text/markdown; charset=utf-8',
+};
+function contentTypeFor(filename) {
+    const ext = extname(filename).toLowerCase();
+    return MIME_TYPES[ext] ?? 'application/octet-stream';
+}
+export async function serveScrapbookFile(c, ctx) {
+    const site = c.req.query('site');
+    const path = c.req.query('path');
+    const name = c.req.query('name');
+    const secret = c.req.query('secret') === '1';
+    if (!site || !path || !name) {
+        return c.json({ error: 'site, path, and name query params are required' }, 400);
+    }
+    if (!(site in ctx.config.sites)) {
+        return c.json({ error: `unknown site: ${site}` }, 404);
+    }
+    let result;
+    try {
+        result = readScrapbookFile(ctx.projectRoot, ctx.config, site, path, name, {
+            secret,
+        });
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        // The core helper throws on invalid slug / invalid filename / file
+        // not found / path traversal. Treat all of them as 404 from the
+        // operator's perspective — the read-only endpoint shouldn't
+        // distinguish "doesn't exist" from "off-limits".
+        return c.json({ error: reason }, 404);
+    }
+    // Hono's c.body() expects a BodyInit. Node Buffers are typed as
+    // `Uint8Array<ArrayBufferLike>` but Hono's overload demands
+    // `Uint8Array<ArrayBuffer>` — copy into a fresh buffer to satisfy
+    // the type without bypassing typing. Scrapbook files are small
+    // (the operator put them there by hand) so the copy cost is fine.
+    const src = result.content;
+    const copy = new Uint8Array(src.byteLength);
+    copy.set(src);
+    return c.body(copy, 200, {
+        'Content-Type': contentTypeFor(result.name),
+        'Content-Length': String(result.size),
+        'Cache-Control': 'private, max-age=10',
+    });
+}
+//# sourceMappingURL=scrapbook-file.js.map

package/dist/routes/scrapbook-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scrapbook-file.js","sourceRoot":"","sources":["../../src/routes/scrapbook-file.ts"],"names":[],"mappings":"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"}

package/dist/routes/scrapbook-mutations.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Mutation endpoints for the standalone scrapbook viewer
+ * (`/dev/scrapbook/<site>/<path>`). Five POST endpoints — save, rename,
+ * delete, create, upload — that the client at
+ * `plugins/deskwork-studio/public/src/scrapbook-client.ts` calls when
+ * the operator edits a slip, renames it, deletes it, drafts a new note,
+ * or drops a file onto the page.
+ *
+ * Phase 13 ported the client chrome but never landed these routes;
+ * Phase 16d retrofitted only the read path. v0.4.1 closes the gap
+ * (issue #21).
+ *
+ * Design notes:
+ *   - Path resolution + traversal protection runs through
+ *     `@deskwork/core/scrapbook` helpers (`scrapbookFilePath` etc.).
+ *     Those throw on `..` sequences, absolute paths, and any filename
+ *     that escapes the scrapbook dir; we surface those as 400.
+ *   - The client speaks `{ site, slug, filename, body }` for save/create,
+ *     `{ site, slug, oldName, newName }` for rename, `{ site, slug,
+ *     filename }` for delete, multipart `{ site, slug, file }` for
+ *     upload. Endpoints accept those exact field names.
+ *   - We never log file contents on save / upload (privacy). Logging
+ *     filename + slug is fine but kept silent here — the studio's
+ *     console is the operator's, not a server log.
+ *   - Errors from the core helpers carry text like `"file not found:
+ *     <name>"`, `"file already exists: <name>"`, or `"resolved path
+ *     escapes scrapbook dir"`. We map those onto the right HTTP code
+ *     so the client UI can flash a useful message.
+ */
+import { Hono } from 'hono';
+import type { StudioContext } from './api.ts';
+export declare function createScrapbookMutationsRouter(ctx: StudioContext): Hono;
+//# sourceMappingURL=scrapbook-mutations.d.ts.map

package/dist/routes/scrapbook-mutations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scrapbook-mutations.d.ts","sourceRoot":"","sources":["../../src/routes/scrapbook-mutations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAc5B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AA0F9C,wBAAgB,8BAA8B,CAAC,GAAG,EAAE,aAAa,GAAG,IAAI,CAqSvE"}

package/dist/routes/scrapbook-mutations.js

@@ -0,0 +1,310 @@
+/**
+ * Mutation endpoints for the standalone scrapbook viewer
+ * (`/dev/scrapbook/<site>/<path>`). Five POST endpoints — save, rename,
+ * delete, create, upload — that the client at
+ * `plugins/deskwork-studio/public/src/scrapbook-client.ts` calls when
+ * the operator edits a slip, renames it, deletes it, drafts a new note,
+ * or drops a file onto the page.
+ *
+ * Phase 13 ported the client chrome but never landed these routes;
+ * Phase 16d retrofitted only the read path. v0.4.1 closes the gap
+ * (issue #21).
+ *
+ * Design notes:
+ *   - Path resolution + traversal protection runs through
+ *     `@deskwork/core/scrapbook` helpers (`scrapbookFilePath` etc.).
+ *     Those throw on `..` sequences, absolute paths, and any filename
+ *     that escapes the scrapbook dir; we surface those as 400.
+ *   - The client speaks `{ site, slug, filename, body }` for save/create,
+ *     `{ site, slug, oldName, newName }` for rename, `{ site, slug,
+ *     filename }` for delete, multipart `{ site, slug, file }` for
+ *     upload. Endpoints accept those exact field names.
+ *   - We never log file contents on save / upload (privacy). Logging
+ *     filename + slug is fine but kept silent here — the studio's
+ *     console is the operator's, not a server log.
+ *   - Errors from the core helpers carry text like `"file not found:
+ *     <name>"`, `"file already exists: <name>"`, or `"resolved path
+ *     escapes scrapbook dir"`. We map those onto the right HTTP code
+ *     so the client UI can flash a useful message.
+ */
+import { Hono } from 'hono';
+import { classify, createScrapbookMarkdown, deleteScrapbookFile, renameScrapbookFile, saveScrapbookFile, writeScrapbookUpload, } from '@deskwork/core/scrapbook';
+import { existsSync, mkdirSync, renameSync, statSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { scrapbookFilePath } from '@deskwork/core/scrapbook';
+/**
+ * Validate the common `{ site, slug, secret? }` envelope. Returns a
+ * typed object or a 400/404 Response that the caller propagates
+ * directly. The site existence check is here so every mutation 404s
+ * on unknown sites the same way the read endpoint does.
+ */
+function checkEnvelope(ctx, body) {
+    const site = body.site;
+    const slug = body.slug;
+    if (typeof site !== 'string' || site.length === 0) {
+        return { error: 'site is required', status: 400 };
+    }
+    if (typeof slug !== 'string' || slug.length === 0) {
+        return { error: 'slug is required', status: 400 };
+    }
+    if (!(site in ctx.config.sites)) {
+        return { error: `unknown site: ${site}`, status: 404 };
+    }
+    const secretRaw = body.secret;
+    if (secretRaw !== undefined && typeof secretRaw !== 'boolean') {
+        return { error: 'secret must be a boolean when provided', status: 400 };
+    }
+    return { site, slug, secret: secretRaw === true };
+}
+/**
+ * Map a core-helper error message onto the right HTTP status. The core
+ * helpers throw plain `Error` with descriptive text; we keep the text
+ * in the response body so the client can surface it.
+ */
+function statusForError(message) {
+    if (/already exists/i.test(message))
+        return 409;
+    if (/not found/i.test(message))
+        return 404;
+    // Slug, filename, traversal, and missing-arg errors are all 400.
+    return 400;
+}
+function isJsonObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+async function readJson(c) {
+    let raw;
+    try {
+        raw = await c.req.json();
+    }
+    catch {
+        return { ok: false, status: 400, error: 'invalid JSON body' };
+    }
+    if (!isJsonObject(raw)) {
+        return { ok: false, status: 400, error: 'body must be a JSON object' };
+    }
+    return { ok: true, value: raw };
+}
+// ---------------------------------------------------------------------------
+// Route module
+// ---------------------------------------------------------------------------
+export function createScrapbookMutationsRouter(ctx) {
+    const app = new Hono();
+    // POST /api/dev/scrapbook/save
+    // Body: { site, slug, filename, body }
+    // Behavior: write `body` to <contentDir>/<slug>/scrapbook/<filename>.
+    // Creates the file if missing (delegates to create when absent so the
+    // operator's first save lands rather than 404'ing).
+    app.post('/save', async (c) => {
+        const parsed = await readJson(c);
+        if (!parsed.ok)
+            return c.json({ error: parsed.error }, parsed.status);
+        const env = checkEnvelope(ctx, parsed.value);
+        if ('error' in env)
+            return c.json({ error: env.error }, env.status);
+        const filename = parsed.value.filename;
+        const bodyText = parsed.value.body;
+        if (typeof filename !== 'string' || filename.length === 0) {
+            return c.json({ error: 'filename is required' }, 400);
+        }
+        if (typeof bodyText !== 'string') {
+            return c.json({ error: 'body must be a string' }, 400);
+        }
+        let item;
+        try {
+            // Resolve to test for existence. If absent, create-then-return.
+            const abs = scrapbookFilePath(ctx.projectRoot, ctx.config, env.site, env.slug, filename, { secret: env.secret });
+            if (!existsSync(abs)) {
+                // Only `.md` files can be created by the create helper, but
+                // save's contract is "write whatever was sent". For non-md
+                // files that don't yet exist, fall through to upload semantics.
+                if (filename.endsWith('.md')) {
+                    item = createScrapbookMarkdown(ctx.projectRoot, ctx.config, env.site, env.slug, filename, bodyText, { secret: env.secret });
+                }
+                else {
+                    item = writeScrapbookUpload(ctx.projectRoot, ctx.config, env.site, env.slug, filename, Buffer.from(bodyText, 'utf-8'), { secret: env.secret });
+                }
+            }
+            else {
+                item = saveScrapbookFile(ctx.projectRoot, ctx.config, env.site, env.slug, filename, bodyText, { secret: env.secret });
+            }
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            return c.json({ error: reason }, statusForError(reason));
+        }
+        return c.json({ item }, 200);
+    });
+    // POST /api/dev/scrapbook/rename
+    // Body: { site, slug, oldName, newName, secret?, toSecret? }
+    //
+    // Two modes:
+    //   - In-place rename: secret = source location (defaults to false);
+    //     toSecret omitted (or equal to secret). The file is renamed
+    //     inside the same section.
+    //   - Cross-section move (#28): secret = source, toSecret = target
+    //     section. When secret !== toSecret, the file is moved between
+    //     `scrapbook/` and `scrapbook/secret/`. The studio's UI exposes
+    //     this as "Mark secret" / "Mark public".
+    //
+    // 409 if the target newName already exists (in the destination
+    // section). 404 if oldName is missing in the source section.
+    app.post('/rename', async (c) => {
+        const parsed = await readJson(c);
+        if (!parsed.ok)
+            return c.json({ error: parsed.error }, parsed.status);
+        const env = checkEnvelope(ctx, parsed.value);
+        if ('error' in env)
+            return c.json({ error: env.error }, env.status);
+        const oldName = parsed.value.oldName;
+        const newName = parsed.value.newName;
+        if (typeof oldName !== 'string' || oldName.length === 0) {
+            return c.json({ error: 'oldName is required' }, 400);
+        }
+        if (typeof newName !== 'string' || newName.length === 0) {
+            return c.json({ error: 'newName is required' }, 400);
+        }
+        const toSecretRaw = parsed.value.toSecret;
+        if (toSecretRaw !== undefined && typeof toSecretRaw !== 'boolean') {
+            return c.json({ error: 'toSecret must be a boolean when provided' }, 400);
+        }
+        const toSecret = toSecretRaw === undefined ? env.secret : toSecretRaw;
+        let item;
+        try {
+            if (toSecret === env.secret) {
+                item = renameScrapbookFile(ctx.projectRoot, ctx.config, env.site, env.slug, oldName, newName, { secret: env.secret });
+            }
+            else {
+                // Cross-section move. Use the path-resolver to compute the
+                // source and destination absolute paths under the right
+                // sub-roots (and let the resolver enforce traversal guards).
+                // Then physically rename across the two paths.
+                const srcAbs = scrapbookFilePath(ctx.projectRoot, ctx.config, env.site, env.slug, oldName, { secret: env.secret });
+                const dstAbs = scrapbookFilePath(ctx.projectRoot, ctx.config, env.site, env.slug, newName, { secret: toSecret });
+                if (!existsSync(srcAbs)) {
+                    return c.json({ error: `file not found: "${oldName}"` }, 404);
+                }
+                if (existsSync(dstAbs)) {
+                    return c.json({ error: `target name already exists: "${newName}"` }, 409);
+                }
+                // Ensure the destination directory exists (creates `secret/`
+                // when promoting public → secret for the first time).
+                mkdirSync(dirname(dstAbs), { recursive: true });
+                renameSync(srcAbs, dstAbs);
+                const st = statSync(dstAbs);
+                // Build the response item the same shape the helper uses.
+                item = {
+                    name: newName,
+                    kind: classify(newName),
+                    size: st.size,
+                    mtime: st.mtime.toISOString(),
+                };
+            }
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            return c.json({ error: reason }, statusForError(reason));
+        }
+        return c.json({ item }, 200);
+    });
+    // POST /api/dev/scrapbook/delete
+    // Body: { site, slug, filename }
+    // Behavior: unlink the file. 404 if missing.
+    app.post('/delete', async (c) => {
+        const parsed = await readJson(c);
+        if (!parsed.ok)
+            return c.json({ error: parsed.error }, parsed.status);
+        const env = checkEnvelope(ctx, parsed.value);
+        if ('error' in env)
+            return c.json({ error: env.error }, env.status);
+        const filename = parsed.value.filename;
+        if (typeof filename !== 'string' || filename.length === 0) {
+            return c.json({ error: 'filename is required' }, 400);
+        }
+        try {
+            deleteScrapbookFile(ctx.projectRoot, ctx.config, env.site, env.slug, filename, { secret: env.secret });
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            return c.json({ error: reason }, statusForError(reason));
+        }
+        return c.json({ ok: true }, 200);
+    });
+    // POST /api/dev/scrapbook/create
+    // Body: { site, slug, filename, body? }
+    // Behavior: create a new markdown file. 409 if it already exists.
+    app.post('/create', async (c) => {
+        const parsed = await readJson(c);
+        if (!parsed.ok)
+            return c.json({ error: parsed.error }, parsed.status);
+        const env = checkEnvelope(ctx, parsed.value);
+        if ('error' in env)
+            return c.json({ error: env.error }, env.status);
+        const filename = parsed.value.filename;
+        const bodyText = parsed.value.body ?? '';
+        if (typeof filename !== 'string' || filename.length === 0) {
+            return c.json({ error: 'filename is required' }, 400);
+        }
+        if (typeof bodyText !== 'string') {
+            return c.json({ error: 'body must be a string' }, 400);
+        }
+        let item;
+        try {
+            item = createScrapbookMarkdown(ctx.projectRoot, ctx.config, env.site, env.slug, filename, bodyText, { secret: env.secret });
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            return c.json({ error: reason }, statusForError(reason));
+        }
+        return c.json({ item }, 200);
+    });
+    // POST /api/dev/scrapbook/upload
+    // Multipart body: { site, slug, file, secret? }
+    // Behavior: save the uploaded file (binary-safe) at
+    // <contentDir>/<slug>/scrapbook/<file.name>, or under
+    // `scrapbook/secret/` when the `secret` form field is the literal
+    // string "true". 409 if it already exists — operator must rename
+    // or delete first.
+    app.post('/upload', async (c) => {
+        let form;
+        try {
+            form = await c.req.formData();
+        }
+        catch {
+            return c.json({ error: 'invalid multipart body' }, 400);
+        }
+        const site = form.get('site');
+        const slug = form.get('slug');
+        const file = form.get('file');
+        const secretField = form.get('secret');
+        const secret = typeof secretField === 'string' && secretField === 'true';
+        if (typeof site !== 'string' || site.length === 0) {
+            return c.json({ error: 'site is required' }, 400);
+        }
+        if (typeof slug !== 'string' || slug.length === 0) {
+            return c.json({ error: 'slug is required' }, 400);
+        }
+        if (!(site in ctx.config.sites)) {
+            return c.json({ error: `unknown site: ${site}` }, 404);
+        }
+        if (!(file instanceof File)) {
+            return c.json({ error: 'file is required (multipart)' }, 400);
+        }
+        const filename = file.name;
+        if (typeof filename !== 'string' || filename.length === 0) {
+            return c.json({ error: 'uploaded file has no name' }, 400);
+        }
+        let item;
+        try {
+            const buf = Buffer.from(await file.arrayBuffer());
+            item = writeScrapbookUpload(ctx.projectRoot, ctx.config, site, slug, filename, buf, { secret });
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            return c.json({ error: reason }, statusForError(reason));
+        }
+        return c.json({ item }, 200);
+    });
+    return app;
+}
+//# sourceMappingURL=scrapbook-mutations.js.map