@lincyaw/cli 0.0.0-stage → 1.0.0-rc.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,52 @@
-# Temporary Holding Version
+# @lincyaw/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The `presmium` command: `new`, `check`, `ir`, `build`, `dev` and `serve` for Presmium documents and workspaces.
+
+Part of [Presmium](https://github.com/Lincyaw/presmium), which turns structured teaching documents into web pages, slides, Jupyter notebooks and narrated lectures.
+
+## Install
+
+Most people install the `presmium` package, which brings this command with the renderers and the official plugins:
+
+```sh
+pnpm add -g @lincyaw/presmium
+```
+
+In a project that picks its own renderers and plugins, install the CLI with them (Node.js 22.19 or later):
+
+```sh
+pnpm add -D @lincyaw/cli @lincyaw/web @lincyaw/render-slides @lincyaw/render-notebook
+```
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `presmium check [deck]` | Compile and run the checks and publication checks (`--json`, `--update-lock`, `--env`, `--audience`, `--external-links`) |
+| `presmium ir [deck]` | Print the IR as JSON (`--out`) |
+| `presmium build [deck]` | Build `dist/ir.json` and `dist/<renderer>/` (`--to`, `--out`, `--audience`); at a workspace root, the workspace site in `dist/web/` |
+| `presmium dev [deck]` | Dev servers that update on save (`--to`, `--out`, `--server-port`, `--allow`) |
+| `presmium new [dir]` | A new lecture, workspace or plugin project (`--type`, `--title`, `--name`, `--no-git`); from `create-presmium`, which the `presmium` package brings |
+| `presmium serve [dir]` | The workspace service, on this machine: the documents and their sites, compiled on demand (`--port`, `--host`, `--operator-dir`, `--preview-origin`) |
+| `presmium studio [dir]` | The workbench (experimental), from `@lincyaw/studio` installed in the project (`--port`, `--host`); installed globally, it is `presmium-studio` |
+
+`[deck]` is a directory with `lecture.json` or an entry file, by default the current directory. Exit codes: 0 no errors, 1 error findings, 2 usage or internal error. `presmium --help` lists every option.
+
+## Testing plugins
+
+`@lincyaw/cli/testing` runs the real command in a child process, for integration tests:
+
+```ts
+import { presmium } from '@lincyaw/cli/testing'
+
+const { code, stdout } = await presmium(dir, ['build', '--to', 'web'])
+```
+
+## Documentation
+
+- [Author guide](https://github.com/Lincyaw/presmium/blob/main/site/guide/locales/en/lecture.json)
+- [Plugin guide](https://github.com/Lincyaw/presmium/blob/main/site/plugins/locales/en/lecture.json)
+
+## License
+
+Apache-2.0

package/bin/presmium.mjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import { createJiti } from 'jiti'
+
+const emitWarning = process.emitWarning
+process.emitWarning = (warning, ...args) => {
+  const code = typeof args[0] === 'object' ? args[0]?.code : args[1]
+  if (code !== 'DEP0040') emitWarning.call(process, warning, ...args)
+}
+
+const jiti = createJiti(import.meta.url)
+const { main } = await jiti.import('../src/cli.ts')
+process.exitCode = await main(process.argv.slice(2))

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@lincyaw/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0-rc.1",
+  "description": "The presmium command: build, dev, ir, check and serve for Presmium documents",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Lincyaw/presmium.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/Lincyaw/presmium/tree/main/packages/cli#readme",
+  "bugs": "https://github.com/Lincyaw/presmium/issues",
+  "keywords": [
+    "presmium",
+    "cli",
+    "myst",
+    "slides"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22.19"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "presmium": "./bin/presmium.mjs"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./testing": "./src/testing.ts"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "dependencies": {
+    "jiti": "^2.7.0",
+    "@lincyaw/kernel": "1.0.0-rc.1",
+    "@lincyaw/compiler": "1.0.0-rc.1",
+    "@lincyaw/server": "1.0.0-rc.1",
+    "@lincyaw/workspace": "1.0.0-rc.1",
+    "@lincyaw/skills": "1.0.0-rc.1"
+  }
 }

package/src/check.ts

@@ -0,0 +1,91 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { ANCHOR_LOCK_PATH, errorMessage } from '@lincyaw/kernel'
+import type { AnchorString, Finding } from '@lincyaw/kernel'
+import { checkContext, Compiler, sortFindings } from '@lincyaw/compiler'
+import type { Compilation, CompilerOptions } from '@lincyaw/compiler'
+
+export interface CheckOptions {
+  deck: string
+  updateLock?: boolean
+  compiler?: CompilerOptions
+  environments?: boolean
+  externalLinks?: boolean
+}
+
+export interface LockUpdate {
+  file: string
+  anchors: number
+  changed: boolean
+}
+
+export interface CheckResult {
+  entry: string
+  findings: Finding[]
+  lock?: LockUpdate
+}
+
+export async function runCheck(options: CheckOptions): Promise<CheckResult> {
+  const compiler = new Compiler(options.deck, options.compiler)
+  let compilation = await compiler.compile()
+  const entryText = await readFile(compilation.entry, 'utf8')
+  const findings: Finding[] = []
+  const fail = (message: string, line: number) =>
+    findings.push({ checkId: 'presmium.plugins', severity: 'error', message, source: { file: compilation.entry, line } })
+
+  let lock: LockUpdate | undefined
+  if (options.updateLock) {
+    lock = await updateLock(compilation, (name, error) => fail(`plugin "${name}" failed to list anchors: ${errorMessage(error)}`, jsonLine(entryText, name)))
+    compilation = await compiler.compile()
+  }
+
+  findings.push(...await compilation.check({ externalLinks: options.externalLinks }))
+  if (options.environments) findings.push(...await probeEnvironments(compilation, entryText))
+  const all = [...compilation.doc.diagnostics, ...findings].map(f => f.source ? f : { ...f, source: { file: compilation.entry, line: 1 } })
+  return { entry: compilation.entry, findings: sortFindings(all), lock }
+}
+
+export async function probeEnvironments(compilation: Compilation, text: string): Promise<Finding[]> {
+  const findings: Finding[] = []
+  for (const { name, spec, provider, context } of compilation.environments) {
+    let reason: string | undefined
+    try {
+      reason = await provider.probe?.(name, spec, context)
+    } catch (error) {
+      reason = errorMessage(error)
+    }
+    if (reason) findings.push({ checkId: 'presmium.execute', severity: 'error', message: `environment "${name}" (${spec.kind}) is not reachable: ${reason}`, source: { file: compilation.entry, line: jsonLine(text, name) } })
+  }
+  return findings
+}
+
+async function updateLock(compilation: Compilation, onError: (plugin: string, error: unknown) => void): Promise<LockUpdate> {
+  const file = join(compilation.deckDir, ANCHOR_LOCK_PATH)
+  const before = await readFile(file, 'utf8').catch(() => undefined)
+  const ctx = checkContext(compilation)
+  const anchors = new Set<AnchorString>()
+  let complete = true
+  for (const { name, plugin } of compilation.plugins) {
+    try {
+      for (const anchor of await plugin?.anchors?.(ctx) ?? []) anchors.add(anchor)
+    } catch (error) {
+      complete = false
+      onError(name, error)
+    }
+  }
+  const { lock } = compilation
+  for (const anchor of [...anchors].sort()) lock.record(anchor, await compilation.resolvers.resolve(anchor, ctx.src, lock.get(anchor)))
+  if (complete) lock.retain(anchors)
+  const text = lock.serialize()
+  if (text !== before) {
+    await mkdir(dirname(file), { recursive: true })
+    await writeFile(file, text)
+  }
+  return { file, anchors: lock.size, changed: text !== before }
+}
+
+/** JSON property locations are diagnostic hints; entity paths are supplied by document validation. */
+function jsonLine(text: string, property: string): number {
+  const index = text.indexOf(JSON.stringify(property))
+  return index < 0 ? 1 : text.slice(0, index).split("\n").length
+}

package/src/cli.ts

@@ -0,0 +1,399 @@
+import { existsSync, statSync } from 'node:fs'
+import { mkdir, writeFile } from 'node:fs/promises'
+import { createRequire } from 'node:module'
+import { dirname, join, relative, resolve } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { parseArgs } from 'node:util'
+import { createJiti } from 'jiti'
+import { APPROVAL_KINDS, errorMessage } from '@lincyaw/kernel'
+import { bracketIPv6, ffmpegInstallCommand, findFfmpeg, irRevision, lanAddresses } from '@lincyaw/kernel/node'
+import type { ApprovalKind, Finding, Severity } from '@lincyaw/kernel'
+import { build, Compiler, dev, resolveEntry } from '@lincyaw/compiler'
+import type { BuildReport, Compilation, RunStats } from '@lincyaw/compiler'
+import { isAnyAddress, isLoopback, serverConfigKey, servedDocument, startServer } from '@lincyaw/server'
+import type { ApprovalPolicy } from '@lincyaw/server'
+import { buildWorkspace, isWorkspaceRoot, serveWorkspace } from '@lincyaw/workspace'
+import type { WorkspaceBuild } from '@lincyaw/workspace'
+import { runCheck } from './check.ts'
+import type { CheckResult } from './check.ts'
+import { devHost } from './dev-host.ts'
+import { CLI_MESSAGES, systemLocale } from './messages.ts'
+
+const BUNDLED = fileURLToPath(new URL('..', import.meta.url))
+const PRESMIUM_BIN = fileURLToPath(new URL('../bin/presmium.mjs', import.meta.url))
+
+export interface MainOptions {
+  /** The package whose dependencies hold the renderers and plugins a document does not install itself. */
+  bundled?: string
+  /** The presmium command that presmium studio starts. */
+  bin?: string
+}
+
+const t = CLI_MESSAGES[systemLocale()]
+
+const OPTIONS = {
+  'build': ['to', 'out', 'audience'],
+  'dev': ['to', 'out', 'server-port', 'allow'],
+  'ir': ['out'],
+  'check': ['json', 'update-lock', 'env', 'audience', 'external-links'],
+  'serve': ['port', 'host', 'operator-dir', 'preview-origin', 'public-url'],
+} as const
+
+type Name = keyof typeof OPTIONS
+
+interface Command {
+  name: Name
+  entry: string
+  workspace?: string
+  to?: string[]
+  out?: string
+  json: boolean
+  updateLock: boolean
+  env: boolean
+  audience?: string
+  externalLinks: boolean
+  serverPort?: number
+  allow: ApprovalKind[]
+  operatorDir?: string
+  port?: number
+  listenAddress?: string
+  previewOrigins: string[]
+  publicUrl?: string
+}
+
+export async function main(argv: string[], options: MainOptions = {}): Promise<number> {
+  const bundled = options.bundled ?? BUNDLED
+  if (argv[0] === 'new') return runNewCommand(argv.slice(1), bundled)
+  if (argv[0] === 'skills') return (await import('@lincyaw/skills')).main(argv.slice(1))
+  if (argv[0] === 'studio') return runStudioCommand(argv.slice(1), bundled, options.bin ?? PRESMIUM_BIN)
+  let command: Command | 'help'
+  try {
+    command = parseCommand(argv)
+  } catch (error) {
+    process.stderr.write(`presmium: ${errorMessage(error)}\n\n${t.usage}\n`)
+    return 2
+  }
+  if (command === 'help') {
+    process.stdout.write(`${t.usage}\n`)
+    return 0
+  }
+  try {
+    switch (command.name) {
+      case 'check': return await runCheckCommand(command, bundled)
+      case 'ir': return await runIrCommand(command, bundled)
+      case 'build': return await runBuildCommand(command, bundled)
+      case 'dev': return await runDevCommand(command, bundled)
+      case 'serve': return await runServeCommand(command, bundled)
+    }
+  } catch (error) {
+    process.stderr.write(`presmium: ${errorMessage(error)}\n`)
+    return 2
+  }
+}
+
+function parseCommand(argv: string[]): Command | 'help' {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      'to': { type: 'string' },
+      'out': { type: 'string' },
+      'json': { type: 'boolean', default: false },
+      'update-lock': { type: 'boolean', default: false },
+      'env': { type: 'boolean', default: false },
+      'audience': { type: 'string' },
+      'external-links': { type: 'boolean', default: false },
+      'server-port': { type: 'string' },
+      'allow': { type: 'string' },
+      'operator-dir': { type: 'string' },
+      'port': { type: 'string' },
+      'host': { type: 'string' },
+      'preview-origin': { type: 'string', multiple: true },
+      'public-url': { type: 'string' },
+      'help': { type: 'boolean', short: 'h', default: false },
+    },
+  })
+  if (values.help) return 'help'
+  const [name, deck = '.', ...extra] = positionals
+  if (!name) throw new Error(t.missingCommand)
+  if (!(name in OPTIONS)) throw new Error(t.unknownCommand(name))
+  const allowed: readonly string[] = OPTIONS[name as Name]
+  const given = Object.entries(values).filter(([key, value]) => key !== 'help' && value !== undefined && value !== false)
+  const wrong = given.find(([key]) => !allowed.includes(key))
+  if (wrong) throw new Error(t.optionNotFor(wrong[0], name))
+  if (extra.length > 0) throw new Error(t.unexpectedArgument(extra[0]!))
+  const workspace = name === 'build' && existsSync(deck) && statSync(deck).isDirectory() && isWorkspaceRoot(resolve(deck)) ? resolve(deck) : undefined
+  if (workspace && values.to) throw new Error(t.toNotForWorkspace)
+  if (workspace && values.audience !== undefined) throw new Error(t.audienceNotForWorkspace)
+  const audience = values.audience?.trim()
+  if (values.audience !== undefined && !/^[\w.-]+$/.test(audience ?? '')) throw new Error(t.badAudience(values.audience))
+  const directory = name === 'serve'
+  const entry = directory || workspace ? resolve(deck) : resolveEntry(deck)
+  if (!existsSync(entry) || (directory && !statSync(entry).isDirectory())) throw new Error(t.notFound(entry))
+  const to = values.to?.split(',').map(id => id.trim()).filter(Boolean)
+  if (to?.length === 0) throw new Error(t.emptyTo)
+  const allow = values.allow?.split(',').map(kind => kind.trim()).filter(Boolean) ?? []
+  const unknown = allow.find(kind => !(APPROVAL_KINDS as readonly string[]).includes(kind))
+  if (unknown) throw new Error(t.badAllow(APPROVAL_KINDS, unknown))
+  const previewOrigins = values['preview-origin'] ?? []
+  const notOrigin = previewOrigins.find(origin => !isOrigin(origin))
+  if (notOrigin !== undefined) throw new Error(t.badPreviewOrigin(notOrigin))
+  const publicUrl = values['public-url']
+  if (publicUrl !== undefined && !isPublicUrl(publicUrl)) throw new Error(t.badPublicUrl(publicUrl))
+  return {
+    name: name as Name,
+    entry,
+    ...workspace ? { workspace } : {},
+    to,
+    out: values.out,
+    json: values.json,
+    updateLock: values['update-lock'],
+    env: values.env,
+    ...audience ? { audience } : {},
+    externalLinks: values['external-links'],
+    serverPort: parsePort(values['server-port'], '--server-port'),
+    allow: allow as ApprovalKind[],
+    operatorDir: values['operator-dir'],
+    port: parsePort(values.port, '--port'),
+    listenAddress: values.host,
+    previewOrigins,
+    ...publicUrl ? { publicUrl } : {},
+  }
+}
+
+/** An http(s) address, optionally with the path a proxy forwards; no credentials, query or fragment. */
+function isPublicUrl(value: string): boolean {
+  try {
+    const url = new URL(value)
+    return /^https?:$/.test(url.protocol) && !url.username && !url.password && !url.search && !url.hash
+  } catch {
+    return false
+  }
+}
+
+function isOrigin(value: string): boolean {
+  try {
+    const url = new URL(value)
+    return /^https?:$/.test(url.protocol) && url.origin === value
+  } catch {
+    return false
+  }
+}
+
+function parsePort(value: string | undefined, option: string): number | undefined {
+  if (value === undefined) return undefined
+  const n = Number(value)
+  if (!Number.isInteger(n) || n < 0 || n > 65535) throw new Error(t.badPort(option, value))
+  return n
+}
+
+async function runCheckCommand(command: Command, bundled: string): Promise<number> {
+  const result = await runCheck({
+    deck: command.entry,
+    updateLock: command.updateLock,
+    environments: command.env,
+    externalLinks: command.externalLinks,
+    compiler: { bundled, ...command.audience ? { audience: command.audience } : {} },
+  })
+  process.stdout.write(command.json ? `${JSON.stringify(checkJson(result), null, 2)}\n` : checkText(result))
+  return exitCode(result.findings)
+}
+
+async function runIrCommand(command: Command, bundled: string): Promise<number> {
+  const { doc } = await new Compiler(command.entry, { bundled }).compile()
+  const json = `${JSON.stringify(doc, null, 2)}\n`
+  if (command.out) {
+    const file = resolve(command.out)
+    await mkdir(dirname(file), { recursive: true })
+    await writeFile(file, json)
+  } else {
+    process.stdout.write(json)
+  }
+  process.stderr.write(findingLines(doc.diagnostics).join('\n') + (doc.diagnostics.length ? '\n' : ''))
+  return exitCode(doc.diagnostics)
+}
+
+async function runBuildCommand(command: Command, bundled: string): Promise<number> {
+  if (command.workspace) {
+    const report = await buildWorkspace(command.workspace, { outDir: command.out, bundled })
+    process.stdout.write(workspaceText(report))
+    return exitCode(report.findings)
+  }
+  const compilation = await new Compiler(command.entry, { bundled, ...command.audience ? { audience: command.audience } : {} }).compile({ pruneCache: true })
+  const outDir = resolve(command.out ?? join(compilation.deckDir, 'dist'))
+  const report = await build(compilation, { outDir, to: command.to })
+  process.stdout.write(buildText(report, compilation.runStats, compilation.audience?.name))
+  return exitCode(report.findings)
+}
+
+async function runDevCommand(command: Command, bundled: string): Promise<number> {
+  let latest: Compilation | undefined
+  const deckDir = dirname(command.entry)
+  const approvals: Partial<Record<ApprovalKind, ApprovalPolicy>> = Object.fromEntries(command.allow.map(kind => [kind, 'allow']))
+  const host = devHost(() => latest)
+  const server = await startServer({
+    mode: 'dev',
+    port: command.serverPort,
+    approvals,
+    serverHost: host,
+    document: async dir => (dir === '' && latest ? servedDocument(latest) : undefined),
+    stateFile: join(deckDir, '.presmium', 'server.json'),
+  })
+  const compiler = new Compiler(command.entry, { bundled, priority: 'interactive', services: server.services })
+  const outDir = resolve(command.out ?? join(compiler.deckDir, '.presmium', 'dev'))
+  await mkdir(outDir, { recursive: true })
+  await writeFile(join(outDir, '.gitignore'), '*\n')
+  let devServers
+  try {
+    devServers = await dev(compiler, {
+      outDir,
+      to: command.to,
+      server: { url: server.url },
+      onCompile(compilation, findings) {
+        const changed = latest && serverConfigKey(latest) !== serverConfigKey(compilation)
+        latest = compilation
+        const revision = irRevision(compilation.doc)
+        server.diagnostics.compiled('', compilation.doc, compilation.workspaceRoot, revision)
+        server.diagnostics.replace({ document: '', origin: 'preview' }, findings.filter(finding => finding.checkId === 'presmium.render'), { root: compilation.workspaceRoot, irRevision: revision })
+        if (changed) void server.unmount('', { preserveFocus: true }).catch((error: unknown) => {
+          process.stderr.write(`${t.unmountFailed(errorMessage(error))}\n`)
+        })
+        const lines = findingLines(findings)
+        lines.push(t.compiled(compilation.doc.sections.length, summary(findings)))
+        process.stdout.write(`${lines.join('\n')}\n`)
+      },
+    })
+  } catch (error) {
+    await server.close()
+    throw error
+  }
+  for (const { renderer, url } of devServers.servers) process.stdout.write(`${renderer}  ${url}\n`)
+  process.stdout.write(`server  ${server.url}\nmcp  ${server.url}/mcp${t.token(relative(process.cwd(), join(deckDir, '.presmium', 'server.json')))}\n`)
+  process.stdout.write(`${t.watching(relative(process.cwd(), devServers.ir))}\n`)
+  await new Promise<void>((done) => {
+    process.once('SIGINT', done)
+    process.once('SIGTERM', done)
+  })
+  await devServers.close()
+  await server.close()
+  return 0
+}
+
+async function runServeCommand(command: Command, bundled: string): Promise<number> {
+  const started = await serveWorkspace({
+    dir: command.entry,
+    listenAddress: command.listenAddress,
+    port: command.port,
+    ...command.operatorDir ? { operatorDir: resolve(command.operatorDir) } : {},
+    bundled,
+    check: compilation => compilation.check(),
+    previewOrigins: command.previewOrigins,
+    ...command.publicUrl ? { publicUrl: command.publicUrl } : {},
+  })
+  process.stdout.write(`serve  ${started.url}\n${networkLines(command.listenAddress, started.url)}workspace  ${started.root}\nmcp  ${started.mcp.url}${t.token(started.mcp.stateFile)}\n`)
+  if (command.listenAddress && !isLoopback(command.listenAddress)) {
+    process.stderr.write(`${t.serveOpen(command.listenAddress, new URL(started.url).port)}\n`)
+  }
+  if (!findFfmpeg()) process.stderr.write(`${t.noFfmpeg(ffmpegInstallCommand())}\n`)
+  await new Promise<void>((done) => {
+    process.once('SIGINT', done)
+    process.once('SIGTERM', done)
+  })
+  await started.close()
+  return 0
+}
+
+function resolveInstalled(name: string, bundled: string): string | undefined {
+  for (const from of [pathToFileURL(join(bundled, 'package.json')).href, import.meta.url, pathToFileURL(join(process.cwd(), 'package.json')).href]) {
+    try {
+      return createRequire(from).resolve(name)
+    } catch {
+    }
+  }
+  return undefined
+}
+
+async function runNewCommand(argv: string[], bundled: string): Promise<number> {
+  const entry = resolveInstalled('create-presmium', bundled)
+  if (!entry) {
+    process.stderr.write(`${t.newMissing}\n`)
+    return 2
+  }
+  const { main: createMain } = await createJiti(import.meta.url).import<{ main(argv: string[]): Promise<number> }>(entry)
+  return createMain(argv)
+}
+
+async function runStudioCommand(argv: string[], bundled: string, presmiumBin: string): Promise<number> {
+  const entry = resolveInstalled('@lincyaw/studio', bundled)
+  if (!entry) {
+    process.stderr.write(`${t.studioMissing}\n`)
+    return 2
+  }
+  const { main: studioMain } = await createJiti(import.meta.url).import<{ main(argv: string[], options: { presmium: string }): Promise<number> }>(entry)
+  return studioMain(argv, { presmium: presmiumBin })
+}
+
+function networkLines(listenAddress: string | undefined, url: string): string {
+  if (!listenAddress || isLoopback(listenAddress)) return ''
+  const { port } = new URL(url)
+  const addresses = isAnyAddress(listenAddress) ? lanAddresses() : [bracketIPv6(listenAddress)]
+  return addresses.map(address => `network  http://${address}:${port}/\n`).join('')
+}
+
+function exitCode(findings: Finding[]): number {
+  return findings.some(f => f.severity === 'error') ? 1 : 0
+}
+
+function counts(findings: Finding[]): Record<Severity, number> {
+  const result: Record<Severity, number> = { error: 0, warning: 0, info: 0 }
+  for (const f of findings) result[f.severity]++
+  return result
+}
+
+function summary(findings: Finding[]): string {
+  const n = counts(findings)
+  return findings.length === 0 ? t.noProblems : t.counts(n.error, n.warning, n.info)
+}
+
+function findingLines(findings: Finding[], cwd = process.cwd()): string[] {
+  return findings.flatMap((f) => {
+    const where = f.source ? `${relative(cwd, f.source.file)}${f.source.line ? `:${f.source.line}` : ''}` : ''
+    return [`${where}  ${t.severity[f.severity]}  ${f.message}  (${f.checkId})`, ...f.hint ? [t.hint(f.hint)] : []]
+  })
+}
+
+function checkJson(result: CheckResult) {
+  return { entry: result.entry, counts: counts(result.findings), findings: result.findings, lock: result.lock }
+}
+
+function checkText(result: CheckResult, cwd = process.cwd()): string {
+  const out = findingLines(result.findings, cwd)
+  if (result.lock) {
+    out.push(t.lock(relative(cwd, result.lock.file), result.lock.changed, result.lock.anchors))
+  }
+  out.push(summary(result.findings))
+  return `${out.join('\n')}\n`
+}
+
+function workspaceText(report: WorkspaceBuild, cwd = process.cwd()): string {
+  const out = findingLines(report.findings, cwd)
+  for (const { dir, title, runs } of report.documents) {
+    out.push(`document  ${dir || '.'}  ${title}${runs.executed + runs.cached > 0 ? t.documentRuns(runs.executed, runs.cached) : ''}`)
+  }
+  out.push(`web  ${relative(cwd, report.outDir)}`)
+  out.push(summary(report.findings))
+  return `${out.join('\n')}\n`
+}
+
+function buildText(report: BuildReport, runs: RunStats, audience?: string, cwd = process.cwd()): string {
+  const out = findingLines(report.findings, cwd)
+  if (audience) out.push(`audience  ${audience}`)
+  out.push(`ir  ${relative(cwd, report.ir)}`)
+  for (const { renderer, outDir, skipped } of report.outputs) {
+    out.push(`${renderer}  ${relative(cwd, outDir)}${skipped.length ? t.notRendered(skipped.length) : ''}`)
+    for (const s of skipped) out.push(`    ${s.section}#${s.block}: ${s.reason}`)
+  }
+  if (runs.executed + runs.cached > 0) out.push(t.codeRuns(runs.executed, runs.cached, runs.sandbox && runs.executed > 0 ? runs.sandbox : undefined))
+  out.push(summary(report.findings))
+  return `${out.join('\n')}\n`
+}

package/src/dev-host.ts

@@ -0,0 +1,30 @@
+import { buildSummary, buildToDist, runBlock } from '@lincyaw/compiler'
+import type { Compilation } from '@lincyaw/compiler'
+import type { ServerHost } from '@lincyaw/server'
+
+export function devHost(latest: () => Compilation | undefined): ServerHost {
+  const current = (document: string): Compilation => {
+    const compilation = latest()
+    if (document !== '' || !compilation) throw new Error(document === '' ? 'the deck is still compiling' : `no document ${JSON.stringify(document)} in presmium dev`)
+    return compilation
+  }
+  return {
+    get workspaceRoot() { return latest()?.workspaceRoot },
+    async documents() {
+      const compilation = latest()
+      return compilation ? [{ dir: '', title: compilation.doc.meta.title, lang: compilation.doc.meta.lang }] : []
+    },
+    async compile(document) {
+      const { doc } = current(document)
+      return { doc, diagnostics: doc.diagnostics }
+    },
+    async check(document) {
+      const compilation = current(document)
+      return [...compilation.doc.diagnostics, ...await compilation.check()]
+    },
+    async build(document, options = {}) {
+      return buildSummary(await buildToDist(current(document), options))
+    },
+    run: async (document, target, signal) => runBlock(current(document), target, signal),
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { main } from './cli.ts'
+export type { MainOptions } from './cli.ts'

package/src/messages.ts

@@ -0,0 +1,219 @@
+export { systemLocale } from '@lincyaw/kernel/node'
+import { DOCUMENT_ENTRY } from '@lincyaw/kernel'
+import type { Locale } from '@lincyaw/kernel'
+
+// The lines that start with a key and two spaces (`serve  <url>`, `workspace  <root>`, `mcp  <url>`, `<renderer>  <url>`)
+// are read by programs (`@lincyaw/dsh/launch`, the tests): their keys, URLs and paths stay the same in both languages.
+export interface CliMessages {
+  usage: string
+  missingCommand: string
+  unknownCommand(name: string): string
+  optionNotFor(option: string, command: string): string
+  unexpectedArgument(argument: string): string
+  toNotForWorkspace: string
+  audienceNotForWorkspace: string
+  badAudience(value: string): string
+  notFound(entry: string): string
+  emptyTo: string
+  badAllow(kinds: readonly string[], value: string): string
+  badPreviewOrigin(value: string): string
+  badPublicUrl(value: string): string
+  badPort(option: string, value: string): string
+  unmountFailed(error: string): string
+  compiled(sections: number, summary: string): string
+  token(file: string): string
+  watching(ir: string): string
+  serveOpen(address: string, port: string): string
+  noFfmpeg(command: string): string
+  newMissing: string
+  studioMissing: string
+  noProblems: string
+  counts(errors: number, warnings: number, infos: number): string
+  severity: Record<'error' | 'warning' | 'info', string>
+  hint(text: string): string
+  lock(file: string, changed: boolean, anchors: number): string
+  documentRuns(executed: number, cached: number): string
+  notRendered(blocks: number): string
+  codeRuns(executed: number, cached: number, sandbox?: string): string
+}
+
+export const CLI_MESSAGES: Record<Locale, CliMessages> = {
+  'zh-CN': {
+    usage: `用法：presmium <命令> [<文稿>] [<选项>]
+
+<文稿> 是含有 ${DOCUMENT_ENTRY} 的目录，或这个文件本身（默认为 .）。
+
+命令：
+  new     在目录中新建项目（没有给出时逐项询问），由 create-presmium 完成
+          --type <种类>   lecture、workspace、site 或 plugin（默认询问）
+          --theme <主题>  site 的主题：course、docs 或 showcase（默认 course）
+          --title <标题>  讲义、工作区或网站的标题
+          --name <包名>   插件的包名
+          --no-git        不运行 git init
+  skills  安装内置技能（与 MCP 和可视化编辑器共用）
+          install <目录> [--json]  安装缺少的 .agents/skills，保留已有技能
+          --name <技能>   只安装指定技能，可重复
+          --json          以 JSON 打印安装结果
+  build   导出文稿：写出 <输出>/ir.json 与 <输出>/<形态>/；在工作区的根目录
+          （有 presmium.workspace.yaml）把整个工作区导出为网站，写到 <输出>/web/
+          --to <形态>     要导出的形态，以逗号分隔（默认为文稿声明的形态）
+          --out <目录>    输出目录（默认为 <文稿>/dist）
+          --audience <名称>  只导出面向这类读者的内容（例如 student），并在写出的每个
+                          文件中查找被略去内容的句子
+  dev     实时预览：启动 Presmium 服务与各形态的预览服务器，保存后自动更新
+          --to <形态>     要预览的形态，以逗号分隔
+          --out <目录>    工作目录（默认为 <文稿>/.presmium/dev）
+          --server-port <端口>  Presmium 服务的端口（默认为空闲端口）
+          --allow <种类>  无需询问即允许的操作：operate、spend、write、agent
+  ir      以 JSON 打印文稿的运行快照
+          --out <文件>    写入文件，而不是打印
+  check   检查文稿并运行插件的检查
+          --json          以 JSON 打印结果
+          --update-lock   重新定位代码锚点，并重写 .presmium/anchors.lock.json
+          --env           同时连接 execute.environments 中的运行环境
+          --audience <名称>  按面向这类读者的内容检查
+          --external-links   同时检查外部链接（装有 lychee 时用它）
+  serve   在本机提供工作区服务（参数是工作区的根目录或一份文稿）：工作区网站、
+          各文稿与其版本历史、审阅、插件的服务端路由与课堂同步；不加 --host 时
+          只在本机监听
+          --port <端口>   端口（默认为 4310）
+          --host <地址>   监听的地址（默认为 127.0.0.1）；0.0.0.0 或局域网中的地址
+                          让同一网络中的其他设备也能使用，且没有登录：任何能访问
+                          这个端口的人都以你的身份操作
+          --operator-dir <目录>  运营者目录（默认为用户的状态目录）
+          --preview-origin <来源>  （可重复）嵌入预览的 Presmium Studio 页面的来源，
+                          例如 http://127.0.0.1:4320；设置 PRESMIUM_SERVICE_TOKEN 时，
+                          工作区的路由要求它（Authorization: Bearer）
+          --public-url <网址>  反向代理在前面时浏览器使用的地址：信任它的主机，预览与产物
+                          的地址用它给出；带路径时代理原样转发该路径，服务的全部内容都在它下面
+  studio  启动 Presmium Studio（实验性）：浏览器中的编辑应用与这个目录（工作区的
+          根目录或一份文稿）的工作区服务，只打印一个要打开的网址。需要另外安装
+          @lincyaw/studio（约 865 MB）
+          --port <端口>   Presmium Studio 的端口（默认为 4320，被占用时取空闲端口）
+          --host <地址>   改为监听本机在局域网中的这个地址，而不是 127.0.0.1，且没有
+                          登录：任何能访问这个端口的人都以你的身份操作
+
+  -h, --help   显示本说明
+
+退出码：0 没有错误，1 有错误级别的问题，2 用法错误或内部错误。`,
+    missingCommand: '缺少命令。请在 presmium 之后给出命令，例如 presmium build。',
+    unknownCommand: name => `没有命令“${name}”。可用的命令见 presmium --help。`,
+    optionNotFor: (option, command) => `选项 --${option} 不能用于 presmium ${command}。可用的选项见 presmium --help。`,
+    unexpectedArgument: argument => `多余的参数“${argument}”。每个命令只接受一个文稿或目录。`,
+    toNotForWorkspace: '--to 不能用于工作区：工作区总是导出为网站。',
+    audienceNotForWorkspace: '--audience 暂不能用于工作区。请分别为每份文稿加 --audience 导出。',
+    badAudience: value => `“${value}”不是读者类别的名称。请给出字母、数字、.、_ 或 - 组成的名称，例如 student。`,
+    notFound: entry => `找不到 ${entry}。请检查路径，或用 presmium new 新建文稿。`,
+    emptyTo: '--to 至少需要一个形态，例如 --to web。',
+    badAllow: (kinds, value) => `--allow 不接受“${value}”。可用的种类：${kinds.join('、')}。`,
+    badPreviewOrigin: value => `“${value}”不是来源。请给出协议、主机与端口，例如 http://127.0.0.1:4320。`,
+    badPublicUrl: value => `“${value}”不是可用的网址。请给出浏览器访问的地址，例如 https://preview.example.com 或 https://example.com/user/a/preview/。`,
+    badPort: (option, value) => `${option} 需要 0 到 65535 之间的端口号，而不是“${value}”。`,
+    unmountFailed: error => `presmium: 无法关闭上一次加载的服务端扩展：${error}`,
+    compiled: (sections, summary) => `已更新 ${sections} 个页面；${summary}`,
+    token: file => ` （访问令牌在 ${file} 中）`,
+    watching: ir => `正在监视修改；运行快照在 ${ir}`,
+    noFfmpeg: command => `presmium serve: 没有找到 FFmpeg，讲授视频只能由浏览器导出为 WebM，画质较低。安装后可导出清晰的 MP4：${command}`,
+    serveOpen: (address, port) => `presmium serve: 正在 ${address} 上监听，局域网中的设备可以访问，且没有登录：任何能访问端口 ${port} 的人都以你的身份使用这个工作区（编辑、运行代码、允许操作）。请只在可信的网络中使用；不加 --host 时只在本机监听。`,
+    newMissing: 'presmium new: 没有安装 create-presmium。它随 presmium 一起安装，请运行 pnpm add -g @lincyaw/presmium。',
+    studioMissing: 'presmium studio: 这里没有安装 Presmium Studio（实验性，约 865 MB）。请运行 pnpm add -g @lincyaw/studio 后使用 presmium-studio，或在本项目中运行 pnpm add -D @lincyaw/studio。',
+    noProblems: '没有问题',
+    counts: (errors, warnings, infos) => `${errors} 个错误，${warnings} 个警告，${infos} 条信息`,
+    severity: { error: '错误', warning: '警告', info: '信息' },
+    hint: text => `    建议：${text}`,
+    lock: (file, changed, anchors) => `${file} ${changed ? '已更新' : '没有变化'}（${anchors} 个锚点）`,
+    documentRuns: (executed, cached) => `  （代码运行：执行 ${executed} 个，取自缓存 ${cached} 个）`,
+    notRendered: blocks => `  （${blocks} 个内容块未显示）`,
+    codeRuns: (executed, cached, sandbox) => `代码运行：执行 ${executed} 个，取自缓存 ${cached} 个${sandbox ? `，隔离方式为 ${sandbox}` : ''}`,
+  },
+  'en': {
+    usage: `Usage: presmium <command> [deck] [options]
+
+The deck is a directory holding ${DOCUMENT_ENTRY}, or that entry file (default: .).
+
+Commands:
+  new     a new project in the directory (default: asks), from create-presmium
+          --type <kind>   lecture, workspace, site, or plugin (default: asks)
+          --theme <name>  site theme: course, docs, or showcase (default: course)
+          --title <text>  the lecture, workspace, or site title
+          --name <name>   the plugin’s package name
+          --no-git        do not run git init
+  skills  install bundled skills, shared with MCP and the visual editor
+          install <dir> [--json]  install missing .agents/skills; keep existing skills
+          --name <skill>  install only the named skill; repeat for more
+          --json          print the installation result as JSON
+  build   export the deck: writes <out>/ir.json and <out>/<renderer>/; at a workspace root
+          (presmium.workspace.yaml) exports the workspace as a website into <out>/web/
+          --to <ids>      forms to export, comma-separated (default: the deck’s renderers)
+          --out <dir>     output directory (default: <deck>/dist)
+          --audience <name>  only the content for this audience (e.g. student); then every file
+                          written is scanned for the sentences of the content left out
+  dev     live preview: starts the Presmium server and the renderers’ dev servers, updates on save
+          --to <ids>      forms to preview, comma-separated
+          --out <dir>     working directory (default: <deck>/.presmium/dev)
+          --server-port <n>  port of the Presmium server (default: a free port)
+          --allow <kinds>    approvals given without asking: operate, spend, write, agent
+  ir      print the runtime snapshot as JSON
+          --out <file>    write it to a file instead
+  check   check the deck and run the plugins’ checks
+          --json          print the result as JSON
+          --update-lock   re-resolve anchors and rewrite .presmium/anchors.lock.json
+          --env           also connect to the environments of execute.environments
+          --audience <name>  check the content for this audience
+          --external-links   also check the external links, with lychee when it is installed
+  serve   the workspace service for you on this machine (the argument is the workspace root, or
+          a deck): the workspace site, the documents and their history, the reviews, the plugins’
+          routes, and the classroom sync; without --host it listens on this machine only
+          --port <n>      port (default: 4310)
+          --host <addr>   address to listen on (default: 127.0.0.1); 0.0.0.0 or an address on the
+                          local network opens it to your other devices there, with no login:
+                          whoever reaches the port works as you
+          --operator-dir <dir>  the operator directory (default: the user’s state directory)
+          --preview-origin <origin>  (repeatable) the origin of a Presmium Studio whose pages embed
+                          the previews, e.g. http://127.0.0.1:4320; with PRESMIUM_SERVICE_TOKEN set,
+                          the workspace’s routes ask for it (Authorization: Bearer)
+          --public-url <url>  the address browsers use when a reverse proxy fronts the service: its
+                          host is trusted, and previews and outputs are linked under it; with a path, the
+                          proxy forwards that path unchanged and everything the service serves is below it
+  studio  Presmium Studio (experimental): the editing app in the browser and the workspace service
+          of the directory (the workspace root, or a deck); prints the one address to open. It is
+          the package @lincyaw/studio (about 865 MB), installed beside this one
+          --port <n>      Presmium Studio’s port (default: 4320, or a free one when that is in use)
+          --host <addr>   listen on this address of the machine on the local network instead of
+                          127.0.0.1, with no login: whoever reaches the port works as you
+
+  -h, --help   show this help
+
+Exit Codes: 0 no errors, 1 error findings, 2 usage or internal error.`,
+    missingCommand: 'No command given. Put a command after presmium, for example presmium build.',
+    unknownCommand: name => `There is no command “${name}”. See presmium --help for the commands.`,
+    optionNotFor: (option, command) => `The option --${option} does not apply to presmium ${command}. See presmium --help for its options.`,
+    unexpectedArgument: argument => `Unexpected argument “${argument}”. Each command takes one deck or directory.`,
+    toNotForWorkspace: '--to does not apply to a workspace: its site is the web form.',
+    audienceNotForWorkspace: '--audience does not apply to a workspace yet. Export each document with --audience instead.',
+    badAudience: value => `“${value}” is not the name of an audience. Give a name of letters, digits, ., _, or -, such as student.`,
+    notFound: entry => `Couldn’t find ${entry}. Check the path, or make a document with presmium new.`,
+    emptyTo: '--to needs at least one renderer, such as --to web.',
+    badAllow: (kinds, value) => `--allow does not take “${value}”. The kinds are ${kinds.join(', ')}.`,
+    badPreviewOrigin: value => `“${value}” is not an origin. Give a scheme, host, and port, such as http://127.0.0.1:4320.`,
+    badPublicUrl: value => `“${value}” is not a usable address. Give the address browsers use, such as https://preview.example.com or https://example.com/user/a/preview/.`,
+    badPort: (option, value) => `${option} takes a port number from 0 to 65535, not “${value}”.`,
+    unmountFailed: error => `presmium: couldn’t close the previous server contributions: ${error}`,
+    compiled: (sections, summary) => `compiled ${sections} sections; ${summary}`,
+    token: file => ` (its token is in ${file})`,
+    watching: ir => `watching; runtime snapshot in ${ir}`,
+    noFfmpeg: command => `presmium serve: FFmpeg was not found, so lecture videos export from the browser as WebM, at a lower quality. Install it for sharp MP4 videos: ${command}`,
+    serveOpen: (address, port) => `presmium serve: listening on ${address}, on the local network, with no login: anyone who reaches port ${port} uses this workspace as you (edits, runs code, approves). Use it on a network you trust; without --host it listens on this machine only.`,
+    newMissing: 'presmium new: create-presmium is not installed. It comes with the presmium package: run pnpm add -g @lincyaw/presmium.',
+    studioMissing: 'presmium studio: Presmium Studio is not installed here (experimental, about 865 MB). Run pnpm add -g @lincyaw/studio, then presmium-studio; or run pnpm add -D @lincyaw/studio in this project.',
+    noProblems: 'no problems',
+    counts: (errors, warnings, infos) => `${errors} errors, ${warnings} warnings, ${infos} infos`,
+    severity: { error: 'error', warning: 'warning', info: 'info' },
+    hint: text => `    hint: ${text}`,
+    lock: (file, changed, anchors) => `${file} ${changed ? 'updated' : 'unchanged'} (${anchors} anchors)`,
+    documentRuns: (executed, cached) => `  (code runs: ${executed} executed, ${cached} from cache)`,
+    notRendered: blocks => `  (${blocks} blocks not rendered)`,
+    codeRuns: (executed, cached, sandbox) => `code runs: ${executed} executed, ${cached} from cache${sandbox ? `, isolated by ${sandbox}` : ''}`,
+  },
+}
+

package/src/testing.ts

@@ -0,0 +1,24 @@
+import { execFile } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+
+export const PRESMIUM_BIN = fileURLToPath(new URL('../bin/presmium.mjs', import.meta.url))
+
+export interface Run {
+  code: number
+  stdout: string
+  stderr: string
+}
+
+export function run(command: string, args: string[], options: { cwd?: string, env?: NodeJS.ProcessEnv } = {}): Promise<Run> {
+  return new Promise((resolve) => {
+    execFile(command, args, { cwd: options.cwd, env: options.env, maxBuffer: 256 << 20 }, (error, stdout, stderr) => {
+      resolve({ code: !error ? 0 : typeof error.code === 'number' ? error.code : -1, stdout, stderr })
+    })
+  })
+}
+
+export function presmium(cwd: string, args: string[], env: Record<string, string> = {}): Promise<Run> {
+  const { NODE_ENV: _test, ...inherited } = process.env
+  return run(process.execPath, [PRESMIUM_BIN, ...args], { cwd, env: { ...inherited, ...env } })
+}
+