paperlint 2.0.0

package/dist/link-skills.js

@@ -0,0 +1,199 @@
+/**
+ * Makes the shipped skills visible to Claude Code: one RELATIVE symlink per skill,
+ * `<project>/.claude/skills/<name> -> <the installed package>/skills/<name>`.
+ *
+ * 🔴 WHY THIS EXISTS. The README used to say the skills "sit in `node_modules/…/skills/` and Claude
+ * Code reads them from there". It does not: Claude Code discovers project skills in
+ * `.claude/skills/<name>/SKILL.md` (plus user and plugin skills), never inside `node_modules`. So a
+ * consumer who followed the install to the letter had no `/paper-pipeline` at all (Codex review on
+ * #45). A plugin could not carry them either — it gets no `node_modules`, and 23 of 24 skills run
+ * scripts (`docs/install.md`, "Why it is shaped this way"). The one consumer where the skills
+ * DID work had made these links by hand; this module makes the same links, so the layout is the
+ * proven one rather than a new one.
+ *
+ * The links are what make the project-root-relative script paths inside the skills
+ * (`.claude/skills/paper-pipeline/scripts/x.mjs`) resolve in a consumer at all.
+ *
+ * ── THE THREE RULES ─────────────────────────────────────────────────────────
+ *   what to link      every subdirectory holding a SKILL.md under the package's
+ *                     `SHIPPED_SKILLS_DIR` (consumer.mjs). No list, no count.
+ *   where it points   the package as it RESOLVES BY NAME from the project, spelled through the
+ *                     project's own `node_modules/paperlint` when that path leads to
+ *                     the same place. Under pnpm the resolved path is the version-stamped
+ *                     `.pnpm/…` store directory; a link spelled that way dangles after the next
+ *                     upgrade, a link through `node_modules/paperlint` does not.
+ *   what it touches   only what is missing. An entry that already leads to the shipped skill is
+ *                     left alone; ANY other entry of the same name — a directory, a file, a link
+ *                     elsewhere, a dangling link — is someone else's, and is reported, not replaced.
+ */
+/* eslint-disable boundaries/dependencies -- legacy I/O, moves behind a port in #76 */
+import { existsSync, lstatSync, mkdirSync, readlinkSync, realpathSync, symlinkSync, unlinkSync, } from "node:fs";
+/* eslint-enable boundaries/dependencies */
+import { createRequire } from "node:module";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+import { installedSkills, LEGACY_PACKAGE_NAME, PACKAGE_NAME, SHIPPED_SKILLS_DIR, } from "../skills/paper-pipeline/scripts/consumer.mjs";
+export { PACKAGE_NAME };
+/** Where Claude Code looks for project skills, relative to the project root. */
+export const SKILLS_HOME = join(".claude", "skills");
+/**
+ * The installed package, asked of Node from the PROJECT, not from wherever this code runs. A copy
+ * run out of the npx cache is not the project's install, and a link into a cache is a link that
+ * disappears with it — so "does not resolve from here" is an answer, not something to paper over.
+ *
+ * @returns `dir` — the real directory; `spelled` — the same directory as the project names it.
+ */
+export function locatePackage(project) {
+    let manifest;
+    try {
+        const req = createRequire(pathToFileURL(join(project, "__rpp_locate__.js")).href);
+        manifest = req.resolve(`${PACKAGE_NAME}/package.json`);
+    }
+    catch (e) {
+        return {
+            error: `${e.code ?? "error"}: ${e.message.split("\n")[0]}`,
+        };
+    }
+    const dir = realpathSync(dirname(manifest));
+    // Node's own walk, without its realpath step: the first `node_modules/<name>` up the tree that
+    // leads to the package that resolved.
+    for (let d = realpathSync(project);; d = dirname(d)) {
+        const candidate = join(d, "node_modules", PACKAGE_NAME);
+        try {
+            if (realpathSync(candidate) === dir)
+                return { dir, spelled: candidate };
+        }
+        catch {
+            // not here — keep walking
+        }
+        if (dirname(d) === d)
+            break;
+    }
+    return { dir, spelled: dir };
+}
+/** The skills the package ships: every skill under its `SHIPPED_SKILLS_DIR`. */
+export function shippedSkills(pkgDir) {
+    const skillsDir = join(pkgDir, SHIPPED_SKILLS_DIR);
+    // A missing directory is an error, never an empty list: zero skills linked must not read as a
+    // clean run.
+    if (!existsSync(skillsDir))
+        return { error: `the package's skills directory is missing: ${skillsDir}` };
+    // The same function every reader of an installed skills directory calls (rpp#62): the writer
+    // and the readers of this fact share one definition of "a skill is here", links included.
+    try {
+        return { skillsDir, names: installedSkills(skillsDir) };
+    }
+    catch (e) {
+        return { error: e.message };
+    }
+}
+/**
+ * What occupies `entry`, judged against the directory it should lead to. A link spelled exactly as
+ * an install under the package's old name wrote it (`legacyTarget`) is `stale`: ours, from before
+ * the rename, and replaced on the next `init`.
+ */
+function inspect(entry, want, legacyTarget) {
+    let st;
+    try {
+        st = lstatSync(entry);
+    }
+    catch {
+        return { status: "missing" };
+    }
+    if (st.isSymbolicLink() && readlinkSync(entry) === legacyTarget)
+        return {
+            status: "stale",
+            reason: `a link into ${LEGACY_PACKAGE_NAME}, the package's old name — \`npx ${PACKAGE_NAME} init\` replaces it`,
+        };
+    try {
+        if (realpathSync(entry) === want)
+            return { status: "present" };
+    }
+    catch {
+        return st.isSymbolicLink()
+            ? {
+                status: "foreign",
+                reason: `a dangling link to ${readlinkSync(entry)}`,
+            }
+            : { status: "foreign", reason: "an entry that cannot be resolved" };
+    }
+    if (st.isSymbolicLink())
+        return { status: "foreign", reason: `a link to ${readlinkSync(entry)}` };
+    return {
+        status: "foreign",
+        reason: st.isDirectory() ? "a directory" : "a file",
+    };
+}
+/**
+ * One skill: inspect its entry and, when writing, create the link — or replace one an install
+ * under the package's old name made.
+ */
+function linkOne(name, { entry, target, want, write, }) {
+    const legacyTarget = target.replace(`node_modules${sep}${PACKAGE_NAME}${sep}`, `node_modules${sep}${LEGACY_PACKAGE_NAME}${sep}`);
+    const seen = inspect(entry, want, legacyTarget);
+    const fixable = seen.status === "missing" || seen.status === "stale";
+    if (!write || !fixable) {
+        const status = seen.status === "stale" ? "foreign" : seen.status;
+        return seen.reason
+            ? { name, status, reason: seen.reason }
+            : { name, status };
+    }
+    try {
+        if (seen.status === "stale")
+            unlinkSync(entry);
+        symlinkSync(target, entry, "dir");
+        return { name, status: seen.status === "stale" ? "replaced" : "created" };
+    }
+    catch (e) {
+        return {
+            name,
+            status: "foreign",
+            reason: `could not create the link: ${e.message}`,
+        };
+    }
+}
+/**
+ * Link every shipped skill into `<project>/.claude/skills/`, or — with `write: false` — only
+ * report which ones are missing (that is what `paperlint doctor` asks).
+ */
+export function linkSkills(project, { write = true, locate = locatePackage, } = {}) {
+    const pkg = locate(project);
+    if ("error" in pkg)
+        return {
+            ok: false,
+            error: `${PACKAGE_NAME} does not resolve from ${project} (${pkg.error})`,
+        };
+    const shipped = shippedSkills(pkg.dir);
+    if ("error" in shipped)
+        return { ok: false, error: shipped.error };
+    // The same directory, as the project spells it: the real skills dir re-rooted on `spelled`.
+    const spelledSkills = join(pkg.spelled, relative(pkg.dir, shipped.skillsDir));
+    const home = join(project, SKILLS_HOME);
+    if (write && shipped.names.length > 0) {
+        try {
+            mkdirSync(home, { recursive: true });
+        }
+        catch (e) {
+            return {
+                ok: false,
+                error: `cannot create ${home}: ${e.message}`,
+            };
+        }
+    }
+    // A relative target resolves against the directory that PHYSICALLY holds the link, so it is
+    // computed from the real one — `.claude` may itself be a symlink.
+    const physicalHome = existsSync(home) ? realpathSync(home) : resolve(home);
+    let example = null;
+    const links = shipped.names.map((name) => {
+        const target = relative(physicalHome, join(spelledSkills, name));
+        example ??= target;
+        return linkOne(name, {
+            entry: join(home, name),
+            target,
+            want: realpathSync(join(shipped.skillsDir, name)),
+            write,
+        });
+    });
+    return { ok: true, home, example, links };
+}
+//# sourceMappingURL=link-skills.js.map

package/dist/link-skills.js.map

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

package/dist/new-paper.d.ts

@@ -0,0 +1,48 @@
+export type PaperFormat = "tex" | "md";
+export declare const FORMATS: readonly PaperFormat[];
+export declare const DEFAULT_FORMAT: PaperFormat;
+/** The package's default templates. Read from disk, so they ship in the tarball (`files`). */
+export declare const PACKAGE_TEMPLATES: string;
+/**
+ * The project's override directory, inside the papers directory. It starts with a dot, and that
+ * is what keeps it from being a paper: discovery (`papersIn`, `checkStructure`, `detectPapers`)
+ * skips dot-directories, and `buildConfig` ignores it for ESLint.
+ */
+export declare const OVERRIDE_DIR = ".template";
+export declare const STATUS_FILE = "PIPELINE-STATUS.md";
+export declare const SOURCE_FILE: Readonly<Record<PaperFormat, string>>;
+export declare const isFormat: (v: unknown) => v is PaperFormat;
+/**
+ * Why a name is refused, or null. `[a-z0-9._-]+` is the charset; a LEADING dot is refused on top
+ * of it, because discovery skips dot-directories — a paper named `.x` would be created and then
+ * never linted, which is worse than a refusal.
+ */
+export declare function nameProblem(name: string): string | null;
+export interface FileOutcome {
+    readonly file: string;
+    /** `created` from a template, `kept` because it was already there. */
+    readonly status: "created" | "kept";
+    /** Which template it came from, for a created file. */
+    readonly from?: "project" | "package";
+}
+export type NewPaperResult = {
+    readonly ok: true;
+    readonly dir: string;
+    /** The folder did not exist before this run. */
+    readonly fresh: boolean;
+    readonly files: readonly FileOutcome[];
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/**
+ * The files a paper folder must end up with: the scorecard, plus a source in `format` — unless
+ * it already has a source in EITHER format, in which case that one stands and nothing is added.
+ */
+export declare function wantedFiles(dir: string, format: PaperFormat): string[];
+export declare function newPaper(papersRoot: string, name: string, format: PaperFormat, { packageTemplates }?: {
+    packageTemplates?: string;
+}): NewPaperResult;
+/** The report lines, shared by `paperlint new` and the first-paper offer in `paperlint init`. */
+export declare function reportNewPaper(result: NewPaperResult, here: (p: string) => string): string[];
+//# sourceMappingURL=new-paper.d.ts.map

package/dist/new-paper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"new-paper.d.ts","sourceRoot":"","sources":["../src/new-paper.ts"],"names":[],"mappings":"AA4BA,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,IAAI,CAAC;AACvC,eAAO,MAAM,OAAO,EAAE,SAAS,WAAW,EAAkB,CAAC;AAC7D,eAAO,MAAM,cAAc,EAAE,WAAmB,CAAC;AAEjD,8FAA8F;AAC9F,eAAO,MAAM,iBAAiB,QAE7B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,YAAY,cAAc,CAAC;AAExC,eAAO,MAAM,WAAW,uBAAuB,CAAC;AAChD,eAAO,MAAM,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,CAG7D,CAAC;AAEF,eAAO,MAAM,QAAQ,GAAI,GAAG,OAAO,KAAG,CAAC,IAAI,WACP,CAAC;AAErC;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAMvD;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sEAAsE;IACtE,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAAC;IACpC,uDAAuD;IACvD,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;CACvC;AAED,MAAM,MAAM,cAAc,GACtB;IACE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,gDAAgD;IAChD,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;CACxC,GACD;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,MAAM,EAAE,CAKtE;AAGD,wBAAgB,QAAQ,CACtB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,WAAW,EACnB,EAAE,gBAAoC,EAAE,GAAE;IAAE,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAAO,GAC3E,cAAc,CAsChB;AAED,iGAAiG;AACjG,wBAAgB,cAAc,CAC5B,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,GAC1B,MAAM,EAAE,CAYV"}

package/dist/new-paper.js

@@ -0,0 +1,110 @@
+/**
+ * `paperlint new <name>` — a paper folder the linter accepts, made from a template FILE.
+ *
+ * 🔴 WHY THIS EXISTS. `paperlint lint` requires `PIPELINE-STATUS.md` in every paper folder, and until
+ * this command nothing made one: the template sat inside a fenced block of a reference page and a
+ * human copied it. The README's own "First run" example opened with the error for the missing file.
+ *
+ * Every rule below is taken from a tool that already solved it (docs/prior-art/paper-folder-scaffolding.md):
+ *   - the template is a FILE with a lookup order — the project's `<papers>/.template/<file>` first,
+ *     the package's `templates/paper/<file>` second (Hugo's archetypes);
+ *   - it NEVER overwrites: on an existing folder it adds only the missing required files, which is
+ *     also the migration for an old folder that has only `paper.md` (`cargo init`);
+ *   - the name is validated, because it becomes a path and, through the hooks, a shell argument.
+ *
+ * The only substitution is `{{name}}` → the folder name. Nothing else in a template is touched.
+ */
+/* eslint-disable boundaries/dependencies -- legacy I/O, moves behind a port in #76 */
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync, } from "node:fs";
+/* eslint-enable boundaries/dependencies */
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+export const FORMATS = ["tex", "md"];
+export const DEFAULT_FORMAT = "tex";
+/** The package's default templates. Read from disk, so they ship in the tarball (`files`). */
+export const PACKAGE_TEMPLATES = fileURLToPath(new URL("../templates/paper/", import.meta.url));
+/**
+ * The project's override directory, inside the papers directory. It starts with a dot, and that
+ * is what keeps it from being a paper: discovery (`papersIn`, `checkStructure`, `detectPapers`)
+ * skips dot-directories, and `buildConfig` ignores it for ESLint.
+ */
+export const OVERRIDE_DIR = ".template";
+export const STATUS_FILE = "PIPELINE-STATUS.md";
+export const SOURCE_FILE = {
+    tex: "paper.tex",
+    md: "paper.md",
+};
+export const isFormat = (v) => FORMATS.includes(v);
+/**
+ * Why a name is refused, or null. `[a-z0-9._-]+` is the charset; a LEADING dot is refused on top
+ * of it, because discovery skips dot-directories — a paper named `.x` would be created and then
+ * never linted, which is worse than a refusal.
+ */
+export function nameProblem(name) {
+    if (!/^[a-z0-9._-]+$/.test(name))
+        return `\`${name}\` — a paper name may hold only a-z, 0-9, dot, underscore and hyphen (it becomes a path and a shell argument)`;
+    if (name.startsWith("."))
+        return `\`${name}\` — a name starting with a dot is skipped by paper discovery, so it would never be linted`;
+    return null;
+}
+/**
+ * The files a paper folder must end up with: the scorecard, plus a source in `format` — unless
+ * it already has a source in EITHER format, in which case that one stands and nothing is added.
+ */
+export function wantedFiles(dir, format) {
+    const hasSource = Object.values(SOURCE_FILE).some((f) => existsSync(join(dir, f)));
+    return hasSource ? [STATUS_FILE] : [STATUS_FILE, SOURCE_FILE[format]];
+}
+// Documented in README.md#starting-a-paper — update it when this changes.
+export function newPaper(papersRoot, name, format, { packageTemplates = PACKAGE_TEMPLATES } = {}) {
+    const problem = nameProblem(name);
+    if (problem)
+        return { ok: false, reason: problem };
+    const dir = join(papersRoot, name);
+    const fresh = !existsSync(dir);
+    if (!fresh && !statSync(dir).isDirectory())
+        return { ok: false, reason: `${dir} exists and is not a directory` };
+    const files = [];
+    const toWrite = [];
+    for (const file of wantedFiles(dir, format)) {
+        if (existsSync(join(dir, file))) {
+            files.push({ file, status: "kept" });
+            continue;
+        }
+        const project = join(papersRoot, OVERRIDE_DIR, file);
+        const fromPackage = join(packageTemplates, file);
+        const [src, from] = existsSync(project)
+            ? [project, "project"]
+            : [fromPackage, "package"];
+        // A missing package template is a broken install, not a reason to write an empty file.
+        if (!existsSync(src))
+            return {
+                ok: false,
+                reason: `no template for ${file}: ${src} is missing`,
+            };
+        const text = readFileSync(src, "utf8").split("{{name}}").join(name);
+        toWrite.push({ file, text, from });
+    }
+    // Read every template before writing any file, so a missing one leaves no half-made folder.
+    mkdirSync(dir, { recursive: true });
+    for (const { file, text, from } of toWrite) {
+        // `wx`: fail rather than overwrite, even if something appeared since the check above.
+        writeFileSync(join(dir, file), text, { encoding: "utf8", flag: "wx" });
+        files.push({ file, status: "created", from });
+    }
+    return { ok: true, dir, fresh, files };
+}
+/** The report lines, shared by `paperlint new` and the first-paper offer in `paperlint init`. */
+export function reportNewPaper(result, here) {
+    if (!result.ok)
+        return [`  ✗ ${result.reason}`];
+    const out = [
+        `  ${result.fresh ? "✓ created" : "✓ already there, only missing files added:"} ${here(result.dir)}`,
+    ];
+    for (const f of result.files)
+        out.push(f.status === "created"
+            ? `      + ${f.file}  (from the ${f.from === "project" ? `project's ${OVERRIDE_DIR}/` : "package"} template)`
+            : `      = ${f.file}  (kept — never overwritten)`);
+    return out;
+}
+//# sourceMappingURL=new-paper.js.map

package/dist/new-paper.js.map

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

package/dist/pdf-facts.d.ts

@@ -0,0 +1,44 @@
+import { type Fonts, type PageText, type RawFont } from "./pdf-geometry.ts";
+import type { PageLayout } from "./domain/page-layout.ts";
+/**
+ * What `readPdf` measured. `last` is the last page's words; `classifyLastPage` reads it. `layout` is
+ * every page's text boxes, for banal (`adapters/banal/xml.ts` writes them as the XML banal reads).
+ */
+export interface PdfFacts {
+    readonly pages: number;
+    readonly fonts: Fonts;
+    readonly last: PageText;
+    readonly layout: readonly PageLayout[];
+}
+export type PdfReadFailure = "unreadable" | "encrypted" | "zero-fonts-on-text" | "empty";
+export type PdfRead = {
+    readonly ok: true;
+    readonly facts: PdfFacts;
+} | {
+    readonly ok: false;
+    readonly reason: PdfReadFailure;
+    readonly detail: string;
+};
+/** The port `paperlint build` and the facts writer take, so a test can hand them any outcome. */
+export type PdfReader = (path: string) => Promise<PdfRead>;
+/**
+ * The options every read uses, exactly as measured in the spike. `fontExtraProperties` is
+ * load-bearing: without it pdf.js exports no `type`/`subtype`, and every font's program is unknown.
+ * `disableFontFace` keeps pdf.js from trying to install fonts into a page that does not exist here.
+ */
+export declare const PDFJS_OPTIONS: {
+    readonly disableFontFace: true;
+    readonly fontExtraProperties: true;
+    readonly verbosity: 0;
+    readonly useSystemFonts: false;
+    readonly isEvalSupported: false;
+};
+/** A font object pdf.js left in `commonObjs`, read into a `RawFont`, or null when it is not one. */
+export declare function rawFontOf(id: string, obj: unknown): RawFont | null;
+/** Read a PDF from disk. Never throws for a property of the file; see the module header. */
+export declare const readPdf: PdfReader;
+/** The one wording of a failed read, as a build step or a CLI prints it. */
+export declare function describeFailure(r: Extract<PdfRead, {
+    ok: false;
+}>, pdf: string): string;
+//# sourceMappingURL=pdf-facts.d.ts.map

package/dist/pdf-facts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pdf-facts.d.ts","sourceRoot":"","sources":["../src/pdf-facts.ts"],"names":[],"mappings":"AAsBA,OAAO,EAKL,KAAK,KAAK,EACV,KAAK,QAAQ,EACb,KAAK,OAAO,EAGb,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,UAAU,EAAW,MAAM,yBAAyB,CAAC;AAUnE;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,CAAC;CACxC;AAED,MAAM,MAAM,cAAc,GACxB,YAAY,GAAG,WAAW,GAAG,oBAAoB,GAAG,OAAO,CAAC;AAE9D,MAAM,MAAM,OAAO,GACf;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAA;CAAE,GAC/C;IACE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,CAAC;AAEN,iGAAiG;AACjG,MAAM,MAAM,SAAS,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAE3D;;;;GAIG;AACH,eAAO,MAAM,aAAa;;;;;;CAMhB,CAAC;AAeX,oGAAoG;AACpG,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,GAAG,IAAI,CAclE;AAgMD,4FAA4F;AAC5F,eAAO,MAAM,OAAO,EAAE,SAgBrB,CAAC;AAEF,4EAA4E;AAC5E,wBAAgB,eAAe,CAC7B,CAAC,EAAE,OAAO,CAAC,OAAO,EAAE;IAAE,EAAE,EAAE,KAAK,CAAA;CAAE,CAAC,EAClC,GAAG,EAAE,MAAM,GACV,MAAM,CAER"}