@dolusoft/command-protocol 0.0.0-stage → 1.0.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dolusoft
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,75 @@
-# Temporary Holding Version
+# @dolusoft/command-protocol
 
-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 JSON types of [Command Console](https://github.com/dolusoft/command-console) and its line tokenizer. No
+dependencies, no framework, no DOM.
+
+```sh
+pnpm add @dolusoft/command-protocol
+```
+
+Most consumers use it through `@dolusoft/command-console` (which re-exports its types) or
+`@dolusoft/command-console-core`. Use it directly when a server or a test builds console output, or to split a line the way the console does.
+
+## Types
+
+Every type here is plain JSON: finite numbers only, no `undefined` (an optional field without a value is absent), and
+a value survives `JSON.parse(JSON.stringify(x))` unchanged. `JsonValue`, `JsonPrimitive` and `isJsonValue` describe and
+check it. Functions (a command's `run` and `complete`, callbacks) live in the core, never here.
+
+- **Entries** of the scrollback: `ConsoleEntry` is an `InputEntry` (`id`, `prompt` when the line ended, `text` or
+  `null` when redacted, `redacted`, `status: 'submitted' | 'cancelled'`) or an `OutputEntry` (`id`,
+  `tone: 'default' | 'error' | 'notice'`, `blocks`, optional `inputId` of the line it answers, optional `quiet: true`
+  for output a live region should not read out).
+- **Blocks** of an output entry (`OutputBlock`), never HTML:
+
+  | Block     | Fields                                                               |
+  | --------- | -------------------------------------------------------------------- |
+  | `text`    | `text`                                                               |
+  | `json`    | `value: JsonValue`                                                   |
+  | `table`   | `columns: { key, label }[]`, `rows: Record<string, JsonPrimitive>[]` |
+  | `list`    | `items: string[]`                                                    |
+  | `message` | `code: MessageCode`, `params?` (made by the library)                 |
+  | `custom`  | `kind`, `data?: JsonValue` (drawn by the consumer)                   |
+
+- **Messages** (`MessageCode`, `MessageParams`): the library writes no text, only codes. `command-not-found`
+  (`{ name }`), `command-failed` (no params: the error's text is never shown), `unterminated-quote` (`{ index }`),
+  `interrupted`. For a sensitive line `name` and `index` are `null`.
+- **Commands**: `CommandSpec` is the JSON part of a command (`name`, `aliases`, `summary`, `usage`, `hidden`,
+  `sensitive: boolean | { fromArg }`). `CommandResponse` is what a command may return (`output`, `tone`, `quiet`,
+  `effects`).
+- **Effects** (`ConsoleEffect`): `clear`, `close`, `push-context` (`frame`), `pop-context` (`count?`, default 1),
+  `reset-context`, `clear-recall`. They apply in order, before the response's output.
+- **Context frames** (`ContextFrame`): `{ id, prompt, data? }`. The top frame's `prompt` is the prompt of the next line.
+
+## Line syntax
+
+Whitespace (tabs included) separates tokens. `'…'` groups literally. `"…"` groups, and inside it `\"` and `\\` are the
+only escapes. Outside quotes `\` is an ordinary character, so `C:\data` stays `C:\data`. Adjacent parts join one token
+(`a"b c"d` is `ab cd`); `''` and `""` give an empty token. There is no line continuation.
+
+```ts
+import { quoteArgument, tokenize } from '@dolusoft/command-protocol'
+
+tokenize(`set title "Hello \\"world\\""`).tokens.map(t => t.value)
+// ['set', 'title', 'Hello "world"']
+
+const result = tokenize(`set title 'Hello`)
+// result.ok === false, result.error: { code: 'unterminated-quote', index: 10 }
+// result.tokens still holds the tolerant tokens; the last one has open: true
+
+const args = ['set', 'path', 'C:\\Program Files']
+const line = args.map(quoteArgument).join(' ')
+// "set path 'C:\\Program Files'", which tokenizes back to the same three values
+```
+
+Each `Token` has its `value` (quotes removed), `start` and `end` (UTF-16 offsets into the line, `end` exclusive,
+covering the raw text including its quotes), `quoted` and `open`. An unclosed quote gives `ok: false` with the index of
+the opening quote, and the tokens are still returned: the last one is `open` and runs to the end of the line. The
+console refuses such a line; completion works on the tolerant tokens. Nothing is ever dropped.
+
+`quoteArgument(value)` returns the shortest of: the bare value, `'value'`, or `"value"` with escapes; it always
+tokenizes back to `value`.
+
+## License
+
+MIT, see [LICENSE.md](./LICENSE.md).

package/dist/command-protocol.js

@@ -0,0 +1,166 @@
+// src/json.ts
+/**
+* Whether `value` is a JSON value that survives
+* `JSON.parse(JSON.stringify(value))` unchanged: strings, booleans, `null`,
+* finite numbers, dense arrays and plain objects (prototype `Object.prototype`
+* or `null`) of such values, without cycles. `undefined`, functions, symbols,
+* bigints, class instances (`Date`, `Map`, …), sparse arrays and non-finite
+* numbers are not. `-0` is accepted; it reads back as `0`.
+*/
+function isJsonValue(value) {
+	return check(value, []);
+}
+function check(value, path) {
+	if (value === null) return true;
+	switch (typeof value) {
+		case "string":
+		case "boolean": return true;
+		case "number": return Number.isFinite(value);
+		case "object": break;
+		default: return false;
+	}
+	const object = value;
+	if (path.includes(object)) return false;
+	path.push(object);
+	const result = Array.isArray(object) ? checkArray(object, path) : checkObject(object, path);
+	path.pop();
+	return result;
+}
+function checkArray(array, path) {
+	if (Object.getPrototypeOf(array) !== Array.prototype) return false;
+	for (let i = 0; i < array.length; i++) if (!(i in array) || !check(array[i], path)) return false;
+	return true;
+}
+function checkObject(object, path) {
+	const prototype = Object.getPrototypeOf(object);
+	if (prototype !== Object.prototype && prototype !== null) return false;
+	if (Object.getOwnPropertySymbols(object).length > 0) return false;
+	const record = object;
+	for (const key of Object.keys(record)) if (!check(record[key], path)) return false;
+	return true;
+}
+// src/syntax/tokenize.ts
+var whitespace = /\s/;
+/** Whether `char` separates tokens (`\s`, so tabs and line breaks too). */
+function isSeparator(char) {
+	return whitespace.test(char);
+}
+/**
+* Splits a line into tokens. Runs of whitespace separate. `'…'` groups
+* literally. `"…"` groups, and inside it `\"` and `\\` are the only escapes;
+* any other `\` is kept. Outside quotes `\` is an ordinary character. Adjacent
+* parts join one token (`a"b c"d` is `ab cd`); `''` and `""` give an empty
+* token. `start`/`end` cover the raw text of each token, quotes included.
+*/
+function tokenize(line) {
+	const tokens = [];
+	let error = null;
+	let i = 0;
+	const length = line.length;
+	while (i < length) {
+		if (isSeparator(line[i])) {
+			i++;
+			continue;
+		}
+		const start = i;
+		let value = "";
+		let quoted = false;
+		let open = false;
+		while (i < length && !isSeparator(line[i])) {
+			const char = line[i];
+			if (char === "'") {
+				quoted = true;
+				const close = line.indexOf("'", i + 1);
+				if (close === -1) {
+					value += line.slice(i + 1);
+					open = true;
+					error = {
+						code: "unterminated-quote",
+						index: i
+					};
+					i = length;
+					break;
+				}
+				value += line.slice(i + 1, close);
+				i = close + 1;
+			} else if (char === "\"") {
+				quoted = true;
+				const opening = i;
+				i++;
+				let closed = false;
+				while (i < length) {
+					const inner = line[i];
+					if (inner === "\"") {
+						closed = true;
+						i++;
+						break;
+					}
+					const next = line.charAt(i + 1);
+					if (inner === "\\" && (next === "\"" || next === "\\")) {
+						value += next;
+						i += 2;
+					} else {
+						value += inner;
+						i++;
+					}
+				}
+				if (!closed) {
+					open = true;
+					error = {
+						code: "unterminated-quote",
+						index: opening
+					};
+					break;
+				}
+			} else {
+				value += char;
+				i++;
+			}
+		}
+		tokens.push({
+			value,
+			start,
+			end: i,
+			quoted,
+			open
+		});
+	}
+	return error === null ? {
+		ok: true,
+		tokens
+	} : {
+		ok: false,
+		tokens,
+		error
+	};
+}
+// src/syntax/quote.ts
+/**
+* The shortest form of `value` that `tokenize` reads back as one token with
+* that value: bare when it is non-empty and has no whitespace and no quote,
+* else `'…'` when it has no `'`, else `"…"` with `"` written as `\"` and a
+* `\` written as `\\` where it comes before a `"`, a `\` or the closing quote.
+*/
+function quoteArgument(value) {
+	if (value === "" || needsQuotes(value)) return value.includes("'") ? doubleQuote(value) : `'${value}'`;
+	return value;
+}
+function needsQuotes(value) {
+	for (const char of value) if (char === "'" || char === "\"" || isSeparator(char)) return true;
+	return false;
+}
+function doubleQuote(value) {
+	let result = "\"";
+	for (let i = 0; i < value.length; i++) {
+		const char = value[i];
+		if (char === "\"") result += "\\\"";
+		else if (char === "\\") {
+			const next = value.charAt(i + 1);
+			result += next === "" || next === "\"" || next === "\\" ? "\\\\" : "\\";
+		} else result += char;
+	}
+	return `${result}"`;
+}
+export { isJsonValue, quoteArgument, tokenize };
+
+//# sourceMappingURL=command-protocol.js.map

package/dist/command-protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-protocol.js","names":[],"sources":["../src/json.ts","../src/syntax/tokenize.ts","../src/syntax/quote.ts"],"sourcesContent":["/** A JSON leaf. Numbers are finite: `NaN` and the infinities are not JSON. */\nexport type JsonPrimitive = string | number | boolean | null\n\n/**\n * A JSON value: a primitive, an array of values or a plain object of values.\n * Every protocol type is made of these (P4).\n */\nexport type JsonValue =\n  JsonPrimitive | JsonValue[] | { [key: string]: JsonValue }\n\n/**\n * Whether `value` is a JSON value that survives\n * `JSON.parse(JSON.stringify(value))` unchanged: strings, booleans, `null`,\n * finite numbers, dense arrays and plain objects (prototype `Object.prototype`\n * or `null`) of such values, without cycles. `undefined`, functions, symbols,\n * bigints, class instances (`Date`, `Map`, …), sparse arrays and non-finite\n * numbers are not. `-0` is accepted; it reads back as `0`.\n */\nexport function isJsonValue(value: unknown): value is JsonValue {\n  return check(value, [])\n}\n\nfunction check(value: unknown, path: object[]): boolean {\n  if (value === null) {\n    return true\n  }\n  switch (typeof value) {\n    case 'string':\n    case 'boolean':\n      return true\n    case 'number':\n      return Number.isFinite(value)\n    case 'object':\n      break\n    default:\n      return false\n  }\n  const object = value\n  if (path.includes(object)) {\n    return false\n  }\n  path.push(object)\n  const result = Array.isArray(object)\n    ? checkArray(object as unknown[], path)\n    : checkObject(object, path)\n  path.pop()\n  return result\n}\n\nfunction checkArray(array: unknown[], path: object[]): boolean {\n  if (Object.getPrototypeOf(array) !== Array.prototype) {\n    return false\n  }\n  for (let i = 0; i < array.length; i++) {\n    if (!(i in array) || !check(array[i], path)) {\n      return false\n    }\n  }\n  return true\n}\n\nfunction checkObject(object: object, path: object[]): boolean {\n  const prototype: unknown = Object.getPrototypeOf(object)\n  if (prototype !== Object.prototype && prototype !== null) {\n    return false\n  }\n  if (Object.getOwnPropertySymbols(object).length > 0) {\n    return false\n  }\n  const record = object as Record<string, unknown>\n  for (const key of Object.keys(record)) {\n    if (!check(record[key], path)) {\n      return false\n    }\n  }\n  return true\n}\n","// The line syntax (ADR 0007): shell-like quoting, `\\` literal outside double\n// quotes, no continuation. The tokenizer never drops a character: every\n// non-whitespace character of the line is inside exactly one token's span.\n\n/** One token of a line. */\nexport interface Token {\n  /** The token's text with grouping quotes and escapes removed. */\n  value: string\n  /** UTF-16 offset of the token's first raw character in the line. */\n  start: number\n  /** UTF-16 offset after the token's last raw character (exclusive). */\n  end: number\n  /** True when any part of the token is quoted (`'…'` or `\"…\"`). */\n  quoted: boolean\n  /**\n   * True when the token ends in a quote that is not closed; it then runs to\n   * the end of the line. Only the last token can be open.\n   */\n  open: boolean\n}\n\n/** The error of a line whose quote is not closed. */\nexport interface TokenizeError {\n  code: 'unterminated-quote'\n  /** UTF-16 offset of the opening quote that is not closed. */\n  index: number\n}\n\n/**\n * The tokens of a line. With `ok: false` the tokens are still returned\n * (tolerant): the last one has `open: true`. Dispatch refuses such a line;\n * completion works on its tokens.\n */\nexport type TokenizeResult =\n  | { ok: true; tokens: Token[] }\n  | { ok: false; tokens: Token[]; error: TokenizeError }\n\nconst whitespace = /\\s/\n\n/** Whether `char` separates tokens (`\\s`, so tabs and line breaks too). */\nexport function isSeparator(char: string): boolean {\n  return whitespace.test(char)\n}\n\n/**\n * Splits a line into tokens. Runs of whitespace separate. `'…'` groups\n * literally. `\"…\"` groups, and inside it `\\\"` and `\\\\` are the only escapes;\n * any other `\\` is kept. Outside quotes `\\` is an ordinary character. Adjacent\n * parts join one token (`a\"b c\"d` is `ab cd`); `''` and `\"\"` give an empty\n * token. `start`/`end` cover the raw text of each token, quotes included.\n */\nexport function tokenize(line: string): TokenizeResult {\n  const tokens: Token[] = []\n  let error: TokenizeError | null = null\n  let i = 0\n  const length = line.length\n\n  while (i < length) {\n    if (isSeparator(line[i])) {\n      i++\n      continue\n    }\n    const start = i\n    let value = ''\n    let quoted = false\n    let open = false\n\n    while (i < length && !isSeparator(line[i])) {\n      const char = line[i]\n      if (char === \"'\") {\n        quoted = true\n        const close = line.indexOf(\"'\", i + 1)\n        if (close === -1) {\n          value += line.slice(i + 1)\n          open = true\n          error = { code: 'unterminated-quote', index: i }\n          i = length\n          break\n        }\n        value += line.slice(i + 1, close)\n        i = close + 1\n      } else if (char === '\"') {\n        quoted = true\n        const opening = i\n        i++\n        let closed = false\n        while (i < length) {\n          const inner = line[i]\n          if (inner === '\"') {\n            closed = true\n            i++\n            break\n          }\n          const next = line.charAt(i + 1)\n          if (inner === '\\\\' && (next === '\"' || next === '\\\\')) {\n            value += next\n            i += 2\n          } else {\n            value += inner\n            i++\n          }\n        }\n        if (!closed) {\n          open = true\n          error = { code: 'unterminated-quote', index: opening }\n          break\n        }\n      } else {\n        value += char\n        i++\n      }\n    }\n\n    tokens.push({ value, start, end: i, quoted, open })\n  }\n\n  return error === null ? { ok: true, tokens } : { ok: false, tokens, error }\n}\n","import { isSeparator } from './tokenize'\n\n/**\n * The shortest form of `value` that `tokenize` reads back as one token with\n * that value: bare when it is non-empty and has no whitespace and no quote,\n * else `'…'` when it has no `'`, else `\"…\"` with `\"` written as `\\\"` and a\n * `\\` written as `\\\\` where it comes before a `\"`, a `\\` or the closing quote.\n */\nexport function quoteArgument(value: string): string {\n  if (value === '' || needsQuotes(value)) {\n    return value.includes(\"'\") ? doubleQuote(value) : `'${value}'`\n  }\n  return value\n}\n\nfunction needsQuotes(value: string): boolean {\n  for (const char of value) {\n    if (char === \"'\" || char === '\"' || isSeparator(char)) {\n      return true\n    }\n  }\n  return false\n}\n\nfunction doubleQuote(value: string): string {\n  let result = '\"'\n  for (let i = 0; i < value.length; i++) {\n    const char = value[i]\n    if (char === '\"') {\n      result += '\\\\\"'\n    } else if (char === '\\\\') {\n      const next = value.charAt(i + 1)\n      result += next === '' || next === '\"' || next === '\\\\' ? '\\\\\\\\' : '\\\\'\n    } else {\n      result += char\n    }\n  }\n  return `${result}\"`\n}\n"],"mappings":"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"}

package/dist/types/block.d.ts

@@ -0,0 +1,69 @@
+import type { JsonPrimitive, JsonValue } from './json.js';
+/** Plain text, rendered preformatted. */
+export interface TextBlock {
+    type: 'text';
+    text: string;
+}
+/** A JSON value, rendered as `JSON.stringify(value, null, 2)`. */
+export interface JsonBlock {
+    type: 'json';
+    value: JsonValue;
+}
+/** One column of a table block: the row key it reads and its header text. */
+export interface TableColumn {
+    key: string;
+    label: string;
+}
+/** A table: a header row from `columns`, then one row per `rows` item. */
+export interface TableBlock {
+    type: 'table';
+    columns: TableColumn[];
+    rows: Record<string, JsonPrimitive>[];
+}
+/** A list of text items. */
+export interface ListBlock {
+    type: 'list';
+    items: string[];
+}
+/**
+ * A message the library makes. It carries a code, never text: the Vue package
+ * renders it from its labels (P7).
+ */
+export interface MessageBlock {
+    type: 'message';
+    code: MessageCode;
+    params?: Record<string, JsonPrimitive>;
+}
+/** A block the consumer renders itself, told apart by `kind`. */
+export interface CustomBlock {
+    type: 'custom';
+    kind: string;
+    data?: JsonValue;
+}
+/** One piece of an output entry. Output is never HTML (ADR 0005). */
+export type OutputBlock = TextBlock | JsonBlock | TableBlock | ListBlock | MessageBlock | CustomBlock;
+/**
+ * The messages the library makes:
+ *
+ * - `command-not-found`: the first token names no command.
+ * - `command-failed`: the command threw or rejected; the error's text is never
+ *   shown (S-06).
+ * - `unterminated-quote`: the line has a quote that is not closed.
+ * - `interrupted`: a running command was cancelled.
+ */
+export type MessageCode = 'command-not-found' | 'command-failed' | 'unterminated-quote' | 'interrupted';
+/**
+ * The parameters of each message code. For a sensitive line `name` and
+ * `index` are `null`. A code without parameters has an empty record; its
+ * block carries no `params`.
+ */
+export interface MessageParams {
+    'command-not-found': {
+        name: string | null;
+    };
+    'command-failed': Record<string, never>;
+    'unterminated-quote': {
+        index: number | null;
+    };
+    interrupted: Record<string, never>;
+}

package/dist/types/command.d.ts

@@ -0,0 +1,62 @@
+import type { OutputBlock } from './block.js';
+import type { ContextFrame } from './context.js';
+import type { OutputEntry } from './entry.js';
+/**
+ * The JSON part of a command: its names and how it is listed and redacted.
+ * The core adds the functions (`run`, `complete`) to it.
+ */
+export interface CommandSpec {
+    /** Non-empty, no whitespace, no quote characters; unique with the aliases. */
+    name: string;
+    /** Other names that run the same command; the same rules as `name`. */
+    aliases?: string[];
+    /** One line on what the command does, for the consumer's help. */
+    summary?: string;
+    /** How the command is called, for the consumer's help. */
+    usage?: string;
+    /** Not listed by `getCommands` and not completed by name. */
+    hidden?: boolean;
+    /**
+     * Arguments at and after `fromArg` are secret, so the line is redacted and
+     * those positions are never completed. `true` is `{ fromArg: 0 }`.
+     */
+    sensitive?: boolean | {
+        fromArg: number;
+    };
+}
+/** What a command returns, as JSON. */
+export interface CommandResponse {
+    /** A string is one text block. */
+    output?: string | OutputBlock[];
+    /** Default `'default'`. */
+    tone?: OutputEntry['tone'];
+    /** Copied to the output entry. */
+    quiet?: true;
+    /** Applied in order, before the output is appended. */
+    effects?: ConsoleEffect[];
+}
+/**
+ * A change a command asks the console to make:
+ *
+ * - `clear`: empty the entries.
+ * - `close`: ask the consumer to close the console.
+ * - `push-context`: push a frame on the context stack.
+ * - `pop-context`: pop `count` frames (default 1); stops at the root.
+ * - `reset-context`: return to the root.
+ * - `clear-recall`: empty the recall list.
+ */
+export type ConsoleEffect = {
+    type: 'clear';
+} | {
+    type: 'close';
+} | {
+    type: 'push-context';
+    frame: ContextFrame;
+} | {
+    type: 'pop-context';
+    count?: number;
+} | {
+    type: 'reset-context';
+} | {
+    type: 'clear-recall';
+};

package/dist/types/context.d.ts

@@ -0,0 +1,14 @@
+import type { JsonValue } from './json.js';
+/**
+ * One level of the context stack. The stack runs bottom → top; the root is
+ * implicit and has no frame. The prompt of a new input entry is the top
+ * frame's `prompt`. What a frame means is the consumer's (`data`).
+ */
+export interface ContextFrame {
+    /** Identifies the frame; a change of the id sequence is a context change. */
+    id: string;
+    /** The prompt shown while this frame is on top. */
+    prompt: string;
+    /** The consumer's data for this frame. */
+    data?: JsonValue;
+}

package/dist/types/entry.d.ts

@@ -0,0 +1,27 @@
+import type { OutputBlock } from './block.js';
+/** One entry of the scrollback: a line the user ended, or output. */
+export type ConsoleEntry = InputEntry | OutputEntry;
+/** A line the user ended, with the prompt it was ended with. */
+export interface InputEntry {
+    id: string;
+    kind: 'input';
+    /** The prompt when the line ended. */
+    prompt: string;
+    /** The trimmed line; `null` when the line was sensitive. */
+    text: string | null;
+    /** True when the line was sensitive and its text is not kept. */
+    redacted: boolean;
+    /** `cancelled` when the line was ended with Ctrl+C. */
+    status: 'submitted' | 'cancelled';
+}
+/** What a command or the library wrote. */
+export interface OutputEntry {
+    id: string;
+    kind: 'output';
+    tone: 'default' | 'error' | 'notice';
+    blocks: OutputBlock[];
+    /** The input entry this output answers. */
+    inputId?: string;
+    /** Not announced by the live region (long output such as a whole config). */
+    quiet?: true;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,9 @@
+export type { JsonPrimitive, JsonValue } from './json.js';
+export { isJsonValue } from './json.js';
+export type { ConsoleEntry, InputEntry, OutputEntry } from './entry.js';
+export type { CustomBlock, JsonBlock, ListBlock, MessageBlock, MessageCode, MessageParams, OutputBlock, TableBlock, TableColumn, TextBlock } from './block.js';
+export type { CommandResponse, CommandSpec, ConsoleEffect } from './command.js';
+export type { ContextFrame } from './context.js';
+export type { Token, TokenizeError, TokenizeResult } from './syntax/tokenize.js';
+export { tokenize } from './syntax/tokenize.js';
+export { quoteArgument } from './syntax/quote.js';

package/dist/types/json.d.ts

@@ -0,0 +1,18 @@
+/** A JSON leaf. Numbers are finite: `NaN` and the infinities are not JSON. */
+export type JsonPrimitive = string | number | boolean | null;
+/**
+ * A JSON value: a primitive, an array of values or a plain object of values.
+ * Every protocol type is made of these (P4).
+ */
+export type JsonValue = JsonPrimitive | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/**
+ * Whether `value` is a JSON value that survives
+ * `JSON.parse(JSON.stringify(value))` unchanged: strings, booleans, `null`,
+ * finite numbers, dense arrays and plain objects (prototype `Object.prototype`
+ * or `null`) of such values, without cycles. `undefined`, functions, symbols,
+ * bigints, class instances (`Date`, `Map`, …), sparse arrays and non-finite
+ * numbers are not. `-0` is accepted; it reads back as `0`.
+ */
+export declare function isJsonValue(value: unknown): value is JsonValue;

package/dist/types/syntax/quote.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The shortest form of `value` that `tokenize` reads back as one token with
+ * that value: bare when it is non-empty and has no whitespace and no quote,
+ * else `'…'` when it has no `'`, else `"…"` with `"` written as `\"` and a
+ * `\` written as `\\` where it comes before a `"`, a `\` or the closing quote.
+ */
+export declare function quoteArgument(value: string): string;

package/dist/types/syntax/tokenize.d.ts

@@ -0,0 +1,45 @@
+/** One token of a line. */
+export interface Token {
+    /** The token's text with grouping quotes and escapes removed. */
+    value: string;
+    /** UTF-16 offset of the token's first raw character in the line. */
+    start: number;
+    /** UTF-16 offset after the token's last raw character (exclusive). */
+    end: number;
+    /** True when any part of the token is quoted (`'…'` or `"…"`). */
+    quoted: boolean;
+    /**
+     * True when the token ends in a quote that is not closed; it then runs to
+     * the end of the line. Only the last token can be open.
+     */
+    open: boolean;
+}
+/** The error of a line whose quote is not closed. */
+export interface TokenizeError {
+    code: 'unterminated-quote';
+    /** UTF-16 offset of the opening quote that is not closed. */
+    index: number;
+}
+/**
+ * The tokens of a line. With `ok: false` the tokens are still returned
+ * (tolerant): the last one has `open: true`. Dispatch refuses such a line;
+ * completion works on its tokens.
+ */
+export type TokenizeResult = {
+    ok: true;
+    tokens: Token[];
+} | {
+    ok: false;
+    tokens: Token[];
+    error: TokenizeError;
+};
+/** Whether `char` separates tokens (`\s`, so tabs and line breaks too). */
+export declare function isSeparator(char: string): boolean;
+/**
+ * Splits a line into tokens. Runs of whitespace separate. `'…'` groups
+ * literally. `"…"` groups, and inside it `\"` and `\\` are the only escapes;
+ * any other `\` is kept. Outside quotes `\` is an ordinary character. Adjacent
+ * parts join one token (`a"b c"d` is `ab cd`); `''` and `""` give an empty
+ * token. `start`/`end` cover the raw text of each token, quotes included.
+ */
+export declare function tokenize(line: string): TokenizeResult;

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@dolusoft/command-protocol",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0",
+  "description": "The JSON of a command console: entries, output blocks, command specs, responses, effects, context frames, and the line tokenizer. No dependencies.",
+  "private": false,
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "sideEffects": false,
+  "main": "./dist/command-protocol.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./dist/command-protocol.js"
+    }
+  },
+  "engines": {
+    "node": ">=22.18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dolusoft/command-console.git",
+    "directory": "packages/command-protocol"
+  },
+  "bugs": {
+    "url": "https://github.com/dolusoft/command-console/issues"
+  },
+  "homepage": "https://github.com/dolusoft/command-console#readme",
+  "license": "MIT",
+  "scripts": {
+    "build": "vite build && tsc -p tsconfig.build.json && node ../../scripts/emit-type-extensions.mjs dist/types"
+  }
 }