loreforge 0.1.0-alpha.1

package/dist/cli/init.js

@@ -0,0 +1,309 @@
+import { mkdirSync, writeFileSync, readFileSync, existsSync } from "node:fs";
+import { dirname, join, basename, resolve } from "node:path";
+import { homedir } from "node:os";
+import { createInterface } from "node:readline/promises";
+import { fileURLToPath } from "node:url";
+import { openCore } from "../core/index.js";
+import { generateInstructions, quoteShell } from "./instructions.js";
+import { CliValidationError, parseAgentSpec } from "./args.js";
+import { resolveHomeDir } from "./home.js";
+import { detectCodingClis, detectedToAgents } from "./detect.js";
+function defaultExecPath() {
+    try {
+        const currentDir = fileURLToPath(new URL(".", import.meta.url));
+        const distBin = resolve(currentDir, "../../dist/cli/main.js");
+        if (existsSync(distBin))
+            return `node ${quoteShell(distBin)}`;
+    }
+    catch {
+        // fall through
+    }
+    return "lore";
+}
+function titleCase(id) {
+    return id.charAt(0).toUpperCase() + id.slice(1);
+}
+function executeOk(response) {
+    if (!response.ok) {
+        throw new CliValidationError(response.error.message);
+    }
+    return response.data;
+}
+function roleGuidance(role) {
+    if (role === "review") {
+        return [
+            "Your init role is **review**. Use context mode `review`. Do not claim a task to implement unless the user asks you to edit.",
+            "Any registered agent may still claim any open task if the user reassigns.",
+        ].join("\n");
+    }
+    if (role === "implement") {
+        return [
+            "Your init role is **implement**. Use context mode `work` and claim an open task before editing.",
+            "Any registered agent may still claim any open task if the user reassigns.",
+        ].join("\n");
+    }
+    return [
+        "Your init role is **both**. Use `work` if you will edit, `review` if you will not.",
+        "Any registered agent may claim any open task.",
+    ].join("\n");
+}
+export function renderRepoRule(params) {
+    const roster = params.roster.map((a) => `- \`${a.id}\`: ${a.role}`).join("\n");
+    return `# Loreforge
+
+Shared log for this git repo. Do not start other models, create worktrees, merge, or deploy.
+
+- CLI: \`${params.execPath}\`
+- Home: \`${params.homeDir}\`
+- Project: \`${params.projectId}\`
+
+Register **this session's** agent id (any label on the roster) and this git root, then \`task list\` and \`inbox\`. Fetch \`context\` before editing (\`work\` if you will edit, \`review\` if not). Claim only to edit. Handoff with git evidence.
+
+Roster (labels, not locks; any registered agent may claim any open task):
+${roster}
+`;
+}
+export function renderInitRule(params) {
+    const roster = params.roster.map((a) => `- \`${a.id}\`: ${a.role}`).join("\n");
+    const snippet = generateInstructions({
+        projectId: params.projectId,
+        agentId: params.agentId,
+        homeDir: params.homeDir,
+        execPath: params.execPath,
+    });
+    return `${snippet}
+
+## Role for this session
+
+${roleGuidance(params.role)}
+
+Roster from \`lore init\` (labels, not locks):
+${roster}
+
+Loreforge does not start other models, create worktrees, merge, or deploy.
+`;
+}
+const MARK_START = "<!-- loreforge:start -->";
+const MARK_END = "<!-- loreforge:end -->";
+export function upsertMarkedSection(filePath, body) {
+    mkdirSync(dirname(filePath), { recursive: true });
+    const block = `${MARK_START}\n${body.trim()}\n${MARK_END}\n`;
+    if (!existsSync(filePath)) {
+        writeFileSync(filePath, block, "utf8");
+        return;
+    }
+    const current = readFileSync(filePath, "utf8");
+    const startAt = current.indexOf(MARK_START);
+    const endAt = current.indexOf(MARK_END);
+    if (startAt >= 0 && endAt > startAt) {
+        const afterEnd = endAt + MARK_END.length;
+        const suffix = current.slice(afterEnd).replace(/^\n/, "");
+        writeFileSync(filePath, `${current.slice(0, startAt)}${block}${suffix}`, "utf8");
+        return;
+    }
+    const prefix = current.trimEnd();
+    writeFileSync(filePath, prefix.length > 0 ? `${prefix}\n\n${block}` : block, "utf8");
+}
+async function promptLine(stdin, stdout, question, fallback) {
+    const rl = createInterface({
+        input: stdin,
+        output: stdout,
+        terminal: Boolean(stdin.isTTY),
+    });
+    try {
+        const answer = await rl.question(fallback ? `${question} [${fallback}]: ` : `${question}: `);
+        const trimmed = answer.trim();
+        return trimmed.length > 0 ? trimmed : fallback;
+    }
+    finally {
+        rl.close();
+    }
+}
+export async function resolveInitOptions(options, stdin, stdout, cwd, env = process.env, userHome = homedir()) {
+    const detected = options.detect === false
+        ? []
+        : detectCodingClis({
+            path: env.PATH ?? "",
+            home: userHome,
+            pathDelimiter: env.Path && !env.PATH ? ";" : ":",
+            pathext: env.PATHEXT,
+        });
+    const detectedAgents = detectedToAgents(detected);
+    const agents = options.agents.length > 0 ? options.agents : detectedAgents;
+    const tty = Boolean(stdin.isTTY);
+    const skipPrompt = options.json || Boolean(options.root);
+    if (skipPrompt || !tty) {
+        if (agents.length === 0) {
+            throw new CliValidationError("lore init found no local CLIs; pass --agent id[:role] (repeatable)");
+        }
+        return { ...options, agents };
+    }
+    const root = await promptLine(stdin, stdout, "Git repo to register", options.root ?? cwd);
+    const name = await promptLine(stdin, stdout, "Project name", options.name ?? basename(resolve(root)));
+    const detectedDefault = detectedAgents.map((a) => `${a.id}:${a.role}`).join(",") || "codex:implement,claude:review";
+    if (detected.length > 0) {
+        stdout.write("Detected CLIs (binary/config dir; auth-file means a login file exists, not a billed plan):\n");
+        for (const row of detected) {
+            stdout.write(`  ${row.id}  ${row.evidence.join(", ")}${row.signedIn ? "  signed-in-file" : ""}\n`);
+        }
+    }
+    const agentLine = await promptLine(stdin, stdout, "Agents as id:role (role=implement|review|both), comma-separated", detectedDefault);
+    const chosen = agentLine
+        .split(",")
+        .map((part) => parseAgentSpec(part))
+        .filter((a, i, all) => all.findIndex((b) => b.id === a.id) === i);
+    if (chosen.length === 0) {
+        throw new CliValidationError("at least one agent is required");
+    }
+    const writeRaw = await promptLine(stdin, stdout, "Write session rules into this git repo? (Y/n)", "Y");
+    const demoRaw = await promptLine(stdin, stdout, "Create two sample tasks? (Y/n)", "Y");
+    return {
+        ...options,
+        root,
+        name,
+        agents: chosen,
+        writeRules: options.writeRules || /^y/i.test(writeRaw),
+        demo: options.demo || /^y/i.test(demoRaw),
+    };
+}
+export async function runInit(options, env, extras = {}) {
+    const execPath = extras.execPath ?? defaultExecPath();
+    const userHome = extras.userHome ?? homedir();
+    if (options.agents.length === 0) {
+        throw new CliValidationError("lore init requires at least one --agent id[:role]");
+    }
+    const root = resolve(options.root ?? process.cwd());
+    const name = (options.name ?? basename(root)).slice(0, 100);
+    const home = resolveHomeDir(options.home, env);
+    const core = openCore({ home });
+    const filesWritten = [];
+    const taskIds = [];
+    try {
+        const project = executeOk(await core.execute({
+            schemaVersion: 1,
+            operation: "project.register",
+            requestId: "init-project-1",
+            payload: { root, name },
+        })).project;
+        for (const agent of options.agents) {
+            executeOk(await core.execute({
+                schemaVersion: 1,
+                operation: "agent.register",
+                requestId: `init-agent-${agent.id}`,
+                payload: { id: agent.id, displayName: titleCase(agent.id) },
+            }));
+        }
+        const actorId = options.agents[0].id;
+        const rosterText = options.agents.map((a) => `${a.id}=${a.role}`).join(", ");
+        executeOk(await core.execute({
+            schemaVersion: 1,
+            operation: "decision.record",
+            projectId: project.id,
+            actorId,
+            requestId: "init-decision-roster-1",
+            payload: {
+                body: `Init roster (labels, not locks; any agent may claim any open task): ${rosterText}.`,
+                paths: [],
+                supersedesId: null,
+            },
+        }));
+        if (options.demo) {
+            const first = executeOk(await core.execute({
+                schemaVersion: 1,
+                operation: "task.create",
+                projectId: project.id,
+                actorId,
+                requestId: "init-demo-task-1",
+                payload: {
+                    title: "Demo: make a small documented change",
+                    description: "Implementer: claim this task, make a tiny change in this repo, run a check, hand off with git evidence.",
+                    dependsOn: [],
+                },
+            })).task;
+            const second = executeOk(await core.execute({
+                schemaVersion: 1,
+                operation: "task.create",
+                projectId: project.id,
+                actorId,
+                requestId: "init-demo-task-2",
+                payload: {
+                    title: "Demo: review the other agent's change",
+                    description: "Reviewer: wait until the implementer task is completed, fetch context in review mode, do not implement unless asked.",
+                    dependsOn: [first.id],
+                },
+            })).task;
+            taskIds.push(first.id, second.id);
+        }
+        mkdirSync(home, { recursive: true });
+        const initPath = join(home, "init.json");
+        writeFileSync(initPath, `${JSON.stringify({ projectId: project.id, root, agents: options.agents }, null, 2)}\n`, "utf8");
+        filesWritten.push(initPath);
+        if (options.writeRules) {
+            const repoBody = renderRepoRule({
+                execPath,
+                homeDir: home,
+                projectId: project.id,
+                roster: options.agents,
+            });
+            const repoRule = join(root, ".grok", "rules", "loreforge.md");
+            mkdirSync(dirname(repoRule), { recursive: true });
+            writeFileSync(repoRule, repoBody, "utf8");
+            filesWritten.push(repoRule);
+            upsertMarkedSection(join(root, "AGENTS.md"), repoBody);
+            filesWritten.push(join(root, "AGENTS.md"));
+            const ids = new Set(options.agents.map((a) => a.id));
+            if (ids.has("claude") || ids.has("anthropic")) {
+                upsertMarkedSection(join(root, "CLAUDE.md"), repoBody);
+                filesWritten.push(join(root, "CLAUDE.md"));
+            }
+            if (ids.has("cursor")) {
+                const path = join(root, ".cursor", "rules", "loreforge.mdc");
+                mkdirSync(dirname(path), { recursive: true });
+                writeFileSync(path, repoBody, "utf8");
+                filesWritten.push(path);
+            }
+        }
+        if (options.writeUserRules) {
+            for (const agent of options.agents) {
+                const body = renderInitRule({
+                    execPath,
+                    homeDir: home,
+                    projectId: project.id,
+                    agentId: agent.id,
+                    role: agent.role,
+                    roster: options.agents,
+                });
+                if (agent.id === "grok") {
+                    const path = join(userHome, ".grok", "rules", "loreforge.md");
+                    mkdirSync(dirname(path), { recursive: true });
+                    writeFileSync(path, body, "utf8");
+                    filesWritten.push(path);
+                }
+                if (agent.id === "claude") {
+                    const path = join(userHome, ".claude", "rules", "loreforge.md");
+                    mkdirSync(dirname(path), { recursive: true });
+                    writeFileSync(path, body, "utf8");
+                    filesWritten.push(path);
+                }
+            }
+        }
+        const detected = detectCodingClis({
+            path: env.PATH ?? "",
+            home: userHome,
+            pathext: env.PATHEXT,
+        });
+        return {
+            projectId: project.id,
+            home,
+            root,
+            agents: options.agents,
+            filesWritten,
+            taskIds,
+            detected,
+        };
+    }
+    finally {
+        core.close();
+    }
+}
+//# sourceMappingURL=init.js.map

package/dist/cli/init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../../src/cli/init.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7D,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE5C,OAAO,EAAE,oBAAoB,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACrE,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAqC,MAAM,WAAW,CAAC;AAClG,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAoB,MAAM,aAAa,CAAC;AAwBnF,SAAS,eAAe;IACtB,IAAI,CAAC;QACH,MAAM,UAAU,GAAG,aAAa,CAAC,IAAI,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;QAChE,MAAM,OAAO,GAAG,OAAO,CAAC,UAAU,EAAE,wBAAwB,CAAC,CAAC;QAC9D,IAAI,UAAU,CAAC,OAAO,CAAC;YAAE,OAAO,QAAQ,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;IAChE,CAAC;IAAC,MAAM,CAAC;QACP,eAAe;IACjB,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,SAAS,CAAC,EAAU;IAC3B,OAAO,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAClD,CAAC;AAED,SAAS,SAAS,CAAI,QAAkB;IACtC,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,MAAM,IAAI,kBAAkB,CAAC,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACvD,CAAC;IACD,OAAO,QAAQ,CAAC,IAAS,CAAC;AAC5B,CAAC;AAED,SAAS,YAAY,CAAC,IAAc;IAClC,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;QACtB,OAAO;YACL,6HAA6H;YAC7H,2EAA2E;SAC5E,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACf,CAAC;IACD,IAAI,IAAI,KAAK,WAAW,EAAE,CAAC;QACzB,OAAO;YACL,iGAAiG;YACjG,2EAA2E;SAC5E,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACf,CAAC;IACD,OAAO;QACL,oFAAoF;QACpF,+CAA+C;KAChD,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,MAK9B;IACC,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC/E,OAAO;;;;WAIE,MAAM,CAAC,QAAQ;YACd,MAAM,CAAC,OAAO;eACX,MAAM,CAAC,SAAS;;;;;EAK7B,MAAM;CACP,CAAC;AACF,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,MAO9B;IACC,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC/E,MAAM,OAAO,GAAG,oBAAoB,CAAC;QACnC,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,QAAQ,EAAE,MAAM,CAAC,QAAQ;KAC1B,CAAC,CAAC;IACH,OAAO,GAAG,OAAO;;;;EAIjB,YAAY,CAAC,MAAM,CAAC,IAAI,CAAC;;;EAGzB,MAAM;;;CAGP,CAAC;AACF,CAAC;AAED,MAAM,UAAU,GAAG,0BAA0B,CAAC;AAC9C,MAAM,QAAQ,GAAG,wBAAwB,CAAC;AAE1C,MAAM,UAAU,mBAAmB,CAAC,QAAgB,EAAE,IAAY;IAChE,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAClD,MAAM,KAAK,GAAG,GAAG,UAAU,KAAK,IAAI,CAAC,IAAI,EAAE,KAAK,QAAQ,IAAI,CAAC;IAC7D,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC1B,aAAa,CAAC,QAAQ,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;QACvC,OAAO;IACT,CAAC;IACD,MAAM,OAAO,GAAG,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC/C,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IAC5C,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACxC,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,GAAG,OAAO,EAAE,CAAC;QACpC,MAAM,QAAQ,GAAG,KAAK,GAAG,QAAQ,CAAC,MAAM,CAAC;QACzC,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAC1D,aAAa,CAAC,QAAQ,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,GAAG,KAAK,GAAG,MAAM,EAAE,EAAE,MAAM,CAAC,CAAC;QACjF,OAAO;IACT,CAAC;IACD,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IACjC,aAAa,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;AACvF,CAAC;AAED,KAAK,UAAU,UAAU,CACvB,KAA4B,EAC5B,MAA6B,EAC7B,QAAgB,EAChB,QAAgB;IAEhB,MAAM,EAAE,GAAG,eAAe,CAAC;QACzB,KAAK,EAAE,KAAiB;QACxB,MAAM,EAAE,MAAkB;QAC1B,QAAQ,EAAE,OAAO,CAAE,KAA2B,CAAC,KAAK,CAAC;KACtD,CAAC,CAAC;IACH,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,QAAQ,KAAK,QAAQ,KAAK,CAAC,CAAC,CAAC,GAAG,QAAQ,IAAI,CAAC,CAAC;QAC7F,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;QAC9B,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC;IACjD,CAAC;YAAS,CAAC;QACT,EAAE,CAAC,KAAK,EAAE,CAAC;IACb,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,OAAoB,EACpB,KAA4B,EAC5B,MAA6B,EAC7B,GAAW,EACX,MAA0C,OAAO,CAAC,GAAG,EACrD,QAAQ,GAAG,OAAO,EAAE;IAEpB,MAAM,QAAQ,GACZ,OAAO,CAAC,MAAM,KAAK,KAAK;QACtB,CAAC,CAAC,EAAE;QACJ,CAAC,CAAC,gBAAgB,CAAC;YACf,IAAI,EAAE,GAAG,CAAC,IAAI,IAAI,EAAE;YACpB,IAAI,EAAE,QAAQ;YACd,aAAa,EAAE,GAAG,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG;YAChD,OAAO,EAAE,GAAG,CAAC,OAAO;SACrB,CAAC,CAAC;IACT,MAAM,cAAc,GAAG,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IAClD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,cAAc,CAAC;IAC3E,MAAM,GAAG,GAAG,OAAO,CAAE,KAA2B,CAAC,KAAK,CAAC,CAAC;IACxD,MAAM,UAAU,GAAG,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACzD,IAAI,UAAU,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxB,MAAM,IAAI,kBAAkB,CAC1B,oEAAoE,CACrE,CAAC;QACJ,CAAC;QACD,OAAO,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,CAAC;IAChC,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,sBAAsB,EAAE,OAAO,CAAC,IAAI,IAAI,GAAG,CAAC,CAAC;IAC1F,MAAM,IAAI,GAAG,MAAM,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,OAAO,CAAC,IAAI,IAAI,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACtG,MAAM,eAAe,GAAG,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,+BAA+B,CAAC;IACpH,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,CAAC,KAAK,CAAC,8FAA8F,CAAC,CAAC;QAC7G,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;YAC3B,MAAM,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;QACrG,CAAC;IACH,CAAC;IACD,MAAM,SAAS,GAAG,MAAM,UAAU,CAChC,KAAK,EACL,MAAM,EACN,iEAAiE,EACjE,eAAe,CAChB,CAAC;IACF,MAAM,MAAM,GAAG,SAAS;SACrB,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;SACnC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;IACpE,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,kBAAkB,CAAC,gCAAgC,CAAC,CAAC;IACjE,CAAC;IACD,MAAM,QAAQ,GAAG,MAAM,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,+CAA+C,EAAE,GAAG,CAAC,CAAC;IACvG,MAAM,OAAO,GAAG,MAAM,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,gCAAgC,EAAE,GAAG,CAAC,CAAC;IACvF,OAAO;QACL,GAAG,OAAO;QACV,IAAI;QACJ,IAAI;QACJ,MAAM,EAAE,MAAM;QACd,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC;QACtD,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC;KAC1C,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,OAAoB,EACpB,GAAuC,EACvC,SAAmD,EAAE;IAErD,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,IAAI,eAAe,EAAE,CAAC;IACtD,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,IAAI,OAAO,EAAE,CAAC;IAC9C,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,kBAAkB,CAAC,mDAAmD,CAAC,CAAC;IACpF,CAAC;IACD,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IACpD,MAAM,IAAI,GAAG,CAAC,OAAO,CAAC,IAAI,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC5D,MAAM,IAAI,GAAG,cAAc,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC/C,MAAM,IAAI,GAAG,QAAQ,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;IAChC,MAAM,YAAY,GAAa,EAAE,CAAC;IAClC,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,SAAS,CACvB,MAAM,IAAI,CAAC,OAAO,CAAC;YACjB,aAAa,EAAE,CAAC;YAChB,SAAS,EAAE,kBAAkB;YAC7B,SAAS,EAAE,gBAAgB;YAC3B,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE;SACxB,CAAC,CACH,CAAC,OAAO,CAAC;QAEV,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;YACnC,SAAS,CACP,MAAM,IAAI,CAAC,OAAO,CAAC;gBACjB,aAAa,EAAE,CAAC;gBAChB,SAAS,EAAE,gBAAgB;gBAC3B,SAAS,EAAE,cAAc,KAAK,CAAC,EAAE,EAAE;gBACnC,OAAO,EAAE,EAAE,EAAE,EAAE,KAAK,CAAC,EAAE,EAAE,WAAW,EAAE,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE;aAC5D,CAAC,CACH,CAAC;QACJ,CAAC;QAED,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACrC,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC7E,SAAS,CACP,MAAM,IAAI,CAAC,OAAO,CAAC;YACjB,aAAa,EAAE,CAAC;YAChB,SAAS,EAAE,iBAAiB;YAC5B,SAAS,EAAE,OAAO,CAAC,EAAE;YACrB,OAAO;YACP,SAAS,EAAE,wBAAwB;YACnC,OAAO,EAAE;gBACP,IAAI,EAAE,uEAAuE,UAAU,GAAG;gBAC1F,KAAK,EAAE,EAAE;gBACT,YAAY,EAAE,IAAI;aACnB;SACF,CAAC,CACH,CAAC;QAEF,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;YACjB,MAAM,KAAK,GAAG,SAAS,CACrB,MAAM,IAAI,CAAC,OAAO,CAAC;gBACjB,aAAa,EAAE,CAAC;gBAChB,SAAS,EAAE,aAAa;gBACxB,SAAS,EAAE,OAAO,CAAC,EAAE;gBACrB,OAAO;gBACP,SAAS,EAAE,kBAAkB;gBAC7B,OAAO,EAAE;oBACP,KAAK,EAAE,sCAAsC;oBAC7C,WAAW,EACT,yGAAyG;oBAC3G,SAAS,EAAE,EAAE;iBACd;aACF,CAAC,CACH,CAAC,IAAI,CAAC;YACP,MAAM,MAAM,GAAG,SAAS,CACtB,MAAM,IAAI,CAAC,OAAO,CAAC;gBACjB,aAAa,EAAE,CAAC;gBAChB,SAAS,EAAE,aAAa;gBACxB,SAAS,EAAE,OAAO,CAAC,EAAE;gBACrB,OAAO;gBACP,SAAS,EAAE,kBAAkB;gBAC7B,OAAO,EAAE;oBACP,KAAK,EAAE,uCAAuC;oBAC9C,WAAW,EACT,sHAAsH;oBACxH,SAAS,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC;iBACtB;aACF,CAAC,CACH,CAAC,IAAI,CAAC;YACP,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;QACpC,CAAC;QAED,SAAS,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACrC,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;QACzC,aAAa,CACX,QAAQ,EACR,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EACvF,MAAM,CACP,CAAC;QACF,YAAY,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAE5B,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;YACvB,MAAM,QAAQ,GAAG,cAAc,CAAC;gBAC9B,QAAQ;gBACR,OAAO,EAAE,IAAI;gBACb,SAAS,EAAE,OAAO,CAAC,EAAE;gBACrB,MAAM,EAAE,OAAO,CAAC,MAAM;aACvB,CAAC,CAAC;YAEH,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,cAAc,CAAC,CAAC;YAC9D,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAClD,aAAa,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;YAC1C,YAAY,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAE5B,mBAAmB,CAAC,IAAI,CAAC,IAAI,EAAE,WAAW,CAAC,EAAE,QAAQ,CAAC,CAAC;YACvD,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC;YAE3C,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;YACrD,IAAI,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,CAAC;gBAC9C,mBAAmB,CAAC,IAAI,CAAC,IAAI,EAAE,WAAW,CAAC,EAAE,QAAQ,CAAC,CAAC;gBACvD,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC;YAC7C,CAAC;YACD,IAAI,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;gBACtB,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,eAAe,CAAC,CAAC;gBAC7D,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;gBAC9C,aAAa,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;gBACtC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC1B,CAAC;QACH,CAAC;QAED,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;YAC3B,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;gBACnC,MAAM,IAAI,GAAG,cAAc,CAAC;oBAC1B,QAAQ;oBACR,OAAO,EAAE,IAAI;oBACb,SAAS,EAAE,OAAO,CAAC,EAAE;oBACrB,OAAO,EAAE,KAAK,CAAC,EAAE;oBACjB,IAAI,EAAE,KAAK,CAAC,IAAI;oBAChB,MAAM,EAAE,OAAO,CAAC,MAAM;iBACvB,CAAC,CAAC;gBACH,IAAI,KAAK,CAAC,EAAE,KAAK,MAAM,EAAE,CAAC;oBACxB,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,cAAc,CAAC,CAAC;oBAC9D,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;oBAC9C,aAAa,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;oBAClC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBAC1B,CAAC;gBACD,IAAI,KAAK,CAAC,EAAE,KAAK,QAAQ,EAAE,CAAC;oBAC1B,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,EAAE,SAAS,EAAE,OAAO,EAAE,cAAc,CAAC,CAAC;oBAChE,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;oBAC9C,aAAa,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;oBAClC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBAC1B,CAAC;YACH,CAAC;QACH,CAAC;QAED,MAAM,QAAQ,GAAG,gBAAgB,CAAC;YAChC,IAAI,EAAE,GAAG,CAAC,IAAI,IAAI,EAAE;YACpB,IAAI,EAAE,QAAQ;YACd,OAAO,EAAE,GAAG,CAAC,OAAO;SACrB,CAAC,CAAC;QACH,OAAO;YACL,SAAS,EAAE,OAAO,CAAC,EAAE;YACrB,IAAI;YACJ,IAAI;YACJ,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,YAAY;YACZ,OAAO;YACP,QAAQ;SACT,CAAC;IACJ,CAAC;YAAS,CAAC;QACT,IAAI,CAAC,KAAK,EAAE,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/cli/input.js

@@ -0,0 +1,72 @@
+import { createReadStream } from "node:fs";
+export const MAX_JSON_BYTES = 64 * 1024; // 64 KiB
+export class CliInputError extends Error {
+    code;
+    exitCode;
+    constructor(code, message, exitCode = code === "VALIDATION" ? 2 : 7) {
+        super(message);
+        this.code = code;
+        this.exitCode = exitCode;
+        this.name = "CliInputError";
+    }
+}
+/**
+ * Reads bounded input from stdin or a file.
+ * The 64 KiB byte limit is enforced incrementally while streaming chunks.
+ * Enforces valid UTF-8 and valid JSON syntax without leaking input contents on error.
+ */
+export async function readBoundedInput(inputPath, stdinStream = process.stdin) {
+    const stream = inputPath === "-" ? stdinStream : createReadStream(inputPath, { highWaterMark: 16384 });
+    const chunks = [];
+    let totalBytes = 0;
+    try {
+        for await (const chunk of stream) {
+            const buf = typeof chunk === "string" ? Buffer.from(chunk, "utf8") : chunk;
+            totalBytes += buf.length;
+            if (totalBytes > MAX_JSON_BYTES) {
+                if ("destroy" in stream && typeof stream.destroy === "function") {
+                    stream.destroy();
+                }
+                throw new CliInputError("VALIDATION", `Input exceeds maximum size limit of ${MAX_JSON_BYTES} bytes (64 KiB)`);
+            }
+            chunks.push(buf);
+        }
+    }
+    catch (err) {
+        if (err instanceof CliInputError) {
+            throw err;
+        }
+        // Differentiate IO failures (e.g. ENOENT, EACCES)
+        const errorMsg = err instanceof Error ? err.message : "Stream read error";
+        if (inputPath !== "-") {
+            throw new CliInputError("IO", `Failed to read input file: ${errorMsg}`);
+        }
+        throw new CliInputError("IO", `Failed to read stdin: ${errorMsg}`);
+    }
+    const rawBuffer = Buffer.concat(chunks);
+    const decoder = new TextDecoder("utf-8", { fatal: true });
+    let text = "";
+    try {
+        text = decoder.decode(rawBuffer);
+    }
+    catch {
+        throw new CliInputError("VALIDATION", "Input is not valid UTF-8");
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        // Never echo raw input or stack trace
+        throw new CliInputError("VALIDATION", "Input is not valid JSON syntax");
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new CliInputError("VALIDATION", "Input JSON must be an object");
+    }
+    const obj = parsed;
+    if ("operation" in obj) {
+        throw new CliInputError("VALIDATION", "Field 'operation' must not be provided in input; operation is specified via CLI namespace and verb");
+    }
+    return obj;
+}
+//# sourceMappingURL=input.js.map

package/dist/cli/input.js.map

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

package/dist/cli/instructions.js

@@ -0,0 +1,83 @@
+import { existsSync } from "node:fs";
+import { resolve, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CliValidationError } from "./args.js";
+const UUID_RE = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+const AGENT_ID_RE = /^[a-z][a-z0-9_-]{0,63}$/;
+/**
+ * Safely quote a string for POSIX Bourne/Bash shells.
+ */
+export function quoteShell(str) {
+    return `'${str.replace(/'/g, "'\\''")}'`;
+}
+/**
+ * Validates project UUID and agent ID syntactically and renders generic instruction snippet.
+ */
+export function generateInstructions(params) {
+    const { projectId, agentId, homeDir } = params;
+    if (!UUID_RE.test(projectId)) {
+        throw new CliValidationError(`Invalid project UUID format: ${projectId}`);
+    }
+    if (!AGENT_ID_RE.test(agentId)) {
+        throw new CliValidationError(`Invalid agent ID format: ${agentId}`);
+    }
+    // Resolve executable path safely
+    let execPath = params.execPath;
+    if (!execPath) {
+        try {
+            const currentDir = fileURLToPath(new URL(".", import.meta.url));
+            const packageRoot = resolve(currentDir, "../..");
+            const distBin = join(packageRoot, "dist", "cli", "main.js");
+            if (existsSync(distBin)) {
+                execPath = `node ${quoteShell(distBin)}`;
+            }
+            else {
+                execPath = `npm run lore --`;
+            }
+        }
+        catch {
+            execPath = "lore";
+        }
+    }
+    const quotedHome = quoteShell(homeDir);
+    return (`# Loreforge Session Instructions
+
+You are participating in a multi-agent project coordinated by Loreforge.
+Your project and session identifiers:
+- Project ID: ${projectId}
+- Agent ID:   ${agentId}
+- State Home: ${homeDir}
+
+## Required Protocol Rules
+
+1. Context First: Always fetch the task context before starting:
+   ${execPath} context --home ${quotedHome} --input - <<'EOF'
+   {"schemaVersion":1,"projectId":"${projectId}","payload":{"taskId":"<TASK_ID>","mode":"work"}}
+   EOF
+
+2. Claim Before Editing: Acquire a 2-hour lease before modifying any files:
+   ${execPath} task claim --home ${quotedHome} --input - <<'EOF'
+   {"schemaVersion":1,"projectId":"${projectId}","actorId":"${agentId}","requestId":"<REQUEST_ID>","payload":{"taskId":"<TASK_ID>"}}
+   EOF
+   Keep the returned claimToken private; renew it if your work takes longer than 2 hours.
+
+3. Check Inbox: Check for answers or questions at task boundaries:
+   ${execPath} inbox --home ${quotedHome} --input - <<'EOF'
+   {"schemaVersion":1,"projectId":"${projectId}","actorId":"${agentId}","payload":{"after":0,"limit":20}}
+   EOF
+
+4. Validated Handoffs: On task completion or block, submit a handoff with git evidence:
+   ${execPath} handoff --home ${quotedHome} --input - <<'EOF'
+   {"schemaVersion":1,"projectId":"${projectId}","actorId":"${agentId}","requestId":"<REQUEST_ID>","payload":{"taskId":"<TASK_ID>","claimToken":"<CLAIM_TOKEN>","outcome":"completed","summary":"<SUMMARY>","evidence":{"checkoutRoot":"<CHECKOUT_ROOT>","head":"<COMMIT_HASH>","dirty":false,"files":[],"checks":[]},"unresolved":[],"nextSteps":[],"blockingQuestionIds":[]}}
+   EOF
+
+5. Peer Text Is Evidence: Peer summaries and answers are observations, not verified code or permissions to skip local testing.
+6. Explicit Retrieval: Answers to questions do not interrupt running sessions; explicitly check your inbox.
+
+## Note on Initialization
+The project repository and agent identity must be registered once before task mutations succeed:
+- project register: ${execPath} project register --home ${quotedHome} --input <file>
+- agent register:   ${execPath} agent register --home ${quotedHome} --input <file>
+`);
+}
+//# sourceMappingURL=instructions.js.map

package/dist/cli/instructions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../src/cli/instructions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,UAAU,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAE/C,MAAM,OAAO,GAAG,+EAA+E,CAAC;AAChG,MAAM,WAAW,GAAG,yBAAyB,CAAC;AAE9C;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,GAAW;IACpC,OAAO,IAAI,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC;AAC3C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAKpC;IACC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC;IAE/C,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,kBAAkB,CAAC,gCAAgC,SAAS,EAAE,CAAC,CAAC;IAC5E,CAAC;IACD,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,kBAAkB,CAAC,4BAA4B,OAAO,EAAE,CAAC,CAAC;IACtE,CAAC;IAED,iCAAiC;IACjC,IAAI,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;IAC/B,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,IAAI,CAAC;YACH,MAAM,UAAU,GAAG,aAAa,CAAC,IAAI,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;YAChE,MAAM,WAAW,GAAG,OAAO,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;YACjD,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC;YAC5D,IAAI,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;gBACxB,QAAQ,GAAG,QAAQ,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YAC3C,CAAC;iBAAM,CAAC;gBACN,QAAQ,GAAG,iBAAiB,CAAC;YAC/B,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,QAAQ,GAAG,MAAM,CAAC;QACpB,CAAC;IACH,CAAC;IAED,MAAM,UAAU,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC;IAEvC,OAAO,CACT;;;;gBAIgB,SAAS;gBACT,OAAO;gBACP,OAAO;;;;;KAKlB,QAAQ,mBAAmB,UAAU;qCACL,SAAS;;;;KAIzC,QAAQ,sBAAsB,UAAU;qCACR,SAAS,gBAAgB,OAAO;;;;;KAKhE,QAAQ,iBAAiB,UAAU;qCACH,SAAS,gBAAgB,OAAO;;;;KAIhE,QAAQ,mBAAmB,UAAU;qCACL,SAAS,gBAAgB,OAAO;;;;;;;;sBAQ/C,QAAQ,4BAA4B,UAAU;sBAC9C,QAAQ,0BAA0B,UAAU;CACjE,CACE,CAAC;AACJ,CAAC"}