@kernhq/module-quire 0.13.1 → 0.15.0

package/src/client/transfers.ts

@@ -0,0 +1,142 @@
+import type { ExportFormat, ExportScope, ImportSource, TransferState } from '../contract/index.js'
+import { t } from './i18n.js'
+
+/**
+ * The bits of the transfer screens that are not a screen.
+ *
+ * Two dialogs and a page draw the same four vocabularies — a scope, a format, a source and a state
+ * — and the same download. Written out once here because the alternative is four copies of a
+ * `switch` that has to agree with the contract's enums: a `TransferState` gaining a fifth member
+ * would then be four silent gaps rather than one type error.
+ *
+ * Every label is a function rather than a constant. A module is defined once at import time while
+ * the interface language can change afterwards, so a map built at module scope would be frozen in
+ * whatever language happened to be loaded first — the same reason `module.ts` writes its nav labels
+ * as getters.
+ */
+
+/** The four states, as a person reads them rather than as the column stores them. */
+export function stateLabel(state: TransferState): string {
+  return state === 'queued'
+    ? t('transfer_queued')
+    : state === 'running'
+      ? t('transfer_running')
+      : state === 'done'
+        ? t('transfer_done')
+        : t('transfer_failed')
+}
+
+/**
+ * What a state looks like at a glance.
+ *
+ * `queued` and `running` share the spinner deliberately: the difference between "a worker has not
+ * picked this up" and "a worker is on it" is the sentence beside the icon, not the icon — two
+ * different in-progress glyphs would be two things to learn for one meaning.
+ */
+export function stateIcon(state: TransferState): string {
+  return state === 'done' ? 'circle-check' : state === 'failed' ? 'triangle-alert' : 'loader'
+}
+
+/** Where the export took its pages from. */
+export function scopeLabel(scope: ExportScope): string {
+  return scope === 'page'
+    ? t('export_scope_page')
+    : scope === 'subtree'
+      ? t('export_scope_subtree')
+      : t('export_scope_space')
+}
+
+/**
+ * The formats a person may actually pick.
+ *
+ * `docx` is in `ExportFormat` and is not here, because the server refuses it at `exports.start` —
+ * see `services/export.ts` for why a Word file nothing in this repository can open is worse than a
+ * refusal. Offering a control whose only outcome is an error is the shape this list exists to
+ * prevent; the dialog says the same thing in a sentence instead, which answers the question
+ * ("where is Word?") without pretending to have an answer it does not have.
+ */
+export const EXPORT_FORMATS: readonly Exclude<ExportFormat, 'docx'>[] = ['markdown', 'html', 'pdf']
+
+export function formatLabel(format: ExportFormat): string {
+  return format === 'markdown'
+    ? t('export_format_markdown')
+    : format === 'html'
+      ? t('export_format_html')
+      : format === 'pdf'
+        ? t('export_format_pdf')
+        : t('export_format_docx')
+}
+
+export function formatDescription(format: Exclude<ExportFormat, 'docx'>): string {
+  return format === 'markdown'
+    ? t('export_format_markdown_desc')
+    : format === 'html'
+      ? t('export_format_html_desc')
+      : t('export_format_pdf_desc')
+}
+
+export const IMPORT_SOURCES: readonly ImportSource[] = ['notion', 'confluence', 'markdown']
+
+export function sourceLabel(source: ImportSource): string {
+  return source === 'notion'
+    ? t('import_source_notion')
+    : source === 'confluence'
+      ? t('import_source_confluence')
+      : t('import_source_markdown')
+}
+
+export function sourceDescription(source: ImportSource): string {
+  return source === 'notion'
+    ? t('import_source_notion_desc')
+    : source === 'confluence'
+      ? t('import_source_confluence_desc')
+      : t('import_source_markdown_desc')
+}
+
+/** Neither `done` nor `failed`, so something is still going to happen to it. */
+export const isRunning = (state: TransferState): boolean => state === 'queued' || state === 'running'
+
+/**
+ * How far along a job is, as a fraction, or `null` while there is nothing honest to draw.
+ *
+ * `total` is 0 until the job has finished counting what it is about to do, and a bar sitting at 0%
+ * for the first few seconds of every export reads as a job that is stuck. Null means "say it is
+ * running, in words" — which is true — rather than drawing a measurement nobody has taken.
+ */
+export function progressRatio(counts: {
+  total: number
+  done: number
+  skipped: number
+  failed: number
+}): number | null {
+  if (counts.total <= 0) return null
+  const seen = counts.done + counts.skipped + counts.failed
+  return Math.max(0, Math.min(1, seen / counts.total))
+}
+
+/**
+ * Fetch an artefact the browser has just been given a link to.
+ *
+ * A hidden anchor rather than `location.href`, and rather than `window.open`: `open` is what a
+ * pop-up blocker stops when it happens after an `await`, and assigning `location` sends the whole
+ * document at a URL that only *usually* comes back as a download. A click on an `<a>` is the one
+ * gesture every browser treats as "fetch this file", and the page it happened on is untouched.
+ *
+ * `filename` is honoured for a same-origin address only — the `download` attribute is ignored
+ * cross-origin, which is every real instance, where the name comes from the `Content-Disposition`
+ * the presigned URL was signed with. It is passed anyway because `dev:mock` hands back a `data:`
+ * URL, and there the attribute is the only thing that names the file.
+ */
+export function startDownload(url: string, filename?: string): void {
+  const anchor = document.createElement('a')
+  anchor.href = url
+  anchor.rel = 'noreferrer noopener'
+  if (filename) anchor.download = filename
+  anchor.style.display = 'none'
+  document.body.appendChild(anchor)
+  anchor.click()
+  anchor.remove()
+}
+
+/** An error as a line of text, whatever was thrown. */
+export const messageOf = (err: unknown): string => (err instanceof Error ? err.message : String(err))

package/src/contract/models.ts

@@ -321,4 +321,347 @@ export const Publication = z.object({
 })
 export type Publication = z.infer<typeof Publication>
 
+// =====================================================================================
+// Getting work in and out
+// =====================================================================================
+
+/**
+ * How much of the tree an export takes.
+ *
+ * `page` is one page; `subtree` is a page and everything under it; `space` is every page in a space.
+ * The three are not a convenience — they are the three questions people actually ask ("send me this",
+ * "send me this section", "get us off this product"), and the middle one is the one a flat
+ * page-by-page export cannot answer without somebody clicking three hundred times.
+ */
+export const ExportScope = z.enum(['page', 'subtree', 'space'])
+export type ExportScope = z.infer<typeof ExportScope>
+
+/**
+ * What comes out.
+ *
+ * `html` and `pdf` are rendered by the same static renderer the public site uses — never the live
+ * document and never the draft, so an export of a `page` is what a reader is served rather than what
+ * the last person to open it happened to be typing.
+ */
+export const ExportFormat = z.enum(['markdown', 'html', 'docx', 'pdf'])
+export type ExportFormat = z.infer<typeof ExportFormat>
+
+/** Where a transfer is. `done` and `failed` are terminal; nothing moves out of either. */
+export const TransferState = z.enum(['queued', 'running', 'done', 'failed'])
+export type TransferState = z.infer<typeof TransferState>
+
+/**
+ * A job's own progress, shared by both directions.
+ *
+ * `skipped` is the counter that matters and the one a progress bar leaves out. An export skips a page
+ * the requester may not read; an import skips a file it cannot map. Reporting the count is the
+ * difference between an artefact that is quietly missing things and one that says how many.
+ *
+ * Every field defaults, so a job that has not started yet parses as four zeroes rather than as
+ * absent — a client should never have to distinguish "no progress" from "no counters".
+ */
+export const TransferCounts = z.object({
+  total: z.number().int().nonnegative().default(0),
+  done: z.number().int().nonnegative().default(0),
+  skipped: z.number().int().nonnegative().default(0),
+  failed: z.number().int().nonnegative().default(0),
+})
+export type TransferCounts = z.infer<typeof TransferCounts>
+
+/**
+ * A request to take a page, a subtree or a space out of Quire as a file.
+ *
+ * There is no artefact URL here and there should not be. `fileId` is an opaque id, not an address:
+ * the download is a signed URL a procedure mints per request, so that the fence on who may fetch a
+ * subtree export — which flattens pages of different readerships into one file — is applied at the
+ * moment of the fetch rather than baked into a link that outlives it. A client that builds a storage
+ * key from an id is the mistake `migrations/0009` had to go back and scrub out of published HTML.
+ */
+export const ExportJob = z.object({
+  id: Id,
+  workspaceId: WorkspaceId,
+  requestedBy: UserId,
+  scope: ExportScope,
+  /** the page for `page` and `subtree`, the space for `space`; `scope` says which */
+  targetId: Id,
+  format: ExportFormat,
+  state: TransferState,
+  /** null until the job succeeds — an artefact that is still being written is not offered */
+  fileId: Id.nullable(),
+  /**
+   * Why it failed, in the words of whatever failed — a Gotenberg refusal, the name of a page that
+   * would not render. Diagnostic, not a user-facing string: a screen says its piece from a message
+   * key chosen by `state`, and shows this beside it for the person who has to act on it.
+   */
+  error: z.string().nullable(),
+  counts: TransferCounts,
+  createdAt: Timestamp,
+  /** null while `queued` or `running` */
+  finishedAt: Timestamp.nullable(),
+})
+export type ExportJob = z.infer<typeof ExportJob>
+
+/** What kind of export is being read in. */
+export const ImportSource = z.enum(['notion', 'confluence', 'markdown'])
+export type ImportSource = z.infer<typeof ImportSource>
+
+/**
+ * What happened to one file.
+ *
+ * Three outcomes and not two, because "not imported" covers two different situations a person needs
+ * to tell apart: a file Quire deliberately did not want (an asset already inlined, a Notion index
+ * page that duplicates the folder) is `skipped`, and a file that should have become a page and did
+ * not is `failed`. Collapsing them turns a broken import into a tidy-looking one.
+ */
+export const ImportOutcome = z.enum(['imported', 'skipped', 'failed'])
+export type ImportOutcome = z.infer<typeof ImportOutcome>
+
+/**
+ * One row of the report: what the file was, what became of it, and which.
+ *
+ * The failure list is the feature. A real Notion export has files that will not map, and an import
+ * that silently drops forty pages is worse than one that refuses — so every file in the upload gets
+ * an entry, including the ones that worked, and the report is complete rather than a list of
+ * complaints. `path` is the path inside the archive, which is what somebody has to go and look at.
+ */
+export const ImportReportEntry = z.object({
+  /** the file's path inside the uploaded archive, exactly as it appeared */
+  path: z.string(),
+  outcome: ImportOutcome,
+  /** the page it became, for `imported`; null for the other two */
+  pageId: Id.nullable().default(null),
+  /**
+   * Why, for `skipped` and `failed`; null for `imported`.
+   *
+   * Free text on purpose: the reasons are as varied as the exports people have, and a closed enum
+   * here would either be wrong within a week or force every unexpected file into an `other` that
+   * tells nobody anything.
+   */
+  reason: z.string().nullable().default(null),
+})
+export type ImportReportEntry = z.infer<typeof ImportReportEntry>
+
+/**
+ * A Notion export zip, a Confluence export or a folder of Markdown, on its way into one space.
+ *
+ * `sourceFileId` is the upload, not an artefact — the opposite direction from `ExportJob.fileId`, and
+ * named differently for that reason. An import produces pages, not a file.
+ *
+ * Internal links between imported pages are rewritten to Quire page ids as the import goes; a link
+ * that cannot be resolved becomes plain text rather than a dead link, and the page that carried it
+ * still counts as `imported`. That choice is why `report` is per *file* and not per *link*: a page
+ * that arrived with one unresolvable link is an imported page, not a failure.
+ */
+export const ImportJob = z.object({
+  id: Id,
+  workspaceId: WorkspaceId,
+  requestedBy: UserId,
+  source: ImportSource,
+  /** the space being written into. An import always targets one space; there is no scope here. */
+  targetId: Id,
+  /** the uploaded archive — consumed by the job, and present before the job exists */
+  sourceFileId: Id,
+  state: TransferState,
+  /** why the *job* failed; why one *file* failed is that file's entry in `report` */
+  error: z.string().nullable(),
+  counts: TransferCounts,
+  /** one entry per file in the upload, in the order they were read */
+  report: z.array(ImportReportEntry),
+  createdAt: Timestamp,
+  /** null while `queued` or `running` */
+  finishedAt: Timestamp.nullable(),
+})
+export type ImportJob = z.infer<typeof ImportJob>
+
+// =====================================================================================
+// Templates
+// =====================================================================================
+
+/**
+ * What a template makes.
+ *
+ * `page` — one page; the body is a page doc.
+ * `space` — a whole space; the body is a tree of pages, each with its own body.
+ *
+ * Two rather than one with a "just make the root" flag, because they are made from different places
+ * and answer different questions: a page template is offered on "New page" inside a space that
+ * already exists, and a space template is what somebody reaches for when there is no space yet.
+ */
+export const TemplateKind = z.enum(['page', 'space'])
+export type TemplateKind = z.infer<typeof TemplateKind>
+
+/**
+ * The starters this module ships.
+ *
+ * **They are constants in the module, not rows in a customer's database**, and the key is what a
+ * constant has instead of an id. `migrations/0011_templates.sql` argues the choice at length; the
+ * short of it is that a migration runs once per *database* and has no workspace to seed into, that a
+ * seeded row is frozen at the release that wrote it, and that a row holds one language in a product
+ * that ships five.
+ *
+ * A workspace edits a starter by **overriding** it: a `Template` row carrying one of these keys takes
+ * that starter's place in the picker rather than sitting beside it, so the first edit writes one row,
+ * a workspace that never touches them has none, and resetting is deleting the row.
+ *
+ * `Template.key` is deliberately **not** this enum — see the comment there.
+ */
+export const TemplateStarterKey = z.enum([
+  'meeting-notes',
+  'decision-record',
+  'requirements',
+  'retrospective',
+  'how-to',
+])
+export type TemplateStarterKey = z.infer<typeof TemplateStarterKey>
+export const TEMPLATE_STARTER_KEYS = TemplateStarterKey.options
+
+/**
+ * What a variable's type decides, which is **the control somebody is shown and not the storage**.
+ *
+ * Every filled value is substituted into prose as text, whatever the type: `{{sprint}}` in a heading
+ * becomes characters in a heading. The type is what turns "type the date" into a date picker and
+ * "type one of these four" into a menu — the difference between a form somebody fills correctly and
+ * one they fill approximately.
+ */
+export const TemplateVariableType = z.enum(['text', 'number', 'date', 'select', 'user'])
+export type TemplateVariableType = z.infer<typeof TemplateVariableType>
+
+/**
+ * The names a template author may not take, because the module already fills them.
+ *
+ * `date` and `author` are the two the plan names. The other three are reserved now rather than
+ * later, and that is the whole reason the list is longer than it needs to be today: adding
+ * `{{time}}` in a future release would silently change what an existing template renders if some
+ * author had already declared a variable of that name. Reserving a name costs an author one
+ * synonym; taking one back costs somebody a document that used to be right.
+ */
+export const TEMPLATE_BUILT_IN_VARIABLES = ['date', 'time', 'author', 'space', 'workspace'] as const
+
+/**
+ * What appears between the braces.
+ *
+ * ASCII, lowercase, no spaces — the same shape as `Space.key` and for the same reason: this string
+ * is matched against the body, so `{{Sprint}}` and `{{sprint}}` being two variables is exactly the
+ * near-duplicate that `labels_ws_space_name_uq` refuses next door. An author's own language belongs
+ * in `label`, which is the half a person actually reads.
+ */
+export const TemplateVariableName = z
+  .string()
+  .min(1)
+  .max(40)
+  .regex(/^[a-z][a-z0-9_]*$/, 'lowercase letters, digits and underscores, starting with a letter')
+  .refine(
+    (name) => !(TEMPLATE_BUILT_IN_VARIABLES as readonly string[]).includes(name),
+    'that name is filled by the module itself',
+  )
+
+/**
+ * One thing somebody is asked before the page is made.
+ *
+ * Every field but `name`, `label` and `type` defaults, so a variable written by an older client
+ * still parses. Note what that does to the *output* type: it makes them required, so anything
+ * constructing a variable supplies all six — which is the point, and the reason a widened contract
+ * is additive for parsing and breaking for constructing.
+ */
+export const TemplateVariable = z.object({
+  name: TemplateVariableName,
+  /** what the person filling it in reads; their own language goes here, not in `name` */
+  label: z.string().min(1).max(120),
+  type: TemplateVariableType,
+  /** the menu, for `select`; empty for every other type */
+  options: z.array(z.string().min(1).max(120)).max(50).default([]),
+  /** what the field starts with — text whatever the type, because substitution is textual */
+  default: z.string().max(2000).nullable().default(null),
+  /** whether the page can be made without it */
+  required: z.boolean().default(false),
+})
+export type TemplateVariable = z.infer<typeof TemplateVariable>
+
+/**
+ * One page of a space template, and everything under it.
+ *
+ * Recursive because a space is a tree and flattening it into a list with parent pointers would mean
+ * inventing local ids that exist only inside the column — an identifier nothing outside this
+ * document ever resolves. The depth is bounded by the space it was made from.
+ *
+ * The type is written out and the schema annotated with it, rather than left to inference, because
+ * a self-referencing `const` has no type TypeScript can name on its own and the package emits
+ * declarations.
+ */
+export type TemplateSpaceNode = {
+  title: string
+  icon: string | null
+  doc: Record<string, unknown>
+  children: TemplateSpaceNode[]
+}
+export const TemplateSpaceNode: z.ZodType<TemplateSpaceNode, TemplateSpaceNode> = z.lazy(() =>
+  z.object({
+    title: z.string().max(300),
+    icon: z.string().max(64).nullable(),
+    /** the page's body, with the same `{{variables}}` in it as any other */
+    doc: RichDoc,
+    children: z.array(TemplateSpaceNode),
+  }),
+)
+
+/**
+ * The body of a `space` template: the tree, under one key.
+ *
+ * An object rather than a bare array so that `Template.doc` is a JSON object for both kinds — the
+ * column defaults to `'{}'`, and a default that is the wrong *type* for half the rows is a default
+ * that lies. It also means the two bodies are told apart by their keys rather than by `typeof`.
+ */
+export const TemplateSpaceBody = z.object({ pages: z.array(TemplateSpaceNode) })
+export type TemplateSpaceBody = z.infer<typeof TemplateSpaceBody>
+
+/**
+ * A page, or a whole space, saved so it can be made again.
+ *
+ * `doc` is left opaque here for the reason `RichDoc` is: this file is not what knows the shape of a
+ * document. It is a page doc when `kind` is `page` and a `TemplateSpaceBody` when `kind` is `space`,
+ * and the server parses the second with the schema above.
+ *
+ * A shipped starter is not one of these — it has no id, no workspace and no timestamps, because it
+ * is a constant. What the picker returns is the starters and these together, with a row carrying a
+ * starter's `key` standing in for that starter.
+ */
+export const Template = z.object({
+  id: Id,
+  workspaceId: WorkspaceId,
+  /** null is workspace-wide; a space id scopes it to one space. Always null when `kind` is `space`. */
+  spaceId: Id.nullable(),
+  kind: TemplateKind,
+  /**
+   * The starter this row replaces, or null for somebody's own template.
+   *
+   * `z.string()` and **not** `TemplateStarterKey`, deliberately. This is stored data: a release that
+   * stopped shipping a starter would turn every override of it into a parse failure, which is a
+   * picker that throws rather than a picker missing one entry. A key naming a starter that no longer
+   * exists is an ordinary custom template, and the read side treats it as one.
+   */
+  key: z.string().min(1).max(64).nullable(),
+  /** true exactly when `key` is set — the database holds the pair to that with a check constraint */
+  builtIn: z.boolean(),
+  name: z.string().min(1).max(120),
+  description: z.string().max(2000),
+  /** a Lucide icon name, or an emoji */
+  icon: z.string().max(64).nullable(),
+  doc: RichDoc,
+  variables: z.array(TemplateVariable),
+  createdBy: UserId.nullable(),
+  createdAt: Timestamp,
+  updatedAt: Timestamp,
+})
+export type Template = z.infer<typeof Template>
+
+/**
+ * A template without its body.
+ *
+ * This exists so that opening a picker does not download every template's prose to draw a list of
+ * names — thirty page docs to render thirty rows, of which one is ever used. The body is fetched
+ * when a template is chosen.
+ */
+export const TemplateSummary = Template.omit({ doc: true })
+export type TemplateSummary = z.infer<typeof TemplateSummary>
+
 export const Ok = z.object({ ok: z.literal(true) })

package/src/contract/permissions.ts

@@ -64,6 +64,56 @@ export const quirePermissions = definePermissions([
     defaultRoles: ['owner', 'admin', 'member'],
     dangerous: false,
   },
+  /**
+   * Taking pages out of Kern as a file.
+   *
+   * A separate key from `quire.page.view` rather than a consequence of it, and the distinction is
+   * one administrators actually make: reading a handbook a page at a time and walking out with the
+   * whole thing in a zip are different acts, and the second is the one a leaver does on their last
+   * afternoon. Every page in an export is still checked against `quire.page.view` as it is written,
+   * so this grants nothing extra — it decides whether the bulk shape is available at all.
+   *
+   * Not `dangerous`, because it destroys nothing and every page in the result is one the exporter
+   * could already open. The import side is the dangerous half: that one writes.
+   *
+   * A guest is deliberately not in the default set. A guest is somebody invited to read one thing,
+   * and the difference between reading it and keeping a copy of the section around it is exactly
+   * what a guest is a guest for.
+   */
+  {
+    key: 'quire.page.export',
+    label: 'Export pages',
+    description: 'Take a page, a section or a space out as Markdown, HTML or PDF',
+    scope: 'space',
+    defaultRoles: ['owner', 'admin', 'member'],
+    dangerous: false,
+  },
+  /**
+   * Bringing pages in from somewhere else, in bulk.
+   *
+   * **`dangerous`, where the export half is not**, and the asymmetry is the whole reason this is a
+   * separate key rather than `quire.page.create` applied a thousand times. An export reads pages the
+   * exporter could already open; an import *writes* — hundreds of pages, a page tree, databases with
+   * their columns — into a space, in one act, from a file nobody in the workspace has read. Undoing
+   * it means finding every page it made and trashing them, which is not a button. The tracker marks
+   * `tracker.import.run` the same way and for the same reason.
+   *
+   * Owner and admin only, and that is a deliberate step up from `quire.page.create`. Somebody who may
+   * write in a space is not thereby somebody who may reshape it: an ordinary member creating pages
+   * makes them one at a time, with the tree in front of them.
+   *
+   * It is not a substitute for the narrower keys. An import still writes only where the requester
+   * holds this permission *on that space*, and the job re-asks when it runs rather than trusting the
+   * answer from when it was queued — a permission taken away between the two is a job that fails.
+   */
+  {
+    key: 'quire.page.import',
+    label: 'Import pages',
+    description: 'Bring a Notion, Confluence or Markdown export into a space as pages',
+    scope: 'space',
+    defaultRoles: ['owner', 'admin'],
+    dangerous: true,
+  },
   {
     key: 'quire.page.delete',
     label: 'Delete pages permanently',
@@ -205,6 +255,73 @@ export const quireProcedureAuthz: Record<string, ProcedureAuthz> = {
   'databases.removeView': { check: 'page', permission: 'quire.page.edit' },
   'databases.setRelation': { check: 'page', permission: 'quire.page.edit' },
 
+  /*
+   * `start` is declared `page` because that is the branch that can be bound narrowly and therefore
+   * the branch worth proving: a `page` or `subtree` export resolves the target page's own ancestor
+   * chain and asks about it, so a page-scoped DENY of `quire.page.export` refuses the export of that
+   * page and of any section containing it. A `space` export has no one page to resolve — it is the
+   * whole space — so that branch asks the same permission at space scope, which is the narrowest
+   * scope that exists for it. `export.int.test.ts` covers the space branch against a space-scoped
+   * DENY, because the sweep in `authz.int.test.ts` only ever sends the page branch.
+   *
+   * `get` and `list` are `workspace` for the same reason `favorites.list` is: "my own exports" has
+   * no narrower scope. What keeps them private is not a permission at all but the `requested_by`
+   * filter in the query — row-level security fences the tenant, and a tenant is not a person.
+   */
+  'exports.start': { check: 'page', permission: 'quire.page.export' },
+  'exports.get': { check: 'workspace', permission: 'quire.page.export' },
+  'exports.list': { check: 'workspace', permission: 'quire.page.export' },
+
+  /*
+   * `start` is `space` where its export counterpart is `page`, and the difference is not an
+   * oversight. An import has no page to be scoped to — it *creates* the pages — so the space it
+   * writes into is the narrowest scope that exists for it, and a space-scoped DENY of
+   * `quire.page.import` is what has to refuse it. The check is asked twice on purpose: once here,
+   * before a row is recorded, and again inside the job as the person who asked, because a job runs
+   * minutes later and a permission can be taken away in between.
+   *
+   * `get` and `list` are `workspace` for the same reason `exports.get` and `favorites.list` are:
+   * "my own imports" has no narrower scope. What keeps them private is the `requested_by` filter in
+   * the query rather than a permission — row-level security fences the tenant, and a tenant is not
+   * a person.
+   */
+  'imports.start': { check: 'space', permission: 'quire.page.import' },
+  'imports.get': { check: 'workspace', permission: 'quire.page.import' },
+  'imports.list': { check: 'workspace', permission: 'quire.page.import' },
+
+  /*
+   * A template is a space's furniture, so it follows `labels.*` exactly: reading is
+   * `quire.space.view` and writing is `quire.space.manage`. Changing one changes what everybody in
+   * the space is offered the next time they make a page, which is not a thing somebody who may edit
+   * one page should be able to do to everybody else's.
+   *
+   * Three of the five are `check: 'space'` although four of them take a *template* id, not a space
+   * id. A template id carries no scope of its own, so the row is read first and the question is
+   * asked about the space it belongs to — the same shape as `labels.update` next door. A
+   * workspace-wide template (`space_id is null`) has no narrower scope than the workspace, and the
+   * handlers say so out loud rather than silently falling back to the space of whoever asked.
+   *
+   * `createFromPage` is the one that is `check: 'page'`, and it is the interesting one: it *copies a
+   * page's prose into a template*, so the question that actually protects anything is whether this
+   * person may read that page. A page-scoped DENY of `quire.page.view` has to refuse it, or a
+   * contractor allowed one page of a handbook could lift a page they cannot open into a template and
+   * read it there. `quire.space.manage` is asked as well, in the same handler, and
+   * `templates.int.test.ts` covers that half — this column names one permission, and the one worth
+   * proving with a page-scoped binding is the read.
+   *
+   * `instantiate` asks `quire.page.create` and not `space.manage`: what it does is make a page.
+   * Somebody who may write in a space may use its templates; only somebody who configures the space
+   * may change them. Its `space` branch — which makes a *space* — asks `quire.space.manage` at
+   * workspace scope on top, for the same reason `spaces.create` does; the sweep sends the page
+   * branch, and `templates.int.test.ts` covers the other.
+   */
+  'templates.list': { check: 'space', permission: 'quire.space.view' },
+  'templates.get': { check: 'space', permission: 'quire.space.view' },
+  'templates.createFromPage': { check: 'page', permission: 'quire.page.view' },
+  'templates.update': { check: 'space', permission: 'quire.space.manage' },
+  'templates.remove': { check: 'space', permission: 'quire.space.manage' },
+  'templates.instantiate': { check: 'space', permission: 'quire.page.create' },
+
   'publishing.publish': { check: 'page', permission: 'quire.page.publish' },
   'publishing.revert': { check: 'page', permission: 'quire.page.edit' },