@svgrid/enterprise 2.5.2 → 2.6.0

package/dist/studio/cli.js

@@ -0,0 +1,70 @@
+import { introspectDrizzle, introspectDrizzleAll, introspectJson } from './introspect.js';
+import { introspectPrisma, introspectPrismaAll } from './introspect-prisma.js';
+import { mergeManaged, scaffold, skipUserOwned } from './scaffold.js';
+import { scaffoldApp } from './scaffold-app.js';
+import { verifyScaffold } from './verify.js';
+/** A `.prisma` file (by extension or a `model X {` block) parses as Prisma; otherwise Drizzle. */
+function isPrismaSource(path, source) {
+    return /\.prisma$/i.test(path) || /\bmodel\s+\w+\s*\{/.test(source);
+}
+/** Resolve an EntitySchema from whichever input was provided. */
+export async function resolveSchema(options, io) {
+    if (options.schema)
+        return options.schema;
+    if (options.from) {
+        const src = await io.readFile(options.from);
+        if (src == null)
+            throw new Error(`runStudioAdd: schema file not found: ${options.from}`);
+        return isPrismaSource(options.from, src)
+            ? introspectPrisma(src, options.table)
+            : introspectDrizzle(src, options.table);
+    }
+    if (options.rows) {
+        return introspectJson(options.name ?? options.route ?? 'entity', options.rows);
+    }
+    throw new Error('runStudioAdd: provide `from` (a Drizzle or Prisma schema file), `rows`, or `schema`');
+}
+/**
+ * Resolve **every** entity from a Drizzle or Prisma schema file (the `--all
+ * --from` path), linked so foreign keys become working relation lookups.
+ */
+export async function resolveSchemas(from, io) {
+    const src = await io.readFile(from);
+    if (src == null)
+        throw new Error(`runStudioAddApp: schema file not found: ${from}`);
+    return isPrismaSource(from, src) ? introspectPrismaAll(src) : introspectDrizzleAll(src);
+}
+/** Merge-write a set of generated files, preserving user edits outside managed regions. */
+async function writeAll(files, io) {
+    const written = [];
+    for (const file of files) {
+        const existing = await io.readFile(file.path);
+        // User-owned companions (a screen's `handlers.ts`) carry no managed markers -
+        // they're scaffolded once and then the developer's code forever. Skip if it
+        // already exists so a regenerate never clobbers hand-written logic. See
+        // HANDLERS-DESIGN.md (the round-trip contract).
+        if (skipUserOwned(file, existing != null))
+            continue;
+        // Regenerating? Replace only the managed region, keep the user's edits.
+        await io.writeFile(file.path, mergeManaged(existing, file.contents));
+        written.push(file.path);
+    }
+    return written;
+}
+export async function runStudioAdd(options, io) {
+    const schema = await resolveSchema(options, io);
+    const { files } = scaffold(schema, options);
+    const written = await writeAll(files, io);
+    const verify = await verifyScaffold(files);
+    return { schema, written, verify };
+}
+/**
+ * Scaffold a whole multi-entity app - every entity's screen plus a nav layout
+ * and home page - and merge-write it. The `--all` path behind `svgrid-studio`.
+ */
+export async function runStudioAddApp(schemas, options, io) {
+    const { files } = scaffoldApp(schemas, options);
+    const written = await writeAll(files, io);
+    const verify = await verifyScaffold(files);
+    return { written, verify };
+}

package/dist/studio/copilot-core.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Studio Copilot - the pure, testable core. Builds the model request for "edit
+ * this project per the user's instruction" and parses/validates the model's
+ * reply back into a StudioProject. No network here: the CLI designer server
+ * does the actual Anthropic call (keys stay server-side), and the designer
+ * additionally re-validates + puts the result on the undo stack, so a bad
+ * edit is one Ctrl+Z away.
+ */
+import { type StudioProject } from './project.js';
+export type CopilotMessages = {
+    system: string;
+    messages: Array<{
+        role: 'user';
+        content: string;
+    }>;
+};
+/** The system + user messages for one copilot edit round. */
+export declare function buildCopilotMessages(prompt: string, project: StudioProject): CopilotMessages;
+/** Parse the model's reply into a validated StudioProject. Tolerates a fenced
+ *  code block or stray prose around the JSON; throws with a useful message when
+ *  the reply isn't a valid project. */
+export declare function projectFromModelText(text: string): StudioProject;

package/{src/studio/copilot-core.ts → dist/studio/copilot-core.js}

@@ -6,19 +6,13 @@
  * additionally re-validates + puts the result on the undo stack, so a bad
  * edit is one Ctrl+Z away.
  */
-import { parseProject, serializeProject, validateProject, blockPalette, type StudioProject } from './project.js'
-import { UI_COMPONENT_REGISTRY } from './ui-components.js'
-
-export type CopilotMessages = {
-  system: string
-  messages: Array<{ role: 'user'; content: string }>
-}
-
+import { parseProject, serializeProject, validateProject, blockPalette } from './project.js';
+import { UI_COMPONENT_REGISTRY } from './ui-components.js';
 /** The system + user messages for one copilot edit round. */
-export function buildCopilotMessages(prompt: string, project: StudioProject): CopilotMessages {
-  const kinds = blockPalette.map((p) => p.kind).join(', ')
-  const components = UI_COMPONENT_REGISTRY.map((c) => c.key).join(', ')
-  const system = `You are SvGrid Studio's copilot. You edit a Studio project - the JSON model of a data app - according to the user's instruction, and return the COMPLETE updated project as JSON.
+export function buildCopilotMessages(prompt, project) {
+    const kinds = blockPalette.map((p) => p.kind).join(', ');
+    const components = UI_COMPONENT_REGISTRY.map((c) => c.key).join(', ');
+    const system = `You are SvGrid Studio's copilot. You edit a Studio project - the JSON model of a data app - according to the user's instruction, and return the COMPLETE updated project as JSON.
 
 The model, briefly:
 - entities: EntitySchema[] - { name, label, idField, fields: [{ field, label, type, primaryKey?, required?, formula?, options?: [{value,label,color?}], relation?: { entity, labelField } }] }. Field types: text | number | boolean | date | datetime | enum | relation | json.
@@ -32,34 +26,36 @@ Rules:
 - New ids: short kebab/lower-camel strings unique within the project.
 - New entities need at least an id/primary-key field and a label-ish field; give enum fields options with value+label; seed realistic demo data is NOT required.
 - New screens need a unique route and at least one block bound to their entity.
-- Prefer editing over rebuilding; keep the user's structure and naming style.`
-  return {
-    system,
-    messages: [
-      {
-        role: 'user',
-        content: `Current project JSON:\n${serializeProject(project)}\n\nInstruction: ${prompt}\n\nReturn the complete updated project JSON.`,
-      },
-    ],
-  }
+- Prefer editing over rebuilding; keep the user's structure and naming style.`;
+    return {
+        system,
+        messages: [
+            {
+                role: 'user',
+                content: `Current project JSON:\n${serializeProject(project)}\n\nInstruction: ${prompt}\n\nReturn the complete updated project JSON.`,
+            },
+        ],
+    };
 }
-
 /** Parse the model's reply into a validated StudioProject. Tolerates a fenced
  *  code block or stray prose around the JSON; throws with a useful message when
  *  the reply isn't a valid project. */
-export function projectFromModelText(text: string): StudioProject {
-  let candidate = text.trim()
-  const fence = candidate.match(/```(?:json)?\s*([\s\S]*?)```/)
-  if (fence) candidate = fence[1]!.trim()
-  if (!candidate.startsWith('{')) {
-    // Stray prose: cut to the outermost object literal.
-    const start = candidate.indexOf('{')
-    const end = candidate.lastIndexOf('}')
-    if (start === -1 || end <= start) throw new Error('Copilot reply contained no JSON object.')
-    candidate = candidate.slice(start, end + 1)
-  }
-  const project = parseProject(candidate) // throws on malformed/invalid shapes
-  const errors = validateProject(project).filter((i) => i.level === 'error')
-  if (errors.length) throw new Error(`Copilot returned an invalid project: ${errors.map((e) => e.message).join(' ')}`)
-  return project
+export function projectFromModelText(text) {
+    let candidate = text.trim();
+    const fence = candidate.match(/```(?:json)?\s*([\s\S]*?)```/);
+    if (fence)
+        candidate = fence[1].trim();
+    if (!candidate.startsWith('{')) {
+        // Stray prose: cut to the outermost object literal.
+        const start = candidate.indexOf('{');
+        const end = candidate.lastIndexOf('}');
+        if (start === -1 || end <= start)
+            throw new Error('Copilot reply contained no JSON object.');
+        candidate = candidate.slice(start, end + 1);
+    }
+    const project = parseProject(candidate); // throws on malformed/invalid shapes
+    const errors = validateProject(project).filter((i) => i.level === 'error');
+    if (errors.length)
+        throw new Error(`Copilot returned an invalid project: ${errors.map((e) => e.message).join(' ')}`);
+    return project;
 }

package/dist/studio/csv.d.ts

@@ -0,0 +1,36 @@
+/**
+ * CSV / spreadsheet import - turn a pasted or uploaded CSV into a runnable
+ * entity: infer an `EntitySchema` from the header + values, and return the
+ * parsed rows (coerced to real JS types) so they can seed a data source.
+ *
+ * Pure and dependency-free: a hand-rolled RFC-4180-ish reader (quoted fields,
+ * escaped `""`, embedded newlines, CRLF), then per-column type inference. The
+ * Studio generator and the visual designer both call `csvToEntity` to add a
+ * table from a file the user drops in - no backend, no parsing library.
+ */
+import type { EntitySchema } from '../schema.js';
+/**
+ * Sniff the field delimiter from the first (unquoted) line: whichever of
+ * `,` `;` `\t` `|` occurs most. Handles Excel/European exports (`;`) and TSV.
+ */
+export declare function detectDelimiter(text: string): ',' | ';' | '\t' | '|';
+/** Parse CSV/TSV text into a matrix of string cells. Handles quotes, `""`, embedded
+ *  newlines, CRLF, and auto-detects the delimiter (comma / semicolon / tab / pipe). */
+export declare function parseCsv(text: string, delimiter?: string): string[][];
+export type CsvEntity = {
+    schema: EntitySchema;
+    rows: Array<Record<string, unknown>>;
+    /** Fields whose header was renamed to a safe key (original -> key), for a UI note. */
+    renamed: Array<{
+        header: string;
+        field: string;
+    }>;
+};
+/**
+ * Parse CSV text into a ready-to-use entity: an `EntitySchema` (types inferred
+ * per column, an `id` primary key ensured) plus the coerced rows to seed with.
+ *
+ * If the file has no id-like column, a synthetic string `id` (`"1"`, `"2"`, ...)
+ * is added so the grid, edit form, and CRUD have a stable row key.
+ */
+export declare function csvToEntity(name: string, text: string): CsvEntity;

package/dist/studio/csv.js

@@ -0,0 +1,173 @@
+import { refineFields } from '../sources/field-inference.js';
+/**
+ * Sniff the field delimiter from the first (unquoted) line: whichever of
+ * `,` `;` `\t` `|` occurs most. Handles Excel/European exports (`;`) and TSV.
+ */
+export function detectDelimiter(text) {
+    const s = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+    const firstLine = s.slice(0, (s.indexOf('\n') + 1 || s.length + 1) - 1);
+    const candidates = [',', ';', '\t', '|'];
+    let best = ',';
+    let bestCount = -1;
+    for (const d of candidates) {
+        // Count only outside quotes so a comma inside "a,b" doesn't sway the guess.
+        let count = 0, inQ = false;
+        for (const ch of firstLine) {
+            if (ch === '"')
+                inQ = !inQ;
+            else if (ch === d && !inQ)
+                count++;
+        }
+        if (count > bestCount) {
+            bestCount = count;
+            best = d;
+        }
+    }
+    return best;
+}
+/** Parse CSV/TSV text into a matrix of string cells. Handles quotes, `""`, embedded
+ *  newlines, CRLF, and auto-detects the delimiter (comma / semicolon / tab / pipe). */
+export function parseCsv(text, delimiter) {
+    const delim = delimiter ?? detectDelimiter(text);
+    const rows = [];
+    let row = [];
+    let field = '';
+    let inQuotes = false;
+    // Strip a UTF-8 BOM if present so the first header isn't polluted.
+    const s = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+    for (let i = 0; i < s.length; i++) {
+        const c = s[i];
+        if (inQuotes) {
+            if (c === '"') {
+                if (s[i + 1] === '"') {
+                    field += '"';
+                    i++;
+                } // escaped quote
+                else
+                    inQuotes = false;
+            }
+            else
+                field += c;
+        }
+        else if (c === '"') {
+            inQuotes = true;
+        }
+        else if (c === delim) {
+            row.push(field);
+            field = '';
+        }
+        else if (c === '\n') {
+            row.push(field);
+            field = '';
+            rows.push(row);
+            row = [];
+        }
+        else if (c === '\r') {
+            // swallow; the paired \n (or EOF) ends the row
+        }
+        else {
+            field += c;
+        }
+    }
+    // Flush the trailing field/row (files without a final newline).
+    if (field !== '' || row.length > 0) {
+        row.push(field);
+        rows.push(row);
+    }
+    // Drop fully-empty trailing rows (a blank final line).
+    return rows.filter((r) => !(r.length === 1 && r[0] === ''));
+}
+const TRUE_SET = new Set(['true', 'yes', 'y', '1']);
+const FALSE_SET = new Set(['false', 'no', 'n', '0']);
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+const DATETIME_RE = /^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}/;
+const NUMBER_RE = /^-?(?:\d{1,3}(?:,\d{3})+|\d+)(?:\.\d+)?$/; // 1200, -3.5, 1,200
+/** Coerce one raw cell to a JS value, given the column's inferred type. Empty -> null. */
+function coerce(raw, type) {
+    const v = raw.trim();
+    if (v === '')
+        return null;
+    switch (type) {
+        case 'number': return Number(v.replace(/,/g, ''));
+        case 'boolean': return TRUE_SET.has(v.toLowerCase());
+        default: return v; // text / date / datetime / json stay strings (grid + schema handle them)
+    }
+}
+/** Infer a column's type from all its non-empty raw values. Defaults to text. */
+function inferColumnType(values) {
+    const nonEmpty = values.map((v) => v.trim()).filter((v) => v !== '');
+    if (nonEmpty.length === 0)
+        return 'text';
+    const all = (pred) => nonEmpty.every(pred);
+    if (all((v) => NUMBER_RE.test(v)))
+        return 'number';
+    if (all((v) => TRUE_SET.has(v.toLowerCase()) || FALSE_SET.has(v.toLowerCase())))
+        return 'boolean';
+    if (all((v) => DATETIME_RE.test(v)))
+        return 'datetime';
+    if (all((v) => DATE_RE.test(v)))
+        return 'dateString';
+    return 'text';
+}
+/** Turn a header string into a safe, camel-ish field key. */
+function toFieldKey(header, index, taken) {
+    let key = header.trim().replace(/[^\w]+/g, '_').replace(/^_+|_+$/g, '').toLowerCase();
+    if (/^\d/.test(key))
+        key = 'col_' + key;
+    if (!key)
+        key = `col_${index + 1}`;
+    let unique = key, n = 2;
+    while (taken.has(unique))
+        unique = `${key}_${n++}`;
+    taken.add(unique);
+    return unique;
+}
+/**
+ * Parse CSV text into a ready-to-use entity: an `EntitySchema` (types inferred
+ * per column, an `id` primary key ensured) plus the coerced rows to seed with.
+ *
+ * If the file has no id-like column, a synthetic string `id` (`"1"`, `"2"`, ...)
+ * is added so the grid, edit form, and CRUD have a stable row key.
+ */
+export function csvToEntity(name, text) {
+    const matrix = parseCsv(text);
+    if (matrix.length === 0)
+        return { schema: { name, fields: [] }, rows: [], renamed: [] };
+    const headers = matrix[0];
+    const body = matrix.slice(1);
+    const taken = new Set();
+    const renamed = [];
+    const cols = headers.map((h, i) => {
+        const field = toFieldKey(h, i, taken);
+        const values = body.map((r) => r[i] ?? '');
+        const type = inferColumnType(values);
+        if (field !== h.trim())
+            renamed.push({ header: h.trim() || `Column ${i + 1}`, field });
+        return { field, type, index: i };
+    });
+    const rows = body.map((r) => {
+        const obj = {};
+        for (const c of cols)
+            obj[c.field] = coerce(r[c.index] ?? '', c.type);
+        return obj;
+    });
+    // Ensure a primary key: reuse an existing id-like column, else synthesize one.
+    const idCol = cols.find((c) => c.field === 'id') ?? cols.find((c) => /(^|_)id$/.test(c.field));
+    if (!idCol) {
+        rows.forEach((row, i) => { row.id = String(i + 1); });
+        cols.unshift({ field: 'id', type: 'text', index: -1 });
+    }
+    const fields = cols.map((c) => {
+        const f = { field: c.field, type: c.type };
+        const isId = idCol ? c.field === idCol.field : c.field === 'id';
+        if (isId) {
+            f.primaryKey = true;
+            f.readonly = true;
+        }
+        return f;
+    });
+    // Let introspectJson refine any 'json'/edge types from the actual coerced values,
+    // but keep our column types + pk decisions (they saw every row, not just the first).
+    const schema = refineFields({ name, fields });
+    return { schema, rows, renamed };
+}

package/dist/studio/db-connect-string.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Connection-string helpers for the Studio "connect your database" flow. A
+ * guided form collects host / port / database / user / password / SSL and
+ * `buildConnectionString` assembles the driver-ready URL, so users never have to
+ * hand-write `postgresql://user:pass@host:5432/db`. `parseConnectionString` does
+ * the reverse (best-effort) to pre-fill the form from a pasted URL, and
+ * `redactConnectionString` masks the password for display / logs.
+ *
+ * Pure and node-safe (no driver, no node APIs) - shared by the designer server,
+ * the CLI, and the (private) designer SPA, which imports it from
+ * `@svgrid/enterprise/studio`.
+ */
+import type { SqlDialectName } from './introspect-db.js';
+export type SqlConnectionParts = {
+    host?: string;
+    port?: number | string;
+    database?: string;
+    user?: string;
+    password?: string;
+    /** Require TLS (adds the dialect's SSL query param). */
+    ssl?: boolean;
+    /** SQLite only: path to the `.db` file (host / user / etc are ignored). */
+    file?: string;
+};
+/** The npm driver package each dialect needs installed to connect. */
+export declare const DRIVER_PACKAGE: Record<SqlDialectName, string>;
+/** The default TCP port per dialect (null for the file-based SQLite). */
+export declare const DEFAULT_PORT: Record<SqlDialectName, number | null>;
+/** SQLite is a file on disk - the form shows a path field, not host/port/auth. */
+export declare function isFileDialect(dialect: SqlDialectName): boolean;
+/**
+ * Assemble a driver-ready connection string from the guided-form fields. SQLite
+ * returns the bare file path (what better-sqlite3 expects); every other dialect
+ * returns a URL with the credentials percent-encoded so passwords containing
+ * `@`, `:` or `/` don't corrupt it.
+ */
+export declare function buildConnectionString(dialect: SqlDialectName, parts: SqlConnectionParts): string;
+/**
+ * Best-effort inverse of `buildConnectionString` - split a pasted URL back into
+ * form fields so the guided form can pre-fill. Returns `{}` when the input isn't
+ * a parseable URL (the caller keeps whatever the user typed).
+ */
+export declare function parseConnectionString(dialect: SqlDialectName, value: string): SqlConnectionParts;
+/** Mask the password in a connection string for display / logging. */
+export declare function redactConnectionString(value: string): string;

package/dist/studio/db-connect-string.js

@@ -0,0 +1,113 @@
+/** The npm driver package each dialect needs installed to connect. */
+export const DRIVER_PACKAGE = {
+    postgres: 'pg',
+    supabase: 'pg',
+    mysql: 'mysql2',
+    mssql: 'mssql',
+    sqlite: 'better-sqlite3',
+};
+/** The default TCP port per dialect (null for the file-based SQLite). */
+export const DEFAULT_PORT = {
+    postgres: 5432,
+    supabase: 5432,
+    mysql: 3306,
+    mssql: 1433,
+    sqlite: null,
+};
+/** SQLite is a file on disk - the form shows a path field, not host/port/auth. */
+export function isFileDialect(dialect) {
+    return dialect === 'sqlite';
+}
+function urlScheme(dialect) {
+    if (dialect === 'mysql')
+        return 'mysql';
+    if (dialect === 'mssql')
+        return 'mssql';
+    return 'postgresql'; // postgres + supabase
+}
+function sslQuery(dialect, ssl) {
+    if (!ssl)
+        return '';
+    if (dialect === 'mysql')
+        return `?ssl=${encodeURIComponent('{"rejectUnauthorized":true}')}`;
+    if (dialect === 'mssql')
+        return '?encrypt=true&trustServerCertificate=true';
+    return '?sslmode=require'; // postgres + supabase
+}
+/**
+ * Assemble a driver-ready connection string from the guided-form fields. SQLite
+ * returns the bare file path (what better-sqlite3 expects); every other dialect
+ * returns a URL with the credentials percent-encoded so passwords containing
+ * `@`, `:` or `/` don't corrupt it.
+ */
+export function buildConnectionString(dialect, parts) {
+    if (isFileDialect(dialect)) {
+        const file = (parts.file ?? parts.database ?? '').trim();
+        if (!file)
+            throw new Error('buildConnectionString: SQLite needs a database file path');
+        return file;
+    }
+    const host = (parts.host ?? '').trim() || 'localhost';
+    const portRaw = parts.port != null && `${parts.port}`.trim() !== '' ? Number(parts.port) : DEFAULT_PORT[dialect];
+    const port = Number.isFinite(portRaw) ? portRaw : null;
+    const db = (parts.database ?? '').trim();
+    const user = (parts.user ?? '').trim();
+    const pass = parts.password ?? '';
+    const auth = user
+        ? `${encodeURIComponent(user)}${pass ? `:${encodeURIComponent(pass)}` : ''}@`
+        : '';
+    const hostPort = port ? `${host}:${port}` : host;
+    const dbPath = db ? `/${encodeURIComponent(db)}` : '';
+    return `${urlScheme(dialect)}://${auth}${hostPort}${dbPath}${sslQuery(dialect, parts.ssl)}`;
+}
+/**
+ * Best-effort inverse of `buildConnectionString` - split a pasted URL back into
+ * form fields so the guided form can pre-fill. Returns `{}` when the input isn't
+ * a parseable URL (the caller keeps whatever the user typed).
+ */
+export function parseConnectionString(dialect, value) {
+    const raw = (value ?? '').trim();
+    if (!raw)
+        return {};
+    if (isFileDialect(dialect))
+        return { file: raw };
+    try {
+        const u = new URL(raw);
+        const parts = {};
+        if (u.hostname)
+            parts.host = u.hostname;
+        if (u.port)
+            parts.port = Number(u.port);
+        const db = u.pathname.replace(/^\//, '');
+        if (db)
+            parts.database = decodeURIComponent(db);
+        if (u.username)
+            parts.user = decodeURIComponent(u.username);
+        if (u.password)
+            parts.password = decodeURIComponent(u.password);
+        const q = u.searchParams;
+        if (q.get('sslmode') === 'require' || q.has('ssl') || q.get('encrypt') === 'true')
+            parts.ssl = true;
+        return parts;
+    }
+    catch {
+        return {};
+    }
+}
+/** Mask the password in a connection string for display / logging. */
+export function redactConnectionString(value) {
+    const raw = (value ?? '').trim();
+    if (!raw)
+        return raw;
+    try {
+        const u = new URL(raw);
+        if (!u.password)
+            return raw;
+        u.password = '***';
+        return u.toString();
+    }
+    catch {
+        // key=value strings (e.g. mssql "Password=...") and bare paths.
+        return raw.replace(/(password|pwd)=([^;&\s]+)/gi, '$1=***');
+    }
+}

package/dist/studio/deploy-cli.d.ts

@@ -0,0 +1,35 @@
+/**
+ * `svgrid-studio deploy` - the pure, testable core. Resolves WHICH provider to
+ * deploy to (explicit flag > studio.config.json's deploy target > the SvelteKit
+ * adapter in svelte.config.js - never a guess) and WHAT commands that means.
+ * The thin CLI in @svgrid/studio does the file reads + process spawning.
+ */
+export type DeployProvider = 'vercel' | 'netlify' | 'cloudflare' | 'node';
+export type DeployResolution = {
+    ok: true;
+    provider: DeployProvider;
+    source: 'flag' | 'config' | 'adapter';
+} | {
+    ok: false;
+    reason: string;
+};
+/** Resolve the deploy provider from the inputs the CLI gathered (all optional). */
+export declare function resolveDeployTarget(inputs: {
+    flag?: string;
+    configJson?: string | null;
+    svelteConfig?: string | null;
+}): DeployResolution;
+export type DeployPlanCommands = {
+    provider: DeployProvider;
+    /** Run first - validates the app compiles before anything leaves the machine. */
+    build: string;
+    /** The provider CLI command, or null when there's nothing to run (node target). */
+    deploy: string | null;
+    /** Shown before running (login hints, what the command does). */
+    notes: string[];
+};
+/** The commands a provider deploy runs - same one-liners the generated `deploy` script uses. */
+export declare function deployCommands(provider: DeployProvider): DeployPlanCommands;
+/** Env keys declared in .env.example (uncommented `KEY=` lines) that are absent
+ *  from the local .env - surfaced as a preflight warning before deploying. */
+export declare function missingEnvKeys(envExample: string | null, envLocal: string | null): string[];

package/dist/studio/deploy-cli.js

@@ -0,0 +1,81 @@
+/**
+ * `svgrid-studio deploy` - the pure, testable core. Resolves WHICH provider to
+ * deploy to (explicit flag > studio.config.json's deploy target > the SvelteKit
+ * adapter in svelte.config.js - never a guess) and WHAT commands that means.
+ * The thin CLI in @svgrid/studio does the file reads + process spawning.
+ */
+const PROVIDERS = ['vercel', 'netlify', 'cloudflare', 'node'];
+/** Adapter package -> provider (what svelte.config.js imports). */
+const ADAPTERS = [
+    ['@sveltejs/adapter-vercel', 'vercel'],
+    ['@sveltejs/adapter-netlify', 'netlify'],
+    ['@sveltejs/adapter-cloudflare', 'cloudflare'],
+    ['@sveltejs/adapter-node', 'node'],
+];
+const GUIDANCE = 'Set a target: pass --target vercel|netlify|cloudflare|node, pick a deploy target in the Studio designer ' +
+    '(saved to studio.config.json), or pin a concrete SvelteKit adapter in svelte.config.js.';
+/** Resolve the deploy provider from the inputs the CLI gathered (all optional). */
+export function resolveDeployTarget(inputs) {
+    const { flag, configJson, svelteConfig } = inputs;
+    if (flag !== undefined) {
+        if (PROVIDERS.includes(flag))
+            return { ok: true, provider: flag, source: 'flag' };
+        return { ok: false, reason: `Unknown --target "${flag}". Use one of: ${PROVIDERS.join(' | ')}.` };
+    }
+    if (configJson) {
+        try {
+            const deploy = JSON.parse(configJson).deploy;
+            if (deploy && PROVIDERS.includes(deploy))
+                return { ok: true, provider: deploy, source: 'config' };
+            // 'auto' (or unset) means the project never chose a provider - don't guess one.
+        }
+        catch {
+            /* unreadable config - fall through to the adapter */
+        }
+    }
+    if (svelteConfig) {
+        for (const [pkg, provider] of ADAPTERS)
+            if (svelteConfig.includes(pkg))
+                return { ok: true, provider, source: 'adapter' };
+    }
+    return { ok: false, reason: `No deploy target configured. ${GUIDANCE}` };
+}
+/** The commands a provider deploy runs - same one-liners the generated `deploy` script uses. */
+export function deployCommands(provider) {
+    switch (provider) {
+        case 'vercel':
+            return { provider, build: 'npm run build', deploy: 'npx vercel deploy --prod', notes: ['Needs a Vercel login (npx vercel login) and a linked project (first run prompts to link).'] };
+        case 'netlify':
+            return { provider, build: 'npm run build', deploy: 'npx netlify deploy --build --prod', notes: ['Needs a Netlify login (npx netlify login) and a linked site (npx netlify link).'] };
+        case 'cloudflare':
+            return { provider, build: 'npm run build', deploy: 'npx wrangler pages deploy', notes: ['Needs a Cloudflare login (npx wrangler login).'] };
+        case 'node':
+            return {
+                provider,
+                build: 'npm run build',
+                deploy: null,
+                notes: [
+                    'The node target has no hosted provider - after the build, run it yourself:',
+                    '  node build            # serves on PORT (default 3000)',
+                    '  docker build -t app . && docker run -p 3000:3000 --env-file .env app',
+                ],
+            };
+    }
+}
+/** Env keys declared in .env.example (uncommented `KEY=` lines) that are absent
+ *  from the local .env - surfaced as a preflight warning before deploying. */
+export function missingEnvKeys(envExample, envLocal) {
+    if (!envExample)
+        return [];
+    const declared = envExample
+        .split('\n')
+        .map((l) => l.trim())
+        .filter((l) => /^[A-Z][A-Z0-9_]*=/.test(l))
+        .map((l) => l.slice(0, l.indexOf('=')));
+    const present = new Set((envLocal ?? '')
+        .split('\n')
+        .map((l) => l.trim())
+        .filter((l) => /^[A-Z][A-Z0-9_]*=.+/.test(l))
+        .map((l) => l.slice(0, l.indexOf('='))));
+    return declared.filter((k) => !present.has(k));
+}