@interf/compiler 0.33.0 → 0.50.0

package/dist/cli/commands/project.js

@@ -2,7 +2,7 @@
  * `interf project` — Project CRUD against a connected instance.
  *
  *   interf project ls
- *   interf project create <id> --source <path> [--build-plan <id>]
+ *   interf project create <id> --source <path> --intent "..." [--build-plan <id>]
  *   interf project show <id>
  *   interf project rm <id>
  * Every subcommand requires an active connection. If `~/.interf/connection.json`
@@ -11,40 +11,9 @@
  */
 import { resolve } from "node:path";
 import chalk from "chalk";
-import { CONNECT_OR_ERROR_HINT, readActiveConnection, } from "../../packages/runtime/connection-config.js";
+import { callJson, resolveConnection as requireConnection } from "../lib/http-client.js";
 import { projectResourcePath } from "../../packages/runtime/service/routes.js";
 import { ProjectListResponseSchema, ProjectResourceSchema, ProjectWireShapeSchema, } from "../../packages/runtime/schemas/index.js";
-function requireConnection(args) {
-    const conn = readActiveConnection({
-        urlOverride: args.url,
-        authTokenOverride: args.token,
-    });
-    if (!conn) {
-        console.error(CONNECT_OR_ERROR_HINT);
-        process.exit(1);
-    }
-    return { url: conn.url.replace(/\/+$/, ""), token: conn.auth_token };
-}
-async function callJson(url, token, init = {}) {
-    const headers = new Headers(init.headers ?? {});
-    if (token)
-        headers.set("authorization", `Bearer ${token}`);
-    if (init.body && !headers.has("content-type")) {
-        headers.set("content-type", "application/json");
-    }
-    const response = await fetch(url, { ...init, headers });
-    const raw = await response.text();
-    let body = null;
-    if (raw.length > 0) {
-        try {
-            body = JSON.parse(raw);
-        }
-        catch {
-            body = null;
-        }
-    }
-    return { status: response.status, body, raw };
-}
 function statusColor(status) {
     if (status === "ready")
         return chalk.green;
@@ -58,6 +27,8 @@ function renderProjectSummary(project) {
     console.log();
     console.log(`  ${chalk.bold(project.name)}`);
     console.log(chalk.dim(`    Build Plan: ${project.build_plan_id ?? "(not selected)"}`));
+    if (project.intent)
+        console.log(chalk.dim(`    agent task: ${project.intent}`));
     if (project.source_path)
         console.log(chalk.dim(`    source:  ${project.source_path}`));
     const contextGraphPath = project.context_graph_path;
@@ -70,7 +41,7 @@ function renderProjectSummary(project) {
     }
     if (project.artifacts && project.artifacts.length > 0) {
         console.log();
-        console.log(chalk.bold("    Artifacts"));
+        console.log(chalk.bold("    Outputs"));
         const idWidth = Math.max(...project.artifacts.map((entry) => entry.artifact_id.length), 8);
         for (const artifact of project.artifacts) {
             const colored = statusColor(artifact.status)(artifact.status);
@@ -114,7 +85,7 @@ export const projectCommand = {
         }
         const projects = parsed.data.projects;
         if (projects.length === 0) {
-            console.log(chalk.dim("  No Projects yet. Create one with `interf project create <id> --source <path>`."));
+            console.log(chalk.dim("  No Projects yet. Create one with `interf project create <id> --source <path> --intent \"<agent task>\"`."));
             return;
         }
         console.log();
@@ -124,6 +95,7 @@ export const projectCommand = {
             const sourceLabel = project.source.locator;
             const buildPlan = project.build_plan_id ?? "(no Build Plan)";
             console.log(`  ${project.id}`);
+            console.log(chalk.dim(`    agent task: ${project.intent}`));
             console.log(chalk.dim(`    source: ${sourceLabel}`));
             console.log(chalk.dim(`    Build Plan: ${buildPlan}`));
         }
@@ -131,11 +103,13 @@ export const projectCommand = {
         .command("create <project-id>", "Create a Project (Build Plan optional — select or draft it later)", (y) => y
         .positional("project-id", { type: "string", demandOption: true, describe: "Project id (lowercase, dash-separated)" })
         .option("source", { type: "string", demandOption: true, describe: "Path to the Source" })
+        .option("intent", { type: "string", demandOption: true, describe: "Agent task this Project's Context Graph should support" })
         .option("build-plan", { type: "string", describe: "Build Plan id. Optional — select later with `interf plan select`." }), async (args) => {
         const { url, token } = requireConnection(args);
         const sourceAbs = resolve(process.cwd(), args.source);
         const requestBody = {
             id: args.projectId,
+            intent: args.intent,
             source: { kind: "local-folder", locator: sourceAbs },
             ...(args.buildPlan ? { build_plan_id: args.buildPlan } : {}),
         };
@@ -150,7 +124,7 @@ export const projectCommand = {
         if (!args.buildPlan) {
             console.log(chalk.dim(`  no Build Plan selected yet — pick or draft one before building:`));
             console.log(chalk.dim(`    interf plan select ${args.projectId} <plan-id>`));
-            console.log(chalk.dim(`    interf plan draft ${args.projectId} --intent "..."`));
+            console.log(chalk.dim(`    interf plan draft ${args.projectId}`));
         }
         const parsed = ProjectWireShapeSchema.safeParse(body);
         if (parsed.success && parsed.data.build_plan_id && parsed.data.context_graph.value) {

package/dist/cli/commands/reset.d.ts

@@ -1,9 +1,8 @@
 import type { CommandModule } from "yargs";
-interface ResetArgs {
+import { type ConnectionArgs } from "../lib/http-client.js";
+interface ResetArgs extends ConnectionArgs {
     projectId: string;
     mode?: "build" | "all";
-    url?: string;
-    token?: string;
 }
 export declare const resetCommand: CommandModule<unknown, ResetArgs>;
 export {};

package/dist/cli/commands/reset.js

@@ -5,28 +5,7 @@
  *   interf reset bristol --mode all  # also clear Build Plan draft runs
  */
 import chalk from "chalk";
-import { CONNECT_OR_ERROR_HINT, readActiveConnection } from "../../packages/runtime/connection-config.js";
-function resolveConnection(args) {
-    const conn = readActiveConnection({
-        urlOverride: args.url,
-        authTokenOverride: args.token,
-    });
-    if (!conn) {
-        console.error(CONNECT_OR_ERROR_HINT);
-        process.exit(1);
-    }
-    return { url: conn.url.replace(/\/+$/, ""), token: conn.auth_token };
-}
-async function callJson(url, token, init = {}) {
-    const headers = new Headers(init.headers ?? {});
-    if (token)
-        headers.set("authorization", `Bearer ${token}`);
-    if (init.body && !headers.has("content-type"))
-        headers.set("content-type", "application/json");
-    const response = await fetch(url, { ...init, headers });
-    const raw = await response.text();
-    return { status: response.status, raw };
-}
+import { callJson, resolveConnection } from "../lib/http-client.js";
 export const resetCommand = {
     command: "reset <project-id>",
     describe: "Reset a Project's built output",

package/dist/cli/commands/runs.js

@@ -3,41 +3,13 @@
  *
  *   interf runs ls [--project <id>]
  *   interf runs status <run-id>
+ *   interf runs events <run-id>
+ *   interf runs artifacts <run-id>
  *   interf runs cancel <run-id>
  */
 import chalk from "chalk";
-import { CONNECT_OR_ERROR_HINT, readActiveConnection } from "../../packages/runtime/connection-config.js";
-import { RunObservabilityListResponseSchema, RunObservabilityResourceSchema, } from "../../packages/runtime/schemas/index.js";
-function resolveConnection(args) {
-    const conn = readActiveConnection({
-        urlOverride: args.url,
-        authTokenOverride: args.token,
-    });
-    if (!conn) {
-        console.error(CONNECT_OR_ERROR_HINT);
-        process.exit(1);
-    }
-    return { url: conn.url.replace(/\/+$/, ""), token: conn.auth_token };
-}
-async function callJson(url, token, init = {}) {
-    const headers = new Headers(init.headers ?? {});
-    if (token)
-        headers.set("authorization", `Bearer ${token}`);
-    if (init.body && !headers.has("content-type"))
-        headers.set("content-type", "application/json");
-    const response = await fetch(url, { ...init, headers });
-    const raw = await response.text();
-    let body = null;
-    if (raw) {
-        try {
-            body = JSON.parse(raw);
-        }
-        catch {
-            body = null;
-        }
-    }
-    return { status: response.status, body, raw };
-}
+import { callJson, resolveConnection } from "../lib/http-client.js";
+import { RunArtifactsResponseSchema, RunEventsResponseSchema, RunObservabilityListResponseSchema, RunObservabilityResourceSchema, } from "../../packages/runtime/schemas/index.js";
 function runStatusColor(status) {
     if (status === "succeeded" || status === "completed")
         return chalk.green;
@@ -90,7 +62,7 @@ function renderRunStatus(run) {
     const artifacts = run.artifacts ?? [];
     if (artifacts.length > 0) {
         console.log();
-        console.log(chalk.bold("    Artifacts"));
+        console.log(chalk.bold("    Outputs"));
         for (const artifact of artifacts.slice(0, 12)) {
             const stage = artifact.stage_id ? chalk.dim(` ← ${artifact.stage_id}`) : "";
             console.log(`      ${artifact.label ?? "output"}: ${chalk.dim(artifact.path)}${stage}`);
@@ -121,6 +93,35 @@ function renderRunStatus(run) {
     console.log(chalk.dim("  Run with --json for the raw run resource."));
     console.log();
 }
+function renderEvents(events) {
+    if (events.length === 0) {
+        console.log(chalk.dim("  No events recorded for this run."));
+        return;
+    }
+    console.log();
+    for (const event of events) {
+        // stage_id / path exist only on some event variants; read defensively.
+        const stageId = "stage_id" in event ? event.stage_id : undefined;
+        const path = "path" in event ? event.path : undefined;
+        const detail = [stageId, path].filter(Boolean).join(" · ");
+        console.log(`  ${chalk.dim(event.timestamp)} ${chalk.bold(event.type)}${detail ? chalk.dim(`  ${detail}`) : ""}`);
+    }
+    console.log();
+    console.log(chalk.dim("  Run with --json for full event payloads."));
+    console.log();
+}
+function renderArtifacts(artifacts) {
+    if (artifacts.length === 0) {
+        console.log(chalk.dim("  No artifacts recorded for this run."));
+        return;
+    }
+    console.log();
+    for (const artifact of artifacts) {
+        const stage = artifact.stage_id ? chalk.dim(` ← ${artifact.stage_id}`) : "";
+        console.log(`  ${artifact.label ?? artifact.role}: ${chalk.dim(artifact.path)}${stage}`);
+    }
+    console.log();
+}
 export const runsCommand = {
     command: "runs <subcommand>",
     describe: "Inspect durable Runs on the connected instance",
@@ -198,6 +199,58 @@ export const runsCommand = {
             process.exit(1);
         }
         renderRunStatus(parsed.data);
+    })
+        .command("events <run-id>", "Read the durable event log for a Build run", (y) => y
+        .positional("run-id", { type: "string", demandOption: true, describe: "Run id" })
+        .option("json", {
+        type: "boolean",
+        default: false,
+        describe: "Print the raw JSON event array",
+    }), async (args) => {
+        const { url, token } = resolveConnection(args);
+        const { status, body, raw } = await callJson(`${url}/v1/runs/${encodeURIComponent(args.runId)}/events`, token);
+        if (status !== 200) {
+            console.error(chalk.red(`Failed to read events for ${args.runId} (HTTP ${status}).`));
+            if (raw)
+                console.error(raw);
+            process.exit(1);
+        }
+        const parsed = RunEventsResponseSchema.safeParse(body);
+        if (!parsed.success) {
+            console.error(chalk.red(`Failed to parse events for ${args.runId}.`));
+            process.exit(1);
+        }
+        if (args.json) {
+            console.log(JSON.stringify(parsed.data.events, null, 2));
+            return;
+        }
+        renderEvents(parsed.data.events);
+    })
+        .command("artifacts <run-id>", "Read the artifact manifest for a finished Build run", (y) => y
+        .positional("run-id", { type: "string", demandOption: true, describe: "Run id" })
+        .option("json", {
+        type: "boolean",
+        default: false,
+        describe: "Print the raw JSON artifact array",
+    }), async (args) => {
+        const { url, token } = resolveConnection(args);
+        const { status, body, raw } = await callJson(`${url}/v1/runs/${encodeURIComponent(args.runId)}/artifacts`, token);
+        if (status !== 200) {
+            console.error(chalk.red(`Failed to read artifacts for ${args.runId} (HTTP ${status}).`));
+            if (raw)
+                console.error(raw);
+            process.exit(1);
+        }
+        const parsed = RunArtifactsResponseSchema.safeParse(body);
+        if (!parsed.success) {
+            console.error(chalk.red(`Failed to parse artifacts for ${args.runId}.`));
+            process.exit(1);
+        }
+        if (args.json) {
+            console.log(JSON.stringify(parsed.data.artifacts, null, 2));
+            return;
+        }
+        renderArtifacts(parsed.data.artifacts);
     })
         .command("cancel <run-id>", "Cancel a running run", (y) => y.positional("run-id", { type: "string", demandOption: true, describe: "Run id" }), async (args) => {
         const { url, token } = resolveConnection(args);

package/dist/cli/commands/status.js

@@ -3,29 +3,8 @@
  */
 import chalk from "chalk";
 import { CONNECT_OR_ERROR_HINT, readActiveConnection } from "../../packages/runtime/connection-config.js";
+import { callJsonSafe } from "../lib/http-client.js";
 import { InstanceResourceSchema, ProjectListResponseSchema, } from "../../packages/runtime/schemas/index.js";
-async function callJson(url, token) {
-    const headers = new Headers();
-    if (token)
-        headers.set("authorization", `Bearer ${token}`);
-    try {
-        const response = await fetch(url, { headers });
-        const raw = await response.text();
-        let body = null;
-        if (raw) {
-            try {
-                body = JSON.parse(raw);
-            }
-            catch {
-                body = null;
-            }
-        }
-        return { status: response.status, body };
-    }
-    catch {
-        return { status: 0, body: null };
-    }
-}
 export const statusCommand = {
     command: "status",
     describe: "Show connection + Project summary",
@@ -44,7 +23,7 @@ export const statusCommand = {
         }
         const url = conn.url.replace(/\/+$/, "");
         const token = conn.auth_token;
-        const instance = await callJson(`${url}/v1/instance`, token);
+        const instance = await callJsonSafe(`${url}/v1/instance`, token);
         if (instance.status === 0) {
             console.error(chalk.red(`Connection ${url} is unreachable.`));
             console.error(CONNECT_OR_ERROR_HINT);
@@ -67,7 +46,7 @@ export const statusCommand = {
             console.log(`  Uptime:   ${instanceResource.data.uptime_seconds}s`);
         }
         console.log(`  Auth:     ${instanceResource.data.auth_required ? "required (token in connection.json)" : "open (explicit dev/test mode)"}`);
-        const projects = await callJson(`${url}/v1/projects`, token);
+        const projects = await callJsonSafe(`${url}/v1/projects`, token);
         const parsedProjects = ProjectListResponseSchema.safeParse(projects.body);
         if (!parsedProjects.success) {
             console.error(chalk.red("Connected service returned an invalid Project list."));

package/dist/cli/commands/traces.js

@@ -5,37 +5,9 @@
  *   interf traces show <trace-kind> --project <id>
  */
 import chalk from "chalk";
-import { CONNECT_OR_ERROR_HINT, readActiveConnection } from "../../packages/runtime/connection-config.js";
+import { callJson, resolveConnection } from "../lib/http-client.js";
 import { TracesSchema, } from "../../packages/contracts/lib/project-schema.js";
 import { projectSubresourcePath } from "../../packages/runtime/service/routes.js";
-function resolveConnection(args) {
-    const conn = readActiveConnection({
-        urlOverride: args.url,
-        authTokenOverride: args.token,
-    });
-    if (!conn) {
-        console.error(CONNECT_OR_ERROR_HINT);
-        process.exit(1);
-    }
-    return { url: conn.url.replace(/\/+$/, ""), token: conn.auth_token };
-}
-async function callJson(url, token) {
-    const headers = new Headers();
-    if (token)
-        headers.set("authorization", `Bearer ${token}`);
-    const response = await fetch(url, { headers });
-    const raw = await response.text();
-    let body = null;
-    if (raw) {
-        try {
-            body = JSON.parse(raw);
-        }
-        catch {
-            body = null;
-        }
-    }
-    return { status: response.status, body, raw };
-}
 function tracesUrl(baseUrl, projectId) {
     return `${baseUrl}${projectSubresourcePath(projectId, "traces")}`;
 }

package/dist/cli/commands/wizard.js

@@ -17,29 +17,8 @@ import { homedir } from "node:os";
 import { basename, resolve } from "node:path";
 import { spawn } from "node:child_process";
 import { ConnectionRecordSchema, readActiveConnection, writeConnection, } from "../../packages/runtime/connection-config.js";
+import { callJsonSafe } from "../lib/http-client.js";
 import { LOCAL_SERVICE_DEFAULT_HOST, LOCAL_SERVICE_DEFAULT_PORT } from "../../packages/runtime/service/routes.js";
-async function callJson(url, token) {
-    const headers = new Headers();
-    if (token)
-        headers.set("authorization", `Bearer ${token}`);
-    try {
-        const response = await fetch(url, { headers });
-        const raw = await response.text();
-        let body = null;
-        if (raw) {
-            try {
-                body = JSON.parse(raw);
-            }
-            catch {
-                body = null;
-            }
-        }
-        return { status: response.status, body };
-    }
-    catch {
-        return { status: 0, body: null };
-    }
-}
 function spawnInterf(args) {
     return new Promise((resolveSpawn) => {
         const child = spawn(process.argv[1] ?? "interf", args, { stdio: "inherit" });
@@ -233,7 +212,7 @@ async function promptForConnection(reason) {
         auth_token: String(tokenValue ?? "").trim() || null,
     });
     const url = record.url.replace(/\/+$/, "");
-    const probe = await callJson(`${url}/health`, record.auth_token);
+    const probe = await callJsonSafe(`${url}/health`, record.auth_token);
     if (probe.status === 0) {
         return promptForConnection(`Connection ${url} is unreachable.`);
     }
@@ -308,10 +287,17 @@ async function flowCreateProject(conn) {
     const sourcePath = await promptSourcePath();
     if (!sourcePath)
         return null;
+    const intent = await p.text({
+        message: "What should the agent do with this Source?",
+        placeholder: "Compare the launch timeline against approval notes and produce a sourced handoff.",
+        validate: (value) => String(value).trim().length > 0 ? undefined : "Agent task is required.",
+    });
+    if (p.isCancel(intent))
+        return null;
     // Offer saved Build Plans, but keep selection optional. The agent-first
     // path usually creates the Project from Source first, then drafts a
     // custom Build Plan for review.
-    const buildPlansResp = await callJson(`${conn.url}/v1/build-plans`, conn.token);
+    const buildPlansResp = await callJsonSafe(`${conn.url}/v1/build-plans`, conn.token);
     const buildPlans = buildPlansResp.body?.build_plans ?? [];
     const buildPlanOptions = buildPlans
         .map((plan) => ({ value: plan.build_plan_id ?? plan.id ?? "", label: `${plan.build_plan_id ?? plan.id ?? "(?)"}${plan.label ? ` - ${plan.label}` : ""}` }))
@@ -369,6 +355,8 @@ async function flowCreateProject(conn) {
         String(projectId),
         "--source",
         resolve(String(sourcePath)),
+        "--intent",
+        String(intent),
         ...(buildPlanId ? ["--build-plan", buildPlanId] : []),
     ]);
     if (exitCode !== 0)
@@ -376,7 +364,7 @@ async function flowCreateProject(conn) {
     return { id: String(projectId), buildPlanId };
 }
 async function pickProject(conn, message) {
-    const projects = await callJson(`${conn.url}/v1/projects`, conn.token);
+    const projects = await callJsonSafe(`${conn.url}/v1/projects`, conn.token);
     const list = projects.body?.projects ?? [];
     if (list.length === 0) {
         console.log(chalk.dim("  No Projects yet. Create one first."));
@@ -590,8 +578,8 @@ async function showAgentInstallCards() {
     return "rerun";
 }
 async function fetchAgentState(conn) {
-    const instance = await callJson(`${conn.url}/v1/instance`, conn.token);
-    const agentsResponse = await callJson(`${conn.url}/v1/agents`, conn.token);
+    const instance = await callJsonSafe(`${conn.url}/v1/instance`, conn.token);
+    const agentsResponse = await callJsonSafe(`${conn.url}/v1/agents`, conn.token);
     if (instance.status !== 200)
         return null;
     // Older engines don't expose /v1/agents. Surface the gap explicitly so
@@ -632,7 +620,7 @@ async function runWizard(args) {
     }
     else {
         const url = initial.url.replace(/\/+$/, "");
-        const probe = await callJson(`${url}/health`, initial.auth_token);
+        const probe = await callJsonSafe(`${url}/health`, initial.auth_token);
         if (probe.status === 0) {
             if (!args.url && await probeHealth(DEFAULT_ENGINE_URL)) {
                 conn = await connectToReachableEngine(DEFAULT_ENGINE_URL);
@@ -655,7 +643,7 @@ async function runWizard(args) {
     if (!conn) {
         return;
     }
-    const instance = await callJson(`${conn.url}/v1/instance`, conn.token);
+    const instance = await callJsonSafe(`${conn.url}/v1/instance`, conn.token);
     console.log();
     console.log(chalk.bold(`  Connected to ${conn.url}`));
     console.log(chalk.dim(`  ${instance.body?.project_count ?? 0} project(s)`));

package/dist/cli/lib/http-client.d.ts

@@ -0,0 +1,39 @@
+/** Per-call connection overrides parsed from `--url` / `--token` flags. */
+export interface ConnectionArgs {
+    url?: string;
+    token?: string;
+}
+/** Resolved connection: normalized base URL plus an optional bearer token. */
+export interface ResolvedConnection {
+    url: string;
+    token: string | null;
+}
+/**
+ * Resolve the active connection or exit non-zero with the connect-or-error
+ * hint. Mutating CLI commands never auto-start a service, so absence here is a
+ * hard error.
+ */
+export declare function resolveConnection(args: ConnectionArgs): ResolvedConnection;
+/** Outcome of a JSON request: HTTP status, parsed body (null on empty/parse-fail), and the raw text. */
+export interface JsonResponse<T> {
+    status: number;
+    body: T | null;
+    raw: string;
+}
+/**
+ * Issue a request and parse the response body as JSON.
+ *
+ * - Attaches the bearer token and a JSON content-type for bodied requests.
+ * - Returns `body: null` when the response is empty or not valid JSON; callers
+ *   inspect `status`/`raw` to handle those cases.
+ * - Network/transport errors reject (callers that need reachability probing use
+ *   {@link callJsonSafe}).
+ */
+export declare function callJson<T = unknown>(url: string, token: string | null, init?: RequestInit): Promise<JsonResponse<T>>;
+/**
+ * Reachability-tolerant variant of {@link callJson}. A network/transport error
+ * is reported as `status: 0` instead of rejecting, so probe paths (e.g.
+ * `interf status`, the wizard) can distinguish "unreachable" from an HTTP
+ * error.
+ */
+export declare function callJsonSafe<T = unknown>(url: string, token: string | null, init?: RequestInit): Promise<JsonResponse<T>>;

package/dist/cli/lib/http-client.js

@@ -0,0 +1,73 @@
+/**
+ * CLI-owned HTTP + connection helpers.
+ *
+ * Every `interf` command is a thin authorized client of one connected
+ * instance. The connection-resolution and JSON-fetch logic was previously
+ * copy-pasted into every command file; this module is the single definition
+ * the commands import.
+ *
+ * This is deliberately CLI-scoped. The runtime's own `fetchJson`
+ * (`runtime/client.ts`) is private and 500ms-timeout-scoped — it is not the
+ * reuse target for interactive CLI calls, which must not impose a short
+ * timeout on long Build/benchmark requests.
+ */
+import { CONNECT_OR_ERROR_HINT, readActiveConnection, } from "../../packages/runtime/connection-config.js";
+/**
+ * Resolve the active connection or exit non-zero with the connect-or-error
+ * hint. Mutating CLI commands never auto-start a service, so absence here is a
+ * hard error.
+ */
+export function resolveConnection(args) {
+    const conn = readActiveConnection({
+        urlOverride: args.url,
+        authTokenOverride: args.token,
+    });
+    if (!conn) {
+        console.error(CONNECT_OR_ERROR_HINT);
+        process.exit(1);
+    }
+    return { url: conn.url.replace(/\/+$/, ""), token: conn.auth_token };
+}
+/**
+ * Issue a request and parse the response body as JSON.
+ *
+ * - Attaches the bearer token and a JSON content-type for bodied requests.
+ * - Returns `body: null` when the response is empty or not valid JSON; callers
+ *   inspect `status`/`raw` to handle those cases.
+ * - Network/transport errors reject (callers that need reachability probing use
+ *   {@link callJsonSafe}).
+ */
+export async function callJson(url, token, init = {}) {
+    const headers = new Headers(init.headers ?? {});
+    if (token)
+        headers.set("authorization", `Bearer ${token}`);
+    if (init.body && !headers.has("content-type")) {
+        headers.set("content-type", "application/json");
+    }
+    const response = await fetch(url, { ...init, headers });
+    const raw = await response.text();
+    let body = null;
+    if (raw.length > 0) {
+        try {
+            body = JSON.parse(raw);
+        }
+        catch {
+            body = null;
+        }
+    }
+    return { status: response.status, body, raw };
+}
+/**
+ * Reachability-tolerant variant of {@link callJson}. A network/transport error
+ * is reported as `status: 0` instead of rejecting, so probe paths (e.g.
+ * `interf status`, the wizard) can distinguish "unreachable" from an HTTP
+ * error.
+ */
+export async function callJsonSafe(url, token, init = {}) {
+    try {
+        return await callJson(url, token, init);
+    }
+    catch {
+        return { status: 0, body: null, raw: "" };
+    }
+}