narraeon 0.1.0

package/dist/node/cli/NarraeonCli.js

@@ -0,0 +1,163 @@
+import { createConnection } from "node:net";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+import { resolveAppPaths } from "../runtime/config/appPaths.js";
+import { parseWebPort, startWebServer, } from "../server/startWebServer.js";
+export class NarraeonCliUsageError extends Error {
+}
+export async function runNarraeonCli(input) {
+    const output = input.writeOutput ?? ((message) => process.stdout.write(message));
+    const errorOutput = input.writeError ?? ((message) => process.stderr.write(message));
+    const command = parseCliCommand(input.args, input.environment);
+    if (command === null) {
+        output(cliHelp);
+        return { kind: "help" };
+    }
+    const url = `http://127.0.0.1:${command.port}`;
+    const inspect = input.inspectServer ?? inspectLocalWebServer;
+    const inspection = await inspect(url);
+    if (inspection === "narraeon") {
+        output(`Narraeon is already running: ${url}\n`);
+        await openBrowser(command, url, input.openUrl, errorOutput);
+        return { kind: "reused", url };
+    }
+    if (inspection === "occupied")
+        throw new Error(`Port ${String(command.port)} is already in use`);
+    const start = input.startServer ?? startWebServer;
+    let server;
+    try {
+        server = await start({
+            paths: resolveAppPaths(input.environment),
+            staticRoot: input.staticRoot,
+            port: command.port,
+        });
+    }
+    catch (error) {
+        if (hasErrorCode(error, "EADDRINUSE"))
+            throw new Error(`Port ${String(command.port)} is already in use`, {
+                cause: error,
+            });
+        throw error;
+    }
+    output(`Narraeon started: ${url}\n`);
+    await openBrowser(command, url, input.openUrl, errorOutput);
+    return { kind: "started", url, server };
+}
+export function resolvePackagedWebRoot(moduleUrl) {
+    return fileURLToPath(new URL("../../web/", moduleUrl));
+}
+export async function inspectLocalWebServer(url) {
+    let response;
+    try {
+        response = await fetch(`${url}/health`, {
+            signal: AbortSignal.timeout(750),
+        });
+    }
+    catch {
+        return (await acceptsTcpConnections(url)) ? "occupied" : "available";
+    }
+    let payload;
+    try {
+        payload = await response.json();
+    }
+    catch {
+        return "occupied";
+    }
+    return response.ok && isNarraeonHealth(payload) ? "narraeon" : "occupied";
+}
+function acceptsTcpConnections(url) {
+    const target = new URL(url);
+    return new Promise((resolveInspection) => {
+        const socket = createConnection({
+            host: target.hostname,
+            port: Number(target.port),
+        });
+        let settled = false;
+        const settle = (occupied) => {
+            if (settled)
+                return;
+            settled = true;
+            socket.destroy();
+            resolveInspection(occupied);
+        };
+        socket.setTimeout(750);
+        socket.once("connect", () => settle(true));
+        socket.once("timeout", () => settle(true));
+        socket.once("error", (error) => settle(error.code !== "ECONNREFUSED"));
+    });
+}
+function parseCliCommand(args, environment) {
+    const parsed = parseRawArguments(args);
+    if (parsed.values.help === true || parsed.positionals.length === 0)
+        return null;
+    if (parsed.positionals.length !== 1 || parsed.positionals[0] !== "web")
+        throw new NarraeonCliUsageError(`Unknown command: ${parsed.positionals.join(" ") || "(empty)"}`);
+    let port;
+    try {
+        port = parseWebPort(parsed.values.port ?? environment.NARRAEON_PORT, parsed.values.port === undefined ? "NARRAEON_PORT" : "--port");
+    }
+    catch (error) {
+        throw new NarraeonCliUsageError(errorMessage(error));
+    }
+    return {
+        kind: "web",
+        port,
+        openBrowser: parsed.values.open !== false,
+    };
+}
+function parseRawArguments(args) {
+    try {
+        return parseArgs({
+            args,
+            allowNegative: true,
+            allowPositionals: true,
+            strict: true,
+            options: {
+                help: { type: "boolean", short: "h" },
+                open: { type: "boolean" },
+                port: { type: "string", short: "p" },
+            },
+        });
+    }
+    catch (error) {
+        throw new NarraeonCliUsageError(errorMessage(error));
+    }
+}
+async function openBrowser(command, url, openUrl, writeError) {
+    if (!command.openBrowser)
+        return;
+    try {
+        await openUrl(url);
+    }
+    catch (error) {
+        writeError(`Could not open a browser automatically. Open ${url} manually: ${errorMessage(error)}\n`);
+    }
+}
+function isNarraeonHealth(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "status" in value &&
+        value.status === "ok" &&
+        "protocol" in value &&
+        value.protocol === "narraeon.runtime/v1");
+}
+function hasErrorCode(value, code) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    if ("code" in value && value.code === code)
+        return true;
+    return "cause" in value && hasErrorCode(value.cause, code);
+}
+function errorMessage(value) {
+    return value instanceof Error ? value.message : String(value);
+}
+export const cliHelp = `Narraeon
+
+Usage:
+  narraeon web [--port <port>] [--no-open]
+
+Options:
+  -p, --port <port>  Local web port (default: 4317)
+      --no-open      Do not open a browser after startup
+  -h, --help         Show help
+`;

package/dist/node/cli/main.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import open from "open";
+import { cliHelp, NarraeonCliUsageError, resolvePackagedWebRoot, runNarraeonCli, } from "./NarraeonCli.js";
+try {
+    const result = await runNarraeonCli({
+        args: process.argv.slice(2),
+        environment: process.env,
+        staticRoot: resolvePackagedWebRoot(import.meta.url),
+        openUrl: async (url) => {
+            await open(url);
+        },
+    });
+    if (result.kind === "started")
+        installGracefulShutdown(result.server);
+}
+catch (error) {
+    process.stderr.write(`Narraeon failed to start: ${errorMessage(error)}\n`);
+    if (error instanceof NarraeonCliUsageError)
+        process.stderr.write(`\n${cliHelp}`);
+    process.exitCode = 1;
+}
+function installGracefulShutdown(server) {
+    let closing = false;
+    const close = () => {
+        if (closing)
+            return;
+        closing = true;
+        void server.close().catch((error) => {
+            process.stderr.write(`Narraeon failed to stop: ${errorMessage(error)}\n`);
+            process.exitCode = 1;
+        });
+    };
+    process.once("SIGINT", close);
+    process.once("SIGTERM", close);
+}
+function errorMessage(value) {
+    return value instanceof Error ? value.message : String(value);
+}

package/dist/node/protocol/appPreferences.js

@@ -0,0 +1,5 @@
+export const appLocales = ["en", "zh-CN"];
+export const defaultAppLocale = "en";
+export function isAppLocale(value) {
+    return appLocales.includes(value);
+}

package/dist/node/protocol/contentTree.js

@@ -0,0 +1,14 @@
+/** Case/Unicode folding used when comparing portable current-tree paths. */
+export function portableContentTreePathKey(path) {
+    return path.normalize("NFKC").toLocaleLowerCase("en-US");
+}
+export const defaultPortableContentTreeLimits = {
+    maxFiles: 1_024,
+    maxFileBytes: 4 * 1024 * 1024,
+    maxTotalBytes: 32 * 1024 * 1024,
+};
+export function maximumPortableContentArchiveBytes(limits) {
+    return limits.maxTotalBytes + limits.maxFiles * 1_024 + 65_557;
+}
+export const maxPortableContentArchiveBytes = maximumPortableContentArchiveBytes(defaultPortableContentTreeLimits);
+export const maxPortableContentArchiveBase64Characters = Math.ceil(maxPortableContentArchiveBytes / 3) * 4;

package/dist/node/protocol/modelConnections.js

@@ -0,0 +1,110 @@
+export const modelProviderPresets = [
+    {
+        id: "custom",
+        name: "Custom endpoint",
+        provider: "chat_completions",
+        baseUrl: "",
+    },
+    {
+        id: "openai",
+        name: "OpenAI · Responses API",
+        provider: "openai_responses",
+        baseUrl: "https://api.openai.com/v1",
+    },
+    {
+        id: "openai-chat",
+        name: "OpenAI · Chat Completions",
+        provider: "chat_completions",
+        baseUrl: "https://api.openai.com/v1",
+    },
+    {
+        id: "anthropic",
+        name: "Anthropic",
+        provider: "anthropic_messages",
+        baseUrl: "https://api.anthropic.com/v1",
+    },
+    {
+        id: "deepseek",
+        name: "DeepSeek",
+        provider: "chat_completions",
+        baseUrl: "https://api.deepseek.com",
+    },
+    {
+        id: "kimi",
+        name: "Kimi / Moonshot",
+        provider: "chat_completions",
+        baseUrl: "https://api.moonshot.cn/v1",
+    },
+    {
+        id: "kimi-code",
+        name: "Kimi Coding",
+        provider: "chat_completions",
+        baseUrl: "https://api.kimi.com/coding/v1",
+    },
+    {
+        id: "glm",
+        name: "Zhipu GLM",
+        provider: "chat_completions",
+        baseUrl: "https://open.bigmodel.cn/api/paas/v4",
+    },
+    {
+        id: "glm-code",
+        name: "Zhipu GLM Coding",
+        provider: "chat_completions",
+        baseUrl: "https://open.bigmodel.cn/api/coding/paas/v4",
+    },
+    {
+        id: "qwen",
+        name: "Alibaba Qwen",
+        provider: "chat_completions",
+        baseUrl: "https://dashscope.aliyuncs.com/compatible-mode/v1",
+    },
+    {
+        id: "qwen-plan",
+        name: "Alibaba Qwen Token Plan",
+        provider: "chat_completions",
+        baseUrl: "https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
+    },
+    {
+        id: "xai",
+        name: "xAI",
+        provider: "chat_completions",
+        baseUrl: "https://api.x.ai/v1",
+    },
+    {
+        id: "mistral",
+        name: "Mistral",
+        provider: "chat_completions",
+        baseUrl: "https://api.mistral.ai/v1",
+    },
+    {
+        id: "volcengine",
+        name: "Volcano Engine Ark",
+        provider: "chat_completions",
+        baseUrl: "https://ark.cn-beijing.volces.com/api/v3",
+    },
+    {
+        id: "hunyuan",
+        name: "Tencent Hunyuan",
+        provider: "chat_completions",
+        baseUrl: "https://api.hunyuan.cloud.tencent.com/v1",
+    },
+    {
+        id: "siliconflow",
+        name: "SiliconFlow",
+        provider: "chat_completions",
+        baseUrl: "https://api.siliconflow.cn/v1",
+    },
+    {
+        id: "openrouter",
+        name: "OpenRouter",
+        provider: "chat_completions",
+        baseUrl: "https://openrouter.ai/api/v1",
+    },
+    {
+        id: "groq",
+        name: "Groq",
+        provider: "chat_completions",
+        baseUrl: "https://api.groq.com/openai/v1",
+    },
+];

package/dist/node/protocol/playerViews.js

@@ -0,0 +1 @@
+export {};

package/dist/node/protocol/v1.js

@@ -0,0 +1,278 @@
+import { maxPortableContentArchiveBase64Characters } from "./contentTree.js";
+export const v1Protocol = "narraeon.runtime/v1";
+export class V1ProtocolError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.name = "V1ProtocolError";
+        this.code = code;
+    }
+}
+export function parseV1Envelope(value) {
+    if (!isRecord(value) || value.protocol !== v1Protocol)
+        throw new V1ProtocolError("incompatible_data", "Requests must use the current narraeon.runtime/v1 protocol");
+    if (!isRecord(value.request) || typeof value.request.type !== "string")
+        throw new V1ProtocolError("invalid_request", "V1 request is missing request.type");
+    if (!requestTypes.has(value.request.type))
+        throw new V1ProtocolError("invalid_request", `V1 does not support command: ${value.request.type}`);
+    validateRequestFields(value.request);
+    return value;
+}
+const requiredFields = {
+    "preferences.save": { locale: "string" },
+    "model.save": { connection: "object" },
+    "model.select": { connectionId: "string" },
+    "model.delete": { connectionId: "string" },
+    "model.models": { provider: "string", baseUrl: "string" },
+    "content.read": { packageId: "string" },
+    "content.replace": { packageId: "string", files: "array" },
+    "content.copy": { packageId: "string" },
+    "content.delete": { packageId: "string" },
+    "content.rename": { packageId: "string", name: "string" },
+    "content.import": { archiveBase64: "string" },
+    "content.export": { packageId: "string" },
+    "setting-improvement.start": {
+        improvementId: "string",
+        packageId: "string",
+        goal: "string",
+        mode: "string",
+        contextPaths: "array",
+    },
+    "setting-improvement.confirm": { improvementId: "string" },
+    "setting-improvement.progress": { improvementId: "string" },
+    "setting-improvement.revise-plan": {
+        improvementId: "string",
+        feedback: "string",
+    },
+    "setting-improvement.revise-candidate": {
+        improvementId: "string",
+        feedback: "string",
+    },
+    "setting-improvement.apply": { improvementId: "string" },
+    "setting-improvement.discard": { improvementId: "string" },
+    "play.create": { name: "string" },
+    "play.copy": { presetId: "string" },
+    "play.save": { presetId: "string", name: "string", files: "object" },
+    "play.rename": { presetId: "string", name: "string" },
+    "play.delete": { presetId: "string" },
+    "play.enable": { presetId: "string", enabled: "boolean" },
+    "play.scripts": { presetId: "string", enabled: "boolean" },
+    "play.select": { presetId: "string" },
+    "play.export": { presetId: "string" },
+    "play.import": { name: "string", files: "array" },
+    "play.workbench.read": {},
+    "prompt.preview": {
+        packageId: "string",
+        playerInput: "string",
+        model: "object",
+    },
+    "world.create": {
+        operationId: "string",
+        packageId: "string",
+        model: "object",
+    },
+    "world.read": { worldId: "string" },
+    "world.rename": { worldId: "string", name: "string" },
+    "world.delete": { worldId: "string" },
+    "artifacts.read": { worldId: "string" },
+    "artifacts.debug": { worldId: "string" },
+    "world.creation-outcome": { operationId: "string" },
+    "world.repair-materialization": { worldId: "string" },
+    "world.control-draft.save": { worldId: "string", files: "array" },
+    "world.control-draft.preview": { worldId: "string" },
+    "world.control-draft.apply": { worldId: "string" },
+    "world.derive": {
+        operationId: "string",
+        sourceWorldId: "string",
+        sourceHead: "string",
+    },
+    "play.chain.revise-player": {
+        operationId: "string",
+        worldId: "string",
+        chainId: "string",
+        eventId: "number",
+        replacementExchangeId: "string",
+        replacementText: "string",
+    },
+    "play.chain.start": {
+        worldId: "string",
+        chainId: "string",
+        exchangeId: "string",
+        playerText: "string",
+    },
+    "play.chain.append": {
+        worldId: "string",
+        chainId: "string",
+        exchangeId: "string",
+        playerText: "string",
+    },
+    "play.chain.inspect": { worldId: "string" },
+    "correction.begin": { worldId: "string", operationId: "string" },
+    "correction.read": { candidateId: "string", document: "string" },
+    "correction.patch": {
+        candidateId: "string",
+        expectedVersion: "number",
+        target: "string",
+        expectedHash: "string",
+        edits: "array",
+    },
+    "correction.replace": {
+        candidateId: "string",
+        expectedVersion: "number",
+        target: "string",
+        expectedHash: "string",
+        contents: "string",
+    },
+    "correction.preview": { candidateId: "string", expectedVersion: "number" },
+    "correction.apply": { candidateId: "string", expectedVersion: "number" },
+    "correction.cancel": { candidateId: "string", expectedVersion: "number" },
+};
+function validateRequestFields(request) {
+    for (const [field, kind] of Object.entries(requiredFields[request.type] ?? {})) {
+        const value = request[field];
+        const valid = kind === "array"
+            ? Array.isArray(value)
+            : kind === "object"
+                ? isRecord(value)
+                : typeof value === kind;
+        const allowsEmptyString = request.type === "play.chain.append" && field === "playerText";
+        if (!valid || (kind === "string" && value === "" && !allowsEmptyString))
+            throw new V1ProtocolError("invalid_request", `${String(request.type)}.${field} is invalid`);
+    }
+    if (request.type === "preferences.save" &&
+        request.locale !== "en" &&
+        request.locale !== "zh-CN")
+        throw new V1ProtocolError("invalid_request", "preferences.save.locale must be en or zh-CN");
+    if (request.type === "content.import") {
+        const archiveBase64 = request.archiveBase64;
+        if (archiveBase64.length > maxPortableContentArchiveBase64Characters ||
+            archiveBase64.length % 4 !== 0 ||
+            !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u.test(archiveBase64))
+            throw new V1ProtocolError("invalid_request", "content.import.archiveBase64 is not a supported content-package ZIP");
+        const unexpectedFields = Object.keys(request).filter((field) => field !== "type" && field !== "archiveBase64");
+        if (unexpectedFields.length > 0)
+            throw new V1ProtocolError("invalid_request", `content.import contains unsupported fields: ${unexpectedFields.join(", ")}`);
+        return;
+    }
+    if (request.type === "prompt.preview" && request.playPresetId !== undefined) {
+        if (typeof request.playPresetId !== "string" || request.playPresetId === "")
+            throw new V1ProtocolError("invalid_request", "prompt.preview.playPresetId is invalid");
+    }
+    if (request.type === "prompt.preview" &&
+        request.playPresetRevision !== undefined &&
+        (typeof request.playPresetRevision !== "string" ||
+            request.playPresetRevision === ""))
+        throw new V1ProtocolError("invalid_request", "prompt.preview.playPresetRevision is invalid");
+    if (request.type === "prompt.preview" &&
+        request.playPresetRevision !== undefined &&
+        request.playPresetId === undefined)
+        throw new V1ProtocolError("invalid_request", "prompt.preview.playPresetRevision must be provided with playPresetId");
+    if (request.type === "play.create" && request.files !== undefined) {
+        if (!isRecord(request.files) ||
+            !Object.values(request.files).every((contents) => typeof contents === "string"))
+            throw new V1ProtocolError("invalid_request", "play.create.files must be Record<string,string>");
+    }
+    if (request.type === "play.save" &&
+        !Object.values(request.files).every((contents) => typeof contents === "string"))
+        throw new V1ProtocolError("invalid_request", "play.save.files must be Record<string,string>");
+    if (request.type === "play.save" &&
+        request.structure !== undefined &&
+        !isRecord(request.structure))
+        throw new V1ProtocolError("invalid_request", "play.save.structure must be a structured map");
+    if (request.type === "play.workbench.read") {
+        if (request.presetId !== undefined &&
+            (typeof request.presetId !== "string" || request.presetId === ""))
+            throw new V1ProtocolError("invalid_request", "play.workbench.read.presetId is invalid");
+        if (request.revision !== undefined &&
+            (typeof request.revision !== "string" || request.revision === ""))
+            throw new V1ProtocolError("invalid_request", "play.workbench.read.revision is invalid");
+        if (request.revision !== undefined && request.presetId === undefined)
+            throw new V1ProtocolError("invalid_request", "play.workbench.read.revision must be provided with presetId");
+    }
+    if (request.type === "play.import") {
+        if (!request.files.every((file) => isRecord(file) &&
+            typeof file.path === "string" &&
+            typeof file.contents === "string" &&
+            file.encoding === undefined))
+            throw new V1ProtocolError("invalid_request", "play.import.files is invalid");
+    }
+    if ((request.type === "artifacts.read" || request.type === "artifacts.debug") &&
+        "channel" in request &&
+        request.channel !== undefined &&
+        (typeof request.channel !== "string" || request.channel.length === 0))
+        throw new V1ProtocolError("invalid_request", `${request.type}.channel is invalid`);
+    if (request.type === "artifacts.debug" &&
+        request.operationId !== undefined &&
+        (typeof request.operationId !== "string" || request.operationId === ""))
+        throw new V1ProtocolError("invalid_request", "artifacts.debug.operationId is invalid");
+    if (request.type !== "setting-improvement.start")
+        return;
+    if (request.mode !== "plan_first" && request.mode !== "direct_candidate")
+        throw new V1ProtocolError("invalid_request", "setting-improvement.start.mode is invalid");
+    if (!request.contextPaths.every((path) => typeof path === "string" && path.length > 0))
+        throw new V1ProtocolError("invalid_request", "setting-improvement.start.contextPaths is invalid");
+}
+const requestTypes = new Set([
+    "workspace.read",
+    "preferences.read",
+    "preferences.save",
+    "model.read",
+    "model.save",
+    "model.select",
+    "model.delete",
+    "model.models",
+    "content.create",
+    "content.read",
+    "content.replace",
+    "content.copy",
+    "content.delete",
+    "content.rename",
+    "content.import",
+    "content.export",
+    "setting-improvement.start",
+    "setting-improvement.confirm",
+    "setting-improvement.progress",
+    "setting-improvement.revise-plan",
+    "setting-improvement.revise-candidate",
+    "setting-improvement.apply",
+    "setting-improvement.discard",
+    "play.read",
+    "play.create",
+    "play.copy",
+    "play.save",
+    "play.rename",
+    "play.delete",
+    "play.enable",
+    "play.scripts",
+    "play.select",
+    "play.export",
+    "play.import",
+    "play.workbench.read",
+    "prompt.preview",
+    "world.create",
+    "world.read",
+    "world.rename",
+    "world.delete",
+    "artifacts.read",
+    "artifacts.debug",
+    "world.creation-outcome",
+    "world.repair-materialization",
+    "world.control-draft.save",
+    "world.control-draft.preview",
+    "world.control-draft.apply",
+    "world.derive",
+    "play.chain.revise-player",
+    "play.chain.start",
+    "play.chain.append",
+    "play.chain.inspect",
+    "correction.begin",
+    "correction.read",
+    "correction.patch",
+    "correction.replace",
+    "correction.preview",
+    "correction.apply",
+    "correction.cancel",
+]);
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}