claude: Add Quarto API and error message documentation

gordonwoodhull · gordonwoodhull · commit 27d381ea9bd9 · 2025-11-20T16:54:21.000-05:00
- llm-docs/quarto-api.md: Step-by-step guide for adding functionality to
  the Quarto API (type definitions in @quarto/types and implementation in
  quarto-api.ts), including usage patterns for internal and external engines
- llm-docs/error-messages.md: Style guide for writing idiomatic error
  messages with proper newline placement (end messages with \n, never start
  with \n or use empty calls)
diff --git a/llm-docs/error-messages.md b/llm-docs/error-messages.md
@@ -0,0 +1,103 @@
+# Writing Error Messages in Quarto
+
+## The Rule
+
+Each `error()`, `warning()`, or `info()` call should be **exactly one line**.
+
+- ✅ End messages with `\n` to add blank lines after
+- ❌ Never start messages with `\n`
+- ❌ Never use empty `error("")` calls
+
+## Why This Matters
+
+Quarto's logging prefixes each call with `ERROR:` / `WARNING:` / `INFO:`. Starting a message with `\n` or using empty calls creates confusing output:
+
+```
+ERROR: Multiple files found
+ERROR:
+Or specify entry point:    ← Empty "ERROR:" line from \n at start
+```
+
+## Adding Blank Lines
+
+To add a blank line between sections, end the **previous** message with `\n`:
+
+### ✅ Good
+
+```typescript
+error("Multiple .ts files found in src/\n");  // \n at END
+error("Specify entry point as argument:");
+error("  quarto call build-ts-extension src/my-engine.ts");
+```
+
+Output:
+```
+ERROR: Multiple .ts files found in src/
+ERROR:
+ERROR: Specify entry point as argument:
+ERROR:   quarto call build-ts-extension src/my-engine.ts
+```
+
+### ❌ Bad
+
+```typescript
+error("Multiple .ts files found in src/");
+error("\nSpecify entry point as argument:");  // \n at START
+error("  quarto call build-ts-extension src/my-engine.ts");
+```
+
+Output:
+```
+ERROR: Multiple .ts files found in src/
+ERROR:
+ERROR: Specify entry point as argument:     ← Blank "ERROR:" line before
+ERROR:   quarto call build-ts-extension src/my-engine.ts
+```
+
+### ❌ Also Bad
+
+```typescript
+error("Multiple .ts files found in src/");
+error("");  // Empty call to add spacing
+error("Specify entry point as argument:");
+```
+
+Output:
+```
+ERROR: Multiple .ts files found in src/
+ERROR:                                      ← Empty "ERROR:" line
+ERROR: Specify entry point as argument:
+```
+
+## Complete Example
+
+Here's a real example from `build-ts-extension` showing proper formatting:
+
+### ✅ Good
+
+```typescript
+error("No src/ directory found.\n");
+error("Create a TypeScript file in src/:");
+error("  mkdir -p src");
+error("  touch src/my-engine.ts\n");
+error("Or specify entry point as argument:");
+error("  quarto call build-ts-extension src/my-engine.ts");
+```
+
+Output:
+```
+ERROR: No src/ directory found.
+ERROR:
+ERROR: Create a TypeScript file in src/:
+ERROR:   mkdir -p src
+ERROR:   touch src/my-engine.ts
+ERROR:
+ERROR: Or specify entry point as argument:
+ERROR:   quarto call build-ts-extension src/my-engine.ts
+```
+
+Notice:
+- Each `error()` call is one complete line
+- Blank lines are created by ending the previous message with `\n`
+- Indentation (with spaces) is preserved within each message
+- Message flow is clear and readable
diff --git a/llm-docs/quarto-api.md b/llm-docs/quarto-api.md
@@ -0,0 +1,188 @@
+# Quarto API and @quarto/types
+
+## Building @quarto/types
+
+To build the @quarto/types package:
+
+```
+cd packages/quarto-types
+npm run build
+```
+
+This runs typecheck and then bundles all type definitions into `dist/index.d.ts`.
+
+---
+
+## Updating the Quarto API
+
+The Quarto API is how external execution engines access Quarto's core functionality. The API exists in two places:
+
+1. **Type definitions** in `packages/quarto-types/` - consumed by external engines (TypeScript)
+2. **Implementation** in `src/core/quarto-api.ts` - used within quarto-cli
+
+### Step-by-step: Adding to the Quarto API
+
+Follow these steps in order when adding new functionality to the API:
+
+#### 1. Update quarto-types type definitions
+
+**Add auxiliary types** (if needed):
+
+- Types belong in `packages/quarto-types/src/`
+- Follow the existing file organization:
+  - `system.ts` - System/process types (ProcessResult, TempContext, etc.)
+  - `console.ts` - Console/UI types (SpinnerOptions, etc.)
+  - `jupyter.ts` - Jupyter-specific types
+  - `check.ts` - Check command types
+  - `execution.ts` - Execution engine types
+  - etc.
+- Create new files if needed for logical grouping
+
+**Export types from index.ts:**
+
+```typescript
+// In packages/quarto-types/src/index.ts
+export type * from "./your-new-file.ts";
+```
+
+**Add to QuartoAPI interface:**
+
+```typescript
+// In packages/quarto-types/src/quarto-api.ts
+
+// 1. Import any new types at the top
+import type { YourNewType } from "./your-file.ts";
+
+// 2. Add to the QuartoAPI interface
+export interface QuartoAPI {
+  // ... existing namespaces
+
+  yourNamespace: {
+    yourMethod: (param: YourNewType) => ReturnType;
+  };
+}
+```
+
+#### 2. Test the type definitions
+
+```bash
+cd packages/quarto-types
+npm run build
+```
+
+This will:
+
+- Run `tsc --noEmit` to typecheck
+- Bundle types into `dist/index.d.ts`
+- Show any type errors
+
+Fix any errors before proceeding.
+
+#### 3. Update the internal QuartoAPI interface
+
+The file `src/core/quarto-api.ts` contains a **duplicate** QuartoAPI interface definition used for the internal implementation. Update it to match:
+
+```typescript
+// In src/core/quarto-api.ts (near top of file)
+export interface QuartoAPI {
+  // ... existing namespaces
+
+  yourNamespace: {
+    yourMethod: (param: YourNewType) => ReturnType;
+  };
+}
+```
+
+**Note:** This interface must match the one in quarto-types, but uses internal types.
+
+#### 4. Wire up the implementation
+
+Still in `src/core/quarto-api.ts`:
+
+**Add imports** (near top):
+
+```typescript
+import { yourMethod } from "./your-module.ts";
+```
+
+**Add to quartoAPI object** (at bottom):
+
+```typescript
+export const quartoAPI: QuartoAPI = {
+  // ... existing namespaces
+
+  yourNamespace: {
+    yourMethod,
+  },
+};
+```
+
+#### 5. Verify with typecheck
+
+Run the quarto typecheck:
+
+```bash
+package/dist/bin/quarto
+```
+
+No output means success! Fix any type errors.
+
+#### 6. Commit with built artifact
+
+**Always commit the built `dist/index.d.ts` file** along with source changes:
+
+```bash
+git add packages/quarto-types/src/your-file.ts \
+        packages/quarto-types/src/index.ts \
+        packages/quarto-types/src/quarto-api.ts \
+        packages/quarto-types/dist/index.d.ts \
+        src/core/quarto-api.ts
+
+git commit -m "Add yourNamespace to Quarto API"
+```
+
+### Using the Quarto API in source files
+
+#### Inside quarto-cli (internal modules)
+
+```typescript
+// Import the quartoAPI instance
+import { quartoAPI as quarto } from "../../core/quarto-api.ts";
+
+// Use it
+const caps = await quarto.jupyter.capabilities();
+await quarto.console.withSpinner({ message: "Working..." }, async () => {
+  // do work
+});
+```
+
+#### External engines
+
+External engines receive the API via their `init()` method:
+
+```typescript
+let quarto: QuartoAPI;
+
+export const myEngineDiscovery: ExecutionEngineDiscovery = {
+  init: (quartoAPI: QuartoAPI) => {
+    quarto = quartoAPI; // Store for later use
+  },
+
+  // ... other methods can now use quarto
+};
+```
+
+#### Removing old imports
+
+When moving functionality to the API, **remove direct imports** from internal modules:
+
+```typescript
+// ❌ OLD - direct import
+import { withSpinner } from "../../core/console.ts";
+
+// ✅ NEW - use API
+import { quartoAPI as quarto } from "../../core/quarto-api.ts";
+const result = await quarto.console.withSpinner(...);
+```
+
+This ensures external engines and internal code use the same interface.
diff --git a/src/command/call/build-ts-extension/cmd.ts b/src/command/call/build-ts-extension/cmd.ts
@@ -88,11 +88,11 @@ async function autoDetectEntryPoint(
     error("  mkdir -p src");
     error("  touch src/my-engine.ts\n");
     error("Or specify entry point as argument:");
-    error("  quarto call build-ts-extension src/my-engine.ts");
+    error("  quarto call build-ts-extension src/my-engine.ts\n");
 
     // Only show deno.json config if it already exists
     if (existsSync("deno.json")) {
-      error("\nOr configure in deno.json:");
+      error("Or configure in deno.json:");
       error("  {");
       error('    "bundle": {');
       error('      "entryPoint": "path/to/file.ts"');
@@ -140,13 +140,13 @@ async function autoDetectEntryPoint(
 
   error(`Multiple .ts files found in src/: ${tsFiles.join(", ")}\n`);
   error("Specify entry point as argument:");
-  error("  quarto call build-ts-extension src/my-engine.ts");
-  error("\nOr rename one file to mod.ts:");
-  error(`  mv src/${tsFiles[0]} src/mod.ts`);
+  error("  quarto call build-ts-extension src/my-engine.ts\n");
+  error("Or rename one file to mod.ts:");
+  error(`  mv src/${tsFiles[0]} src/mod.ts\n`);
 
   // Only show deno.json config if it already exists
   if (existsSync("deno.json")) {
-    error("\nOr configure in deno.json:");
+    error("Or configure in deno.json:");
     error("  {");
     error('    "bundle": {');
     error('      "entryPoint": "src/my-engine.ts"');
