shadok-ai 0.2.45 → 0.2.47

package/README.md

@@ -15,9 +15,10 @@ npx shadok-ai
 Then open **http://localhost:3789**.
 
 **Prerequisites:** Node ≥ 20 and the [`claude`](https://claude.com/claude-code)
-CLI installed and signed in on the machine (shadok-ai drives your existing
-Claude Code, on your subscription). `tmux` is optional but recommended — with
-it, agents survive the server restarting.
+CLI installed (shadok-ai drives your existing Claude Code, on your
+subscription). It does **not** need to be signed in beforehand — if it isn't,
+the cockpit offers the sign-in itself (see below). `tmux` is optional but
+recommended — with it, agents survive the server restarting.
 
 On the first run it asks once for an optional **Telegram bot token** (press
 Enter to skip; you can add it later from the web UI).
@@ -74,6 +75,12 @@ Enter to skip; you can add it later from the web UI).
   the chat can't express. With tmux there is also an **experimental real
   terminal** (xterm.js over the pane's byte stream) when a snapshot isn't enough.
 - **Diff panel** — what an agent actually changed, against its base.
+- **Phone layout** — the cockpit is a fixed chassis that never pans sideways,
+  sized on the *visual* viewport so the composer stays clear of the browser's
+  own bar and, when the keyboard opens, sits right above it (the instrument bar
+  folds away while you type). Fields are 16px, which is what stops Safari from
+  zooming in on focus. The agents column is replaced by a channel selector in
+  the channel bar.
 - **Tweak Shadok-AI** — a card pinned at the bottom of the agents column. One
   click clones shadok-ai's own source into `~/.shadok-ai/self/shadok-ai` and
   starts an agent on it in its own worktree; that agent delivers its change as a
@@ -156,6 +163,48 @@ location / {
 The client picks `wss://` on its own when the page is HTTPS, so there is nothing
 to configure on that side.
 
+### Signing in to Claude
+
+A fresh machine — most often a fresh container — has two things in its way, and
+shadok handles both so you never need a shell on the host.
+
+**The first-run screens are pre-answered.** A virgin `claude` opens on a theme
+picker, then on a per-directory trust dialog, and an agent started there never
+reaches a prompt: no input box, every prompt fails, the tab reads "failed to
+start". shadok seeds the answers in `~/.claude.json` — at boot for the global
+ones, and before every spawn for the session's directory, because a worktree is
+a brand-new directory and therefore a brand-new trust dialog. The seeding is
+**purely additive**: a value already there is never overwritten, so on a machine
+that has used Claude Code before, nothing is written at all.
+
+**The sign-in is offered in the cockpit.** When the instance isn't signed in, a
+card takes over the page with the OAuth link and a field for the code you get
+back; agents refuse to start until it's done, so you can't accidentally
+manufacture an agent with no credentials. The card exists only while it's
+needed — there is no button that opens it when everything is fine.
+
+**From Telegram**, which is where you usually are when a session signs out
+mid-life:
+
+```
+/login          → replies with the link
+/code <code>    → finishes the sign-in (your message is deleted afterwards)
+```
+
+Both are restricted to the bound board group or the owner's DM, like `/secret` —
+an OAuth code grants access to the account. The sign-in is instance-global, so
+the link is the same on both sides and a code pasted in Telegram also closes the
+card open in a browser. When a spawn is refused for lack of credentials, shadok
+posts **one** message to the board group; it won't repeat until the state flips
+back.
+
+**In Docker**, this replaces the old recreate ritual. `/root/.claude.json` is
+not on a volume, so `docker rm` + recreate used to lose the onboarding state and
+the respawned agents landed on the first-run screen — which meant restoring the
+file *before* starting the container (`docker create` → `docker cp` →
+`docker start`). That ordering is no longer necessary: shadok writes the file
+itself, before any session spawns.
+
 ### SSH identity in Docker
 
 When shadok-ai runs **in a container** it gives itself an SSH key on first boot
@@ -364,14 +413,16 @@ client, or immediately on an explicit `stop` (which ends it for everyone).
 | `{type:"auto-retry"}` / `-cancelled` / `-gave-up` | transient API error being retried |
 | `{type:"version", …}` / `{type:"server-reload", version}` | update available / server updated, reload |
 | `{type:"term-data", data}` | **experimental** — raw pane output (base64) for a client-side terminal emulator |
-| `{type:"gone"}` / `{type:"error", message, code?}` / `{type:"exited", code}` / `{type:"stopped"}` | session lost, errors, termination. `error.code` is `"busy"` for a prompt refused mid-turn, so a machine client needn't match on the message text |
+| `{type:"gone"}` / `{type:"error", message, code?}` / `{type:"exited", code}` / `{type:"stopped"}` | session lost, errors, termination. `error.code` is `"busy"` for a prompt refused mid-turn and `"logged-out"` for a spawn refused because the instance isn't signed in — so a machine client needn't match on the message text |
 
 HTTP endpoints (same auth): `/usage`, `/live`, `/sessions`, `/recover`,
 `/diff`, `/channels` (its GET adds a **derived** `crons` field — never stored),
 `/channel` (DELETE), `/groups`, `/crons`, `/timezone`, `/profiles`, `/secrets`,
 `/telegram`, `/defaults`, `/version`, `/autoupdate`, `/permission-mode`,
 `/tweak/prepare` (POST — clone/refresh shadok-ai's own source, returns the cwd
-to start the tweak agent in).
+to start the tweak agent in), and the sign-in group: `/auth` (GET — `{loggedIn,
+email?, subscriptionType?}`), `/auth/login` (POST — start a flow, returns
+`{url}`; DELETE — cancel it), `/auth/code` (POST `{code}`).
 
 ## Library
 

package/dist/claude-auth.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Claude Code authentication: status, and the interactive login.
+ *
+ * The load-bearing finding behind this module (verified 2026-08-08 against
+ * claude v2.1.226): `claude auth login --claudeai` needs NO PTY. Run with plain
+ * pipes it prints the OAuth URL on stdout and reads the code from stdin. So the
+ * login touches none of the screen heuristics — no `detectDialog`, no
+ * `screenShowsWork`, nothing from the fragile family invariant nº 2 warns
+ * about. It is a spawn, a stdout parser and one write to stdin.
+ *
+ * See docs/superpowers/specs/2026-08-08-claude-onboarding-design.md.
+ */
+export interface AuthStatus {
+    loggedIn: boolean;
+    authMethod?: string;
+    email?: string;
+    subscriptionType?: string;
+}
+/** Pure: `claude auth status --json`. Anything unreadable reads as logged out. */
+export declare function parseAuthStatus(stdout: string): AuthStatus;
+/** Pure: the OAuth URL the CLI printed, or null if it hasn't printed one yet. */
+export declare function parseLoginUrl(chunk: string): string | null;
+/**
+ * Pure: the refusal the CLI printed for the code we submitted, if any.
+ *
+ * There is deliberately no "success" case. The invalid-code wording was
+ * captured from the real CLI; a success wording never was, and a parser that
+ * guessed one would produce a sign-in that silently never completes. Success is
+ * the child exiting cleanly — see `startLogin`.
+ */
+export declare function parseLoginOutcome(chunk: string): "invalid-code" | null;
+export declare function invalidateAuthStatus(): void;
+export declare function authStatus(force?: boolean): Promise<AuthStatus>;
+export declare function loginPending(): boolean;
+export declare function cancelLogin(): void;
+export declare function startLogin(): Promise<{
+    url: string;
+} | {
+    error: string;
+}>;
+export declare function submitLoginCode(code: string): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+}>;

package/dist/claude-auth.js

@@ -0,0 +1,191 @@
+import { execFile, spawn } from "node:child_process";
+/** Pure: `claude auth status --json`. Anything unreadable reads as logged out. */
+export function parseAuthStatus(stdout) {
+    try {
+        const j = JSON.parse(stdout);
+        if (!j || typeof j !== "object" || Array.isArray(j))
+            return { loggedIn: false };
+        if (j.loggedIn !== true)
+            return { loggedIn: false };
+        return {
+            loggedIn: true,
+            ...(typeof j.authMethod === "string" ? { authMethod: j.authMethod } : {}),
+            ...(typeof j.email === "string" ? { email: j.email } : {}),
+            ...(typeof j.subscriptionType === "string" ? { subscriptionType: j.subscriptionType } : {}),
+        };
+    }
+    catch {
+        return { loggedIn: false };
+    }
+}
+/**
+ * Strip ANSI/OSC escape sequences.
+ *
+ * The login output wraps the URL in an OSC 8 hyperlink
+ * (`ESC ] 8 ; ; <url> BEL <visible text> ESC ] 8 ; ; BEL`), so the URL is
+ * physically present TWICE and a naive `visit:\s*(\S+)` captures the escape
+ * plus a fragment of it. Stripping first makes the match trivial.
+ */
+function stripEscapes(s) {
+    return s
+        // OSC 8 open (ESC ] 8 ; ; <url> BEL) and close (ESC ] 8 ; ; BEL).
+        .replace(/\x1b\]8;;[^\x07\x1b]*(?:\x07|\x1b\\)/g, "")
+        // Ordinary CSI colour/cursor sequences.
+        .replace(/\x1b\[[0-9;?]*[A-Za-z]/g, "");
+}
+/** Pure: the OAuth URL the CLI printed, or null if it hasn't printed one yet. */
+export function parseLoginUrl(chunk) {
+    const m = stripEscapes(chunk).match(/visit:\s*(https:\/\/\S+)/);
+    return m ? m[1] : null;
+}
+/**
+ * Pure: the refusal the CLI printed for the code we submitted, if any.
+ *
+ * There is deliberately no "success" case. The invalid-code wording was
+ * captured from the real CLI; a success wording never was, and a parser that
+ * guessed one would produce a sign-in that silently never completes. Success is
+ * the child exiting cleanly — see `startLogin`.
+ */
+export function parseLoginOutcome(chunk) {
+    return /Invalid code/i.test(stripEscapes(chunk)) ? "invalid-code" : null;
+}
+/** How long a status answer is reused. It is a spawn, and the card polls it. */
+const STATUS_TTL_MS = 30_000;
+/** The OAuth URL expires anyway; a child holding stdin open forever is worse. */
+const FLOW_IDLE_MS = 10 * 60_000;
+let cached = null;
+export function invalidateAuthStatus() {
+    cached = null;
+}
+export async function authStatus(force = false) {
+    if (!force && cached && Date.now() - cached.at < STATUS_TTL_MS)
+        return cached.status;
+    const status = await new Promise((resolve) => {
+        execFile("claude", ["auth", "status", "--json"], { timeout: 15_000 }, (_err, stdout) => resolve(parseAuthStatus(stdout ?? "")));
+    });
+    cached = { at: Date.now(), status };
+    return status;
+}
+/**
+ * ONE flow at a time for the whole instance: the credentials are machine-global,
+ * so a second concurrent login would race the first for the same keychain
+ * entry. The upside is free — the web card and Telegram share the same URL, and
+ * a code pasted from either finishes the other's flow.
+ */
+let flow = null;
+export function loginPending() {
+    return flow !== null && !flow.ended;
+}
+export function cancelLogin() {
+    if (!flow)
+        return;
+    clearTimeout(flow.timer);
+    flow.child.kill();
+    flow = null;
+}
+export async function startLogin() {
+    // Reuse a flow that already printed its URL instead of replacing it. Each
+    // flow carries its own PKCE challenge, so restarting would silently kill the
+    // link the user is already looking at — which a plain page reload, or a
+    // second tab, would otherwise do.
+    if (flow && !flow.ended && flow.url)
+        return { url: flow.url };
+    cancelLogin();
+    const child = spawn("claude", ["auth", "login", "--claudeai"], {
+        // BROWSER is neutralised: on a desktop host the CLI would otherwise open a
+        // tab on the SERVER's machine, which is not where the user is.
+        env: { ...process.env, BROWSER: "/usr/bin/true" },
+        stdio: ["pipe", "pipe", "pipe"],
+    });
+    const f = {
+        child,
+        url: null,
+        out: "",
+        pending: null,
+        ended: false,
+        timer: setTimeout(() => cancelLogin(), FLOW_IDLE_MS),
+    };
+    flow = f;
+    const settle = (v) => {
+        const done = f.pending;
+        f.pending = null;
+        done?.(v);
+    };
+    const onData = (d) => {
+        f.out += d.toString();
+        if (parseLoginOutcome(f.out) === "invalid-code")
+            settle("invalid-code");
+    };
+    child.stdout.on("data", onData);
+    child.stderr.on("data", onData);
+    // SUCCESS IS AN EXIT, NOT A STRING. The "Invalid code…" wording was captured
+    // from the real CLI; the success wording never was, and inventing one would
+    // produce a sign-in that silently never completes. A clean exit after a code
+    // was submitted is the signal we can actually prove.
+    child.on("exit", (code) => {
+        f.ended = true;
+        settle(code === 0 ? "success" : "ended");
+    });
+    // A `claude` that is not on PATH must not leave the caller hanging until the
+    // 30s deadline with no explanation.
+    child.on("error", () => {
+        f.ended = true;
+        settle("ended");
+    });
+    return new Promise((resolve) => {
+        const deadline = setTimeout(() => {
+            cancelLogin();
+            resolve({ error: "claude auth login printed no URL within 30s" });
+        }, 30_000);
+        const poll = setInterval(() => {
+            const url = parseLoginUrl(f.out);
+            if (url) {
+                f.url = url;
+                clearInterval(poll);
+                clearTimeout(deadline);
+                resolve({ url });
+            }
+            else if (flow !== f || f.ended) {
+                clearInterval(poll);
+                clearTimeout(deadline);
+                resolve({ error: "the login process ended before printing a URL" });
+            }
+        }, 100);
+    });
+}
+export async function submitLoginCode(code) {
+    const f = flow;
+    if (!f || f.ended)
+        return { ok: false, error: "no sign-in is in progress — start one first" };
+    const trimmed = code.trim();
+    if (!trimmed)
+        return { ok: false, error: "empty code" };
+    // The user is clearly still here: push the idle deadline back.
+    clearTimeout(f.timer);
+    f.timer = setTimeout(() => cancelLogin(), FLOW_IDLE_MS);
+    // Forget what came before, so a stale "Invalid code" from a previous attempt
+    // is never mistaken for the verdict on THIS one.
+    f.out = "";
+    const verdict = await new Promise((resolve) => {
+        const t = setTimeout(() => {
+            f.pending = null;
+            resolve("timeout");
+        }, 30_000);
+        f.pending = (r) => {
+            clearTimeout(t);
+            resolve(r);
+        };
+        f.child.stdin.write(trimmed + "\n");
+    });
+    if (verdict === "success") {
+        cancelLogin();
+        invalidateAuthStatus();
+        return { ok: true };
+    }
+    if (verdict === "invalid-code")
+        return { ok: false, error: "Invalid code. Please make sure the full code was copied." };
+    if (verdict === "ended")
+        return { ok: false, error: "the sign-in was refused — start a new one and try again" };
+    return { ok: false, error: "the CLI did not answer within 30s" };
+}
+//# sourceMappingURL=claude-auth.js.map

package/dist/claude-auth.js.map

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

package/dist/claude-home.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Seeding of Claude Code's first-run state.
+ *
+ * A virgin `claude` opens on its theme picker, then on a per-directory trust
+ * dialog, and never reaches a prompt: no input box, every submitted prompt
+ * fails, the tab reads "failed to start". That is how three zombie agents were
+ * once produced on a production container and found a day later.
+ *
+ * So shadok writes the handful of keys that answer those screens. The module is
+ * PURELY ADDITIVE — it only ever adds keys that are absent — which is what
+ * makes it safe to run unconditionally. Unlike `src/ssh.ts`, which had to
+ * restrict itself to containers (invariant 21), no Docker gate is needed here:
+ * on a machine that has used Claude Code before, the plan is empty and nothing
+ * is written at all.
+ *
+ * See docs/superpowers/specs/2026-08-08-claude-onboarding-design.md.
+ */
+export interface ClaudeHome {
+    hasCompletedOnboarding?: boolean;
+    lastOnboardingVersion?: string;
+    theme?: string;
+    projects?: Record<string, Record<string, unknown>>;
+    [k: string]: unknown;
+}
+/** Pure: the semver out of `claude --version` ("2.1.226 (Claude Code)"). */
+export declare function parseClaudeVersion(stdout: string): string | null;
+/**
+ * Pure: the object to write, or null when nothing is missing.
+ *
+ * Returning null (rather than an identical object) is what lets the writer skip
+ * the write entirely — a multi-megabyte file is not rewritten for nothing.
+ */
+export declare function seedPlan(existing: ClaudeHome, opts: {
+    version: string;
+    cwd?: string;
+}): ClaudeHome | null;
+export interface ClaudeSettings {
+    tui?: string;
+    [k: string]: unknown;
+}
+/**
+ * Pure: `~/.claude/settings.json` after adding the keys that suppress a
+ * first-run *upsell*, or null when nothing is missing.
+ *
+ * The fullscreen upsell ("Flicker-free output · Mouse support · Selected text
+ * auto-copies") is not gated by the onboarding flags — it appears AFTER the
+ * sign-in, which is why no probe caught it before a real account reached the
+ * screen. It is counted by `fullscreenUpsellSeenCount`, but seeding a counter
+ * means guessing its threshold; recording an explicit `tui` preference is the
+ * durable answer, because a choice already made cannot be upsold. Evidence: a
+ * developer machine with `tui` set has never accumulated that counter in 792
+ * startups.
+ */
+export declare function settingsPlan(existing: ClaudeSettings): ClaudeSettings | null;
+/** Called once at boot: the globals, plus the settings that kill the upsell. */
+export declare function ensureClaudeHome(): void;
+/**
+ * Called before EVERY spawn, for that session's directory.
+ *
+ * This cannot be a boot-time-only concern: a worktree is a brand-new directory
+ * for every agent, therefore a brand-new trust dialog every time.
+ */
+export declare function ensureProjectTrusted(cwd: string): void;

package/dist/claude-home.js

@@ -0,0 +1,169 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+/** The per-project keys that answer the trust dialog. */
+const PROJECT_KEYS = ["hasTrustDialogAccepted", "hasCompletedProjectOnboarding"];
+/** Pure: the semver out of `claude --version` ("2.1.226 (Claude Code)"). */
+export function parseClaudeVersion(stdout) {
+    const m = stdout.match(/^\s*(\d+\.\d+\.\d+[^\s(]*)/);
+    return m ? m[1] : null;
+}
+/**
+ * Pure: the object to write, or null when nothing is missing.
+ *
+ * Returning null (rather than an identical object) is what lets the writer skip
+ * the write entirely — a multi-megabyte file is not rewritten for nothing.
+ */
+export function seedPlan(existing, opts) {
+    const out = { ...existing };
+    let changed = false;
+    const add = (key, value) => {
+        if (!(key in out)) {
+            out[key] = value;
+            changed = true;
+        }
+    };
+    // These two answer the theme picker. `theme` is deliberately NOT written:
+    // verified 2026-08-08 that the CLI DELETES an unknown top-level `theme` key
+    // on its next write, and that the picker is already skipped without it — so
+    // seeding one would be cargo cult that also implies we control the theme.
+    add("hasCompletedOnboarding", true);
+    add("lastOnboardingVersion", opts.version);
+    if (opts.cwd) {
+        const projects = { ...(existing.projects ?? {}) };
+        const entry = { ...(projects[opts.cwd] ?? {}) };
+        let entryChanged = false;
+        for (const key of PROJECT_KEYS) {
+            if (!(key in entry)) {
+                entry[key] = true;
+                entryChanged = true;
+            }
+        }
+        if (entryChanged) {
+            projects[opts.cwd] = entry;
+            out.projects = projects;
+            changed = true;
+        }
+    }
+    return changed ? out : null;
+}
+/**
+ * Pure: `~/.claude/settings.json` after adding the keys that suppress a
+ * first-run *upsell*, or null when nothing is missing.
+ *
+ * The fullscreen upsell ("Flicker-free output · Mouse support · Selected text
+ * auto-copies") is not gated by the onboarding flags — it appears AFTER the
+ * sign-in, which is why no probe caught it before a real account reached the
+ * screen. It is counted by `fullscreenUpsellSeenCount`, but seeding a counter
+ * means guessing its threshold; recording an explicit `tui` preference is the
+ * durable answer, because a choice already made cannot be upsold. Evidence: a
+ * developer machine with `tui` set has never accumulated that counter in 792
+ * startups.
+ */
+export function settingsPlan(existing) {
+    if ("tui" in existing)
+        return null; // the user's own choice, never overridden
+    // "fullscreen" is the value both working installations run — shadok reads
+    // content from the transcript, not the screen, so the TUI's rendering mode
+    // does not affect it either way.
+    return { ...existing, tui: "fullscreen" };
+}
+const homeFile = () => path.join(os.homedir(), ".claude.json");
+const settingsFile = () => path.join(os.homedir(), ".claude", "settings.json");
+/** The claude CLI's version, or a conservative fallback. */
+function claudeVersion() {
+    try {
+        return (parseClaudeVersion(execFileSync("claude", ["--version"], { encoding: "utf8" })) ?? "0.0.0");
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+/**
+ * Read the file, or null when it exists but does not parse.
+ *
+ * Null means "leave it alone". We never "repair" an unparseable ~/.claude.json
+ * by overwriting it: the file carries the whole per-project history, and
+ * destroying it costs incomparably more than the screen this module avoids.
+ */
+function readHome(file) {
+    if (!fs.existsSync(file))
+        return {};
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Atomic write: a temp file in the SAME directory, then rename. An interrupted
+ * write must never leave a truncated ~/.claude.json behind.
+ */
+function writeHome(file, data) {
+    const tmp = `${file}.shadok-${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(data, null, 2), { mode: 0o600 });
+    fs.renameSync(tmp, file);
+}
+/** Apply a plan for `cwd` (or the globals only when cwd is undefined). */
+function seed(cwd) {
+    try {
+        const file = homeFile();
+        const existing = readHome(file);
+        if (existing === null)
+            return; // unparseable → hands off
+        const plan = seedPlan(existing, { version: claudeVersion(), cwd });
+        if (plan)
+            writeHome(file, plan);
+    }
+    catch {
+        // A failed seed must never take down the boot path or a spawn — same rule
+        // as ensureSshIdentity.
+    }
+}
+/** Called once at boot: the globals, plus the settings that kill the upsell. */
+export function ensureClaudeHome() {
+    seed();
+    seedSettings();
+}
+/** Apply `settingsPlan` to `~/.claude/settings.json`. Same rules as `seed`. */
+function seedSettings() {
+    try {
+        const file = settingsFile();
+        let existing = {};
+        if (fs.existsSync(file)) {
+            try {
+                const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+                existing =
+                    parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+            }
+            catch {
+                existing = null; // hand-edited into invalid JSON → never clobber it
+            }
+        }
+        if (existing === null)
+            return;
+        const plan = settingsPlan(existing);
+        if (!plan)
+            return;
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        const tmp = `${file}.shadok-${process.pid}.tmp`;
+        fs.writeFileSync(tmp, JSON.stringify(plan, null, 2));
+        fs.renameSync(tmp, file);
+    }
+    catch {
+        // Never take down the boot path.
+    }
+}
+/**
+ * Called before EVERY spawn, for that session's directory.
+ *
+ * This cannot be a boot-time-only concern: a worktree is a brand-new directory
+ * for every agent, therefore a brand-new trust dialog every time.
+ */
+export function ensureProjectTrusted(cwd) {
+    seed(cwd);
+}
+//# sourceMappingURL=claude-home.js.map

package/dist/claude-home.js.map

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