@objectstack/cli 5.0.0 → 5.2.0

package/dist/utils/studio-field-patch.js

@@ -0,0 +1,336 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+/**
+ * Studio field-patch — ts-morph powered surgery on a single field
+ * inside an `ObjectSchema.create({...})` or `defineObject({...})` call.
+ *
+ * Supported field shapes:
+ *   account_number: Field.autonumber({ ...props })          // CallExpression
+ *   owner:          Field.lookup('user', { ...props })      // CallExpression with second-arg object
+ *   custom:         { ...props }                            // bare ObjectLiteral
+ *
+ * Properties we know how to update: `label`, `description`, `required`.
+ * Falsy values (`null`, `''`, `false`) are interpreted as "remove this
+ * property" so the source stays minimal.
+ */
+import { Project, SyntaxKind, } from 'ts-morph';
+/**
+ * Locate the field's inner object-literal and apply the patch.
+ * Writes the file in place when successful.
+ */
+export async function patchObjectFieldFile(absPath, fieldKey, patch) {
+    return withFieldsObj(absPath, async (fieldsObj) => {
+        const fieldProp = fieldsObj.getProperty(fieldKey);
+        if (!fieldProp || !fieldProp.isKind(SyntaxKind.PropertyAssignment)) {
+            return { ok: false, error: `field \`${fieldKey}\` not found in fields` };
+        }
+        const innerObj = resolveInnerObjectLiteral(fieldProp.getInitializer());
+        if (!innerObj) {
+            return { ok: false, error: `field \`${fieldKey}\` initializer has no editable object literal` };
+        }
+        if ('label' in patch)
+            applyStringProp(innerObj, 'label', patch.label);
+        if ('description' in patch)
+            applyStringProp(innerObj, 'description', patch.description);
+        if ('required' in patch)
+            applyBooleanProp(innerObj, 'required', patch.required);
+        return { ok: true };
+    });
+}
+/**
+ * Append a new field to the `fields: { ... }` object literal. The
+ * `initializer` is the raw TS source that goes on the right-hand side
+ * of `<fieldName>: …` — typically an object literal but may be any
+ * expression (e.g. `Field.text({ ... })`).
+ *
+ * Refuses to overwrite an existing field — callers must surface a
+ * conflict to the user.
+ */
+export async function addObjectField(absPath, fieldName, initializer) {
+    if (!/^[a-z_][a-z0-9_]*$/.test(fieldName)) {
+        return { ok: false, error: `invalid field name \`${fieldName}\` (must be snake_case)` };
+    }
+    return withFieldsObj(absPath, async (fieldsObj) => {
+        if (fieldsObj.getProperty(fieldName)) {
+            return { ok: false, error: `field \`${fieldName}\` already exists` };
+        }
+        try {
+            // Append by raw-text insertion so we match the file's existing
+            // indentation / line-break conventions instead of forcing ts-morph
+            // defaults (which produced 6-space indent and a flush-left closing
+            // brace inside a 4-space-indented body).
+            const openBrace = fieldsObj.getFirstChildByKind(SyntaxKind.OpenBraceToken);
+            const closeBrace = fieldsObj.getLastChildByKind(SyntaxKind.CloseBraceToken);
+            if (!openBrace || !closeBrace) {
+                return { ok: false, error: 'malformed object literal (missing braces)' };
+            }
+            const sf = fieldsObj.getSourceFile();
+            const fullText = sf.getFullText();
+            const bodyStart = openBrace.getEnd();
+            const bodyEnd = closeBrace.getStart();
+            // Detect existing indentation by sniffing the original source:
+            //   propIndent  — leading whitespace before the first existing prop
+            //   closeIndent — leading whitespace before the existing close brace
+            // Both are read verbatim so the new prop and the close brace land at
+            // the exact columns the file already uses (handles 2-space, 4-space,
+            // tabs, or anything else without guessing the indent step).
+            const sniffIndent = (pos) => {
+                let i = pos - 1;
+                while (i >= 0 && (fullText[i] === ' ' || fullText[i] === '\t'))
+                    i--;
+                return fullText.slice(i + 1, pos);
+            };
+            const firstProp = fieldsObj.getProperties()[0];
+            const closeIndent = sniffIndent(closeBrace.getStart());
+            let propIndent;
+            if (firstProp && firstProp.isKind(SyntaxKind.PropertyAssignment)) {
+                propIndent = sniffIndent(firstProp.getStart());
+            }
+            else {
+                // Empty `{}` — give the new prop one step beyond the close brace.
+                // Default to two spaces; if the close-brace indent looks tab-based,
+                // use a tab.
+                propIndent = closeIndent + (closeIndent.includes('\t') ? '\t' : '  ');
+            }
+            // Body region between braces; rebuild with the new prop appended,
+            // ensuring trailing comma + newline + indent before the new prop and
+            // a newline + closing indent before the close brace.
+            const body = fullText.slice(bodyStart, bodyEnd);
+            let trimmed = body.replace(/\s+$/, '');
+            if (trimmed && !trimmed.endsWith(','))
+                trimmed += ',';
+            const isEmpty = trimmed.length === 0;
+            const newBody = isEmpty
+                ? `\n${propIndent}${fieldName}: ${initializer},\n${closeIndent}`
+                : `${trimmed}\n${propIndent}${fieldName}: ${initializer},\n${closeIndent}`;
+            // Use raw SourceFile.replaceText to avoid ts-morph auto-reindenting
+            // every line inside the literal (replaceWithText on an ObjectLiteral
+            // re-indents by manipulation settings, shifting unchanged lines).
+            sf.replaceText([bodyStart, bodyEnd], newBody);
+            return { ok: true };
+        }
+        catch (err) {
+            return { ok: false, error: `add failed: ${err?.message ?? String(err)}` };
+        }
+    });
+}
+/**
+ * Re-order the properties inside the `fields: { ... }` object literal
+ * to match `order[]`. Field names absent from `order` are appended at
+ * the end in their existing relative order — keeps the operation safe
+ * if the UI has a stale snapshot.
+ *
+ * Implementation: slice each property's source range out of the file
+ * (including any leading whitespace / blank-line / comment trivia and
+ * the trailing `,`), then concatenate the slices in the new order. By
+ * working on the raw source, indentation, trailing commas, blank-line
+ * separators and inline comments are all preserved verbatim. The only
+ * cost: a hanging blank line that previously sat *between* two props
+ * follows whichever property it precedes after the reorder, which is
+ * the natural and least-surprising behaviour.
+ */
+export async function reorderObjectFields(absPath, order) {
+    if (!Array.isArray(order)) {
+        return { ok: false, error: 'order must be an array of field names' };
+    }
+    return withFieldsObj(absPath, async (fieldsObj) => {
+        const props = fieldsObj.getProperties();
+        const openBrace = fieldsObj.getFirstChildByKind(SyntaxKind.OpenBraceToken);
+        const closeBrace = fieldsObj.getLastChildByKind(SyntaxKind.CloseBraceToken);
+        if (!openBrace || !closeBrace) {
+            return { ok: false, error: 'malformed object literal (missing braces)' };
+        }
+        const sf = fieldsObj.getSourceFile();
+        const fullText = sf.getFullText();
+        const bodyStart = openBrace.getEnd();
+        const bodyEnd = closeBrace.getStart();
+        // For each property: capture the slice from "just after previous prop's
+        // trailing comma" (or bodyStart for the first prop) up to and including
+        // this prop's own trailing comma (skipping inline whitespace up to it).
+        // Leading whitespace / blank lines / comments that precede a prop stay
+        // with that prop, so they travel together when reordered.
+        const slices = new Map();
+        let cursor = bodyStart;
+        for (let i = 0; i < props.length; i++) {
+            const p = props[i];
+            if (!p.isKind(SyntaxKind.PropertyAssignment) && !p.isKind(SyntaxKind.ShorthandPropertyAssignment)) {
+                continue;
+            }
+            const name = p.getName();
+            // Find end-of-slice: skip whitespace after the prop, swallow one comma if present.
+            let end = p.getEnd();
+            while (end < bodyEnd && /[ \t]/.test(fullText[end]))
+                end++;
+            if (fullText[end] === ',')
+                end++;
+            slices.set(name, fullText.slice(cursor, end));
+            cursor = end;
+        }
+        // Anything between the last prop's comma and the close brace (typically
+        // a trailing newline + indentation) becomes the new "tail".
+        const tail = fullText.slice(cursor, bodyEnd);
+        if (slices.size === 0) {
+            return { ok: false, error: '`fields` is empty — nothing to reorder' };
+        }
+        const seen = new Set();
+        const ordered = [];
+        for (const name of order) {
+            const slice = slices.get(name);
+            if (slice !== undefined) {
+                ordered.push(slice);
+                seen.add(name);
+            }
+        }
+        // Append anything the UI didn't know about so we never drop fields.
+        for (const [name, slice] of slices) {
+            if (!seen.has(name))
+                ordered.push(slice);
+        }
+        const newBody = ordered.join('') + tail;
+        try {
+            // sf.replaceText avoids re-indenting unchanged lines, which is what
+            // makes fieldsObj.replaceWithText destroy formatting.
+            sf.replaceText([bodyStart, bodyEnd], newBody);
+            return { ok: true };
+        }
+        catch (err) {
+            return { ok: false, error: `reorder failed: ${err?.message ?? String(err)}` };
+        }
+    });
+}
+/**
+ * Shared entry: open the file, drill into the `fields` literal, run
+ * `mutate(...)`, persist on success. Centralizes the schema-call /
+ * fields-literal lookup that every operation needs.
+ */
+async function withFieldsObj(absPath, mutate) {
+    const project = new Project({ useInMemoryFileSystem: false, skipAddingFilesFromTsConfig: true });
+    let sf;
+    try {
+        sf = project.addSourceFileAtPath(absPath);
+    }
+    catch (err) {
+        return { ok: false, error: `parse failed: ${err?.message ?? String(err)}` };
+    }
+    const schemaCall = findSchemaCall(sf);
+    if (!schemaCall) {
+        return { ok: false, error: 'no ObjectSchema.create / defineObject call found in file' };
+    }
+    const schemaArg = schemaCall.getArguments()[0];
+    if (!schemaArg || !schemaArg.isKind(SyntaxKind.ObjectLiteralExpression)) {
+        return { ok: false, error: 'schema call argument is not an object literal' };
+    }
+    const fieldsProp = schemaArg.getProperty('fields');
+    if (!fieldsProp || !fieldsProp.isKind(SyntaxKind.PropertyAssignment)) {
+        return { ok: false, error: 'schema object has no `fields` property' };
+    }
+    const fieldsInit = fieldsProp.getInitializer();
+    if (!fieldsInit || !fieldsInit.isKind(SyntaxKind.ObjectLiteralExpression)) {
+        return { ok: false, error: '`fields` initializer is not an object literal' };
+    }
+    const result = await mutate(fieldsInit);
+    if (!result.ok)
+        return result;
+    try {
+        await sf.save();
+        return { ok: true };
+    }
+    catch (err) {
+        return { ok: false, error: `write failed: ${err?.message ?? String(err)}` };
+    }
+}
+// ─── helpers ────────────────────────────────────────────────────────
+function findSchemaCall(sf) {
+    const calls = sf.getDescendantsOfKind(SyntaxKind.CallExpression);
+    for (const call of calls) {
+        const expr = call.getExpression().getText();
+        if (expr === 'ObjectSchema.create' || expr === 'defineObject') {
+            return call;
+        }
+    }
+    return null;
+}
+/**
+ * Given a property initializer, return the inner ObjectLiteralExpression
+ * we should patch.
+ *   - `{ ... }`                       → that literal
+ *   - `Field.X({ ... })`              → first arg if object literal
+ *   - `Field.X('rel', { ... })`       → second arg
+ *   - `Field.X({ ... }, { ... })`     → first arg (defensive)
+ */
+function resolveInnerObjectLiteral(init) {
+    if (!init)
+        return null;
+    if (init.isKind(SyntaxKind.ObjectLiteralExpression)) {
+        return init;
+    }
+    if (init.isKind(SyntaxKind.CallExpression)) {
+        const args = init.getArguments();
+        for (const arg of args) {
+            if (arg.isKind(SyntaxKind.ObjectLiteralExpression)) {
+                return arg;
+            }
+        }
+    }
+    return null;
+}
+function applyStringProp(obj, key, value) {
+    const existing = obj.getProperty(key);
+    if (value == null || value === '') {
+        if (existing)
+            existing.remove();
+        return;
+    }
+    const literal = renderStringLiteral(obj, value);
+    if (existing && existing.isKind(SyntaxKind.PropertyAssignment)) {
+        existing.setInitializer(literal);
+    }
+    else {
+        obj.addPropertyAssignment({ name: key, initializer: literal });
+    }
+}
+/**
+ * Render `value` as a TS string literal, preferring whichever quote
+ * style (single vs double) the surrounding object already uses for
+ * existing string props. Falls back to single quotes — the dominant
+ * convention across the codebase — when there's no signal.
+ */
+function renderStringLiteral(obj, value) {
+    let single = 0;
+    let double = 0;
+    for (const p of obj.getProperties()) {
+        if (!p.isKind(SyntaxKind.PropertyAssignment))
+            continue;
+        const init = p.getInitializer();
+        if (!init || !init.isKind(SyntaxKind.StringLiteral))
+            continue;
+        const raw = init.getText();
+        if (raw.startsWith("'"))
+            single++;
+        else if (raw.startsWith('"'))
+            double++;
+    }
+    const useDouble = double > single;
+    if (useDouble || value.includes("'")) {
+        // JSON.stringify gives us proper escaping for `"` and control chars.
+        return JSON.stringify(value);
+    }
+    // Single-quoted: escape only single quotes and backslashes.
+    return `'${value.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+}
+function applyBooleanProp(obj, key, value) {
+    const existing = obj.getProperty(key);
+    // Default for `required` is false, so we omit the property when false
+    // to keep the source minimal — matches what authors hand-write.
+    if (value !== true) {
+        if (existing)
+            existing.remove();
+        return;
+    }
+    if (existing && existing.isKind(SyntaxKind.PropertyAssignment)) {
+        existing.setInitializer('true');
+    }
+    else {
+        obj.addPropertyAssignment({ name: key, initializer: 'true' });
+    }
+}
+//# sourceMappingURL=studio-field-patch.js.map

package/dist/utils/studio-field-patch.js.map

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

package/dist/utils/studio.d.ts

@@ -56,4 +56,32 @@ export declare function createStudioStaticPlugin(distPath: string, options?: {
     init: () => Promise<void>;
     start: (ctx: any) => Promise<void>;
 };
+/**
+ * Dev-only plugin that exposes a tiny write API at
+ * `/_studio/api/metadata/*` so Studio's "Create" dialogs can scaffold
+ * real `.ts` files instead of asking the user to paste a snippet.
+ *
+ * Security posture: enabled ONLY when `isDev === true`. All file paths
+ * must live under `<cwd>`, contain a `/src/` segment, and carry an
+ * approved extension. Path traversal (`..`) and absolute paths are
+ * rejected outright. Existing files are NEVER overwritten unless the
+ * caller passes `mode: 'overwrite'`.
+ *
+ * Endpoints:
+ *   GET  /_studio/api/metadata/layout?package=<id>
+ *     200: { srcRoot: string }   relative to cwd, e.g. "src" or "packages/<id>/src"
+ *
+ *   POST /_studio/api/metadata/file
+ *     body: { path: string, content: string, mode?: 'create' | 'overwrite' }
+ *     200: { ok: true, path: string }
+ *     409: { ok: false, error: 'exists' }
+ *     400: { ok: false, error: ... }
+ */
+export declare function createStudioWriteApiPlugin(cwd: string, options?: {
+    isDev: boolean;
+}): {
+    name: string;
+    init: () => Promise<void>;
+    start: (ctx: any) => Promise<void>;
+};
 //# sourceMappingURL=studio.d.ts.map

package/dist/utils/studio.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"studio.d.ts","sourceRoot":"","sources":["../../src/utils/studio.ts"],"names":[],"mappings":"AAaA,OAAO,EAAS,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAKzD,sEAAsE;AACtE,eAAO,MAAM,WAAW,aAAa,CAAC;AAOtC;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,GAAG,IAAI,CA+CjD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAEzD;AAID;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,GAAE,MAAwB,GAAG,OAAO,CAAC,MAAM,CAAC,CAYlF;AAID,MAAM,WAAW,aAAa;IAC5B,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,2BAA2B;IAC3B,OAAO,EAAE,YAAY,CAAC;CACvB;AAED;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAA;CAAO,GACpC,OAAO,CAAC,aAAa,CAAC,CAwExB;AAID;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM;;;iBAMjC,GAAG;EAwCzB;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,YAAY,CAAC,EAAE,OAAO,CAAA;CAAE;;;iBAMzF,GAAG;EAsEzB"}
+{"version":3,"file":"studio.d.ts","sourceRoot":"","sources":["../../src/utils/studio.ts"],"names":[],"mappings":"AAaA,OAAO,EAAS,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAKzD,sEAAsE;AACtE,eAAO,MAAM,WAAW,aAAa,CAAC;AAOtC;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,GAAG,IAAI,CA+CjD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAEzD;AAID;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,GAAE,MAAwB,GAAG,OAAO,CAAC,MAAM,CAAC,CAYlF;AAID,MAAM,WAAW,aAAa;IAC5B,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,2BAA2B;IAC3B,OAAO,EAAE,YAAY,CAAC;CACvB;AAED;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAA;CAAO,GACpC,OAAO,CAAC,aAAa,CAAC,CAwExB;AAID;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM;;;iBAMjC,GAAG;EAwCzB;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,YAAY,CAAC,EAAE,OAAO,CAAA;CAAE;;;iBAMzF,GAAG;EAsEzB;AAID;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE;IAAE,KAAK,EAAE,OAAO,CAAA;CAAqB;;;iBAM/E,GAAG;EAmMzB"}

package/dist/utils/studio.js

@@ -278,6 +278,231 @@ export function createStudioStaticPlugin(distPath, options) {
         },
     };
 }
+// ─── Dev-only Write API ─────────────────────────────────────────────
+/**
+ * Dev-only plugin that exposes a tiny write API at
+ * `/_studio/api/metadata/*` so Studio's "Create" dialogs can scaffold
+ * real `.ts` files instead of asking the user to paste a snippet.
+ *
+ * Security posture: enabled ONLY when `isDev === true`. All file paths
+ * must live under `<cwd>`, contain a `/src/` segment, and carry an
+ * approved extension. Path traversal (`..`) and absolute paths are
+ * rejected outright. Existing files are NEVER overwritten unless the
+ * caller passes `mode: 'overwrite'`.
+ *
+ * Endpoints:
+ *   GET  /_studio/api/metadata/layout?package=<id>
+ *     200: { srcRoot: string }   relative to cwd, e.g. "src" or "packages/<id>/src"
+ *
+ *   POST /_studio/api/metadata/file
+ *     body: { path: string, content: string, mode?: 'create' | 'overwrite' }
+ *     200: { ok: true, path: string }
+ *     409: { ok: false, error: 'exists' }
+ *     400: { ok: false, error: ... }
+ */
+export function createStudioWriteApiPlugin(cwd, options = { isDev: false }) {
+    return {
+        name: 'com.objectstack.studio-write-api',
+        init: async () => { },
+        start: async (ctx) => {
+            if (!options.isDev)
+                return;
+            const httpServer = ctx.getService?.('http.server');
+            if (!httpServer?.getRawApp) {
+                ctx.logger?.warn?.('Studio write API: http.server not found — skipping');
+                return;
+            }
+            const app = httpServer.getRawApp();
+            const projectRoot = path.resolve(cwd);
+            const ALLOWED_EXT = new Set(['.ts', '.tsx', '.json']);
+            const respond = (_c, status, body) => new Response(JSON.stringify(body), {
+                status,
+                headers: { 'content-type': 'application/json; charset=utf-8' },
+            });
+            // Resolve the most likely source-code root for a given package id.
+            const resolveSrcRoot = (pkgId) => {
+                const candidates = [
+                    pkgId ? path.join('packages', pkgId, 'src') : null,
+                    pkgId ? path.join('examples', pkgId, 'src') : null,
+                    'src', // single-app project layout
+                ].filter(Boolean);
+                for (const c of candidates) {
+                    if (fs.existsSync(path.join(projectRoot, c)))
+                        return c;
+                }
+                return null;
+            };
+            app.get(`${STUDIO_PATH}/api/metadata/layout`, (c) => {
+                const pkgId = c.req.query?.('package') ?? null;
+                const srcRoot = resolveSrcRoot(pkgId);
+                return respond(c, 200, { srcRoot });
+            });
+            app.post(`${STUDIO_PATH}/api/metadata/file`, async (c) => {
+                let body;
+                try {
+                    body = await c.req.json();
+                }
+                catch {
+                    return respond(c, 400, { ok: false, error: 'invalid json body' });
+                }
+                const rel = typeof body?.path === 'string' ? body.path : '';
+                const content = typeof body?.content === 'string' ? body.content : '';
+                const mode = body?.mode === 'overwrite' ? 'overwrite' : 'create';
+                if (!rel)
+                    return respond(c, 400, { ok: false, error: 'path is required' });
+                if (path.isAbsolute(rel) || rel.split(/[\\/]/).includes('..')) {
+                    return respond(c, 400, { ok: false, error: 'path must be a project-relative path without `..`' });
+                }
+                const ext = path.extname(rel).toLowerCase();
+                if (!ALLOWED_EXT.has(ext)) {
+                    return respond(c, 400, { ok: false, error: `unsupported extension ${ext}` });
+                }
+                const abs = path.resolve(projectRoot, rel);
+                if (!abs.startsWith(projectRoot + path.sep)) {
+                    return respond(c, 400, { ok: false, error: 'path escapes project root' });
+                }
+                // Must contain a `/src/` segment — keeps writes scoped to source
+                // code, not random config files at the repo root.
+                const segments = path.relative(projectRoot, abs).split(path.sep);
+                if (!segments.includes('src')) {
+                    return respond(c, 400, { ok: false, error: 'path must live under a src/ directory' });
+                }
+                if (fs.existsSync(abs) && mode === 'create') {
+                    return respond(c, 409, { ok: false, error: 'exists' });
+                }
+                try {
+                    await fs.promises.mkdir(path.dirname(abs), { recursive: true });
+                    await fs.promises.writeFile(abs, content, 'utf-8');
+                    ctx.logger?.info?.(`Studio write API: ${mode} ${rel}`);
+                    return respond(c, 200, { ok: true, path: rel });
+                }
+                catch (err) {
+                    ctx.logger?.error?.(`Studio write API failed: ${err?.message}`);
+                    return respond(c, 500, { ok: false, error: err?.message ?? String(err) });
+                }
+            });
+            ctx.logger?.info?.(`Studio write API mounted at ${STUDIO_PATH}/api/metadata/* (dev mode)`);
+            /**
+             * Shared validation for endpoints that mutate an existing `.ts`
+             * source file by relative path. Returns `{ abs }` on success or
+             * a respond() Response when validation fails.
+             */
+            const validateTsPath = (c, rel) => {
+                if (!rel)
+                    return respond(c, 400, { ok: false, error: 'path is required' });
+                if (path.isAbsolute(rel) || rel.split(/[\\/]/).includes('..')) {
+                    return respond(c, 400, { ok: false, error: 'path must be a project-relative path without `..`' });
+                }
+                if (path.extname(rel).toLowerCase() !== '.ts') {
+                    return respond(c, 400, { ok: false, error: 'only .ts files are supported' });
+                }
+                const abs = path.resolve(projectRoot, rel);
+                if (!abs.startsWith(projectRoot + path.sep)) {
+                    return respond(c, 400, { ok: false, error: 'path escapes project root' });
+                }
+                if (!path.relative(projectRoot, abs).split(path.sep).includes('src')) {
+                    return respond(c, 400, { ok: false, error: 'path must live under a src/ directory' });
+                }
+                if (!fs.existsSync(abs)) {
+                    return respond(c, 404, { ok: false, error: 'file not found' });
+                }
+                return { abs };
+            };
+            app.post(`${STUDIO_PATH}/api/metadata/field-patch`, async (c) => {
+                let body;
+                try {
+                    body = await c.req.json();
+                }
+                catch {
+                    return respond(c, 400, { ok: false, error: 'invalid json body' });
+                }
+                const rel = typeof body?.path === 'string' ? body.path : '';
+                const fieldKey = typeof body?.field === 'string' ? body.field : '';
+                const patch = body?.patch && typeof body.patch === 'object' ? body.patch : null;
+                if (!fieldKey || !patch) {
+                    return respond(c, 400, { ok: false, error: 'field and patch are required' });
+                }
+                const v = validateTsPath(c, rel);
+                if (!v.abs)
+                    return v;
+                try {
+                    const { patchObjectFieldFile } = await import('./studio-field-patch.js');
+                    const result = await patchObjectFieldFile(v.abs, fieldKey, patch);
+                    if (!result.ok)
+                        return respond(c, 400, result);
+                    ctx.logger?.info?.(`Studio field-patch: ${rel} field=${fieldKey} keys=${Object.keys(patch).join(',')}`);
+                    return respond(c, 200, { ok: true, path: rel, field: fieldKey });
+                }
+                catch (err) {
+                    ctx.logger?.error?.(`Studio field-patch failed: ${err?.message}`);
+                    return respond(c, 500, { ok: false, error: err?.message ?? String(err) });
+                }
+            });
+            app.post(`${STUDIO_PATH}/api/metadata/field-add`, async (c) => {
+                let body;
+                try {
+                    body = await c.req.json();
+                }
+                catch {
+                    return respond(c, 400, { ok: false, error: 'invalid json body' });
+                }
+                const rel = typeof body?.path === 'string' ? body.path : '';
+                const fieldName = typeof body?.fieldName === 'string' ? body.fieldName : '';
+                const initializer = typeof body?.initializer === 'string' ? body.initializer : '';
+                if (!fieldName || !initializer) {
+                    return respond(c, 400, { ok: false, error: 'fieldName and initializer are required' });
+                }
+                const v = validateTsPath(c, rel);
+                if (!v.abs)
+                    return v;
+                try {
+                    const { addObjectField } = await import('./studio-field-patch.js');
+                    const result = await addObjectField(v.abs, fieldName, initializer);
+                    if (!result.ok) {
+                        // Existing field is a 409 conflict; other errors stay 400.
+                        const status = result.error.includes('already exists') ? 409 : 400;
+                        return respond(c, status, result);
+                    }
+                    ctx.logger?.info?.(`Studio field-add: ${rel} field=${fieldName}`);
+                    return respond(c, 200, { ok: true, path: rel, field: fieldName });
+                }
+                catch (err) {
+                    ctx.logger?.error?.(`Studio field-add failed: ${err?.message}`);
+                    return respond(c, 500, { ok: false, error: err?.message ?? String(err) });
+                }
+            });
+            app.post(`${STUDIO_PATH}/api/metadata/field-reorder`, async (c) => {
+                let body;
+                try {
+                    body = await c.req.json();
+                }
+                catch {
+                    return respond(c, 400, { ok: false, error: 'invalid json body' });
+                }
+                const rel = typeof body?.path === 'string' ? body.path : '';
+                const order = Array.isArray(body?.order) ? body.order.filter((s) => typeof s === 'string') : null;
+                if (!order || order.length === 0) {
+                    return respond(c, 400, { ok: false, error: 'order is required (non-empty string[])' });
+                }
+                const v = validateTsPath(c, rel);
+                if (!v.abs)
+                    return v;
+                try {
+                    const { reorderObjectFields } = await import('./studio-field-patch.js');
+                    const result = await reorderObjectFields(v.abs, order);
+                    if (!result.ok)
+                        return respond(c, 400, result);
+                    ctx.logger?.info?.(`Studio field-reorder: ${rel} (${order.length} fields)`);
+                    return respond(c, 200, { ok: true, path: rel, count: order.length });
+                }
+                catch (err) {
+                    ctx.logger?.error?.(`Studio field-reorder failed: ${err?.message}`);
+                    return respond(c, 500, { ok: false, error: err?.message ?? String(err) });
+                }
+            });
+        },
+    };
+}
 // ─── Helpers ────────────────────────────────────────────────────────
 const MIME_TYPES = {
     '.html': 'text/html; charset=utf-8',