@svgrid/enterprise 1.2.0 → 2.0.0

package/src/sources/with-entity-rules.test.ts

@@ -0,0 +1,104 @@
+import { describe, expect, it, vi } from 'vitest'
+import type { ServerDataSource, ServerRequest } from '@svgrid/grid'
+import type { EntitySchema } from '../schema'
+import { withEntityRules } from './with-entity-rules'
+
+type Order = { id: string; qty: number; price: number; total: number; createdAt?: string }
+
+const schema: EntitySchema<Order> = {
+  name: 'orders',
+  idField: 'id',
+  fields: [
+    { field: 'id', type: 'text', primaryKey: true, readonly: true },
+    { field: 'qty', type: 'number', required: true },
+    { field: 'price', type: 'number', required: true },
+    { field: 'total', type: 'number', computed: (r) => Number(r.qty) * Number(r.price) },
+  ],
+}
+
+const req: ServerRequest = { startRow: 0, endRow: 10, pageIndex: 0, pageSize: 10, sortModel: [], filterModel: {} }
+
+/** A tiny in-memory source we can wrap. */
+function makeSource(seed: Order[] = []): ServerDataSource<Order> {
+  let rows = [...seed]
+  return {
+    async getRows() {
+      return { rows: [...rows], rowCount: rows.length }
+    },
+    async createRow(input) {
+      const row = { id: 'x', qty: 0, price: 0, total: 0, ...input } as Order
+      rows = [...rows, row]
+      return row
+    },
+    async updateRow(id, patch) {
+      const row = { ...rows.find((r) => r.id === id)!, ...patch }
+      rows = rows.map((r) => (r.id === id ? row : r))
+      return row
+    },
+    async deleteRow(id) {
+      rows = rows.filter((r) => r.id !== id)
+    },
+  }
+}
+
+describe('withEntityRules - computed materialization', () => {
+  it('materializes computed fields on getRows', async () => {
+    const source = withEntityRules(makeSource([{ id: '1', qty: 3, price: 10, total: 0 }]), schema)
+    const { rows } = await source.getRows(req)
+    expect(rows[0]!.total).toBe(30)
+  })
+
+  it('materializes computed fields on the created/updated row', async () => {
+    const source = withEntityRules(makeSource(), schema)
+    const created = await source.createRow!({ id: '1', qty: 2, price: 5 })
+    expect(created.total).toBe(10)
+    const updated = await source.updateRow!('1', { qty: 4, price: 5 })
+    expect(updated.total).toBe(20)
+  })
+})
+
+describe('withEntityRules - hooks', () => {
+  it('runs beforeCreate to transform the payload and afterCreate as a side effect', async () => {
+    const afterCreate = vi.fn()
+    const withHooks: EntitySchema<Order> = {
+      ...schema,
+      hooks: { beforeCreate: (v) => ({ ...v, createdAt: '2026-01-01' }), afterCreate },
+    }
+    const source = withEntityRules(makeSource(), withHooks)
+    const row = await source.createRow!({ id: '1', qty: 1, price: 1 })
+    expect(row.createdAt).toBe('2026-01-01')
+    expect(afterCreate).toHaveBeenCalledWith(expect.objectContaining({ id: '1' }))
+  })
+
+  it('rejects a write when cross-field validate fails', async () => {
+    const withHooks: EntitySchema<Order> = {
+      ...schema,
+      hooks: { validate: (v) => (Number(v.qty) <= 0 ? { qty: 'Quantity must be positive' } : null) },
+    }
+    const source = withEntityRules(makeSource(), withHooks)
+    await expect(source.createRow!({ id: '1', qty: 0, price: 5 })).rejects.toThrow(/Quantity must be positive/)
+  })
+
+  it('vetoes a delete when beforeDelete throws', async () => {
+    const withHooks: EntitySchema<Order> = {
+      ...schema,
+      hooks: { beforeDelete: () => { throw new Error('locked') } },
+    }
+    const source = withEntityRules(makeSource([{ id: '1', qty: 1, price: 1, total: 1 }]), withHooks)
+    await expect(source.deleteRow!('1')).rejects.toThrow(/locked/)
+  })
+
+  it('leaves optional write methods absent when the source lacks them', () => {
+    const readOnly: ServerDataSource<Order> = { getRows: async () => ({ rows: [], rowCount: 0 }) }
+    const wrapped = withEntityRules(readOnly, schema)
+    expect(wrapped.createRow).toBeUndefined()
+    expect(wrapped.deleteRow).toBeUndefined()
+  })
+
+  it('passes through extra source capabilities (getAggregate)', () => {
+    const getAggregate = vi.fn()
+    const source = Object.assign(makeSource(), { getAggregate })
+    const wrapped = withEntityRules(source, schema)
+    expect((wrapped as typeof source).getAggregate).toBe(getAggregate)
+  })
+})

package/src/sources/with-entity-rules.ts

@@ -0,0 +1,78 @@
+/**
+ * withEntityRules - apply an `EntitySchema`'s computed fields and lifecycle
+ * hooks to any `ServerDataSource`, at the mutation boundary. It's a transparent
+ * wrapper: pass the result to `createServerDataSource` (or straight to the grid)
+ * and every read row gets its computed fields materialized, while writes run the
+ * schema's before/after hooks and cross-field validation.
+ *
+ *   const source = withEntityRules(createSqlDataSource(...), orderSchema)
+ *
+ * - `getRows`   -> each row through `applyComputed` (grid can sort/filter the
+ *                  computed value within the fetched page).
+ * - `createRow` -> `hooks.validate` + `hooks.beforeCreate` (may transform the
+ *                  payload or throw), then `applyComputed` on the returned row,
+ *                  then `hooks.afterCreate`.
+ * - `updateRow` -> the same with `beforeUpdate` / `afterUpdate`.
+ * - `deleteRow` -> `hooks.beforeDelete` (throw to veto) then `hooks.afterDelete`.
+ *
+ * Optional write methods stay optional, and any extra source capabilities
+ * (`getAggregate`, `rows()`) pass through untouched. Returning `applyComputed`
+ * rows from every method keeps the controller's optimistic reconciliation
+ * correct (a source must return the same row shape from all methods).
+ */
+import type { RowData, ServerDataSource } from '@svgrid/grid'
+import { applyComputed, validateEntity, type EntitySchema } from '../schema'
+
+function firstError(errors: Record<string, string>): string {
+  return Object.values(errors)[0] ?? 'Validation failed'
+}
+
+export function withEntityRules<TData extends RowData, S extends ServerDataSource<TData>>(
+  source: S,
+  schema: EntitySchema<TData>,
+): S {
+  const hooks = schema.hooks ?? {}
+  const compute = (row: TData) => applyComputed(schema, row)
+
+  const wrapped: ServerDataSource<TData> = {
+    async getRows(request) {
+      const res = await source.getRows(request)
+      return { ...res, rows: res.rows.map(compute) }
+    },
+  }
+
+  if (source.createRow) {
+    const create = source.createRow.bind(source)
+    wrapped.createRow = async (input) => {
+      const errors = await validateEntity(schema, input)
+      if (Object.keys(errors).length) throw new Error(firstError(errors))
+      const payload = hooks.beforeCreate ? await hooks.beforeCreate(input) : input
+      const row = compute(await create(payload))
+      await hooks.afterCreate?.(row)
+      return row
+    }
+  }
+
+  if (source.updateRow) {
+    const update = source.updateRow.bind(source)
+    wrapped.updateRow = async (id, patch) => {
+      const errors = await validateEntity(schema, patch)
+      if (Object.keys(errors).length) throw new Error(firstError(errors))
+      const payload = hooks.beforeUpdate ? await hooks.beforeUpdate(id, patch) : patch
+      const row = compute(await update(id, payload))
+      await hooks.afterUpdate?.(row)
+      return row
+    }
+  }
+
+  if (source.deleteRow) {
+    const del = source.deleteRow.bind(source)
+    wrapped.deleteRow = async (id) => {
+      await hooks.beforeDelete?.(id)
+      await del(id)
+      await hooks.afterDelete?.(id)
+    }
+  }
+
+  return { ...source, ...wrapped } as S
+}

package/src/sources/with-relation-labels.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it, vi } from 'vitest'
+import type { EntitySchema } from '../schema'
+import { createInMemoryDataSource } from '../sveltekit/in-memory'
+import { createRelationLookup } from './relation-lookup'
+import { withRelationLabels } from './with-relation-labels'
+
+type User = { id: string; name: string }
+type Post = { id: string; title: string; authorId: string; author?: string }
+
+const userSchema: EntitySchema<User> = {
+  name: 'users', idField: 'id',
+  fields: [{ field: 'id', type: 'text', primaryKey: true }, { field: 'name', type: 'text' }],
+}
+const postSchema: EntitySchema<Post> = {
+  name: 'posts', idField: 'id',
+  fields: [
+    { field: 'id', type: 'text', primaryKey: true },
+    { field: 'title', type: 'text' },
+    { field: 'authorId', type: 'relation', relation: { entity: 'users', labelField: 'name' } },
+    { field: 'author', type: 'text', readonly: true },
+  ],
+}
+
+function setup() {
+  const users = createInMemoryDataSource<User>(
+    [{ id: 'u1', name: 'Ada' }, { id: 'u2', name: 'Alan' }],
+    userSchema,
+  )
+  const rawPosts = createInMemoryDataSource<Post>(
+    [{ id: 'p1', title: 'A', authorId: 'u1' }, { id: 'p2', title: 'B', authorId: 'u2' }],
+    postSchema,
+  )
+  const lookup = createRelationLookup<User>({ source: users, schema: userSchema, labelField: 'name' })
+  const posts = withRelationLabels(rawPosts, [{ fk: 'authorId', lookup, as: 'author' }])
+  return { posts }
+}
+
+describe('withRelationLabels', () => {
+  it('decorates getRows with the related label', async () => {
+    const { posts } = setup()
+    const { rows } = await posts.getRows({ startRow: 0, endRow: 10, pageIndex: 0, pageSize: 10, sortModel: [], filterModel: {} })
+    expect(rows.map((r) => r.author)).toEqual(['Ada', 'Alan'])
+  })
+
+  it('decorates the created / updated row (same shape from every method)', async () => {
+    const { posts } = setup()
+    const created = await posts.createRow!({ id: 'p3', title: 'C', authorId: 'u1' })
+    expect(created.author).toBe('Ada')
+    const updated = await posts.updateRow!('p3', { authorId: 'u2' })
+    expect(updated.author).toBe('Alan')
+  })
+
+  it('is a no-op with no relations', () => {
+    const raw = createInMemoryDataSource<Post>([], postSchema)
+    expect(withRelationLabels(raw, [])).toBe(raw)
+  })
+
+  it('batches label resolution to one query per page (no N+1)', async () => {
+    const users = createInMemoryDataSource<User>([{ id: 'u1', name: 'Ada' }, { id: 'u2', name: 'Alan' }], userSchema)
+    const spy = vi.spyOn(users, 'getRows')
+    const rawPosts = createInMemoryDataSource<Post>(
+      [
+        { id: 'p1', title: 'A', authorId: 'u1' },
+        { id: 'p2', title: 'B', authorId: 'u2' },
+        { id: 'p3', title: 'C', authorId: 'u1' },
+      ],
+      postSchema,
+    )
+    const lookup = createRelationLookup<User>({ source: users, schema: userSchema, labelField: 'name' })
+    const posts = withRelationLabels(rawPosts, [{ fk: 'authorId', lookup, as: 'author' }])
+    const { rows } = await posts.getRows({ startRow: 0, endRow: 10, pageIndex: 0, pageSize: 10, sortModel: [], filterModel: {} })
+    expect(rows.map((r) => r.author)).toEqual(['Ada', 'Alan', 'Ada'])
+    expect(spy).toHaveBeenCalledTimes(1) // 3 rows, 2 distinct authors -> ONE lookup query
+  })
+})

package/src/sources/with-relation-labels.ts

@@ -0,0 +1,73 @@
+/**
+ * withRelationLabels - decorate a source's rows with the human label of each
+ * foreign key, so the grid can show "Acme Inc" instead of the raw id `42`. It
+ * resolves labels through a `RelationLookup` (the same cached resolver the edit
+ * form's picker uses), so a value is fetched at most once and stays fresh.
+ *
+ *   const postsSource = withRelationLabels(rawPostsSource, [
+ *     { fk: 'authorId', lookup: authorLookup, as: 'author' },
+ *   ])
+ *
+ * Pair it with a schema where the FK field is `hidden: { grid: true }` and a
+ * read-only display column (`author`) shows the label. Because every method
+ * returns the decorated row shape, the controller's optimistic updates stay
+ * correct.
+ */
+import type { RowData, ServerDataSource } from '@svgrid/grid'
+import type { RelationLookup } from './relation-lookup'
+
+export type RelationLabelConfig = {
+  /** Local foreign-key field to resolve. */
+  fk: string
+  /** Resolver for the related entity (see `createRelationLookup`). */
+  lookup: RelationLookup
+  /** Field to write the resolved label onto. */
+  as: string
+}
+
+export function withRelationLabels<TData extends RowData, S extends ServerDataSource<TData>>(
+  source: S,
+  relations: RelationLabelConfig[],
+): S {
+  if (relations.length === 0) return source
+
+  /** Decorate one row (used by create/update returns). */
+  const decorate = async (row: TData): Promise<TData> => {
+    const copy = { ...(row as RowData) }
+    await Promise.all(
+      relations.map(async (r) => {
+        copy[r.as] = (await r.lookup.labelFor(row[r.fk])) ?? ''
+      }),
+    )
+    return copy as TData
+  }
+
+  const wrapped: ServerDataSource<TData> = {
+    async getRows(request) {
+      const res = await source.getRows(request)
+      // Batch: one lookup query per relation for the whole page (no N+1).
+      const maps = await Promise.all(
+        relations.map((r) => r.lookup.labelsFor(res.rows.map((row) => row[r.fk]))),
+      )
+      const rows = res.rows.map((row) => {
+        const copy = { ...(row as RowData) }
+        relations.forEach((r, i) => {
+          copy[r.as] = maps[i]!.get(String(row[r.fk])) ?? ''
+        })
+        return copy as TData
+      })
+      return { ...res, rows }
+    },
+  }
+  if (source.createRow) {
+    const fn = source.createRow.bind(source)
+    wrapped.createRow = async (input) => decorate(await fn(input))
+  }
+  if (source.updateRow) {
+    const fn = source.updateRow.bind(source)
+    wrapped.updateRow = async (id, patch) => decorate(await fn(id, patch))
+  }
+  if (source.deleteRow) wrapped.deleteRow = source.deleteRow.bind(source)
+
+  return { ...source, ...wrapped } as S
+}

package/src/studio/bug-report.test.ts

@@ -0,0 +1,101 @@
+import { describe, it, expect } from 'vitest'
+import type { EntitySchema } from '../schema.js'
+import { createProject, setEntityDataSource } from './project.js'
+import { sanitizeStudioProject, buildStudioBugReport } from './bug-report.js'
+
+const SUPABASE_URL = 'https://myproject.supabase.co'
+const SUPABASE_KEY = 'sb_secret_TOP_SECRET_KEY_123'
+const REST_TOKEN = 'Bearer LEAKED_AUTH_TOKEN_XYZ'
+const PRIVATE_ROW = 'Jane Doe SSN 123-45-6789'
+
+function entity(name: string): EntitySchema {
+  return { name, label: name, idField: 'id', fields: [
+    { field: 'id', type: 'text', primaryKey: true, readonly: true },
+    { field: 'name', type: 'text' },
+  ] }
+}
+
+function projectWithSecrets() {
+  let p = createProject([entity('customers'), entity('orders'), entity('notes')])
+  p = setEntityDataSource(p, 'customers', { kind: 'supabase', table: 'customers', url: SUPABASE_URL, key: SUPABASE_KEY })
+  p = setEntityDataSource(p, 'orders', {
+    kind: 'rest', baseUrl: 'https://api.example.com', path: 'orders', method: 'GET',
+    params: [
+      { name: 'Authorization', location: 'header', type: 'string', value: REST_TOKEN },
+      { name: 'region', location: 'query', type: 'string', value: 'eu' },
+    ],
+  })
+  p = setEntityDataSource(p, 'notes', { kind: 'memory', seed: [{ id: 'n1', name: PRIVATE_ROW }] })
+  return p
+}
+
+describe('sanitizeStudioProject', () => {
+  it('strips credentials + seed rows but keeps schema/screens', () => {
+    const { project, redactions } = sanitizeStudioProject(projectWithSecrets())
+    const json = JSON.stringify(project)
+
+    // No secret of any kind survives.
+    expect(json).not.toContain(SUPABASE_URL)
+    expect(json).not.toContain(SUPABASE_KEY)
+    expect(json).not.toContain(REST_TOKEN)
+    expect(json).not.toContain(PRIVATE_ROW)
+
+    // Non-secret structure is preserved (repro value).
+    expect(json).toContain('"region"') // a non-secret query param name stays
+    expect(json).toContain('eu')        // ...and its value
+    expect(project.entities.map((e) => e.name).sort()).toEqual(['customers', 'notes', 'orders'])
+
+    // Every removal is reported to the user.
+    expect(redactions.join('\n')).toMatch(/Supabase URL redacted/)
+    expect(redactions.join('\n')).toMatch(/Supabase key redacted/)
+    expect(redactions.join('\n')).toMatch(/Authorization.*redacted/)
+    expect(redactions.join('\n')).toMatch(/seed row\(s\) omitted/)
+    expect(redactions.length).toBe(4)
+  })
+
+  it('leaves a project with no secrets unchanged (no false redactions)', () => {
+    const p = createProject([entity('a')])
+    const { redactions } = sanitizeStudioProject(p)
+    // createProject defaults to a memory source with generated seed rows -> that
+    // seed IS data, so it's the only thing (if any) reported; never a credential.
+    expect(redactions.every((r) => !/redacted/i.test(r) || /seed/i.test(r))).toBe(true)
+  })
+})
+
+describe('buildStudioBugReport', () => {
+  it('never leaks secrets into the markdown or the prefilled issue URL', () => {
+    const report = buildStudioBugReport({
+      project: projectWithSecrets(),
+      error: new Error('Cannot read properties of undefined (reading "blocks")'),
+      action: 'generating the app',
+      env: { studioVersion: '0.1.0', node: 'v22.0.0', os: 'win32' },
+    })
+    for (const secret of [SUPABASE_URL, SUPABASE_KEY, REST_TOKEN, PRIVATE_ROW]) {
+      expect(report.markdown).not.toContain(secret)
+      expect(report.issueUrl).not.toContain(encodeURIComponent(secret))
+      expect(report.issueUrl).not.toContain(secret)
+    }
+    expect(report.title).toContain('[Studio]')
+    expect(report.issueUrl).toContain('https://github.com/sv-grid/sv-grid/issues/new')
+    expect(report.markdown).toContain('Sanitized studio.config.json')
+    expect(report.redactions.length).toBe(4)
+  })
+
+  it('truncates the URL for a large project (falls back to paste-the-markdown)', () => {
+    // A project big enough that the full report exceeds the URL cap.
+    const many = Array.from({ length: 40 }, (_, i) => entity(`e${i}`))
+    let p = createProject(many)
+    for (const e of many) p = setEntityDataSource(p, e.name, { kind: 'memory', seed: [] })
+    const report = buildStudioBugReport({ project: p, env: {} })
+    expect(report.truncated).toBe(true)
+    expect(report.issueUrl.length).toBeLessThanOrEqual(7500)
+    expect(report.issueUrl).toContain('issues/new')
+  })
+
+  it('works with no project (a plain crash report)', () => {
+    const report = buildStudioBugReport({ error: 'boom', env: { studioVersion: '0.1.0' } })
+    expect(report.title).toBe('[Studio] boom')
+    expect(report.markdown).toContain('boom')
+    expect(report.redactions).toEqual([])
+  })
+})

package/src/studio/bug-report.ts

@@ -0,0 +1,165 @@
+/**
+ * Studio bug-report core (pure + node-safe, usable from the CLI and the
+ * designer). Two pieces:
+ *
+ *   - `sanitizeStudioProject` - strip credentials + seed DATA from a project so
+ *     a bug report never leaks a user's database or rows. It keeps the SCHEMA,
+ *     screens, and block structure (what actually reproduces a Studio bug) and
+ *     returns a plain-language list of what was removed, so the user sees it.
+ *   - `buildStudioBugReport` - assemble a markdown report + a prefilled GitHub
+ *     "new issue" URL. The URL carries a short summary (GitHub caps the prefill
+ *     ~8 KB); the full sanitized report goes in `markdown` for the caller to
+ *     copy to the clipboard / write to a file and paste in.
+ *
+ * The caller supplies `env` (version / node / os) so this stays free of any
+ * process or DOM access and is trivially testable.
+ */
+import type { EntityDataSource, StudioProject } from './project.js'
+
+const REDACTED = '<redacted>'
+const DEFAULT_REPO = 'sv-grid/sv-grid'
+/** Keep the prefilled issue URL comfortably under browser / GitHub limits. */
+const MAX_URL = 7500
+/** Param names that carry secrets (substring, case-insensitive). */
+const SECRET_NAME_RE = /(key|token|secret|auth|password|pass|bearer|credential)/i
+
+export type SanitizeResult = { project: StudioProject; redactions: string[] }
+
+/** Redact one entity's data source; push a human note for anything removed. */
+function sanitizeSource(entity: string, src: EntityDataSource, redactions: string[]): EntityDataSource {
+  if (src.kind === 'memory') {
+    const { seed, ...rest } = src
+    if (seed?.length) redactions.push(`${entity}: ${seed.length} in-memory seed row(s) omitted`)
+    return rest
+  }
+  if (src.kind === 'pglite') {
+    const { seed, ...rest } = src
+    if (seed?.length) redactions.push(`${entity}: ${seed.length} local-database seed row(s) omitted`)
+    return rest
+  }
+  if (src.kind === 'supabase') {
+    const out = { ...src }
+    if (out.url) { out.url = REDACTED; redactions.push(`${entity}: Supabase URL redacted`) }
+    if (out.key) { out.key = REDACTED; redactions.push(`${entity}: Supabase key redacted`) }
+    return out
+  }
+  if (src.kind === 'rest') {
+    const params = src.params.map((p) => {
+      // Header params and secret-named params carry auth; drop their values.
+      if (p.value && (p.location === 'header' || SECRET_NAME_RE.test(p.name))) {
+        redactions.push(`${entity}: REST ${p.location} param "${p.name}" value redacted`)
+        return { ...p, value: REDACTED }
+      }
+      return p
+    })
+    let baseUrl = src.baseUrl
+    if (/[?&](key|token|apikey|secret|auth|password)=/i.test(baseUrl)) {
+      baseUrl = baseUrl.replace(/([?&](?:key|token|apikey|secret|auth|password)=)[^&]*/gi, `$1${REDACTED}`)
+      redactions.push(`${entity}: credentials in REST baseUrl redacted`)
+    }
+    return { ...src, baseUrl, params }
+  }
+  // sql: the connection string lives in the host env, not the model - nothing to strip.
+  return src
+}
+
+/**
+ * Return a copy of the project safe to attach to a bug report: credentials and
+ * seeded rows removed, schema + screens + blocks intact. Also returns a list of
+ * exactly what was stripped, for transparency.
+ */
+export function sanitizeStudioProject(project: StudioProject): SanitizeResult {
+  const redactions: string[] = []
+  if (!project.dataSources) return { project, redactions }
+  const nextSources: Record<string, EntityDataSource> = {}
+  for (const [name, src] of Object.entries(project.dataSources)) {
+    nextSources[name] = sanitizeSource(name, src, redactions)
+  }
+  return { project: { ...project, dataSources: nextSources }, redactions }
+}
+
+export type StudioEnv = { studioVersion?: string; node?: string; os?: string }
+
+export type BugReportInput = {
+  /** The current project model (studio.config.json). Sanitized before use. */
+  project?: StudioProject
+  /** The error that triggered the report (on a crash), if any. */
+  error?: Error | { message: string; stack?: string } | string
+  /** What the user was doing (e.g. "generating the app", "editing the CRM board"). */
+  action?: string
+  env?: StudioEnv
+  /** `owner/repo` the issue targets (default the public SvGrid repo). */
+  repo?: string
+}
+
+export type BugReport = {
+  title: string
+  /** Full markdown report - copy to clipboard / write to a file and paste in. */
+  markdown: string
+  /** Prefilled GitHub "new issue" URL. */
+  issueUrl: string
+  redactions: string[]
+  /** True when the report was too big for the URL, so `markdown` must be pasted. */
+  truncated: boolean
+}
+
+function normalizeError(e: BugReportInput['error']): { message: string; stack?: string } | undefined {
+  if (!e) return undefined
+  if (typeof e === 'string') return { message: e }
+  return { message: e.message, stack: 'stack' in e ? e.stack : undefined }
+}
+
+function newIssueUrl(repo: string, title: string, body: string): string {
+  const q = new URLSearchParams({ title, body, labels: 'studio,bug' })
+  return `https://github.com/${repo}/issues/new?${q.toString()}`
+}
+
+function envLines(env: StudioEnv): string[] {
+  return [
+    `- Studio: ${env.studioVersion ?? 'unknown'}`,
+    `- Node: ${env.node ?? 'unknown'}`,
+    `- OS: ${env.os ?? 'unknown'}`,
+  ]
+}
+
+function renderSummary(env: StudioEnv, err: ReturnType<typeof normalizeError>, action: string | undefined, redactions: string[]): string {
+  const lines = ['### Environment', ...envLines(env), '']
+  if (action) lines.push('### What I was doing', action, '')
+  if (err) lines.push('### Error', '```', err.message, '```', '')
+  lines.push(`_${redactions.length} item(s) redacted (credentials + seed data)._`)
+  return lines.join('\n')
+}
+
+/**
+ * Build a shareable bug report from the current Studio state. The project is
+ * sanitized first; secrets never reach the markdown or the URL.
+ */
+export function buildStudioBugReport(input: BugReportInput): BugReport {
+  const env = input.env ?? {}
+  const err = normalizeError(input.error)
+  const { project, redactions } = input.project
+    ? sanitizeStudioProject(input.project)
+    : { project: undefined as StudioProject | undefined, redactions: [] as string[] }
+
+  const firstLine = (err?.message ?? 'Bug report').split('\n')[0]!.trim().slice(0, 100)
+  const title = `[Studio] ${firstLine}`
+
+  const md: string[] = ['## SvGrid Studio bug report', '', '### Environment', ...envLines(env), '']
+  if (input.action) md.push('### What I was doing', input.action, '')
+  if (err) md.push('### Error', '```', err.message, ...(err.stack ? ['', err.stack] : []), '```', '')
+  if (project) md.push('### Project', `${project.entities?.length ?? 0} entities, ${project.screens?.length ?? 0} screens.`, '')
+  md.push('### Redactions', redactions.length ? redactions.map((r) => `- ${r}`).join('\n') : '- none', '')
+  if (project) md.push('### Sanitized studio.config.json', '```json', JSON.stringify(project, null, 2), '```')
+  const markdown = md.join('\n')
+
+  const repo = input.repo ?? DEFAULT_REPO
+  let issueUrl = newIssueUrl(repo, title, markdown)
+  let truncated = false
+  if (issueUrl.length > MAX_URL) {
+    truncated = true
+    const body = `${renderSummary(env, err, input.action, redactions)}\n\n> The full sanitized report was copied to your clipboard - paste it below.`
+    issueUrl = newIssueUrl(repo, title, body)
+  }
+
+  return { title, markdown, issueUrl, redactions, truncated }
+}