lagora-cli 1.1.0

package/dist/scripts/agora_playground_harness.py

@@ -0,0 +1,263 @@
+"""Running a submitted kernel and checking it against the reference it shipped with.
+
+The harness lives here rather than inside the submitted file. A kernel is then
+only a statement of what it computes -- a `@legato.compile` function and,
+optionally, a `golden` reference -- and the part that drives it, compares the
+result and prints the verdict cannot be edited away by whoever is working on the
+kernel.
+
+Everything the call needs is read off the kernel's own annotations, the same way
+lowering already synthesizes its arguments, so an author does not repeat the
+shapes a second time in a launcher.
+"""
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+from typing import Any
+
+from legato_runner_annotations import (
+    PreflightError,
+    annotation_source,
+    get_function_def,
+    dtype_name,
+    eval_annotation,
+    is_tensor_annotation,
+    load_module,
+    place_arguments,
+    scalar_arg,
+    select_kernel,
+    tensor_shape_from_annotation_source,
+    top_level_function_names,
+)
+from legato_runner_launchers import kernel_has_launcher, statically_decorated_kernel_names
+
+GOLDEN_NAME = "golden"
+INPUTS_NAME = "inputs"
+SHAPES_NAME = "SHAPES"
+OUTPUT_PARAM_NAMES = {"out", "output", "result"}
+
+# A parameter's memory space decides how its device tensor has to be laid out.
+# Only the spaces observed in working kernels are listed: an unknown one is
+# refused rather than guessed, because a wrong layout surfaces as a corrupt
+# result or a legalization failure well away from its cause.
+DEVICE_KIND_BY_MEMORY_SPACE = {
+    "shared_dram": "dram_word_interleaved",
+    "mpu_dram": "mpu_tensor",
+}
+
+
+def has_playground_contract(kernel_path: Path) -> bool:
+    """Whether this file expects the harness to drive it.
+
+    A file that brings its own launcher keeps running itself -- every kernel
+    submitted before this existed does, and they must not change behaviour.
+    """
+    return bool(statically_decorated_kernel_names(kernel_path)) and not kernel_has_launcher(kernel_path)
+
+
+def memory_space_of(source: str) -> str:
+    """The memory space argument of a tensor_type annotation."""
+    call = ast.parse(source, mode="eval").body
+    if not isinstance(call, ast.Call) or len(call.args) < 3:
+        raise PreflightError(f"tensor annotation is missing its memory space: {source}")
+    space = call.args[2]
+    if not isinstance(space, ast.Constant) or not isinstance(space.value, str):
+        raise PreflightError(f"memory space must be a string literal: {source}")
+    return space.value
+
+
+def device_kind_for(space: str, name: str) -> str:
+    kind = DEVICE_KIND_BY_MEMORY_SPACE.get(space)
+    if not kind:
+        known = ", ".join(sorted(DEVICE_KIND_BY_MEMORY_SPACE))
+        raise PreflightError(
+            f"parameter '{name}' is in memory space '{space}', which the Playground harness does not know how to "
+            f"allocate on the device yet. Supported: {known}. Submit a kernel with its own launcher to run this."
+        )
+    return kind
+
+
+def apply_declared_shapes(module: Any, plan: list[dict[str, Any]]) -> None:
+    """Let a submission pin the shapes to run at.
+
+    An annotation may leave a dimension dynamic, and the site then has to invent
+    a number -- a failure that only shows up at a particular size would never be
+    reproduced, and nothing would say which size was tried. Declaring SHAPES is
+    how a report names the one that matters without materialising tensors.
+    """
+    declared = getattr(module, SHAPES_NAME, None)
+    tensors = {entry["name"]: entry for entry in plan if entry["tensor"]}
+    if declared is not None:
+        if not isinstance(declared, dict):
+            raise PreflightError(f"{SHAPES_NAME} must be a dict of parameter name to shape")
+        for name, shape in declared.items():
+            entry = tensors.get(name)
+            if entry is None:
+                raise PreflightError(f"{SHAPES_NAME} names '{name}', which is not a tensor parameter of the kernel")
+            if not isinstance(shape, (list, tuple)) or not all(isinstance(dim, int) and dim > 0 for dim in shape):
+                raise PreflightError(f"{SHAPES_NAME}['{name}'] must be positive integers, got {shape!r}")
+            if len(shape) != len(entry["shape"]):
+                raise PreflightError(
+                    f"{SHAPES_NAME}['{name}'] has rank {len(shape)}, but the kernel declares rank {len(entry['shape'])}"
+                )
+            entry["shape"] = list(shape)
+            entry["declared"] = True
+
+    # Anything still resting on a substituted dimension is said out loud, so a
+    # reader knows the size was the site's choice and not the report's.
+    for entry in tensors.values():
+        if not entry.get("declared") and entry.get("dynamic"):
+            print(
+                f"[LEGATO_WORKER] shape_substituted {entry['name']}={tuple(entry['shape'])} "
+                f"(annotation leaves a dimension dynamic; declare {SHAPES_NAME} to pin it)",
+                flush=True,
+            )
+
+
+def parameter_plan(jit_function: Any) -> list[dict[str, Any]]:
+    """What each parameter needs: its shape, dtype, device layout and role."""
+    function_def = get_function_def(jit_function)
+    plan: list[dict[str, Any]] = []
+    for arg in function_def.args.args:
+        source = annotation_source(arg.annotation)
+        type_value = eval_annotation(source, jit_function)
+        if not is_tensor_annotation(type_value, source):
+            plan.append({"name": arg.arg, "tensor": False, "scalar": scalar_arg(type_value)})
+            continue
+        name = arg.arg
+        space = memory_space_of(source)
+        plan.append({
+            "name": name,
+            "tensor": True,
+            "shape": tensor_shape_from_annotation_source(source, jit_function),
+            "dtype": dtype_name(type_value, source),
+            "kind": device_kind_for(space, name),
+            "space": space,
+            "output": name.lower() in OUTPUT_PARAM_NAMES or name.lower().endswith(("_out", "_output")),
+            "dynamic": "-1" in source,
+        })
+    return plan
+
+
+def host_values(module: Any, plan: list[dict[str, Any]], torch: Any) -> dict[str, Any]:
+    """The values the kernel and the reference both see.
+
+    A submitted `inputs()` wins. A failure often only reproduces on particular
+    numbers -- zeros, denormals, a specific weight matrix -- and random data
+    would quietly run a different case than the one being reported. Without it,
+    seeded random data keeps a run reproducible at least against itself.
+    """
+    wanted = [entry for entry in plan if entry["tensor"] and not entry["output"]]
+    supplied = getattr(module, INPUTS_NAME, None)
+    if not callable(supplied):
+        torch.manual_seed(0)
+        return {e["name"]: (torch.rand(*e["shape"]) * 2 - 1).to(getattr(torch, e["dtype"])) for e in wanted}
+
+    values = supplied()
+    if not isinstance(values, dict):
+        raise PreflightError(f"{INPUTS_NAME}() must return a dict of parameter name to tensor")
+    for entry in wanted:
+        if entry["name"] not in values:
+            raise PreflightError(f"{INPUTS_NAME}() does not provide '{entry['name']}'")
+        shape = tuple(values[entry["name"]].shape)
+        if shape != tuple(entry["shape"]):
+            raise PreflightError(
+                f"{INPUTS_NAME}()['{entry['name']}'] has shape {shape}, but the kernel declares "
+                f"{tuple(entry['shape'])}"
+            )
+    extra = sorted(set(values) - {entry["name"] for entry in wanted})
+    if extra:
+        raise PreflightError(f"{INPUTS_NAME}() provides {extra}, which the kernel does not take as input")
+    return {entry["name"]: values[entry["name"]] for entry in wanted}
+
+
+def build_arguments(module: Any, jit_function: Any, plan: list[dict[str, Any]]) -> tuple[list[Any], dict[str, Any]]:
+    # torch must come first: it autoloads the torch_ha device backend, and
+    # importing torch_ha first re-enters a half-initialised torch.
+    import torch
+    import torch_ha  # noqa: F401  registers torch.ops.lpu.*
+    host = host_values(module, plan, torch)
+    arguments: list[Any] = []
+    for entry in plan:
+        if not entry["tensor"]:
+            arguments.append(entry["scalar"])
+            continue
+        dtype = getattr(torch, entry["dtype"])
+        device_tensor = torch.ops.lpu.empty_with_kind(
+            list(entry["shape"]), entry["kind"], dtype=dtype, device="lpu:0",
+        )
+        if entry["output"]:
+            device_tensor.copy_(torch.zeros(*entry["shape"], dtype=dtype))
+        else:
+            device_tensor.copy_(host[entry["name"]].to(dtype))
+        arguments.append(device_tensor)
+        entry["device"] = device_tensor
+    return place_arguments(jit_function, arguments), host
+
+
+def pin_single_core(jit_function: Any) -> None:
+    """A kernel that only places on core 0 must not be expanded across all cores."""
+    kinds = getattr(jit_function, "_param_kinds", None) or getattr(jit_function, "param_kinds", None) or {}
+    if any(str(kind).rstrip().removesuffix("_param") == "core" for kind in kinds.values()):
+        import legato.launcher
+
+        legato.launcher._enabled_core_count = lambda: 1
+
+
+def report_value(module: Any, plan: list[dict[str, Any]], host: dict[str, Any]) -> None:
+    """Compare against the kernel's own reference, when it shipped one.
+
+    A kernel without a reference still runs; it just has nothing to be checked
+    against, and says so rather than claiming a pass it cannot support.
+    """
+    import torch
+
+    golden = getattr(module, GOLDEN_NAME, None)
+    if not callable(golden):
+        print(
+            "[LEGATO_WORKER] value=unavailable no golden() reference in the submitted kernel",
+            flush=True,
+        )
+        return
+
+    outputs = [entry for entry in plan if entry.get("tensor") and entry.get("output")]
+    if len(outputs) != 1:
+        print(f"[LAGORA_VALUE_DETAIL] expected exactly one output parameter, found {len(outputs)}", flush=True)
+        print("[LAGORA_VALUE] fail", flush=True)
+        return
+
+    expected = golden(**host)
+    actual = outputs[0]["device"].cpu().float()
+    expected = expected.float() if hasattr(expected, "float") else expected
+    rtol = float(getattr(module, "RTOL", 0.05))
+    atol = float(getattr(module, "ATOL", 0.2))
+
+    if tuple(actual.shape) != tuple(expected.shape):
+        print(f"[LAGORA_VALUE_DETAIL] shape {tuple(actual.shape)} != expected {tuple(expected.shape)}", flush=True)
+        print("[LAGORA_VALUE] fail", flush=True)
+        return
+    if not torch.isfinite(actual).all():
+        print("[LAGORA_VALUE_DETAIL] result contains non-finite values", flush=True)
+        print("[LAGORA_VALUE] fail", flush=True)
+        return
+    max_abs = (actual - expected).abs().max().item()
+    print(f"[LAGORA_VALUE_DETAIL] max_abs_diff={max_abs:.6f} rtol={rtol} atol={atol}", flush=True)
+    print(f"[LAGORA_VALUE] {'pass' if torch.allclose(actual, expected, rtol=rtol, atol=atol) else 'fail'}", flush=True)
+
+
+def run_playground_kernel(kernel_path: Path, output_root: Path) -> None:
+    import legato
+
+    module = load_module(kernel_path)
+    _, jit_function = select_kernel(module, None, top_level_function_names(kernel_path))
+    plan = parameter_plan(jit_function)
+    apply_declared_shapes(module, plan)
+    arguments, host = build_arguments(module, jit_function, plan)
+    pin_single_core(jit_function)
+
+    print("[LAGORA_STAGE] BINARY", flush=True)
+    with legato.session(output_type=legato.OutputType.BINARY, output_path=str(output_root)):
+        jit_function(*arguments)
+
+    report_value(module, plan, host)

package/dist/scripts/announce.js

@@ -0,0 +1,41 @@
+// scripts/announce.ts
+function parseArgs(argv) {
+  if (argv[0] !== "create") {
+    throw new Error("Usage: lagora announce create --api-url <url> --title <title> --body <body> [--link <url>] [--token <token>]");
+  }
+  const values = /* @__PURE__ */ new Map();
+  for (let index = 1; index < argv.length; index += 2) {
+    const option = argv[index];
+    const value = argv[index + 1];
+    if (!option?.startsWith("--") || !value) throw new Error(`${option ?? "option"} requires a value`);
+    values.set(option, value);
+  }
+  return {
+    apiUrl: required(values.get("--api-url"), "--api-url").replace(/\/+$/, ""),
+    title: required(values.get("--title"), "--title"),
+    body: required(values.get("--body"), "--body"),
+    linkUrl: values.get("--link")?.trim() || void 0,
+    token: required(values.get("--token") ?? process.env.LAGORA_ANNOUNCEMENT_TOKEN, "--token or LAGORA_ANNOUNCEMENT_TOKEN")
+  };
+}
+function required(value, name) {
+  if (!value?.trim()) throw new Error(`${name} is required`);
+  return value.trim();
+}
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const response = await fetch(`${args.apiUrl}/api/announcements`, {
+    method: "POST",
+    headers: {
+      authorization: `Bearer ${args.token}`,
+      "content-type": "application/json"
+    },
+    body: JSON.stringify({ title: args.title, body: args.body, linkUrl: args.linkUrl })
+  });
+  const body = await response.text();
+  if (!response.ok) throw new Error(`Announcement failed: HTTP ${response.status} ${body.slice(0, 240)}`);
+  const payload = JSON.parse(body);
+  const delivered = payload && typeof payload === "object" ? Reflect.get(payload, "delivered") : void 0;
+  console.log(`Announcement published to ${typeof delivered === "number" ? delivered : "unknown"} users.`);
+}
+await main();

package/dist/scripts/check-kernel-submission.py

@@ -0,0 +1,90 @@
+"""What the site will be able to do with a kernel, reported at submission time.
+
+Informational, never fatal. An arbitrary kernel is a perfectly good bug report
+-- most of them are -- and refusing it because it cannot be value-checked would
+turn a reporting tool into a formatting gate. But the reporter is the one person
+who knows what the right answer was, and this is the moment to say so; asking
+later means someone else reconstructing their intent.
+"""
+from __future__ import annotations
+
+import argparse
+import ast
+import sys
+from pathlib import Path
+
+
+def defines_golden(tree: ast.Module) -> bool:
+    return any(isinstance(node, ast.FunctionDef) and node.name == "golden" for node in tree.body)
+
+
+def decorated_kernels(tree: ast.Module) -> list[str]:
+    names = []
+    for node in tree.body:
+        if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        for decorator in node.decorator_list:
+            text = ast.unparse(decorator)
+            if "legato.compile" in text or "legato.primitive" in text:
+                names.append(node.name)
+                break
+    return names
+
+
+def has_main_guard(tree: ast.Module) -> bool:
+    for node in ast.walk(tree):
+        if isinstance(node, ast.If) and "__main__" in ast.unparse(node.test):
+            return True
+    return False
+
+
+def report(path: Path) -> list[str]:
+    try:
+        tree = ast.parse(path.read_text())
+    except SyntaxError as error:
+        return [f"error: {path.name} is not valid Python: {error}"]
+
+    kernels = decorated_kernels(tree)
+    notes: list[str] = []
+    if not kernels:
+        notes.append(
+            f"note: no @legato.compile function found in {path.name}. The site can still store and show it, "
+            "but it cannot lower or run it."
+        )
+        return notes
+
+    if has_main_guard(tree):
+        notes.append(
+            f"warning: {path.name} brings its own launcher, so it runs itself and the site's harness steps aside. "
+            "A hardcoded session output type can mislabel every requested lowering artifact. Agent-generated "
+            "submissions must remove the launcher and follow reference/kernel-with-golden.py."
+        )
+        return notes
+
+    if defines_golden(tree):
+        notes.append(f"ok: {path.name} defines golden() and {kernels[0]}(); the site can lower, run and check values.")
+    else:
+        notes.append(
+            f"note: {path.name} has no golden() reference, so the site will lower and run it but report the value "
+            "check as unavailable. Add one if the correct result is known -- see reference/kernel-with-golden.py "
+            "in the lagora skill."
+        )
+    return notes
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("kernel")
+    args = parser.parse_args(argv)
+
+    path = Path(args.kernel)
+    if not path.is_file():
+        print(f"error: kernel not found: {path}", file=sys.stderr)
+        return 1
+    for line in report(path):
+        print(f"[lagora] {line}", file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/dist/scripts/chunk-2EAJVB5D.js

@@ -0,0 +1,100 @@
+// lib/server/encrypted-secrets.ts
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from "node:crypto";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+var SECRET_NAMES = ["githubToken", "sdkCliToken", "announcementToken"];
+var SettingsEncryptionKeyMissingError = class extends Error {
+  constructor() {
+    super("AGORA_SETTINGS_ENCRYPTION_KEY is required before server secrets can be saved");
+    this.name = "SettingsEncryptionKeyMissingError";
+  }
+};
+async function readSecret(name) {
+  const value = (await readSecretFile())[name];
+  return value ? decryptText(value) : void 0;
+}
+async function readGithubToken() {
+  return await readSecret("githubToken");
+}
+async function readSecretFile() {
+  try {
+    const raw = await readFile(secretPath(), "utf8");
+    return parseSecretFile(JSON.parse(raw));
+  } catch (error) {
+    if (error instanceof Error) return {};
+    throw error;
+  }
+}
+function decryptText(value) {
+  const decipher = createDecipheriv("aes-256-gcm", encryptionKey(), Buffer.from(value.iv, "base64"));
+  decipher.setAuthTag(Buffer.from(value.tag, "base64"));
+  return Buffer.concat([
+    decipher.update(Buffer.from(value.ciphertext, "base64")),
+    decipher.final()
+  ]).toString("utf8");
+}
+function encryptionKey() {
+  const configured = process.env.AGORA_SETTINGS_ENCRYPTION_KEY?.trim();
+  if (!configured) throw new SettingsEncryptionKeyMissingError();
+  return createHash("sha256").update(configured).digest();
+}
+function parseSecretFile(value) {
+  if (!isRecord(value)) return {};
+  return Object.fromEntries(
+    SECRET_NAMES.flatMap((name) => {
+      const parsed = parseEncryptedValue(value[name]);
+      return parsed ? [[name, parsed]] : [];
+    })
+  );
+}
+function parseEncryptedValue(value) {
+  if (!isRecord(value)) return void 0;
+  if (value.algorithm !== "aes-256-gcm") return void 0;
+  if (typeof value.iv !== "string") return void 0;
+  if (typeof value.tag !== "string") return void 0;
+  if (typeof value.ciphertext !== "string") return void 0;
+  if (typeof value.updatedAt !== "string") return void 0;
+  return {
+    algorithm: "aes-256-gcm",
+    iv: value.iv,
+    tag: value.tag,
+    ciphertext: value.ciphertext,
+    updatedAt: value.updatedAt
+  };
+}
+function settingsRoot() {
+  return process.env.AGORA_SETTINGS_DIR ? path.resolve(process.env.AGORA_SETTINGS_DIR) : path.join(
+    /*turbopackIgnore: true*/
+    process.cwd(),
+    ".local-data",
+    "settings"
+  );
+}
+function secretPath() {
+  return path.join(settingsRoot(), "secrets.json");
+}
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+// lib/server/git-auth.ts
+async function configuredGithubToken() {
+  return await readGithubToken() ?? process.env.AGORA_GITHUB_TOKEN ?? process.env.GITHUB_TOKEN;
+}
+function gitEnv(token) {
+  if (!token) return process.env;
+  const encoded = Buffer.from(`x-access-token:${token}`).toString("base64");
+  return {
+    ...process.env,
+    GIT_CONFIG_COUNT: "2",
+    GIT_CONFIG_KEY_0: "http.https://github.com/.extraheader",
+    GIT_CONFIG_VALUE_0: `AUTHORIZATION: basic ${encoded}`,
+    GIT_CONFIG_KEY_1: "url.https://github.com/.insteadOf",
+    GIT_CONFIG_VALUE_1: "git@github.com:"
+  };
+}
+
+export {
+  configuredGithubToken,
+  gitEnv
+};

package/dist/scripts/chunk-2KTLCUFI.js

@@ -0,0 +1,29 @@
+// lib/server/sdk-package-index.ts
+function sdkPackageIndex(env = process.env) {
+  const url = env.AGORA_SDK_INDEX_URL?.trim();
+  if (!url) return void 0;
+  return { url, host: env.AGORA_SDK_INDEX_HOST?.trim() || hostFromUrl(url) };
+}
+function sdkPackageIndexEnv(env = process.env, pin) {
+  const index = sdkPackageIndex(env);
+  const versions = typeof pin === "string" ? { legatoVersion: pin } : pin ?? {};
+  return [
+    { name: "AGORA_SDK_INDEX_URL", value: index?.url ?? "" },
+    { name: "AGORA_SDK_INDEX_HOST", value: index?.host ?? "" },
+    // Empty means "resolve the newest in the job" for both lines.
+    { name: "AGORA_LEGATO_PACKAGE_VERSION", value: versions.legatoVersion?.trim() ?? "" },
+    { name: "AGORA_SDK_PACKAGE_VERSION", value: versions.sdkVersion?.trim() ?? "" }
+  ];
+}
+function hostFromUrl(url) {
+  try {
+    return new URL(url).host || void 0;
+  } catch {
+    return void 0;
+  }
+}
+
+export {
+  sdkPackageIndex,
+  sdkPackageIndexEnv
+};

package/dist/scripts/chunk-AZ3EEBVD.js

@@ -0,0 +1,137 @@
+import {
+  internalAppUrl
+} from "./chunk-TJZVQYBL.js";
+
+// scripts/cli-config.ts
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+// scripts/api-session.ts
+var defaultApiUrl = internalAppUrl;
+function apiSession(apiUrl, credentials = {}) {
+  return {
+    apiUrl: baseApiUrl(apiUrl),
+    cookie: credentials.cookie?.trim() || void 0,
+    token: credentials.token?.trim() || void 0
+  };
+}
+async function readJsonFromApi(endpoint, session) {
+  const response = await fetch(endpoint, {
+    headers: requestHeaders(session)
+  });
+  if (!response.ok) {
+    const body = await response.text();
+    throw new Error(`API request failed: HTTP ${response.status} ${body.slice(0, 240)}`);
+  }
+  return response.json();
+}
+async function writeJsonToApi(endpoint, method, body, session) {
+  const response = await fetch(endpoint, {
+    method,
+    headers: requestHeaders(session, { "Content-Type": "application/json" }),
+    body: JSON.stringify(body)
+  });
+  if (!response.ok) {
+    const responseBody = await response.text();
+    throw new Error(`API request failed: HTTP ${response.status} ${responseBody.slice(0, 240)}`);
+  }
+  return response.json();
+}
+function baseApiUrl(apiUrl) {
+  const url = new URL(apiUrl.trim());
+  if (url.username || url.password || url.search || url.hash) {
+    throw new Error("Lagora API URL must not contain credentials, query parameters, or fragments");
+  }
+  const loopback = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]";
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && loopback)) {
+    throw new Error("Lagora API URL must use HTTPS except on loopback");
+  }
+  url.pathname = url.pathname.replace(/\/+$/, "");
+  return url.toString().replace(/\/+$/, "");
+}
+function requestHeaders(session, headers) {
+  return {
+    ...headers,
+    ...session?.cookie ? { Cookie: session.cookie } : {},
+    ...session?.token ? { Authorization: `Bearer ${session.token}` } : {}
+  };
+}
+
+// scripts/cli-config.ts
+var LagoraCliConfigStore = class {
+  constructor(configPath = defaultConfigPath()) {
+    this.path = configPath;
+  }
+  async read() {
+    try {
+      const raw = await readFile(this.path, "utf8");
+      const parsed = JSON.parse(raw);
+      return isConfig(parsed) ? parsed : {};
+    } catch (error) {
+      if (isMissingFileError(error)) return {};
+      if (error instanceof SyntaxError) return {};
+      throw error;
+    }
+  }
+  async write(config) {
+    await mkdir(path.dirname(this.path), { recursive: true });
+    await writeFile(this.path, `${JSON.stringify(config, null, 2)}
+`, { mode: 384 });
+  }
+  async clear() {
+    await rm(this.path, { force: true });
+  }
+  async author(explicitAuthor) {
+    const trimmed = explicitAuthor?.trim();
+    if (trimmed) return trimmed;
+    const config = await this.read();
+    return config.name?.trim() || "Language Developer";
+  }
+  /** Resolves in order: --api-url, LAGORA_API_URL, the saved login, the default. */
+  async apiSession(explicitApiUrl) {
+    const config = await this.read();
+    const explicit = normalizedApiUrl(explicitApiUrl ?? process.env.LAGORA_API_URL);
+    const configured = normalizedApiUrl(config.apiUrl);
+    if (explicit && configured && (config.nativeToken?.trim() || config.sessionCookie?.trim()) && explicit !== configured) {
+      throw new Error(`Saved CLI login belongs to ${configured}; run \`lagora login --api-url ${explicit}\` first`);
+    }
+    const apiUrl = explicit || configured || defaultApiUrl;
+    return {
+      apiUrl,
+      cookie: config.sessionCookie?.trim() || void 0,
+      token: config.nativeToken?.trim() || void 0
+    };
+  }
+};
+function normalizedApiUrl(value) {
+  return value?.trim() ? baseApiUrl(value) : void 0;
+}
+function defaultConfigPath() {
+  const configured = process.env.LAGORA_CONFIG?.trim();
+  if (configured) return path.resolve(configured);
+  const configHome = process.env.XDG_CONFIG_HOME?.trim() || path.join(os.homedir(), ".config");
+  return path.join(configHome, "lagora", "config.json");
+}
+function isConfig(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const name = Reflect.get(value, "name");
+  const passcode = Reflect.get(value, "passcode");
+  const apiUrl = Reflect.get(value, "apiUrl");
+  const sessionCookie = Reflect.get(value, "sessionCookie");
+  const nativeToken = Reflect.get(value, "nativeToken");
+  return (name === void 0 || typeof name === "string") && (passcode === void 0 || typeof passcode === "string") && (apiUrl === void 0 || typeof apiUrl === "string") && (sessionCookie === void 0 || typeof sessionCookie === "string") && (nativeToken === void 0 || typeof nativeToken === "string");
+}
+function isMissingFileError(error) {
+  return error instanceof Error && "code" in error && Reflect.get(error, "code") === "ENOENT";
+}
+
+export {
+  defaultApiUrl,
+  apiSession,
+  readJsonFromApi,
+  writeJsonToApi,
+  baseApiUrl,
+  requestHeaders,
+  LagoraCliConfigStore
+};