@nurix/nustack 0.10.0-dev.10

package/dist/lib/git-sync/whitelist/types.js

@@ -0,0 +1,46 @@
+export const SYNC_PROTOCOL_VERSION = "nustack.dev/v2";
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+function isLimits(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const limits = value;
+    return (typeof limits.defaultMaxBytes === "number" &&
+        typeof limits.blobMaxBytes === "number" &&
+        typeof limits.maxOperations === "number");
+}
+function isEntry(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const entry = value;
+    if (typeof entry.pattern !== "string")
+        return false;
+    if (entry.kind !== "exact" && entry.kind !== "glob")
+        return false;
+    if (entry.direction !== "bidirectional" && entry.direction !== "cloud_to_local" && entry.direction !== "local_to_cloud") {
+        return false;
+    }
+    if (typeof entry.maxBytes !== "number")
+        return false;
+    if (!isStringArray(entry.mediaTypes))
+        return false;
+    if (entry.allowsSupplemental !== undefined && typeof entry.allowsSupplemental !== "boolean")
+        return false;
+    return true;
+}
+export function isWhitelistManifest(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const manifest = value;
+    return (manifest.schemaVersion === 1 &&
+        typeof manifest.manifestId === "string" &&
+        typeof manifest.version === "number" &&
+        typeof manifest.workspaceId === "string" &&
+        typeof manifest.protocolVersion === "string" &&
+        Array.isArray(manifest.entries) &&
+        manifest.entries.every(isEntry) &&
+        isStringArray(manifest.protectedPatterns) &&
+        isLimits(manifest.limits) &&
+        typeof manifest.manifestSha256 === "string");
+}

package/dist/lib/git-sync/whitelist/validation.js

@@ -0,0 +1,60 @@
+const SYMLINK_MODE = "120000";
+const EXECUTABLE_MODE = "100755";
+const NUL = String.fromCharCode(0);
+const MEDIA_TYPE_BY_EXTENSION = {
+    md: "text/markdown",
+    json: "application/json",
+    yaml: "text/yaml",
+    yml: "text/yaml",
+};
+export function mediaTypeForPath(path) {
+    const dot = path.lastIndexOf(".");
+    if (dot < 0)
+        return null;
+    const ext = path.slice(dot + 1).toLowerCase();
+    return MEDIA_TYPE_BY_EXTENSION[ext] ?? null;
+}
+export function frontmatterWorkspaceId(text) {
+    if (!text.startsWith("---"))
+        return null;
+    const firstNewline = text.indexOf("\n");
+    if (firstNewline < 0)
+        return null;
+    if (text.slice(0, firstNewline).trim() !== "---")
+        return null;
+    const rest = text.slice(firstNewline + 1);
+    const closeIndex = rest.search(/\n---\s*(\n|$)/);
+    const block = closeIndex < 0 ? rest : rest.slice(0, closeIndex);
+    for (const line of block.split("\n")) {
+        const match = /^\s*(?:workspace_id|workspaceId|app_id|appId)\s*:\s*(.+?)\s*$/.exec(line);
+        if (match)
+            return match[1].replace(/^["']|["']$/g, "");
+    }
+    return null;
+}
+export function validateOperationContent(input) {
+    if (input.mode === SYMLINK_MODE)
+        return { ok: false, code: "symlink_denied" };
+    if (input.mode === EXECUTABLE_MODE)
+        return { ok: false, code: "executable_denied" };
+    if (input.byteSize > input.entry.maxBytes)
+        return { ok: false, code: "content_too_large" };
+    const mediaType = mediaTypeForPath(input.path);
+    if (mediaType === null || !input.entry.mediaTypes.includes(mediaType)) {
+        return { ok: false, code: "media_type_not_allowed" };
+    }
+    let text;
+    try {
+        text = new TextDecoder("utf-8", { fatal: true }).decode(input.bytes);
+    }
+    catch {
+        return { ok: false, code: "invalid_encoding" };
+    }
+    if (text.includes(NUL))
+        return { ok: false, code: "invalid_encoding" };
+    const declaredWorkspace = frontmatterWorkspaceId(text);
+    if (declaredWorkspace !== null && declaredWorkspace !== input.workspaceId) {
+        return { ok: false, code: "cross_workspace_marker" };
+    }
+    return { ok: true };
+}

package/dist/lib/graph/answer.js

@@ -0,0 +1,171 @@
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { printJsonSuccess } from "../json_output.js";
+import { loadCodegraph } from "./library.js";
+import { refreshIfStale } from "./freshness.js";
+export class GraphNoRepository extends Error {
+    code = "GRAPH_NO_REPOSITORY";
+    constructor(where) {
+        super(`not a git repository: ${where} — pass --repo <path|id> or run inside a checkout`);
+        this.name = "GraphNoRepository";
+    }
+}
+export function resolveRoot(library, repo, cwd) {
+    if (repo !== undefined) {
+        const known = library.findProject(repo);
+        if (known !== undefined)
+            return known.path;
+        const path = resolve(cwd, repo);
+        if (!existsSync(path))
+            throw new GraphNoRepository(repo);
+        return gitRoot(path);
+    }
+    return gitRoot(cwd);
+}
+function gitRoot(from) {
+    try {
+        return execFileSync("git", ["rev-parse", "--show-toplevel"], { cwd: from, stdio: ["ignore", "pipe", "ignore"] })
+            .toString("utf8")
+            .trim();
+    }
+    catch {
+        throw new GraphNoRepository(from);
+    }
+}
+export class GraphUnavailable extends Error {
+    code = "GRAPH_UNAVAILABLE";
+    constructor(reason) {
+        super(reason);
+        this.name = "GraphUnavailable";
+    }
+}
+const progress = (line) => {
+    process.stderr.write(`${line}\n`);
+};
+export async function answerGraph(fn, argv, options, cwd) {
+    const library = await loadCodegraph();
+    const root = resolveRoot(library, options.repo, cwd);
+    const known = library.findFn(fn);
+    if (known === undefined) {
+        throw new GraphUnavailable(`unknown code-graph function '${fn}' — run \`nustack graph functions\` for the list`);
+    }
+    await refreshIfStale(library, root, { noRefresh: options.refresh === false, onProgress: progress });
+    const db = library.open(root);
+    const args = library.parseArgs(known, argv);
+    const budget = options.budget !== undefined ? Number(options.budget) : args["limit"] !== undefined ? 0 : 2000;
+    const answer = library.dispatch({ root, db, budget }, { fn: known.name, args });
+    if (answer.unavailable !== undefined)
+        throw new GraphUnavailable(answer.unavailable);
+    if (options.json === true) {
+        printJsonSuccess(`graph ${known.name}`, answer);
+        return;
+    }
+    console.log(library.renderText(answer));
+}
+export async function indexGraph(options, cwd) {
+    const library = await loadCodegraph();
+    const root = resolveRoot(library, options.repo, cwd);
+    const result = await library.runIndex(root, {
+        maxCommits: options.commits === undefined ? undefined : Number(options.commits),
+        onProgress: options.json === true ? undefined : progress,
+    });
+    if (options.json === true) {
+        printJsonSuccess("graph index", {
+            root: result.root,
+            projectId: result.projectId,
+            store: result.store,
+            files: result.files,
+            commits: result.commits,
+            symbols: result.symbols,
+            edges: result.edges,
+            extractor: result.extractor,
+            head: result.head,
+            elapsedMs: result.elapsedMs,
+        });
+        return;
+    }
+    console.log([
+        `indexed ${result.root}`,
+        `  project id   ${result.projectId}`,
+        `  store        ${result.store}`,
+        `  files        ${result.files}`,
+        `  commits      ${result.commits} (${result.changes} file changes)`,
+        `  symbols      ${result.symbols} across ${result.symbolFiles} files`,
+        `  call edges   ${result.edges} (inferred from syntax, not resolved bindings)`,
+        `  extractor    ${result.extractor} (declarations: ${result.declarationConfidence})`,
+        `  elapsed      ${(result.elapsedMs / 1000).toFixed(1)}s`,
+        "",
+        "next: nustack graph overview",
+    ].join("\n"));
+}
+export async function statusGraph(options, cwd) {
+    const library = await loadCodegraph();
+    const root = resolveRoot(library, options.repo, cwd);
+    const record = library.findProject(root);
+    const health = record === undefined ? undefined : library.projectHealth(record, library.databaseFile(root));
+    const data = {
+        root,
+        projectId: library.projectId(root),
+        indexed: record !== undefined,
+        store: library.storeDir(root),
+        home: library.codegraphHome(),
+        head: library.headOf(root),
+        indexedHead: record?.lastHead ?? null,
+        indexedAt: record?.indexedAt ?? null,
+        files: record?.files ?? 0,
+        symbols: record?.symbols ?? 0,
+        commits: record?.commits ?? 0,
+        extractor: record?.extractor ?? null,
+        isStale: health?.isStale ?? false,
+        isReadable: health?.isReadable ?? false,
+        unreadableReason: health?.unreadableReason ?? "never indexed",
+        schemaVersion: health?.schemaVersion ?? 0,
+        databaseBytes: health?.databaseBytes ?? 0,
+    };
+    if (options.json === true) {
+        printJsonSuccess("graph status", data);
+        return;
+    }
+    if (!data.indexed) {
+        console.log(`${root}\n  not indexed — run: nustack graph index`);
+        return;
+    }
+    const age = data.indexedAt === null ? "never" : `${((Date.now() / 1000 - data.indexedAt) / 3600).toFixed(1)}h ago`;
+    console.log([
+        `${root}`,
+        `  project id   ${data.projectId}`,
+        `  store        ${data.store} (${(data.databaseBytes / 1e6).toFixed(1)} MB, schema v${data.schemaVersion})`,
+        `  indexed      ${age} — ${data.commits} commits, ${data.files} files, ${data.symbols} symbols`,
+        `  head         ${data.indexedHead ?? "unknown"}${data.isStale ? `  [STALE — checkout is at ${data.head ?? "unknown"}]` : "  [current]"}`,
+        `  readable     ${data.isReadable ? "yes" : `no — ${data.unreadableReason}`}`,
+        "",
+        data.isStale ? "the next query refreshes it; --no-refresh answers from this index" : "next: nustack graph overview",
+    ].join("\n"));
+}
+export async function listGraphFunctions(options) {
+    const library = await loadCodegraph();
+    if (options.json === true) {
+        printJsonSuccess("graph functions", {
+            functions: library.FUNCTIONS.map((fn) => ({
+                name: fn.name,
+                summary: fn.summary,
+                cost: fn.cost,
+                args: Object.entries(fn.args).map(([key, spec]) => ({
+                    name: key,
+                    kind: spec.kind,
+                    required: spec.required === true,
+                    positional: spec.positional ?? null,
+                    describe: spec.describe,
+                })),
+            })),
+        });
+        return;
+    }
+    const lines = ["the code graph's query functions — `nustack graph <fn> [args]`", ""];
+    for (const fn of library.FUNCTIONS) {
+        lines.push(`${fn.name.padEnd(18)}${fn.summary}  [${fn.cost}]`);
+    }
+    lines.push("", "index    build or rebuild this repository's graph", "status   what the store holds, and whether it is behind");
+    console.log(lines.join("\n"));
+}

package/dist/lib/graph/freshness.js

@@ -0,0 +1,29 @@
+export function inspect(library, root) {
+    const record = library.findProject(root);
+    if (record === undefined) {
+        return { record: undefined, isStale: false, isReadable: false, unreadableReason: "never indexed" };
+    }
+    const health = library.projectHealth(record, library.databaseFile(root));
+    return {
+        record,
+        isStale: health.isStale,
+        isReadable: health.isReadable,
+        unreadableReason: health.unreadableReason,
+    };
+}
+export class GraphNotIndexed extends Error {
+    code = "GRAPH_NOT_INDEXED";
+    constructor(root) {
+        super(`no code graph for ${root} yet — run: nustack graph index`);
+        this.name = "GraphNotIndexed";
+    }
+}
+export async function refreshIfStale(library, root, options = {}) {
+    const verdict = inspect(library, root);
+    if (verdict.record === undefined)
+        throw new GraphNotIndexed(root);
+    if (!verdict.isStale || options.noRefresh === true)
+        return { refreshed: false, verdict };
+    await library.runIndex(root, { onProgress: options.onProgress });
+    return { refreshed: true, verdict: inspect(library, root) };
+}

package/dist/lib/graph/library.js

@@ -0,0 +1,19 @@
+export class GraphLibraryMissing extends Error {
+    code = "GRAPH_LIBRARY_MISSING";
+    constructor() {
+        super("the code graph library is not installed with this nustack — install it beside the CLI (`npm i -g @nurix/codegraph`) or run nustack from a checkout of the monorepo.");
+        this.name = "GraphLibraryMissing";
+    }
+}
+let cached = null;
+export async function loadCodegraph() {
+    if (cached !== null)
+        return cached;
+    try {
+        cached = (await import("@nurix/codegraph"));
+        return cached;
+    }
+    catch {
+        throw new GraphLibraryMissing();
+    }
+}

package/dist/lib/guards.js

@@ -0,0 +1,106 @@
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]", "::1"]);
+function assertNoControlChars(label, value) {
+    for (const character of value) {
+        const code = character.codePointAt(0) ?? 0;
+        if (code < 0x20 || code === 0x7f) {
+            throw new Error(`${label} contains control characters — refusing to use it`);
+        }
+    }
+}
+function parseSecureUrl(label, raw) {
+    assertNoControlChars(label, raw);
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new Error(`${label} is not a valid URL: ${raw}`);
+    }
+    const isLoopback = LOOPBACK_HOSTS.has(url.hostname);
+    if (url.protocol !== "https:" && !(url.protocol === "http:" && isLoopback)) {
+        throw new Error(`${label} must use https (got ${url.protocol}//${url.host}) — refusing to send credentials over an unencrypted or non-web transport`);
+    }
+    if (url.username !== "" || url.password !== "") {
+        throw new Error(`${label} must not embed credentials`);
+    }
+    return url;
+}
+export function assertSafeNuStackUrl(raw) {
+    const url = parseSecureUrl("The NuStack URL", raw);
+    return url.toString().replace(/\/+$/, "");
+}
+const PACKAGE_NAME_PATTERN = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
+export function assertSafePackageName(name) {
+    assertNoControlChars("The package name", name);
+    if (name.length > 214 || !PACKAGE_NAME_PATTERN.test(name)) {
+        throw new Error(`The catalogue offered an unsafe package name (${name}) — expected a plain npm name like @scope/pkg, not a URL, path, or flag`);
+    }
+    return name;
+}
+export function assertSafeEnvKey(key) {
+    if (!/^[A-Z][A-Z0-9_]*$/.test(key)) {
+        throw new Error(`Unsafe env key from the server: ${key}`);
+    }
+    return key;
+}
+export function assertSafeEnvValue(key, value) {
+    assertNoControlChars(`The value for ${key}`, value);
+    return value;
+}
+export function assertSafeIndexName(index) {
+    if (!/^[a-z0-9][a-z0-9._-]{0,254}$/.test(index)) {
+        throw new Error(`The broker offered an unsafe index name: ${index}`);
+    }
+    return index;
+}
+export function assertSafeElkUrl(raw) {
+    const url = parseSecureUrl("The ELK URL", raw);
+    const port = url.port || (url.protocol === "https:" ? "443" : "80");
+    return `${url.protocol}//${url.hostname}:${port}${url.pathname}${url.search}`;
+}
+export function assertSafeApiKey(key) {
+    if (!/^[A-Za-z0-9+/=_:-]{1,1024}$/.test(key)) {
+        throw new Error("The broker offered an ingest key with unexpected characters");
+    }
+    if (key.includes(":"))
+        return key;
+    const decoded = decodeApiKeyPair(key);
+    return decoded ?? key;
+}
+function decodeApiKeyPair(key) {
+    if (key.length % 4 !== 0)
+        return null;
+    try {
+        const decoded = Buffer.from(key, "base64").toString("utf8");
+        if (!/^[A-Za-z0-9_-]+:[A-Za-z0-9_-]+$/.test(decoded))
+            return null;
+        return Buffer.from(decoded, "utf8").toString("base64") === key ? decoded : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function assertSafeEndpointUrl(raw) {
+    return parseSecureUrl("The service endpoint", raw).toString();
+}
+export function assertSafeOpaqueId(label, raw) {
+    assertNoControlChars(label, raw);
+    if (raw.length === 0 || raw.length > 256 || raw.includes("/")) {
+        throw new Error(`${label} is not a valid identifier (${raw})`);
+    }
+    return raw;
+}
+export function assertSafeBrowserUrl(raw) {
+    assertNoControlChars("The approval URL", raw);
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new Error(`The approval URL is not a valid URL: ${raw}`);
+    }
+    if (url.protocol !== "https:" && url.protocol !== "http:") {
+        throw new Error(`Refusing to open a non-web URL: ${raw}`);
+    }
+    return url.toString();
+}

package/dist/lib/interactive.js

@@ -0,0 +1,12 @@
+import * as p from "@clack/prompts";
+export function isInteractive() {
+    return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+export async function confirmOrFallback(message, fallback) {
+    if (!isInteractive()) {
+        p.log.info(`${message} → ${fallback ? "yes" : "no"} (non-interactive default)`);
+        return fallback;
+    }
+    const answer = await p.confirm({ message });
+    return p.isCancel(answer) ? false : answer;
+}

package/dist/lib/json_output.js

@@ -0,0 +1,8 @@
+export const NUSTACK_JSON_VERSION = 1;
+export function printJsonSuccess(command, data) {
+    console.log(JSON.stringify({ nustackJsonVersion: NUSTACK_JSON_VERSION, command, ok: true, data }));
+}
+export function printJsonError(command, error) {
+    console.log(JSON.stringify({ nustackJsonVersion: NUSTACK_JSON_VERSION, command, ok: false, error }));
+    process.exitCode = 1;
+}

package/dist/lib/lanes/claudeAdapter.js

@@ -0,0 +1,135 @@
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+export function claudeLaneArgs(permissionMode, resumeSessionId) {
+    const args = [
+        "-p",
+        "--input-format",
+        "stream-json",
+        "--output-format",
+        "stream-json",
+        "--verbose",
+        "--include-partial-messages",
+        "--permission-prompt-tool",
+        "stdio",
+    ];
+    if (permissionMode)
+        args.push("--permission-mode", permissionMode);
+    if (resumeSessionId)
+        args.push("--resume", resumeSessionId);
+    return args;
+}
+const DENY_MESSAGE = "Denied by the user in NuStack desktop.";
+const STOP_KILL_GRACE_MS = 3_000;
+export class ClaudeLane {
+    child;
+    pendingApprovals = new Map();
+    interruptSeq = 0;
+    sessionIdSeen = false;
+    killTimer = null;
+    options;
+    constructor(options) {
+        this.options = options;
+        const spawnImpl = options.spawnImpl ?? spawn;
+        this.child = spawnImpl(options.claudeBin ?? "claude", claudeLaneArgs(options.permissionMode, options.resumeSessionId), {
+            cwd: options.cwd,
+            env: options.env ?? process.env,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        this.child.on("error", (error) => {
+            const code = error.code === "ENOENT" ? "CLAUDE_NOT_FOUND" : "ADAPTER_FAILED";
+            options.onProtocolError(code, error.message);
+        });
+        this.child.on("exit", (code) => {
+            if (this.killTimer)
+                clearTimeout(this.killTimer);
+            this.killTimer = null;
+            options.onExit(code);
+        });
+        this.child.stderr.on("data", () => {
+        });
+        const lines = createInterface({ input: this.child.stdout });
+        lines.on("line", (line) => this.handleLine(line));
+    }
+    write(payload) {
+        if (this.child.stdin.writable)
+            this.child.stdin.write(JSON.stringify(payload) + "\n");
+    }
+    handleLine(line) {
+        let frame;
+        try {
+            const parsed = JSON.parse(line);
+            if (typeof parsed !== "object" || parsed === null)
+                throw new Error("not an object");
+            frame = parsed;
+        }
+        catch {
+            this.options.onProtocolError("ADAPTER_FAILED", `unparseable provider line: ${line.slice(0, 120)}`);
+            return;
+        }
+        if (frame.type === "control_request") {
+            this.handleControlRequest(frame);
+            return;
+        }
+        if (!this.sessionIdSeen && frame.type === "system" && frame.subtype === "init" && typeof frame.session_id === "string") {
+            this.sessionIdSeen = true;
+            this.options.onSessionId?.(frame.session_id);
+        }
+        this.options.onEvent(frame);
+    }
+    handleControlRequest(frame) {
+        const requestId = typeof frame.request_id === "string" ? frame.request_id : null;
+        const request = (typeof frame.request === "object" && frame.request !== null ? frame.request : {});
+        const subtype = typeof request.subtype === "string" ? request.subtype : null;
+        if (requestId === null) {
+            this.options.onProtocolError("ADAPTER_FAILED", "control_request without request_id — cannot answer; ignored");
+            return;
+        }
+        if (subtype !== "can_use_tool") {
+            this.write({ type: "control_response", response: { subtype: "error", request_id: requestId, error: `unsupported control request: ${String(subtype)}` } });
+            return;
+        }
+        const toolName = typeof request.tool_name === "string" ? request.tool_name : null;
+        if (toolName === null) {
+            this.write({
+                type: "control_response",
+                response: { subtype: "success", request_id: requestId, response: { behavior: "deny", message: DENY_MESSAGE } },
+            });
+            this.options.onProtocolError("ADAPTER_FAILED", "can_use_tool without tool_name — denied fail-closed");
+            return;
+        }
+        this.pendingApprovals.set(requestId, { toolInput: request.input });
+        this.options.onApprovalRequest({
+            requestId,
+            toolName,
+            displayName: typeof request.display_name === "string" ? request.display_name : null,
+            toolInput: request.input,
+            description: typeof request.description === "string" ? request.description : null,
+        });
+    }
+    sendTurn(text) {
+        this.write({ type: "user", message: { role: "user", content: [{ type: "text", text }] } });
+    }
+    respondApproval(requestId, verdict) {
+        const pending = this.pendingApprovals.get(requestId);
+        if (!pending) {
+            this.options.onProtocolError("APPROVAL_UNROUTABLE", `no pending approval ${requestId} — verdict dropped`);
+            return;
+        }
+        this.pendingApprovals.delete(requestId);
+        const response = verdict === "allow"
+            ? { behavior: "allow", updatedInput: pending.toolInput }
+            : { behavior: "deny", message: DENY_MESSAGE };
+        this.write({ type: "control_response", response: { subtype: "success", request_id: requestId, response } });
+    }
+    interrupt() {
+        this.interruptSeq += 1;
+        this.write({ type: "control_request", request_id: `nustack-interrupt-${this.interruptSeq}`, request: { subtype: "interrupt" } });
+    }
+    stop() {
+        this.child.stdin.end();
+        this.killTimer = setTimeout(() => {
+            this.child.kill("SIGKILL");
+        }, STOP_KILL_GRACE_MS);
+        this.killTimer.unref?.();
+    }
+}

package/dist/lib/lanes/frames.js

@@ -0,0 +1,73 @@
+export const FRAME_VERSION = 1;
+const INBOUND_TYPES = new Set([
+    "lane.open",
+    "lane.turn",
+    "lane.approval",
+    "lane.interrupt",
+    "lane.close",
+    "engine.shutdown",
+]);
+export function parseInboundFrame(line) {
+    let raw;
+    try {
+        raw = JSON.parse(line);
+    }
+    catch {
+        return { ok: false, error: { code: "BAD_FRAME", name: null, message: "not JSON" } };
+    }
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        return { ok: false, error: { code: "BAD_FRAME", name: null, message: "not an object" } };
+    }
+    const frame = raw;
+    const type = typeof frame.type === "string" ? frame.type : null;
+    if (type === null)
+        return { ok: false, error: { code: "BAD_FRAME", name: null, message: "missing type" } };
+    if (!INBOUND_TYPES.has(type)) {
+        return { ok: false, error: { code: "UNKNOWN_FRAME", name: type, message: `unknown frame type: ${type}` } };
+    }
+    if (frame.v !== FRAME_VERSION) {
+        return { ok: false, error: { code: "BAD_FRAME", name: type, message: `unsupported frame version: ${String(frame.v)}` } };
+    }
+    const requireString = (key) => (typeof frame[key] === "string" && frame[key] !== "" ? frame[key] : null);
+    switch (type) {
+        case "engine.shutdown":
+            return { ok: true, frame: { v: FRAME_VERSION, type } };
+        case "lane.open": {
+            const laneId = requireString("laneId");
+            const projectPath = requireString("projectPath");
+            if (!laneId || !projectPath)
+                return { ok: false, error: { code: "BAD_FRAME", name: type, message: "lane.open requires laneId and projectPath" } };
+            const permissionMode = typeof frame.permissionMode === "string" ? frame.permissionMode : undefined;
+            const isolated = frame.isolated === true ? true : undefined;
+            const resumeSessionId = typeof frame.resumeSessionId === "string" && frame.resumeSessionId !== "" ? frame.resumeSessionId : undefined;
+            return { ok: true, frame: { v: FRAME_VERSION, type, laneId, projectPath, permissionMode, isolated, resumeSessionId } };
+        }
+        case "lane.turn": {
+            const laneId = requireString("laneId");
+            const text = typeof frame.text === "string" ? frame.text : null;
+            if (!laneId || text === null)
+                return { ok: false, error: { code: "BAD_FRAME", name: type, message: "lane.turn requires laneId and text" } };
+            return { ok: true, frame: { v: FRAME_VERSION, type, laneId, text } };
+        }
+        case "lane.approval": {
+            const laneId = requireString("laneId");
+            const requestId = requireString("requestId");
+            const verdict = frame.verdict === "allow" || frame.verdict === "deny" ? frame.verdict : null;
+            if (!laneId || !requestId || !verdict)
+                return { ok: false, error: { code: "BAD_FRAME", name: type, message: "lane.approval requires laneId, requestId, verdict" } };
+            return { ok: true, frame: { v: FRAME_VERSION, type, laneId, requestId, verdict } };
+        }
+        case "lane.interrupt":
+        case "lane.close": {
+            const laneId = requireString("laneId");
+            if (!laneId)
+                return { ok: false, error: { code: "BAD_FRAME", name: type, message: `${type} requires laneId` } };
+            return { ok: true, frame: { v: FRAME_VERSION, type, laneId } };
+        }
+        default:
+            return { ok: false, error: { code: "UNKNOWN_FRAME", name: type, message: `unknown frame type: ${type}` } };
+    }
+}
+export function serializeFrame(frame) {
+    return JSON.stringify(frame) + "\n";
+}