@kubohiroya/turbowarp-runtime-adapter 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.6.0
+
+- `createTurboWarpDebuggerLog` と `redactDebuggerLogText` を追加。機能拡張の警告とエラーを、エディターのデバッガーアドオンの Logs タブへ書く（コンソールにも出す）。アドオンの log・warn・error ブロックを使うので、VM と GUI は変更しない。書き出せる Logs には URL のクエリー・ローカルのパス・資格情報を伏せて渡す。行はブロックに結び付けない（アドオンのプレビューが多くのブロックで失敗し、一覧が描かれなくなるため）。既存の公開 API の動作は変えない。
+
 ## 0.4.0
 
 - Node.js 26・pnpm 11.28.8の検証済みツールチェーンとTrusted Publisherリリースに追従。

package/README.ja.md

@@ -13,6 +13,7 @@
 - 小さく検証された host adapter 経由で hats を起動する。
 - Stage target、sprite target、renderer、monitor store を読む。
 - Stage に宣言された exact broadcast name 用の汎用 `broadcastMessageAndWait` port を提供する。
+- 機能拡張の警告とエラーを、エディターのデバッガーの Logs タブへ書く。
 - extension の `getInfo()` block list のうち定型部分を組み立てる。
 - Scratch VM への直接アクセスを狭い interface に閉じ込める。
 
@@ -68,6 +69,24 @@ const surface = build.surface(
 const written = coerceScalarBlockValue(args.VALUE, args.TYPE, {errorCodePrefix: 'K4'});
 ```
 
+## デバッガーのログ
+
+`createTurboWarpDebuggerLog({Scratch, source})` は、機能拡張の警告とエラーを、エディターのデバッガーアドオンの Logs タブへ書く。これを使うすべての機能拡張と、作品自身のログブロックの出力が、同じ場所に並ぶ。各行の先頭には `[source]` を付ける。
+
+```js
+const log = createTurboWarpDebuggerLog({Scratch, source: 'My extension'});
+log.warn('Camera unavailable.', error);
+log.error('Playback failed.', error);
+```
+
+- 書き込み先の runtime は `runtime`、なければ `createTurboWarpRuntimeHost` と同じく `Scratch.vm.runtime` から取る。渡した runtime が runtime でなければ `TWRH-RUNTIME-001` を投げる。どちらもなければコンソールにだけ出す。
+- `log`・`warn`・`error` は、メッセージと省略できる詳細を受け取る。詳細は、`Error` なら `名前: メッセージ [code]`、普通のオブジェクトならおよそ `maxLength` 文字までの JSON にする。デバッガーに届いたかどうかを返す。
+- 行はブロックに結び付けない。アドオンは結び付いたブロックの最初の入力をプレビューするが、自分のログブロック以外の多くのブロック（たとえば数値の入力）ではそのプレビューが失敗し、Logs の一覧全体が描かれなくなる。
+- 同じ内容は常にコンソールにも、手を加えずに出す。詳細は別の引数で渡すので、開発者ツールではスタックも見られる。デバッガーだけに書くときは `console: null` を渡す。
+- Logs タブは内容を書き出せるので、デバッガーへ渡す文は先に `redact` を通す。既定の `redactDebuggerLogText` は、URL を origin とパスだけにし、ローカルのファイルパスを `[local path]` に、`token=`・`password:` などの後ろの値を `[redacted]` に置き換える。`redact: null` ならそのまま渡す。
+- 書き込みにはアドオン自身の log・warn・error ブロック（`runtime.getAddonBlock`）を使う。VM と GUI に新しい口は要らない。アドオンがない環境（プレイヤー、パッケージャー、アドオンを切ったとき）では `available()` が false になり、コンソールにだけ出す。
+- `maxLength` 文字（既定は 1000）を超える行は、文字の途中では切らずに切り詰める。
+
 ## 互換性
 
 既存 app が安定した app 固有 diagnostics を公開している場合は、`errorCodePrefix` を渡せます。たとえば `tm-kamishibai` は runtime interaction mechanics をこの package に委譲しつつ、`K4-BROADCAST-*` error を維持できます。

package/README.md

@@ -14,6 +14,7 @@ This package intentionally does not define app-specific DSL semantics, block met
 - Read the Stage target, the sprite targets, the renderer, and the monitor stores.
 - Provide a generic `broadcastMessageAndWait` port for exact Stage broadcast names.
 - Build the repetitive parts of an extension `getInfo()` block list.
+- Write extension warnings and errors to the Logs tab of the editor's debugger.
 - Keep Scratch VM access behind a narrow interface.
 
 ## Runtime surface
@@ -68,6 +69,24 @@ const surface = build.surface(
 const written = coerceScalarBlockValue(args.VALUE, args.TYPE, {errorCodePrefix: 'K4'});
 ```
 
+## Debugger log
+
+`createTurboWarpDebuggerLog({Scratch, source})` writes an extension's warnings and errors to the Logs tab of the editor's debugger add-on, where every extension using it and the project's own log blocks show together. Each entry starts with `[source]`.
+
+```js
+const log = createTurboWarpDebuggerLog({Scratch, source: 'My extension'});
+log.warn('Camera unavailable.', error);
+log.error('Playback failed.', error);
+```
+
+- The runtime is `runtime`, or else `Scratch.vm.runtime`, as `createTurboWarpRuntimeHost` resolves it. A runtime that is given must be one (`TWRH-RUNTIME-001` otherwise). Without any, entries only reach the console.
+- `log`, `warn` and `error` take a message, an optional detail (an `Error` becomes `Name: message [code]`, a plain object JSON of at most about `maxLength` characters). Each returns whether the entry reached the debugger.
+- An entry is not linked to a block. The add-on previews the first input of a linked block, and that preview fails on most blocks other than its own log blocks (a number input, for one), which stops the whole Logs list from drawing.
+- The entry always goes to the console too, unchanged and with the detail as a separate argument, so developer tools keep the stack. Pass `console: null` to write only to the debugger.
+- The Logs tab can export its entries, so the debugger's text goes through `redact` first. The default, `redactDebuggerLogText`, keeps only the origin and path of a URL, replaces local file paths with `[local path]` and credentials after `token=`, `password:` and the like with `[redacted]`. `redact: null` keeps the text as it is.
+- Entries go through the add-on's own log, warn and error blocks (`runtime.getAddonBlock`), so the VM and the GUI need no new interface. Without the add-on (a player, the packager, the add-on turned off) `available()` is false and entries only reach the console.
+- An entry longer than `maxLength` characters (1000 by default) is cut between characters, never inside one.
+
 ## Compatibility
 
 Consumers that already expose stable app-specific diagnostics can pass `errorCodePrefix`. For example, `tm-kamishibai` can keep `K4-BROADCAST-*` errors while delegating the runtime interaction mechanics to this package.

package/dist/index.d.ts

@@ -162,3 +162,66 @@ export type ScalarBlockValueResult = Readonly<{
 export declare function coerceScalarBlockValue(value: unknown, type: string, options?: {
     errorCodePrefix?: string;
 }): ScalarBlockValueResult;
+export type DebuggerLogLevel = 'log' | 'warn' | 'error';
+/** The slice of the runtime the debugger log reaches through: the editor add-ons' blocks. */
+export interface DebuggerLogRuntimeLike {
+    getAddonBlock?: (procedureCode: string) => {
+        callback(args: Record<string, unknown>, util: {
+            thread?: unknown;
+        }): unknown;
+    } | undefined;
+}
+export interface DebuggerLogConsole {
+    log(...data: unknown[]): void;
+    warn(...data: unknown[]): void;
+    error(...data: unknown[]): void;
+}
+export interface TurboWarpDebuggerLogOptions {
+    /** The runtime to write through. Without it, `Scratch.vm.runtime`, as `createTurboWarpRuntimeHost` resolves it. */
+    runtime?: unknown;
+    Scratch?: ScratchRuntimeHost;
+    /** A name put in front of every entry, so entries from several extensions can be told apart. */
+    source?: string;
+    /**
+     * Where an entry also goes. Defaults to the global `console`, so developer tools keep showing
+     * everything. `null` writes only to the debugger.
+     */
+    console?: DebuggerLogConsole | null;
+    /** Longest text of one debugger entry, in characters (code points). Defaults to 1000. */
+    maxLength?: number;
+    /**
+     * Applied to the debugger's text, which the Logs tab can export. Defaults to
+     * `redactDebuggerLogText`. `null` keeps the text as it is. The console gets the original.
+     */
+    redact?: ((text: string) => string) | null;
+}
+export interface TurboWarpDebuggerLog {
+    /** Whether the editor's debugger add-on is on and takes entries. */
+    available(): boolean;
+    /**
+     * Each returns true when the entry reached the debugger. An entry is not linked to a block: the
+     * add-on previews the first input of a linked block and fails on most blocks that are not its
+     * own log blocks (a number input, for one), which stops the whole Logs list from drawing.
+     */
+    log(message: string, detail?: unknown): boolean;
+    warn(message: string, detail?: unknown): boolean;
+    error(message: string, detail?: unknown): boolean;
+}
+/** The procedure codes of the debugger add-on's log blocks. */
+export declare const debuggerLogProcedureCodes: Readonly<Record<DebuggerLogLevel, string>>;
+/**
+ * Hide what should not leave the machine in a log the Logs tab can export: a URL keeps only its
+ * origin and path, a local file path becomes `[local path]`, and a credential after `token=`,
+ * `password:` and the like becomes `[redacted]`.
+ */
+export declare function redactDebuggerLogText(text: string): string;
+/**
+ * A log that writes to the Logs tab of the editor's debugger add-on, so the warnings and errors of
+ * every extension show in one place next to the project's own log blocks.
+ *
+ * Entries go through the add-on's own log, warn and error blocks (`runtime.getAddonBlock`), so
+ * neither the VM nor the GUI needs a new interface. Without the add-on (a player, the packager,
+ * plain TurboWarp with the add-on off) or without a runtime, an entry only goes to the console.
+ * A runtime that is given must be one: anything else throws `TWRH-RUNTIME-001`.
+ */
+export declare function createTurboWarpDebuggerLog(options?: TurboWarpDebuggerLogOptions): TurboWarpDebuggerLog;

package/dist/index.js

@@ -498,3 +498,131 @@ export function coerceScalarBlockValue(value, type, options = {}) {
     }
     return Object.freeze({ ok: false, code: prefixedCode(prefix, 'VARIABLE-WRITE-TYPE') });
 }
+// The add-on names its blocks with zero-width spaces so that they cannot clash with a project's own.
+const zeroWidthSpace = '\u200B\u200B';
+/** The procedure codes of the debugger add-on's log blocks. */
+export const debuggerLogProcedureCodes = Object.freeze({
+    log: `${zeroWidthSpace}log${zeroWidthSpace} %s`,
+    warn: `${zeroWidthSpace}warn${zeroWidthSpace} %s`,
+    error: `${zeroWidthSpace}error${zeroWidthSpace} %s`,
+});
+/**
+ * Hide what should not leave the machine in a log the Logs tab can export: a URL keeps only its
+ * origin and path, a local file path becomes `[local path]`, and a credential after `token=`,
+ * `password:` and the like becomes `[redacted]`.
+ */
+export function redactDebuggerLogText(text) {
+    return text
+        .replace(/https?:\/\/[^\s<>"']+/gu, (address) => {
+        try {
+            const url = new URL(address);
+            return `${url.origin}${url.pathname}`;
+        }
+        catch {
+            return '[URL]';
+        }
+    })
+        .replace(/(?:file:\/\/|[A-Za-z]:\\|\/(?:Users|home|private|tmp|var|Volumes)\/)[^\s"'<>]*/gu, '[local path]')
+        .replace(/\b(token|password|secret|authorization|api[_-]?key)\s*[:=]\s*[^\s,;]+/giu, '$1=[redacted]');
+}
+// JSON of at most about `budget` characters. Values past the budget are left out, so a large
+// record is not turned into a long string only to be cut.
+function boundedJson(detail, budget) {
+    let used = 0;
+    let cut = false;
+    try {
+        const json = JSON.stringify(detail, (key, value) => {
+            if (used > budget) {
+                cut = true;
+                return undefined;
+            }
+            used += key.length + (typeof value === 'string' ? value.length : 8);
+            return value;
+        });
+        return json === undefined ? '' : `${json}${cut ? '…' : ''}`;
+    }
+    catch {
+        return String(detail);
+    }
+}
+function detailText(detail, budget) {
+    if (detail === undefined || detail === null)
+        return '';
+    if (typeof detail === 'string')
+        return detail;
+    if (typeof detail === 'number' || typeof detail === 'boolean')
+        return String(detail);
+    const record = detail;
+    if (typeof record.message === 'string' || detail instanceof Error) {
+        const name = typeof record.name === 'string' && record.name !== 'Error' ? record.name : '';
+        const message = String(record.message ?? '');
+        const code = typeof record.code === 'string' && record.code ? ` [${record.code}]` : '';
+        return `${name && message ? `${name}: ` : name}${message}${code}`;
+    }
+    return boundedJson(detail, budget);
+}
+function shorten(text, maxLength) {
+    if (text.length <= maxLength)
+        return text;
+    // Count code points, so a cut never leaves half of a surrogate pair.
+    const characters = Array.from(text);
+    if (characters.length <= maxLength)
+        return text;
+    return `${characters.slice(0, Math.max(0, maxLength - 1)).join('')}…`;
+}
+/**
+ * A log that writes to the Logs tab of the editor's debugger add-on, so the warnings and errors of
+ * every extension show in one place next to the project's own log blocks.
+ *
+ * Entries go through the add-on's own log, warn and error blocks (`runtime.getAddonBlock`), so
+ * neither the VM nor the GUI needs a new interface. Without the add-on (a player, the packager,
+ * plain TurboWarp with the add-on off) or without a runtime, an entry only goes to the console.
+ * A runtime that is given must be one: anything else throws `TWRH-RUNTIME-001`.
+ */
+export function createTurboWarpDebuggerLog(options = {}) {
+    const candidate = options.runtime ?? options.Scratch?.vm?.runtime;
+    const runtime = candidate === undefined || candidate === null
+        ? null
+        : validateRuntime(candidate);
+    const output = options.console === undefined ? console : options.console;
+    const prefix = options.source ? `[${options.source}] ` : '';
+    const maxLength = options.maxLength ?? 1000;
+    const redact = options.redact === undefined ? redactDebuggerLogText : options.redact;
+    const block = (level) => {
+        try {
+            return runtime?.getAddonBlock?.(debuggerLogProcedureCodes[level]);
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const write = (level, message, detail) => {
+        if (output) {
+            if (detail === undefined)
+                output[level](`${prefix}${message}`);
+            else
+                output[level](`${prefix}${message}`, detail);
+        }
+        const logBlock = block(level);
+        if (!logBlock)
+            return false;
+        try {
+            const detailPart = detailText(detail, maxLength);
+            let text = `${prefix}${message}${detailPart ? ` ${detailPart}` : ''}`;
+            if (redact)
+                text = redact(text);
+            logBlock.callback({ content: shorten(text, maxLength) }, { thread: undefined });
+            return true;
+        }
+        catch {
+            // The debugger cannot take the entry. The console already has it.
+            return false;
+        }
+    };
+    return Object.freeze({
+        available: () => Boolean(block('log')),
+        log: (message, detail) => write('log', message, detail),
+        warn: (message, detail) => write('warn', message, detail),
+        error: (message, detail) => write('error', message, detail),
+    });
+}

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@kubohiroya/turbowarp-runtime-adapter",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "App-neutral adapters for interacting with the TurboWarp runtime.",
-  "author": "Hiroya Kubo <hiroya@cuc.ac.jp>",
+  "author": {
+    "name": "Hiroya Kubo",
+    "email": "hiroya@cuc.ac.jp",
+    "url": "https://github.com/kubohiroya"
+  },
   "license": "MPL-2.0",
   "type": "module",
   "sideEffects": false,

package/src/index.ts

@@ -743,3 +743,184 @@ export function coerceScalarBlockValue(
   }
   return Object.freeze({ok: false as const, code: prefixedCode(prefix, 'VARIABLE-WRITE-TYPE')});
 }
+
+export type DebuggerLogLevel = 'log' | 'warn' | 'error';
+
+/** The slice of the runtime the debugger log reaches through: the editor add-ons' blocks. */
+export interface DebuggerLogRuntimeLike {
+  getAddonBlock?: (
+    procedureCode: string,
+  ) => {callback(args: Record<string, unknown>, util: {thread?: unknown}): unknown} | undefined;
+}
+
+export interface DebuggerLogConsole {
+  log(...data: unknown[]): void;
+  warn(...data: unknown[]): void;
+  error(...data: unknown[]): void;
+}
+
+export interface TurboWarpDebuggerLogOptions {
+  /** The runtime to write through. Without it, `Scratch.vm.runtime`, as `createTurboWarpRuntimeHost` resolves it. */
+  runtime?: unknown;
+  Scratch?: ScratchRuntimeHost;
+  /** A name put in front of every entry, so entries from several extensions can be told apart. */
+  source?: string;
+  /**
+   * Where an entry also goes. Defaults to the global `console`, so developer tools keep showing
+   * everything. `null` writes only to the debugger.
+   */
+  console?: DebuggerLogConsole | null;
+  /** Longest text of one debugger entry, in characters (code points). Defaults to 1000. */
+  maxLength?: number;
+  /**
+   * Applied to the debugger's text, which the Logs tab can export. Defaults to
+   * `redactDebuggerLogText`. `null` keeps the text as it is. The console gets the original.
+   */
+  redact?: ((text: string) => string) | null;
+}
+
+export interface TurboWarpDebuggerLog {
+  /** Whether the editor's debugger add-on is on and takes entries. */
+  available(): boolean;
+  /**
+   * Each returns true when the entry reached the debugger. An entry is not linked to a block: the
+   * add-on previews the first input of a linked block and fails on most blocks that are not its
+   * own log blocks (a number input, for one), which stops the whole Logs list from drawing.
+   */
+  log(message: string, detail?: unknown): boolean;
+  warn(message: string, detail?: unknown): boolean;
+  error(message: string, detail?: unknown): boolean;
+}
+
+// The add-on names its blocks with zero-width spaces so that they cannot clash with a project's own.
+const zeroWidthSpace = '\u200B\u200B';
+
+/** The procedure codes of the debugger add-on's log blocks. */
+export const debuggerLogProcedureCodes: Readonly<Record<DebuggerLogLevel, string>> = Object.freeze({
+  log: `${zeroWidthSpace}log${zeroWidthSpace} %s`,
+  warn: `${zeroWidthSpace}warn${zeroWidthSpace} %s`,
+  error: `${zeroWidthSpace}error${zeroWidthSpace} %s`,
+});
+
+/**
+ * Hide what should not leave the machine in a log the Logs tab can export: a URL keeps only its
+ * origin and path, a local file path becomes `[local path]`, and a credential after `token=`,
+ * `password:` and the like becomes `[redacted]`.
+ */
+export function redactDebuggerLogText(text: string): string {
+  return text
+    .replace(/https?:\/\/[^\s<>"']+/gu, (address) => {
+      try {
+        const url = new URL(address);
+        return `${url.origin}${url.pathname}`;
+      } catch {
+        return '[URL]';
+      }
+    })
+    .replace(
+      /(?:file:\/\/|[A-Za-z]:\\|\/(?:Users|home|private|tmp|var|Volumes)\/)[^\s"'<>]*/gu,
+      '[local path]',
+    )
+    .replace(
+      /\b(token|password|secret|authorization|api[_-]?key)\s*[:=]\s*[^\s,;]+/giu,
+      '$1=[redacted]',
+    );
+}
+
+// JSON of at most about `budget` characters. Values past the budget are left out, so a large
+// record is not turned into a long string only to be cut.
+function boundedJson(detail: unknown, budget: number): string {
+  let used = 0;
+  let cut = false;
+  try {
+    const json = JSON.stringify(detail, (key: string, value: unknown) => {
+      if (used > budget) {
+        cut = true;
+        return undefined;
+      }
+      used += key.length + (typeof value === 'string' ? value.length : 8);
+      return value;
+    });
+    return json === undefined ? '' : `${json}${cut ? '…' : ''}`;
+  } catch {
+    return String(detail);
+  }
+}
+
+function detailText(detail: unknown, budget: number): string {
+  if (detail === undefined || detail === null) return '';
+  if (typeof detail === 'string') return detail;
+  if (typeof detail === 'number' || typeof detail === 'boolean') return String(detail);
+  const record = detail as {name?: unknown; code?: unknown; message?: unknown};
+  if (typeof record.message === 'string' || detail instanceof Error) {
+    const name = typeof record.name === 'string' && record.name !== 'Error' ? record.name : '';
+    const message = String(record.message ?? '');
+    const code = typeof record.code === 'string' && record.code ? ` [${record.code}]` : '';
+    return `${name && message ? `${name}: ` : name}${message}${code}`;
+  }
+  return boundedJson(detail, budget);
+}
+
+function shorten(text: string, maxLength: number) {
+  if (text.length <= maxLength) return text;
+  // Count code points, so a cut never leaves half of a surrogate pair.
+  const characters = Array.from(text);
+  if (characters.length <= maxLength) return text;
+  return `${characters.slice(0, Math.max(0, maxLength - 1)).join('')}…`;
+}
+
+/**
+ * A log that writes to the Logs tab of the editor's debugger add-on, so the warnings and errors of
+ * every extension show in one place next to the project's own log blocks.
+ *
+ * Entries go through the add-on's own log, warn and error blocks (`runtime.getAddonBlock`), so
+ * neither the VM nor the GUI needs a new interface. Without the add-on (a player, the packager,
+ * plain TurboWarp with the add-on off) or without a runtime, an entry only goes to the console.
+ * A runtime that is given must be one: anything else throws `TWRH-RUNTIME-001`.
+ */
+export function createTurboWarpDebuggerLog(
+  options: TurboWarpDebuggerLogOptions = {},
+): TurboWarpDebuggerLog {
+  const candidate = options.runtime ?? options.Scratch?.vm?.runtime;
+  const runtime =
+    candidate === undefined || candidate === null
+      ? null
+      : (validateRuntime(candidate) as unknown as DebuggerLogRuntimeLike);
+  const output = options.console === undefined ? console : options.console;
+  const prefix = options.source ? `[${options.source}] ` : '';
+  const maxLength = options.maxLength ?? 1000;
+  const redact = options.redact === undefined ? redactDebuggerLogText : options.redact;
+  const block = (level: DebuggerLogLevel) => {
+    try {
+      return runtime?.getAddonBlock?.(debuggerLogProcedureCodes[level]);
+    } catch {
+      return undefined;
+    }
+  };
+
+  const write = (level: DebuggerLogLevel, message: string, detail: unknown) => {
+    if (output) {
+      if (detail === undefined) output[level](`${prefix}${message}`);
+      else output[level](`${prefix}${message}`, detail);
+    }
+    const logBlock = block(level);
+    if (!logBlock) return false;
+    try {
+      const detailPart = detailText(detail, maxLength);
+      let text = `${prefix}${message}${detailPart ? ` ${detailPart}` : ''}`;
+      if (redact) text = redact(text);
+      logBlock.callback({content: shorten(text, maxLength)}, {thread: undefined});
+      return true;
+    } catch {
+      // The debugger cannot take the entry. The console already has it.
+      return false;
+    }
+  };
+
+  return Object.freeze({
+    available: () => Boolean(block('log')),
+    log: (message: string, detail?: unknown) => write('log', message, detail),
+    warn: (message: string, detail?: unknown) => write('warn', message, detail),
+    error: (message: string, detail?: unknown) => write('error', message, detail),
+  });
+}