@nanonets/graft 0.18.0 → 0.19.0

package/dist/brain/watch.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Watching a brain being built, from the terminal.
+ *
+ * `graft brain push` used to end at "it is being mined into rules now — a few
+ * minutes. Watch it finish in your browser." and hand the prompt straight back.
+ * That sentence is the last thing this process ever says about the work, and it
+ * is said BEFORE the part that actually fails: of the repo brains attempted in
+ * production, roughly a third die inside the miner, after the push succeeded.
+ * The terminal has already returned by then, so on this side the failure does
+ * not exist at all — and on a CI runner or over SSH, where nobody is going to
+ * open a browser, it exists nowhere.
+ *
+ * So the push now holds the line and reports the same four stages the browser
+ * shows, off the same row. Ctrl-C detaches without cancelling anything, because
+ * the work is server-side and killing a watcher must never look like killing
+ * the build.
+ *
+ * What it holds the line UNTIL changed with slicing. The history is now mined in
+ * several calls rather than one, and the first of them returns in about ten
+ * seconds; filing all of the rules into the graph takes minutes more. Mining is
+ * where the failures are — the thing this watcher exists to report — and filing
+ * is long, dull and reliable, so the line is held through the first and handed
+ * back before the second. Holding a terminal through five minutes of successful
+ * filing buys nobody anything, and on a CI runner it is five minutes of a job
+ * sitting idle.
+ */
+import type { BrainLink } from "./link.js";
+/** The stages, in the order they happen. The wording matches Trail's build
+ *  screen deliberately: two products describing one process differently is how
+ *  a person ends up unsure whether they are looking at the same thing. */
+export declare const STAGES: readonly [{
+    readonly id: "reach";
+    readonly label: "reaching the repository";
+}, {
+    readonly id: "read";
+    readonly label: "reading its history";
+}, {
+    readonly id: "mine";
+    readonly label: "mining the rules";
+}, {
+    readonly id: "file";
+    readonly label: "filing them into the brain";
+}];
+export type StageId = (typeof STAGES)[number]["id"];
+export type StageState = "waiting" | "doing" | "done" | "failed";
+export interface Stage {
+    id: StageId;
+    label: string;
+    state: StageState;
+    /** A count worth printing beside a stage that has produced one. */
+    detail?: string;
+}
+/** The repo row, as the public endpoint returns it. Only the fields the stages
+ *  read, so a field added server-side cannot quietly change what is printed. */
+export interface RepoState {
+    status: string;
+    errorMessage?: string;
+    ruleCount: number;
+    commitCount: number;
+    threadCount: number;
+    /** Rules in the graph right now, from the job still running. The row's own
+     *  `ruleCount` is only written when that job finishes, so mid-build it is
+     *  zero however many rules are already there.
+     *
+     *  Optional because an older Trail does not send it, and a graft pointed at
+     *  one must fall back to waiting for the finished row rather than reading a
+     *  missing field as "no rules". */
+    filedSoFar?: number;
+    /** Rules the miner has handed over so far. Grows with every slice of the
+     *  history that comes back, so it is a floor and never a total. */
+    foundSoFar?: number;
+}
+export interface BuildView {
+    stages: Stage[];
+    /**
+     * True once rules are in the graph — which is when this watcher has nothing
+     * left to report, not when the job ends. The rest of the slices keep mining
+     * and filing after the prompt comes back.
+     */
+    ready: boolean;
+    done: boolean;
+    /** The server's own words, when it failed. */
+    error: string | null;
+}
+/**
+ * Which stage the work is in.
+ *
+ * The rule that matters is where a failure lands. A row that never left
+ * `pending` failed at the access check; one that read 412 commits and then died
+ * failed in the miner. Reporting both as "could not reach it" would send someone
+ * to fix repository access for a problem that has nothing to do with it.
+ */
+export declare function stagesFrom(repo: RepoState | null): BuildView;
+/**
+ * Read the repo row this brain is building.
+ *
+ * The same endpoint `fetchExpectedRepo` uses, read for its counts rather than
+ * its slug. Null on any failure, so a watcher that cannot reach the API prints
+ * nothing new rather than inventing a failure the build did not have.
+ */
+export declare function fetchRepoState(link: BrainLink, fetchImpl?: typeof fetch): Promise<RepoState | null>;
+/** One printable line per stage that has moved since it was last printed. */
+export declare function linesFor(view: BuildView, already: Set<string>): string[];
+export interface WatchOptions {
+    /** How long to hold before giving up on a build that is still running. */
+    timeoutMs?: number;
+    pollMs?: number;
+    fetchImpl?: typeof fetch;
+    /** Where the lines go. Injected so the tests do not need a console. */
+    write?: (line: string) => void;
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * How the watch ended.
+ *
+ * `building` is the ordinary success: rules are in the brain and the rest of the
+ * history is still being read behind the prompt. `completed` is the same thing
+ * after the whole job has finished, which only happens for a repository small
+ * enough to be mined in one slice.
+ */
+export type WatchOutcome = "completed" | "building" | "failed" | "timed_out" | "unreachable";
+/**
+ * Hold until the brain has rules, printing each stage as it settles.
+ *
+ * Returns on the first rules rather than on the finished job: mining is what
+ * fails and it is done by then, and filing the rest is minutes of work nobody
+ * needs to watch. The caller prints where to see the rest.
+ *
+ * Fifteen minutes by default. That is far more than the mining now takes, and it
+ * stays generous on purpose: a watcher that gives up before the build does would
+ * report a healthy build as a timeout, which is the exact confusion this is
+ * meant to remove. Giving up says so and says the work continues, because it
+ * does.
+ */
+export declare function watchBuild(link: BrainLink, opts?: WatchOptions): Promise<WatchOutcome>;
+//# sourceMappingURL=watch.d.ts.map

package/dist/brain/watch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch.d.ts","sourceRoot":"","sources":["../../src/brain/watch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAG3C;;0EAE0E;AAC1E,eAAO,MAAM,MAAM;;;;;;;;;;;;EAKT,CAAC;AAEX,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC;AACpD,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEjE,MAAM,WAAW,KAAK;IACpB,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,UAAU,CAAC;IAClB,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;gFACgF;AAChF,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;;uCAMmC;IACnC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;uEACmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB;;;;OAIG;IACH,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;IACd,8CAA8C;IAC9C,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAID;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,GAAG,SAAS,CAsD5D;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE,SAAS,EAAE,SAAS,GAAE,OAAO,KAAa,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CA2BhH;AAED,6EAA6E;AAC7E,wBAAgB,QAAQ,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,CAcxE;AAED,MAAM,WAAW,YAAY;IAC3B,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,uEAAuE;IACvE,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,UAAU,GAAG,QAAQ,GAAG,WAAW,GAAG,aAAa,CAAC;AAE7F;;;;;;;;;;;;GAYG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,GAAE,YAAiB,GAAG,OAAO,CAAC,YAAY,CAAC,CAgChG"}

package/dist/brain/watch.js

@@ -0,0 +1,172 @@
+import { baseUrlFor } from "./link.js";
+/** The stages, in the order they happen. The wording matches Trail's build
+ *  screen deliberately: two products describing one process differently is how
+ *  a person ends up unsure whether they are looking at the same thing. */
+export const STAGES = [
+    { id: "reach", label: "reaching the repository" },
+    { id: "read", label: "reading its history" },
+    { id: "mine", label: "mining the rules" },
+    { id: "file", label: "filing them into the brain" },
+];
+const num = (v) => (typeof v === "number" && v > 0 ? v : 0);
+/**
+ * Which stage the work is in.
+ *
+ * The rule that matters is where a failure lands. A row that never left
+ * `pending` failed at the access check; one that read 412 commits and then died
+ * failed in the miner. Reporting both as "could not reach it" would send someone
+ * to fix repository access for a problem that has nothing to do with it.
+ */
+export function stagesFrom(repo) {
+    const commits = num(repo?.commitCount);
+    const threads = num(repo?.threadCount);
+    const rules = num(repo?.ruleCount);
+    const filedSoFar = num(repo?.filedSoFar);
+    const foundSoFar = num(repo?.foundSoFar);
+    const reached = !!repo && repo.status !== "pending";
+    const readIt = commits > 0 || threads > 0;
+    // Rules that exist, whether the job has finished writing its count or not.
+    const hasRules = filedSoFar > 0 || rules > 0;
+    const filed = rules > 0;
+    const failed = repo?.status === "failed";
+    const failedAt = !failed ? null : !reached || !readIt ? "reach" : !hasRules ? "mine" : "file";
+    const order = STAGES.map((s) => s.id);
+    const state = (id) => {
+        if (failedAt === id)
+            return "failed";
+        if (failedAt && order.indexOf(id) > order.indexOf(failedAt))
+            return "waiting";
+        switch (id) {
+            case "reach":
+                return reached ? "done" : "doing";
+            case "read":
+                return readIt ? "done" : reached ? "doing" : "waiting";
+            case "mine":
+                // Done on the first slice's rules. The remaining slices are still being
+                // mined at this point, behind the prompt this watcher is about to
+                // return — which is the whole change.
+                return hasRules ? "done" : readIt ? "doing" : "waiting";
+            case "file":
+                return filed ? "done" : hasRules ? "doing" : readIt ? "waiting" : "waiting";
+        }
+    };
+    const detail = (id) => {
+        if (id === "read" && (commits || threads)) {
+            return [commits ? `${commits} commits` : null, threads ? `${threads} discussions` : null].filter(Boolean).join(", ");
+        }
+        // "so far" because the count grows with each slice that lands. Printing it
+        // as a total would promise history that has not been read yet.
+        if (id === "mine" && foundSoFar)
+            return `${foundSoFar} rules so far`;
+        if (id === "file" && rules)
+            return `${rules} rules`;
+        if (id === "file" && filedSoFar)
+            return `${filedSoFar} rules so far`;
+        return undefined;
+    };
+    return {
+        stages: STAGES.map((s) => ({ id: s.id, label: s.label, state: state(s.id), detail: detail(s.id) })),
+        ready: hasRules && !failed,
+        done: repo?.status === "completed" && filed,
+        error: failed ? (repo?.errorMessage?.trim() || "the read stopped before it finished") : null,
+    };
+}
+/**
+ * Read the repo row this brain is building.
+ *
+ * The same endpoint `fetchExpectedRepo` uses, read for its counts rather than
+ * its slug. Null on any failure, so a watcher that cannot reach the API prints
+ * nothing new rather than inventing a failure the build did not have.
+ */
+export async function fetchRepoState(link, fetchImpl = fetch) {
+    try {
+        const res = await fetchImpl(`${baseUrlFor(link)}/api/public/brains/${encodeURIComponent(link.brainId)}/repo`, {
+            headers: { authorization: `Bearer ${link.token}`, accept: "application/json" },
+            signal: AbortSignal.timeout(5000),
+        });
+        if (!res.ok)
+            return null;
+        const body = (await res.json());
+        if (!body.repo)
+            return null;
+        return {
+            status: String(body.repo.status ?? ""),
+            errorMessage: body.repo.error_message,
+            ruleCount: num(body.repo.rule_count),
+            commitCount: num(body.repo.commit_count),
+            threadCount: num(body.repo.thread_count),
+            filedSoFar: num(body.build?.filed_so_far),
+            foundSoFar: num(body.build?.found_so_far),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** One printable line per stage that has moved since it was last printed. */
+export function linesFor(view, already) {
+    const out = [];
+    for (const s of view.stages) {
+        // Only settled states are printed. A line per poll for a stage that is
+        // merely still running would bury the four that matter under a hundred
+        // that do not — this is a log, not a redrawn frame.
+        if (s.state !== "done" && s.state !== "failed")
+            continue;
+        const key = `${s.id}:${s.state}`;
+        if (already.has(key))
+            continue;
+        already.add(key);
+        const mark = s.state === "done" ? "✓" : "✗";
+        out.push(`  ${mark} ${s.label}${s.detail ? ` — ${s.detail}` : ""}`);
+    }
+    return out;
+}
+/**
+ * Hold until the brain has rules, printing each stage as it settles.
+ *
+ * Returns on the first rules rather than on the finished job: mining is what
+ * fails and it is done by then, and filing the rest is minutes of work nobody
+ * needs to watch. The caller prints where to see the rest.
+ *
+ * Fifteen minutes by default. That is far more than the mining now takes, and it
+ * stays generous on purpose: a watcher that gives up before the build does would
+ * report a healthy build as a timeout, which is the exact confusion this is
+ * meant to remove. Giving up says so and says the work continues, because it
+ * does.
+ */
+export async function watchBuild(link, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 15 * 60 * 1000;
+    const pollMs = opts.pollMs ?? 4000;
+    const write = opts.write ?? ((l) => console.error(l));
+    const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms).unref?.()));
+    const printed = new Set();
+    const startedAt = Date.now();
+    // A row we could never read at all, as opposed to one that answered once and
+    // then stopped answering: the first is a broken link or a host that is down
+    // and is worth saying, the second is a blip the next poll usually covers.
+    let everRead = false;
+    for (;;) {
+        const repo = await fetchRepoState(link, opts.fetchImpl);
+        if (repo) {
+            everRead = true;
+            const view = stagesFrom(repo);
+            for (const line of linesFor(view, printed))
+                write(line);
+            if (view.error) {
+                write(`✗ ${view.error}`);
+                return "failed";
+            }
+            if (view.done)
+                return "completed";
+            // The ordinary ending now. The job is still filing the rules the miner
+            // has handed over, and still mining the older slices of the history, and
+            // neither is worth a terminal sitting on it.
+            if (view.ready)
+                return "building";
+        }
+        if (Date.now() - startedAt >= timeoutMs)
+            return everRead ? "timed_out" : "unreachable";
+        await sleep(pollMs);
+    }
+}
+//# sourceMappingURL=watch.js.map

package/dist/brain/watch.js.map

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

package/dist/cli.js

@@ -20,7 +20,9 @@ import { parseBrainArg, connectBrain, pullBrain, brainStatus } from "./brain/con
 import { rulesForPointers } from "./brain/attach.js";
 import { clearLink } from "./brain/link.js";
 import { buildLocalDigest, fetchExpectedRepo, pushDigest, repoSlugFromGit, sameRepo } from "./brain/push.js";
-import { readLink } from "./brain/link.js";
+import { readLink, writeLink } from "./brain/link.js";
+import { watchBuild } from "./brain/watch.js";
+import { openBrowser, signupUrl, startHandoff } from "./brain/signup.js";
 import { contextDirFor } from "./context/node-file.js";
 import { loadGraphCached } from "./graph/load.js";
 import { ensureFreshChildren, ensureFreshGraph, refreshNote } from "./graph/refresh.js";
@@ -1079,6 +1081,53 @@ program
 const brain = program
     .command("brain")
     .description("The Trail brain attached to this repo: the rules mined from its own history");
+/**
+ * Get this repo a brain from the terminal, by sending the user through signup
+ * in their browser and catching the handoff on loopback.
+ *
+ * Returns the link, already saved, or null when the user should be left alone —
+ * every failure prints its own reason first, because the caller only needs to
+ * know whether to carry on.
+ */
+async function signUpForBrain(repo, slug) {
+    const handoff = await startHandoff();
+    const url = signupUrl({ repo: slug, port: handoff.port, state: handoff.state });
+    const startedAt = Date.now();
+    // Queued before the link is printed rather than after the outcome, because
+    // the outcome is the one thing a terminal handoff can lose: a user who reads
+    // the URL and walks away kills the process, and only an event already on disk
+    // survives that. This is the denominator; `brain_signup_settled` is not.
+    track("brain_signup_opened", {}, { repo });
+    // Printed before the browser opens, and printed whether or not it opens: on a
+    // remote shell nothing can open, and on a desktop the window sometimes lands
+    // behind the terminal. The URL is the thing that always works.
+    console.error(`· ${slug} has no brain yet. Opening your browser to make one:`);
+    console.error(`  ${url}`);
+    // A non-interactive shell has nobody to click anything, so waiting five
+    // minutes for a browser that will never come is worse than saying so now.
+    if (!process.stderr.isTTY) {
+        console.error("· not a terminal — open that link, then run `graft brain connect <brainId>:<token>` here");
+        // Its own outcome, not a timeout: nothing here could have opened a browser,
+        // so folding the two together would read as people abandoning signup when
+        // it is only a remote shell doing what it has to.
+        track("brain_signup_settled", { outcome: "no_tty", duration_bucket: durationBucket(Date.now() - startedAt) }, { repo });
+        handoff.close();
+        return null;
+    }
+    openBrowser(url);
+    console.error("· waiting for you to finish signing up…");
+    const got = await handoff.wait();
+    if ("error" in got) {
+        console.error(`✗ ${got.error}`);
+        // The category, never the sentence: `got.error` names the repo and the link.
+        track("brain_signup_settled", { outcome: got.reason, duration_bucket: durationBucket(Date.now() - startedAt) }, { repo });
+        return null;
+    }
+    writeLink(repo, got.link);
+    console.error(`✓ brain connected to ${slug}`);
+    track("brain_signup_settled", { outcome: "linked", duration_bucket: durationBucket(Date.now() - startedAt) }, { repo });
+    return got.link;
+}
 brain
     .command("connect")
     .description("Attach a brain to this repo and pull its rules")
@@ -1134,19 +1183,32 @@ brain
     .description("Read THIS repo on your machine and build its brain — no GitHub App, works on private repos")
     .argument("[dir]", "target repo directory", ".")
     .option("--no-approve", "leave the mined rules as drafts for review")
+    .option("--no-watch", "return as soon as the push is sent, without following the build")
     .action(async (dir, opts) => {
     const repo = resolve(dir);
-    const link = readLink(repo);
+    // Resolved before the link, because an unlinked repo now signs up for a
+    // brain and Trail creates that brain FOR a named repository. Without a slug
+    // there is nothing to name it after — and the digest builder would fail on
+    // the same missing remote a moment later regardless.
+    const here = repoSlugFromGit(repo);
+    let link = readLink(repo);
     if (!link) {
-        console.error("· no brain attached — run `graft brain connect <brainId>:<token>` first");
-        process.exitCode = 1;
-        return;
+        if (!here) {
+            console.error("✗ this directory has no GitHub `origin` remote — graft can only push a GitHub repository today");
+            process.exitCode = 1;
+            return;
+        }
+        const signedUp = await signUpForBrain(repo, `${here.owner}/${here.name}`);
+        if (!signedUp) {
+            process.exitCode = 1;
+            return;
+        }
+        link = signedUp;
     }
     // What the website said this brain is for. Checked BEFORE any reading, so
     // standing in the wrong checkout costs a message rather than a brain full
     // of another repository's rules — a mistake that is silent afterwards,
     // because the rules look perfectly plausible, just not about your code.
-    const here = repoSlugFromGit(repo);
     const expected = await fetchExpectedRepo(link);
     if (expected && here && !sameRepo(expected.slug, `${here.owner}/${here.name}`)) {
         console.error(`✗ this brain is for ${expected.slug}, but you are in ${here.owner}/${here.name}`);
@@ -1181,8 +1243,46 @@ brain
     }
     const brainLabel = expected?.brainName ? `“${expected.brainName}”` : link.brainId;
     console.error(`✓ sent ${d.owner}/${d.name} to ${brainLabel}`);
-    console.error("· it is being mined into rules now — a few minutes. Watch it finish in your browser.");
-    console.error("  The rules reach this repo on their own; nothing else to run.");
+    // Held rather than handed back. Everything above this line succeeded even
+    // in the runs that end badly: the push lands, and then the miner fails —
+    // which is where roughly a third of production's repo brains die. Returning
+    // the prompt here is what made that invisible from this side, on CI and
+    // over SSH permanently so. `--no-watch` is for a caller that genuinely
+    // wants fire-and-forget, and it prints the old two lines instead.
+    if (opts.watch === false) {
+        console.error("· it is being mined into rules now — a few minutes. Watch it finish in your browser.");
+        console.error("  The rules reach this repo on their own; nothing else to run.");
+        return;
+    }
+    console.error("· building the brain — Ctrl-C detaches, it keeps going without you");
+    const outcome = await watchBuild(link);
+    if (outcome === "completed") {
+        console.error("✓ the brain is built — its rules reach this repo on their own; nothing else to run");
+        return;
+    }
+    // The ordinary ending for anything but a small repository. The history is
+    // mined in slices, and the prompt comes back on the first of them: mining is
+    // the part that fails and it has now succeeded, and the rest is filing,
+    // which is minutes of reliable work nobody gains by watching. The rules
+    // already in the brain are already being served.
+    if (outcome === "building") {
+        console.error("✓ the brain has its first rules — they reach this repo on their own; nothing else to run");
+        console.error("  The rest of the history is still being read. Watch it fill in your browser.");
+        return;
+    }
+    if (outcome === "failed") {
+        // A non-zero exit, unlike every other ending here: this is the one case
+        // where the work did not produce a brain, and a CI step that ran the push
+        // should hear about it the way it hears about any other failure.
+        console.error("  Nothing was lost — the brain is still there. Run `graft brain push` again to retry the read.");
+        process.exitCode = 1;
+        return;
+    }
+    if (outcome === "unreachable") {
+        console.error("· could not reach Trail to follow the build — it is still running. Watch it finish in your browser.");
+        return;
+    }
+    console.error("· still building after 15 minutes — it has not failed, it is just long. Watch it finish in your browser.");
 });
 brain
     .command("status")