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

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 lectures written in MyST Markdown 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 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 @lincyaw/slidev-addon-core
+```
+
+## 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.md` 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/lecture.en.md)
+- [Plugin guide](https://github.com/Lincyaw/presmium/blob/main/site/plugins/lecture.en.md)
+
+## 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,44 @@
 {
   "name": "@lincyaw/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0-rc.0",
+  "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.0",
+    "@lincyaw/workspace": "1.0.0-rc.0",
+    "@lincyaw/server": "1.0.0-rc.0",
+    "@lincyaw/compiler": "1.0.0-rc.0"
+  }
 }

package/src/check.ts

@@ -0,0 +1,85 @@
+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, frontmatterLine, 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)}`, frontmatterLine(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: frontmatterLine(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 }
+}

package/src/cli.ts

@@ -0,0 +1,426 @@
+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 { errorMessage } from '@lincyaw/kernel'
+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 { anyAddress, isLoopback, networkAddresses, 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 './host.ts'
+
+export const BUNDLED = fileURLToPath(new URL('..', import.meta.url))
+
+export interface MainOptions {
+  bundled?: string
+  bin?: string
+}
+
+let bundled = BUNDLED
+let presmiumBin = fileURLToPath(new URL('../bin/presmium.mjs', import.meta.url))
+
+const USAGE = `Usage: presmium <command> [deck] [options]
+
+The deck is a directory holding lecture.md, or an entry file (default: .).
+
+Commands:
+  new     a new project in the directory (default: asks), from create-presmium
+          --type <kind>   lecture, workspace or plugin (default: asks)
+          --title <text>  the lecture's or the workspace's title
+          --name <name>   the plugin's package name
+          --no-git        do not run git init
+  build   compile and render; writes <out>/ir.json and <out>/<renderer>/; at a workspace root
+          (presmium.workspace.yaml) builds the workspace site into <out>/web/
+          --to <ids>      renderers to run, 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     compile, start the Presmium server and the renderers' dev servers, recompile on save
+          --to <ids>      renderers to run, 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 IR as JSON
+          --out <file>    write it to a file instead
+  check   compile 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 deck as compiled 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, 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 workbench 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)
+  studio  the workbench (experimental): DeepSeek Harness with Presmium's bundle 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 (with DeepSeek Harness, about 865 MB), installed beside
+          this one
+          --port <n>      the workbench'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.`
+
+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'],
+} as const
+
+type Name = keyof typeof OPTIONS
+
+const KINDS: readonly ApprovalKind[] = ['operate', 'spend', 'write', 'agent']
+
+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
+  host?: string
+  previewOrigins: string[]
+}
+
+export async function main(argv: string[], options: MainOptions = {}): Promise<number> {
+  bundled = options.bundled ?? BUNDLED
+  if (options.bin) presmiumBin = options.bin
+  if (argv[0] === 'new') return create(argv.slice(1))
+  if (argv[0] === 'studio') return studio(argv.slice(1))
+  let command: Command | 'help'
+  try {
+    command = parseCommand(argv)
+  } catch (error) {
+    process.stderr.write(`presmium: ${errorMessage(error)}\n\n${USAGE}\n`)
+    return 2
+  }
+  if (command === 'help') {
+    process.stdout.write(`${USAGE}\n`)
+    return 0
+  }
+  try {
+    switch (command.name) {
+      case 'check': return await check(command)
+      case 'ir': return await ir(command)
+      case 'build': return await buildDeck(command)
+      case 'dev': return await devDeck(command)
+      case 'serve': return await serve(command)
+    }
+  } 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 },
+      'help': { type: 'boolean', short: 'h', default: false },
+    },
+  })
+  if (values.help) return 'help'
+  const [name, deck = '.', ...extra] = positionals
+  if (!name) throw new Error('missing command')
+  if (!(name in OPTIONS)) throw new Error(`unknown command "${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(`option --${wrong[0]} does not apply to ${name}`)
+  if (extra.length > 0) throw new Error(`unexpected argument "${extra[0]}"`)
+  const workspace = name === 'build' && existsSync(deck) && statSync(deck).isDirectory() && isWorkspaceRoot(resolve(deck)) ? resolve(deck) : undefined
+  if (workspace && values.to) throw new Error('--to does not apply to a workspace: its site is the web form')
+  if (workspace && values.audience !== undefined) throw new Error('--audience does not apply to a workspace yet: build each document for its audience')
+  const audience = values.audience?.trim()
+  if (values.audience !== undefined && !/^[\w.-]+$/.test(audience ?? '')) throw new Error(`--audience takes the name of an audience, e.g. student, not "${values.audience}"`)
+  const directory = name === 'serve'
+  const entry = directory || workspace ? resolve(deck) : resolveEntry(deck)
+  if (!existsSync(entry) || (directory && !statSync(entry).isDirectory())) throw new Error(`${entry} not found`)
+  const to = values.to?.split(',').map(id => id.trim()).filter(Boolean)
+  if (to?.length === 0) throw new Error('--to needs at least one renderer id')
+  const allow = values.allow?.split(',').map(kind => kind.trim()).filter(Boolean) ?? []
+  const unknown = allow.find(kind => !(KINDS as string[]).includes(kind))
+  if (unknown) throw new Error(`--allow takes ${KINDS.join(', ')}, not "${unknown}"`)
+  const previewOrigins = values['preview-origin'] ?? []
+  const notOrigin = previewOrigins.find(origin => !isOrigin(origin))
+  if (notOrigin !== undefined) throw new Error(`--preview-origin takes an origin such as http://127.0.0.1:4320, not "${notOrigin}"`)
+  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: port(values['server-port'], '--server-port'),
+    allow: allow as ApprovalKind[],
+    operatorDir: values['operator-dir'],
+    port: port(values.port, '--port'),
+    host: values.host,
+    previewOrigins,
+  }
+}
+
+function isOrigin(value: string): boolean {
+  try {
+    const url = new URL(value)
+    return /^https?:$/.test(url.protocol) && url.origin === value
+  } catch {
+    return false
+  }
+}
+
+function port(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(`${option} takes a port number, not "${value}"`)
+  return n
+}
+
+async function check(command: Command): 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 ir(command: Command): 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 buildDeck(command: Command): 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.runs, compilation.audience?.name))
+  return exitCode(report.findings)
+}
+
+async function devDeck(command: Command): 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, 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 session
+  try {
+    session = await dev(compiler, {
+      outDir,
+      to: command.to,
+      server: { url: server.url },
+      onCompile(compilation, findings) {
+        latest = compilation
+        const lines = findingLines(findings)
+        lines.push(`compiled ${compilation.doc.sections.length} sections; ${summary(findings)}`)
+        process.stdout.write(`${lines.join('\n')}\n`)
+      },
+    })
+  } catch (error) {
+    await server.close()
+    throw error
+  }
+  for (const { renderer, url } of session.servers) process.stdout.write(`${renderer}  ${url}\n`)
+  process.stdout.write(`server  ${server.url}\nmcp  ${server.url}/mcp (its token is in ${relative(process.cwd(), join(deckDir, '.presmium', 'server.json'))})\n`)
+  process.stdout.write(`watching; IR in ${relative(process.cwd(), session.ir)}\n`)
+  await new Promise<void>((done) => {
+    process.once('SIGINT', done)
+    process.once('SIGTERM', done)
+  })
+  await session.close()
+  await server.close()
+  return 0
+}
+
+async function serve(command: Command): Promise<number> {
+  const started = await serveWorkspace({
+    dir: command.entry,
+    host: command.host,
+    port: command.port,
+    ...command.operatorDir ? { operatorDir: resolve(command.operatorDir) } : {},
+    bundled,
+    check: compilation => compilation.check(),
+    previewOrigins: command.previewOrigins,
+  })
+  process.stdout.write(`serve  ${started.url}\n${networkLines(command.host, started.url)}workspace  ${started.root}\nmcp  ${started.mcp.url} (its token is in ${started.mcp.stateFile})\n`)
+  if (command.host && !isLoopback(command.host)) {
+    process.stderr.write(`presmium serve: listening on ${command.host}, on the local network, with no login: anyone who reaches port ${new URL(started.url).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.\n`)
+  }
+  await new Promise<void>((done) => {
+    process.once('SIGINT', done)
+    process.once('SIGTERM', done)
+  })
+  await started.close()
+  return 0
+}
+
+function installed(name: 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 create(argv: string[]): Promise<number> {
+  const entry = installed('create-presmium')
+  if (!entry) {
+    process.stderr.write('presmium new: create-presmium is not installed; it comes with the presmium package: pnpm add -g presmium\n')
+    return 2
+  }
+  const { main: createMain } = await createJiti(import.meta.url).import<{ main(argv: string[]): Promise<number> }>(entry)
+  return createMain(argv)
+}
+
+async function studio(argv: string[]): Promise<number> {
+  const entry = installed('@lincyaw/studio')
+  if (!entry) {
+    process.stderr.write('presmium studio: the workbench is not installed here. It is the package @lincyaw/studio (experimental; with DeepSeek Harness, about 865 MB): pnpm add -g @lincyaw/studio, then run presmium-studio; or pnpm add -D @lincyaw/studio in this project.\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(host: string | undefined, url: string): string {
+  if (!host || isLoopback(host)) return ''
+  const { port } = new URL(url)
+  const addresses = anyAddress(host) ? networkAddresses() : [host.includes(':') && !host.startsWith('[') ? `[${host}]` : host]
+  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 ? 'no problems' : `${n.error} errors, ${n.warning} warnings, ${n.info} infos`
+}
+
+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}  ${f.severity}  ${f.message}  (${f.checkId})`, ...f.hint ? [`    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) {
+    const state = result.lock.changed ? 'updated' : 'unchanged'
+    out.push(`${relative(cwd, result.lock.file)} ${state} (${result.lock.anchors} 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 ? `  (code runs: ${runs.executed} executed, ${runs.cached} from cache)` : ''}`)
+  }
+  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 ? `  (${skipped.length} blocks not rendered)` : ''}`)
+    for (const s of skipped) out.push(`    ${s.section}#${s.block}: ${s.reason}`)
+  }
+  if (runs.executed + runs.cached > 0) out.push(`code runs: ${runs.executed} executed, ${runs.cached} from cache${runs.sandbox && runs.executed > 0 ? `, isolated by ${runs.sandbox}` : ''}`)
+  out.push(summary(report.findings))
+  return `${out.join('\n')}\n`
+}

package/src/fake-model.ts

@@ -0,0 +1,101 @@
+import { createServer } from 'node:http'
+import type { IncomingHttpHeaders } from 'node:http'
+import type { AddressInfo } from 'node:net'
+
+export type Step = { text: string } | { tool: string, input: Record<string, unknown> }
+
+export interface Received {
+  path: string
+  headers: IncomingHttpHeaders
+  body: Record<string, any>
+}
+
+export interface FakeModel {
+  url: string
+  received: Received[]
+  hold(): void
+  release(): void
+  close(): Promise<void>
+}
+
+const event = (name: string, data: unknown) => `event: ${name}\ndata: ${JSON.stringify(data)}\n\n`
+
+function stream(step: Step, n: number): string {
+  const start = { type: 'message_start', message: { id: `msg_${n}`, type: 'message', role: 'assistant', model: 'fake-model', content: [], stop_reason: null, stop_sequence: null, usage: { input_tokens: 10, output_tokens: 0 } } }
+  const block = 'text' in step
+    ? [event('content_block_start', { type: 'content_block_start', index: 0, content_block: { type: 'text', text: '' } }), event('content_block_delta', { type: 'content_block_delta', index: 0, delta: { type: 'text_delta', text: step.text } })]
+    : [event('content_block_start', { type: 'content_block_start', index: 0, content_block: { type: 'tool_use', id: `toolu_${n}`, name: step.tool, input: {} } }), event('content_block_delta', { type: 'content_block_delta', index: 0, delta: { type: 'input_json_delta', partial_json: JSON.stringify(step.input) } })]
+  return [
+    event('message_start', start),
+    ...block,
+    event('content_block_stop', { type: 'content_block_stop', index: 0 }),
+    event('message_delta', { type: 'message_delta', delta: { stop_reason: 'text' in step ? 'end_turn' : 'tool_use', stop_sequence: null }, usage: { output_tokens: 5 } }),
+    event('message_stop', { type: 'message_stop' }),
+  ].join('')
+}
+
+export async function fakeModel(script: Step[]): Promise<FakeModel> {
+  const received: Received[] = []
+  let held: Promise<void> | undefined
+  let release = () => {}
+  const server = createServer((req, res) => {
+    let body = ''
+    req.setEncoding('utf8').on('data', (chunk: string) => body += chunk)
+    req.on('end', async () => {
+      let parsed: Record<string, any> = {}
+      try {
+        parsed = JSON.parse(body) as Record<string, any>
+      } catch {
+      }
+      const record: Received = { path: req.url ?? '', headers: req.headers, body: parsed }
+      received.push(record)
+      if (req.method !== 'POST' || !(req.url ?? '').endsWith('/v1/messages')) {
+        res.writeHead(404).end()
+        return
+      }
+      await held
+      const turn = (r: Received) => r.path.endsWith('/v1/messages') && Array.isArray(r.body.tools) && r.body.tools.length > 0
+      const n = received.filter(r => r.path.endsWith('/v1/messages')).length
+      const step = turn(record) ? script[received.filter(turn).indexOf(record)] ?? { text: '完毕。' } : { text: 'Presmium' }
+      res.writeHead(200, { 'Content-Type': 'text/event-stream' }).end(stream(step, n))
+    })
+  })
+  const port = await new Promise<number>(done => server.listen(0, '127.0.0.1', () => done((server.address() as AddressInfo).port)))
+  return {
+    url: `http://127.0.0.1:${port}`,
+    received,
+    hold() {
+      held = new Promise(done => release = done)
+    },
+    release() {
+      release()
+      held = undefined
+    },
+    close: () => new Promise<void>((done) => {
+      release()
+      server.close(() => done())
+      server.closeAllConnections()
+    }),
+  }
+}
+
+export async function recordingProxy(): Promise<{ url: string, attempts: string[], close(): Promise<void> }> {
+  const attempts: string[] = []
+  const server = createServer((req, res) => {
+    attempts.push(`${req.method} ${req.url}`)
+    res.writeHead(502).end()
+  })
+  server.on('connect', (req, socket) => {
+    attempts.push(`CONNECT ${req.url}`)
+    socket.end('HTTP/1.1 502 Bad Gateway\r\n\r\n')
+  })
+  const port = await new Promise<number>(done => server.listen(0, '127.0.0.1', () => done((server.address() as AddressInfo).port)))
+  return {
+    url: `http://127.0.0.1:${port}`,
+    attempts,
+    close: () => new Promise<void>((done) => {
+      server.close(() => done())
+      server.closeAllConnections()
+    }),
+  }
+}

package/src/host.ts

@@ -0,0 +1,30 @@
+import { buildView, 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 {
+    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 = {}) {
+      const report = await buildView(current(document), options)
+      return { outputs: report.outputs.map(({ renderer, outDir }) => ({ renderer, outDir })), findings: report.findings }
+    },
+    run: async (document, target, signal) => runBlock(current(document), target, signal),
+  }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export { runCheck } from './check.ts'
+export type { CheckOptions, CheckResult, LockUpdate } from './check.ts'
+export { main } from './cli.ts'

package/src/testing.ts

@@ -0,0 +1,26 @@
+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 } })
+}
+
+export { fakeModel, recordingProxy } from './fake-model.ts'
+export type { FakeModel, Received, Step } from './fake-model.ts'