@fnndsc/brasa 0.56.1 → 0.56.3

package/dist/core/commandRegistry.js

@@ -1,9 +1,15 @@
+import { commandAliases_list, declaration_isParsed } from './commandDeclaration.js';
+import { declaredHandler_make } from './commandParse.js';
+import { declarationHelp_derive } from './commandUsage.js';
 /** The names the core registered, which no backend may take. */
 const coreNames = new Set();
 const envelopeHandlers = {};
 const plainHandlers = {};
 const helpEntries = {};
 const holdsEntries = new Map();
+const declarationEntries = new Map();
+/** Each alias of a declared command, to its declaration. */
+const aliasEntries = new Map();
 /** The listing order, by kind; empty until set. */
 const listingOrder = { envelope: [], plain: [], help: [] };
 /**
@@ -56,14 +62,15 @@ function names_ordered(record, order) {
  * @throws {Error} When a backend's group names a core command.
  */
 export function commands_register(group, owner = 'core') {
+    const declared = (group.declarations ?? []).flatMap((declaration) => [declaration.name, ...declarationAliases_list(declaration).map((alias) => alias.name)]);
+    const names = [...Object.keys(group.envelope ?? {}), ...Object.keys(group.plain ?? {}), ...declared];
     if (owner === 'backend') {
-        const taken = [...Object.keys(group.envelope ?? {}), ...Object.keys(group.plain ?? {})]
-            .filter((name) => coreNames.has(name));
+        const taken = names.filter((name) => coreNames.has(name));
         if (taken.length > 0)
             throw new Error(`a backend cannot replace the core's commands: ${[...new Set(taken)].join(', ')}`);
     }
     else {
-        for (const name of [...Object.keys(group.envelope ?? {}), ...Object.keys(group.plain ?? {})])
+        for (const name of names)
             coreNames.add(name);
     }
     if (group.envelope !== undefined)
@@ -74,6 +81,96 @@ export function commands_register(group, owner = 'core') {
         Object.assign(helpEntries, group.help);
     for (const [name, pieces] of Object.entries(group.holds ?? {}))
         holdsEntries.set(name, pieces);
+    for (const declaration of group.declarations ?? [])
+        declaration_register(declaration);
+}
+/**
+ * The command under each of its other words, as the registry answers them.
+ *
+ * @param declaration - The command's declaration.
+ * @returns One record per alias; none for a command without any.
+ */
+function declarationAliases_list(declaration) {
+    return commandAliases_list(declaration);
+}
+/**
+ * Registers one declared command: its name answered by a handler that parses
+ * the line against the grammar (an expression grammar's handler takes the
+ * words), its help generated from the record, and what it holds. Each alias
+ * is registered the same way under its own word, so its usage and refusals
+ * say the word typed; the command alone is listed among the declarations,
+ * which the schema reads.
+ *
+ * @param declaration - The command's declaration.
+ */
+function declaration_register(declaration) {
+    declarationEntries.set(declaration.name, declaration);
+    declaredName_register(declaration);
+    for (const alias of declarationAliases_list(declaration)) {
+        aliasEntries.set(alias.name, alias);
+        declaredName_register(alias);
+    }
+}
+/**
+ * Answers one word of a declared command: its handlers, its help entry and
+ * what it holds.
+ *
+ * @param declaration - The command, named as the word.
+ */
+function declaredName_register(declaration) {
+    const handler = declaration_isParsed(declaration)
+        ? declaredHandler_make(declaration)
+        : (args) => declaration.handler(args);
+    envelopeHandlers[declaration.name] = handler;
+    // The plain form delivers what the handler answers, as envelopeHandler_wrap
+    // does; the sink is loaded when it runs, so the registry loads no output path.
+    plainHandlers[declaration.name] = async (args) => {
+        const envelope = await handler(args);
+        if (envelope === undefined)
+            return;
+        const { envelope_deliver } = await import('./sink.js');
+        envelope_deliver(envelope);
+    };
+    helpEntries[declaration.name] = declaration_isParsed(declaration)
+        ? declarationHelp_derive(declaration)
+        : {
+            usage: declaration.help.usage,
+            summary: declaration.help.summary,
+            description: declaration.help.description,
+            ...(declaration.help.category !== undefined ? { category: declaration.help.category } : {}),
+            ...(declaration.help.posix !== undefined ? { posix: { ...declaration.help.posix } } : {}),
+            ...(declaration.help.examples !== undefined ? { examples: [...declaration.help.examples] } : {}),
+        };
+    if (declaration.holds !== undefined)
+        holdsEntries.set(declaration.name, declaration.holds);
+}
+/**
+ * A command's declaration, when it has one, by its name or an alias.
+ *
+ * @param name - The command name, or an alias of it (`feeds`).
+ * @returns The declaration (an alias's named as the alias), or undefined for a command not yet declared in one record.
+ *
+ * @example
+ * ```ts
+ * commandDeclaration_get('ls')?.grammar;
+ * commandDeclaration_get('feeds')?.name; // 'feeds', the feed command under that word
+ * ```
+ */
+export function commandDeclaration_get(name) {
+    return declarationEntries.get(name) ?? aliasEntries.get(name);
+}
+/**
+ * Every declared command, in registration order.
+ *
+ * @returns The declarations.
+ *
+ * @example
+ * ```ts
+ * commandDeclarations_list().map((declaration) => declaration.name);
+ * ```
+ */
+export function commandDeclarations_list() {
+    return [...declarationEntries.values()];
 }
 /**
  * What a command holds of the session while it runs.

package/dist/core/commandRegistry.js.map

@@ -1 +1 @@
-{"version":3,"file":"commandRegistry.js","sourceRoot":"","sources":["../../src/core/commandRegistry.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"commandRegistry.js","sourceRoot":"","sources":["../../src/core/commandRegistry.ts"],"names":[],"mappings":"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"}

package/dist/core/commandSchema.d.ts

@@ -0,0 +1,32 @@
+import type { CommandDeclaration } from './commandDeclaration.js';
+/**
+ * One tool: a command, or one of its subcommands, as an assistant calls it.
+ *
+ * @example
+ * ```ts
+ * const tool: CommandTool = { name: 'ls', description: 'List directory contents', inputSchema: { type: 'object' } };
+ * ```
+ */
+export interface CommandTool {
+    /** The command's name, and the subcommand's after an underscore (`berth_anchor`). */
+    readonly name: string;
+    /** What it does: the command's summary, or the subcommand's. */
+    readonly description: string;
+    /** The JSON Schema of its input: an object of its operands and options. */
+    readonly inputSchema: Record<string, unknown>;
+}
+/**
+ * A declared command's tools: the command itself (when it runs bare, or
+ * has no subcommands), and each subcommand, with the command's options
+ * beside the subcommand's own.
+ *
+ * @param declaration - The command.
+ * @returns The tools, the bare command's first.
+ * @throws {Error} For a kind no one registered, or an operand and an option of one name.
+ *
+ * @example
+ * ```ts
+ * commandTools_derive(lsCommand)[0]?.inputSchema; // { type: 'object', properties: { paths: …, long: … }, … }
+ * ```
+ */
+export declare function commandTools_derive(declaration: CommandDeclaration): CommandTool[];

package/dist/core/commandSchema.js

@@ -0,0 +1,117 @@
+/**
+ * @file A declared command as tools: one JSON Schema per command and per
+ * subcommand, whose properties are the operands and options the grammar
+ * declares, each typed by its kind. A pure function of the declaration, so
+ * what an assistant may call is exactly what the shell parses.
+ *
+ * Key components:
+ * - CommandTool: one tool, its name, description and input schema.
+ * - commandTools_derive: the tools of a declaration.
+ *
+ * Typical usage:
+ * ```ts
+ * const tools: CommandTool[] = commandTools_derive(berthCommand);
+ * tools.map((tool) => tool.name); // ['berth', 'berth_anchor', 'berth_close', 'berth_drop', 'berth_clear']
+ * ```
+ *
+ * Dependencies: zod, which writes the JSON Schema; the argument kinds, which
+ * give each value's schema.
+ *
+ * @module
+ */
+import { z } from 'zod';
+import { argumentKind_get } from './argumentKinds.js';
+/**
+ * The schema of one argument's value, by its kind.
+ *
+ * @param argument - The argument.
+ * @param summary - What it is, for the schema's description.
+ * @returns The schema.
+ * @throws {Error} For a kind no one registered.
+ */
+function argument_schema(argument, summary) {
+    const kind = argumentKind_get(argument.kind);
+    if (kind === null)
+        throw new Error(`no argument kind ${argument.kind}`);
+    return kind.schema_make(argument).describe(summary);
+}
+/**
+ * The input schema of one stretch: each operand (a list when it repeats,
+ * required unless optional) and each option (a switch a boolean, a value
+ * option its value or its list of values), all as properties of one object.
+ *
+ * @param grammar - The stretch.
+ * @returns The zod object.
+ * @throws {Error} For an operand and an option of one name.
+ */
+function toolInput_make(grammar) {
+    const shape = {};
+    for (const operand of grammar.operands) {
+        const value = argument_schema(operand, operand.summary);
+        const schema = operand.repeat === true
+            ? z.array(value).min(operand.optional === true ? 0 : 1).describe(operand.summary)
+            : value;
+        shape[operand.name] = operand.optional === true ? schema.optional() : schema;
+    }
+    for (const [key, option] of Object.entries(grammar.options)) {
+        if (Object.hasOwn(shape, key))
+            throw new Error(`${key} names an operand and an option`);
+        shape[key] = optionValue_schema(option).optional();
+    }
+    return z.object(shape).strict();
+}
+/**
+ * One option's value schema: a boolean for a switch, else its value's kind,
+ * a list of them when it repeats.
+ *
+ * @param option - The option.
+ * @returns The schema.
+ */
+function optionValue_schema(option) {
+    if (option.value === undefined)
+        return z.boolean().describe(option.summary);
+    const value = argument_schema(option.value, option.summary);
+    if (option.repeat === true)
+        return z.array(value).describe(option.summary);
+    // One that asks takes null for "ask me".
+    return option.asks === true ? value.nullable() : value;
+}
+/**
+ * One tool, its schema written by zod.
+ *
+ * @param name - The tool's name.
+ * @param description - What it does.
+ * @param grammar - Its stretch of the line.
+ * @returns The tool.
+ */
+function tool_make(name, description, grammar) {
+    return { name, description, inputSchema: z.toJSONSchema(toolInput_make(grammar)) };
+}
+/**
+ * A declared command's tools: the command itself (when it runs bare, or
+ * has no subcommands), and each subcommand, with the command's options
+ * beside the subcommand's own.
+ *
+ * @param declaration - The command.
+ * @returns The tools, the bare command's first.
+ * @throws {Error} For a kind no one registered, or an operand and an option of one name.
+ *
+ * @example
+ * ```ts
+ * commandTools_derive(lsCommand)[0]?.inputSchema; // { type: 'object', properties: { paths: …, long: … }, … }
+ * ```
+ */
+export function commandTools_derive(declaration) {
+    const grammar = declaration.grammar;
+    const own = grammar.options ?? {};
+    const tools = [];
+    if (grammar.subcommands === undefined || grammar.bare !== undefined) {
+        const description = grammar.subcommands === undefined ? declaration.help.summary : (grammar.bare?.summary ?? declaration.help.summary);
+        tools.push(tool_make(declaration.name, description, { operands: grammar.operands ?? [], options: { ...own, ...(grammar.bare?.options ?? {}) } }));
+    }
+    for (const [word, sub] of Object.entries(grammar.subcommands ?? {})) {
+        tools.push(tool_make(`${declaration.name}_${word}`, sub.summary, { operands: sub.operands ?? [], options: { ...own, ...(sub.options ?? {}) } }));
+    }
+    return tools;
+}
+//# sourceMappingURL=commandSchema.js.map

package/dist/core/commandSchema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commandSchema.js","sourceRoot":"","sources":["../../src/core/commandSchema.ts"],"names":[],"mappings":"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"}

package/dist/core/commandUsage.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @file A declared command's usage line and help page, generated from its
+ * grammar: the usage `help` shows and every refusal ends with, and the help
+ * record `help`, `/bin` and the listings read.
+ *
+ * Key components:
+ * - commandUsage_render: the usage line of a command or one of its subcommands.
+ * - declarationHelp_derive: the help record of a declared command.
+ *
+ * Typical usage:
+ * ```ts
+ * commandUsage_render(lsCommand); // 'ls [-l1hrdfaA] [--sort <field>] [path…]'
+ * const help: CommandHelp = declarationHelp_derive(berthCommand);
+ * ```
+ *
+ * Dependencies: the declaration types and the registry's help record.
+ *
+ * @module
+ */
+import type { CommandHelp } from './commandRegistry.js';
+import type { CommandDeclaration } from './commandDeclaration.js';
+/**
+ * A command's usage line, or one subcommand's.
+ *
+ * @param declaration - The command.
+ * @param subcommand - The subcommand, or none for the whole command.
+ * @returns The line, starting with the command's name.
+ *
+ * @example
+ * ```ts
+ * commandUsage_render(berthCommand, 'drop'); // 'berth drop <name>'
+ * ```
+ */
+export declare function commandUsage_render(declaration: CommandDeclaration, subcommand?: string | null): string;
+/**
+ * The help record of a declared command: the usage its grammar generates,
+ * its subcommands, operands and options with their summaries, and its prose.
+ *
+ * @param declaration - The command.
+ * @returns The record `help` renders and the listings read.
+ *
+ * @example
+ * ```ts
+ * declarationHelp_derive(lsCommand).usage; // 'ls [-l1hrdfaA] [--sort <field>] [path…]'
+ * ```
+ */
+export declare function declarationHelp_derive(declaration: CommandDeclaration): CommandHelp;
+/**
+ * The help record of one subcommand of a declared command (`help pacs
+ * query`): its usage, its summary, and its operands and options with the
+ * command's own beside them; the command's examples that run it.
+ *
+ * @param declaration - The command.
+ * @param subcommand - The subcommand's word.
+ * @returns The record, or undefined when the command has no such subcommand.
+ *
+ * @example
+ * ```ts
+ * subcommandHelp_derive(berthCommand, 'drop')?.usage; // 'berth drop <name>'
+ * ```
+ */
+export declare function subcommandHelp_derive(declaration: CommandDeclaration, subcommand: string): CommandHelp | undefined;

package/dist/core/commandUsage.js

@@ -0,0 +1,247 @@
+/** The gap between a help line's left column and its summary. */
+const COLUMN_GAP = 2;
+/**
+ * One operand as usage writes it: `<path>`, `[name]`, `<source>…`, `[path…]`.
+ *
+ * @param operand - The operand.
+ * @returns Its word.
+ */
+function operand_usage(operand) {
+    const word = `${operand.name}${operand.repeat === true ? '…' : ''}`;
+    return operand.optional === true ? `[${word}]` : `<${word}>`;
+}
+/**
+ * One option's name as help writes it: `-l, --long`, `-l`, `--sort <field>`.
+ *
+ * @param option - The option.
+ * @returns Its names, with its value's word.
+ */
+function optionNames_render(option) {
+    const names = [];
+    if (option.short !== undefined)
+        names.push(`-${option.short}`);
+    if (option.long !== undefined)
+        names.push(`--${option.long}`);
+    return `${names.join(', ')}${optionValue_render(option)}`;
+}
+/**
+ * An option's value as usage writes it: ` <field>`, `[=<language>]` for one
+ * that may be left out, ` [<file>]` for one that asks when it has none,
+ * nothing for a switch.
+ *
+ * @param option - The option.
+ * @returns The value's words.
+ */
+function optionValue_render(option) {
+    if (option.value === undefined)
+        return '';
+    if (option.value.optional === true)
+        return `[=<${option.value.name}>]`;
+    return option.asks === true ? ` [<${option.value.name}>]` : ` <${option.value.name}>`;
+}
+/**
+ * The options and operands of one stretch of a line, as usage writes them:
+ * the one-letter switches bundled, the long-only switches, the options that
+ * take a value, then the operands.
+ *
+ * @param line - The stretch's grammar.
+ * @returns Its words, joined by spaces; empty when it takes nothing.
+ */
+function lineTail_render(line) {
+    const options = Object.values(line.options ?? {});
+    const shortSwitches = options
+        .filter((option) => option.value === undefined && option.short !== undefined)
+        .map((option) => option.short)
+        .join('');
+    const parts = [];
+    if (shortSwitches !== '')
+        parts.push(`[-${shortSwitches}]`);
+    for (const option of options) {
+        if (option.value === undefined && option.short === undefined && option.long !== undefined)
+            parts.push(`[--${option.long}]`);
+    }
+    for (const option of options) {
+        if (option.value === undefined)
+            continue;
+        const name = option.long !== undefined ? `--${option.long}` : `-${option.short ?? ''}`;
+        parts.push(`[${name}${optionValue_render(option)}]`);
+    }
+    for (const operand of line.operands ?? [])
+        parts.push(operand_usage(operand));
+    return parts.join(' ');
+}
+/**
+ * Joins a head and a tail with a space, or gives the head alone.
+ *
+ * @param head - The words before.
+ * @param tail - The words after, perhaps none.
+ * @returns The line.
+ */
+function words_join(head, tail) {
+    return tail === '' ? head : `${head} ${tail}`;
+}
+/**
+ * A command's usage line, or one subcommand's.
+ *
+ * @param declaration - The command.
+ * @param subcommand - The subcommand, or none for the whole command.
+ * @returns The line, starting with the command's name.
+ *
+ * @example
+ * ```ts
+ * commandUsage_render(berthCommand, 'drop'); // 'berth drop <name>'
+ * ```
+ */
+export function commandUsage_render(declaration, subcommand = null) {
+    const grammar = declaration.grammar;
+    const subcommands = grammar.subcommands;
+    if (subcommand !== null && subcommands !== undefined) {
+        const chosen = subcommands[subcommand];
+        if (chosen !== undefined)
+            return words_join(`${declaration.name} ${subcommand}`, lineTail_render(chosen));
+    }
+    const own = lineTail_render({ ...(grammar.options !== undefined ? { options: grammar.options } : {}), ...(subcommands === undefined && grammar.operands !== undefined ? { operands: grammar.operands } : {}) });
+    if (subcommands === undefined)
+        return words_join(declaration.name, own);
+    // The bare command's own options are its line, the first choice.
+    const bareTail = grammar.bare?.options !== undefined ? lineTail_render({ options: grammar.bare.options }) : '';
+    const choices = [
+        ...(bareTail !== '' ? [bareTail] : []),
+        ...Object.entries(subcommands).map(([word, sub]) => words_join(word, lineTail_render(sub))),
+    ].join(' | ');
+    const bracketed = grammar.bare !== undefined ? `[${choices}]` : `<${choices}>`;
+    return words_join(words_join(declaration.name, own), bracketed);
+}
+/**
+ * Lines of a help column: each left part padded to the widest, then its summary.
+ *
+ * @param rows - Left part and summary, by row.
+ * @param indent - The spaces before each row.
+ * @returns The lines.
+ */
+function columns_render(rows, indent) {
+    const width = Math.max(0, ...rows.map(([left]) => left.length));
+    return rows.map(([left, summary]) => `${indent}${left.padEnd(width + COLUMN_GAP)}${summary}`);
+}
+/**
+ * One option's help row: its names and its summary, an enum's words after.
+ *
+ * @param option - The option.
+ * @returns The row.
+ */
+function optionRow_make(option) {
+    const values = option.value?.kind === 'enum' ? option.value.values : undefined;
+    return [optionNames_render(option), values === undefined ? option.summary : `${option.summary} (${values.join(', ')})`];
+}
+/**
+ * The help lines of a stretch's operands and options.
+ *
+ * @param line - The stretch's grammar.
+ * @param indent - The spaces before each row.
+ * @returns The lines.
+ */
+function lineRows_render(line, indent) {
+    const rows = [
+        ...(line.operands ?? []).map((operand) => [operand_usage(operand), operand.summary]),
+        ...Object.values(line.options ?? {}).map(optionRow_make),
+    ];
+    return rows.length === 0 ? [] : columns_render(rows, indent);
+}
+/**
+ * The SUBCOMMANDS lines: the bare command's, then each subcommand's with its
+ * operands and options beneath it.
+ *
+ * @param grammar - The command's grammar.
+ * @returns The lines; none for a command without subcommands.
+ */
+function subcommandLines_render(grammar) {
+    const subcommands = grammar.subcommands;
+    if (subcommands === undefined)
+        return [];
+    const heads = [
+        ...(grammar.bare !== undefined ? [['(none)', grammar.bare.summary]] : []),
+        ...Object.entries(subcommands).map(([word, sub]) => [word, sub.summary]),
+    ];
+    const headLines = columns_render(heads, '');
+    const lines = [];
+    let at = 0;
+    if (grammar.bare !== undefined) {
+        lines.push(headLines[at++]);
+        lines.push(...lineRows_render({ ...(grammar.bare.options !== undefined ? { options: grammar.bare.options } : {}) }, '  '));
+    }
+    for (const sub of Object.values(subcommands)) {
+        lines.push(headLines[at++]);
+        lines.push(...lineRows_render(sub, '  '));
+    }
+    return lines;
+}
+/**
+ * The help record of a declared command: the usage its grammar generates,
+ * its subcommands, operands and options with their summaries, and its prose.
+ *
+ * @param declaration - The command.
+ * @returns The record `help` renders and the listings read.
+ *
+ * @example
+ * ```ts
+ * declarationHelp_derive(lsCommand).usage; // 'ls [-l1hrdfaA] [--sort <field>] [path…]'
+ * ```
+ */
+export function declarationHelp_derive(declaration) {
+    const grammar = declaration.grammar;
+    const subcommands = subcommandLines_render(grammar);
+    const own = {
+        ...(grammar.subcommands === undefined && grammar.operands !== undefined ? { operands: grammar.operands } : {}),
+        ...(grammar.options !== undefined ? { options: grammar.options } : {}),
+    };
+    // The subcommands lead the OPTIONS block under a heading of their own,
+    // since that block keeps each line's indent and the subcommands' options
+    // sit beneath them.
+    const ownRows = lineRows_render(own, '');
+    const options = subcommands.length === 0
+        ? ownRows
+        : ['SUBCOMMANDS:', ...subcommands.map((line) => `  ${line}`), ...(ownRows.length > 0 ? ['', ...ownRows] : [])];
+    return {
+        usage: commandUsage_render(declaration),
+        summary: declaration.help.summary,
+        description: declaration.help.description,
+        ...(declaration.help.category !== undefined ? { category: declaration.help.category } : {}),
+        ...(declaration.help.posix !== undefined ? { posix: { ...declaration.help.posix } } : {}),
+        ...(options.length > 0 ? { options } : {}),
+        ...(declaration.help.examples !== undefined ? { examples: [...declaration.help.examples] } : {}),
+    };
+}
+/**
+ * The help record of one subcommand of a declared command (`help pacs
+ * query`): its usage, its summary, and its operands and options with the
+ * command's own beside them; the command's examples that run it.
+ *
+ * @param declaration - The command.
+ * @param subcommand - The subcommand's word.
+ * @returns The record, or undefined when the command has no such subcommand.
+ *
+ * @example
+ * ```ts
+ * subcommandHelp_derive(berthCommand, 'drop')?.usage; // 'berth drop <name>'
+ * ```
+ */
+export function subcommandHelp_derive(declaration, subcommand) {
+    const subcommands = declaration.grammar.subcommands;
+    if (subcommands === undefined || !Object.hasOwn(subcommands, subcommand))
+        return undefined;
+    const chosen = subcommands[subcommand];
+    const options = lineRows_render({
+        ...(chosen.operands !== undefined ? { operands: chosen.operands } : {}),
+        options: { ...(chosen.options ?? {}), ...(declaration.grammar.options ?? {}) },
+    }, '');
+    const lead = `${declaration.name} ${subcommand}`;
+    const examples = (declaration.help.examples ?? []).filter((line) => line === lead || line.startsWith(`${lead} `));
+    return {
+        usage: commandUsage_render(declaration, subcommand),
+        summary: chosen.summary,
+        description: chosen.summary,
+        ...(options.length > 0 ? { options } : {}),
+        ...(examples.length > 0 ? { examples } : {}),
+    };
+}
+//# sourceMappingURL=commandUsage.js.map

package/dist/core/commandUsage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commandUsage.js","sourceRoot":"","sources":["../../src/core/commandUsage.ts"],"names":[],"mappings":"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"}