maestro-flow 0.1.4 → 0.2.1

package/dist/src/tools/team-activity.js

@@ -0,0 +1,159 @@
+/**
+ * Human-team activity log (team-lite collaboration, Wave 2).
+ *
+ * Owns `.workflow/collab/activity.jsonl` — append-only activity bus shared
+ * across a small human team. Each entry records "who did what, when, where".
+ *
+ * Strict namespace separation: this module belongs to the HUMAN collaboration
+ * domain (`.workflow/collab/`) and must NEVER touch `.workflow/.team/` which
+ * is the agent pipeline message bus owned by `src/tools/team-msg.ts`.
+ *
+ * Hot-path contract: `reportActivity` is called from PostToolUse hooks and
+ * must NEVER throw. The underlying `appendLine` from `src/utils/jsonl-log.ts`
+ * already swallows errors; we rely on that and add best-effort wrappers.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getProjectRoot } from '../utils/path-validator.js';
+import { appendLine, tailLast, rotateIfLarge } from '../utils/jsonl-log.js';
+// Max lines read from the tail for recent-activity queries. Cap matches
+// the preflight algorithm described in docs/team-lite-design.md (section
+// "耦合 3"): 500 lines is plenty for a ±35 min window on a small team.
+const RECENT_READ_LIMIT = 500;
+// Clock tolerance (minutes): include events slightly older than the window
+// edge to account for cross-machine clock drift. Matches design doc.
+const CLOCK_TOLERANCE_MIN = 5;
+// Default rotation threshold: 10 MB.
+const DEFAULT_ROTATE_BYTES = 10 * 1024 * 1024;
+// ---------------------------------------------------------------------------
+// Path helpers
+// ---------------------------------------------------------------------------
+/** Absolute path to the current activity log. */
+export function getActivityLogPath() {
+    return join(getProjectRoot(), '.workflow', 'collab', 'activity.jsonl');
+}
+/** Absolute path to the activity archive directory. */
+export function getArchiveDir() {
+    return join(getProjectRoot(), '.workflow', 'collab', 'activity-archives');
+}
+function getStateJsonPath() {
+    return join(getProjectRoot(), '.workflow', 'state.json');
+}
+// ---------------------------------------------------------------------------
+// Write path
+// ---------------------------------------------------------------------------
+/**
+ * Append an activity event to the shared log.
+ *
+ * - `ts` is auto-filled to `new Date().toISOString()` if omitted.
+ * - Silently no-ops on any error — this is called from hot paths.
+ */
+export function reportActivity(evt) {
+    try {
+        const full = {
+            ts: evt.ts ?? new Date().toISOString(),
+            user: evt.user,
+            host: evt.host,
+            action: evt.action,
+            ...(evt.phase_id !== undefined ? { phase_id: evt.phase_id } : {}),
+            ...(evt.task_id !== undefined ? { task_id: evt.task_id } : {}),
+            ...(evt.target !== undefined ? { target: evt.target } : {}),
+        };
+        appendLine(getActivityLogPath(), full);
+    }
+    catch {
+        // Hot path — never throw.
+    }
+}
+// ---------------------------------------------------------------------------
+// Read path
+// ---------------------------------------------------------------------------
+/**
+ * Return activity events from the last `windowMinutes` minutes.
+ *
+ * Algorithm (matches docs/team-lite-design.md section "耦合 3"):
+ *   1. Tail the last 500 lines of activity.jsonl.
+ *   2. Drop malformed entries (`tailLast` already does this).
+ *   3. Keep events with `ts >= now - (windowMinutes + CLOCK_TOLERANCE_MIN)`
+ *      to absorb cross-machine clock drift.
+ *
+ * Results are returned in the natural tail order (oldest -> newest), which
+ * is what `team status` wants for grouping by user.
+ */
+export function readRecentActivity(windowMinutes) {
+    if (windowMinutes <= 0)
+        return [];
+    const entries = tailLast(getActivityLogPath(), RECENT_READ_LIMIT);
+    if (entries.length === 0)
+        return [];
+    const cutoff = Date.now() - (windowMinutes + CLOCK_TOLERANCE_MIN) * 60 * 1000;
+    const out = [];
+    for (const e of entries) {
+        if (!e || typeof e.ts !== 'string')
+            continue;
+        const t = Date.parse(e.ts);
+        if (Number.isNaN(t))
+            continue;
+        if (t >= cutoff)
+            out.push(e);
+    }
+    return out;
+}
+/**
+ * Read the current workflow context from `.workflow/state.json`.
+ *
+ * Returns:
+ *   - `phase_id` from `current_phase` (if present & numeric)
+ *   - `task_id`  from `current_task_id` (if present & string)
+ *
+ * Both fields are optional. Missing state file, parse errors, or missing
+ * fields return `{}` — callers tag activity events with whatever is known.
+ *
+ * Note: `current_task_id` depends on P0.1 which may not be landed yet.
+ */
+export function readWorkflowContext() {
+    const statePath = getStateJsonPath();
+    if (!existsSync(statePath))
+        return {};
+    let raw;
+    try {
+        raw = readFileSync(statePath, 'utf-8');
+    }
+    catch {
+        return {};
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return {};
+    const obj = parsed;
+    const out = {};
+    if (typeof obj.current_phase === 'number') {
+        out.phase_id = obj.current_phase;
+    }
+    if (typeof obj.current_task_id === 'string' && obj.current_task_id) {
+        out.task_id = obj.current_task_id;
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Maintenance
+// ---------------------------------------------------------------------------
+/**
+ * Rotate the activity log if it exceeds `maxBytes`.
+ *
+ * Delegates to `rotateIfLarge` in `src/utils/jsonl-log.ts`, which moves the
+ * file to `.workflow/collab/activity-archives/activity-{YYYY}W{WW}.jsonl`.
+ *
+ * Returns the archive path on success, or `null` if rotation did not run
+ * (file missing, below threshold, or I/O error).
+ */
+export function rotateIfNeeded(maxBytes = DEFAULT_ROTATE_BYTES) {
+    return rotateIfLarge(getActivityLogPath(), maxBytes, getArchiveDir());
+}
+//# sourceMappingURL=team-activity.js.map

package/dist/src/tools/team-activity.js.map

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

package/dist/src/tools/team-members.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Human-team member registry (team-lite collaboration, Wave 2).
+ *
+ * Owns `.workflow/collab/members/{uid}.json` — per-file member records.
+ *
+ * Strict namespace separation: this module belongs to the HUMAN collaboration
+ * domain (`.workflow/collab/`). It must NEVER touch `.workflow/.team/` which
+ * is the agent pipeline message bus owned by `src/tools/team-msg.ts`.
+ *
+ * Per-file layout is deliberate: each member writes their own JSON file so
+ * two concurrent `maestro team join` on different machines never collide on
+ * git merge (vs. a single `members.json` which cannot `merge=union`).
+ */
+export interface MemberRecord {
+    uid: string;
+    name: string;
+    email: string;
+    host: string;
+    role: 'admin' | 'member';
+    joinedAt: string;
+}
+/** Absolute path to the human-collab members directory. */
+export declare function getMembersDir(): string;
+/**
+ * Resolve local git identity via `git config user.name` / `user.email`.
+ * Returns null if either is missing or git is unavailable.
+ */
+export declare function readGitIdentity(): {
+    name: string;
+    email: string;
+} | null;
+/**
+ * Derive a uid from an email address.
+ *
+ * Rule: take the local-part (before '@'), lowercase it.
+ *   "Alice@Example.COM" -> "alice"
+ *
+ * Collision handling is NOT done here — callers must check `getMembersDir`
+ * and append `-2`, `-3`, ... as needed (see `joinTeam`).
+ */
+export declare function deriveUid(email: string): string;
+/** Return the machine hostname. Exported so tests can stub if needed. */
+export declare function getHost(): string;
+/**
+ * List all known members. Returns an empty array if the directory does not
+ * exist yet. Files that fail to parse as `MemberRecord` JSON are skipped
+ * silently — corrupt files should not break `whoami` / `status`.
+ */
+export declare function listMembers(): MemberRecord[];
+/** Read a single member by uid, or null if the file does not exist. */
+export declare function getMemberByUid(uid: string): MemberRecord | null;
+/**
+ * Return the member record matching the current git identity.
+ *
+ * Matching uses `email` (case-insensitive), NOT just `uid`, so two users who
+ * happened to get the same local-part on different domains still resolve to
+ * their own record.
+ *
+ * Returns null if git identity is unavailable or no record matches.
+ */
+export declare function resolveSelf(): MemberRecord | null;
+/**
+ * Join the team. Idempotent.
+ *
+ * Flow:
+ *   1. Read git identity (throws if name/email missing — cannot join without it).
+ *   2. If a record with the same email already exists, return it unchanged
+ *      (preserves `joinedAt` and any prior `role`).
+ *   3. Derive uid from email local-part. If another member with a different
+ *      email already owns that uid, append `-2`, `-3`, ... until free.
+ *   4. Assign role: explicit `opts.role` wins; otherwise the very first member
+ *      to join becomes `admin`, everyone after is `member`.
+ *   5. Write `.workflow/collab/members/{uid}.json` atomically via `writeFileSync`.
+ */
+export declare function joinTeam(opts?: {
+    role?: 'admin' | 'member';
+}): MemberRecord;
+//# sourceMappingURL=team-members.d.ts.map

package/dist/src/tools/team-members.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"team-members.d.ts","sourceRoot":"","sources":["../../../src/tools/team-members.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAeH,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,GAAG,QAAQ,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAMD,2DAA2D;AAC3D,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAUD;;;GAGG;AACH,wBAAgB,eAAe,IAAI;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAKxE;AAcD;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAI/C;AAED,yEAAyE;AACzE,wBAAgB,OAAO,IAAI,MAAM,CAEhC;AAMD;;;;GAIG;AACH,wBAAgB,WAAW,IAAI,YAAY,EAAE,CAkB5C;AAED,uEAAuE;AACvE,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAI/D;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,IAAI,YAAY,GAAG,IAAI,CAQjD;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,QAAQ,CAAC,IAAI,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAA;CAAE,GAAG,YAAY,CAkC3E"}

package/dist/src/tools/team-members.js

@@ -0,0 +1,222 @@
+/**
+ * Human-team member registry (team-lite collaboration, Wave 2).
+ *
+ * Owns `.workflow/collab/members/{uid}.json` — per-file member records.
+ *
+ * Strict namespace separation: this module belongs to the HUMAN collaboration
+ * domain (`.workflow/collab/`). It must NEVER touch `.workflow/.team/` which
+ * is the agent pipeline message bus owned by `src/tools/team-msg.ts`.
+ *
+ * Per-file layout is deliberate: each member writes their own JSON file so
+ * two concurrent `maestro team join` on different machines never collide on
+ * git merge (vs. a single `members.json` which cannot `merge=union`).
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, } from 'node:fs';
+import { join } from 'node:path';
+import { hostname } from 'node:os';
+import { execSync } from 'node:child_process';
+import { getProjectRoot } from '../utils/path-validator.js';
+// ---------------------------------------------------------------------------
+// Path helpers
+// ---------------------------------------------------------------------------
+/** Absolute path to the human-collab members directory. */
+export function getMembersDir() {
+    return join(getProjectRoot(), '.workflow', 'collab', 'members');
+}
+function getMemberFilePath(uid) {
+    return join(getMembersDir(), `${uid}.json`);
+}
+// ---------------------------------------------------------------------------
+// Identity helpers
+// ---------------------------------------------------------------------------
+/**
+ * Resolve local git identity via `git config user.name` / `user.email`.
+ * Returns null if either is missing or git is unavailable.
+ */
+export function readGitIdentity() {
+    const name = tryGitConfig('user.name');
+    const email = tryGitConfig('user.email');
+    if (!name || !email)
+        return null;
+    return { name, email };
+}
+function tryGitConfig(key) {
+    try {
+        const out = execSync(`git config ${key}`, {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+        return out || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Derive a uid from an email address.
+ *
+ * Rule: take the local-part (before '@'), lowercase it.
+ *   "Alice@Example.COM" -> "alice"
+ *
+ * Collision handling is NOT done here — callers must check `getMembersDir`
+ * and append `-2`, `-3`, ... as needed (see `joinTeam`).
+ */
+export function deriveUid(email) {
+    const at = email.indexOf('@');
+    const local = at >= 0 ? email.slice(0, at) : email;
+    return local.trim().toLowerCase();
+}
+/** Return the machine hostname. Exported so tests can stub if needed. */
+export function getHost() {
+    return hostname();
+}
+// ---------------------------------------------------------------------------
+// Reads
+// ---------------------------------------------------------------------------
+/**
+ * List all known members. Returns an empty array if the directory does not
+ * exist yet. Files that fail to parse as `MemberRecord` JSON are skipped
+ * silently — corrupt files should not break `whoami` / `status`.
+ */
+export function listMembers() {
+    const dir = getMembersDir();
+    if (!existsSync(dir))
+        return [];
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const entry of entries) {
+        if (!entry.endsWith('.json'))
+            continue;
+        const rec = readMemberFile(join(dir, entry));
+        if (rec)
+            out.push(rec);
+    }
+    return out;
+}
+/** Read a single member by uid, or null if the file does not exist. */
+export function getMemberByUid(uid) {
+    const path = getMemberFilePath(uid);
+    if (!existsSync(path))
+        return null;
+    return readMemberFile(path);
+}
+/**
+ * Return the member record matching the current git identity.
+ *
+ * Matching uses `email` (case-insensitive), NOT just `uid`, so two users who
+ * happened to get the same local-part on different domains still resolve to
+ * their own record.
+ *
+ * Returns null if git identity is unavailable or no record matches.
+ */
+export function resolveSelf() {
+    const ident = readGitIdentity();
+    if (!ident)
+        return null;
+    const target = ident.email.toLowerCase();
+    for (const m of listMembers()) {
+        if (m.email.toLowerCase() === target)
+            return m;
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Writes
+// ---------------------------------------------------------------------------
+/**
+ * Join the team. Idempotent.
+ *
+ * Flow:
+ *   1. Read git identity (throws if name/email missing — cannot join without it).
+ *   2. If a record with the same email already exists, return it unchanged
+ *      (preserves `joinedAt` and any prior `role`).
+ *   3. Derive uid from email local-part. If another member with a different
+ *      email already owns that uid, append `-2`, `-3`, ... until free.
+ *   4. Assign role: explicit `opts.role` wins; otherwise the very first member
+ *      to join becomes `admin`, everyone after is `member`.
+ *   5. Write `.workflow/collab/members/{uid}.json` atomically via `writeFileSync`.
+ */
+export function joinTeam(opts) {
+    const ident = readGitIdentity();
+    if (!ident) {
+        throw new Error('Git identity not configured. Run `git config user.name "Your Name"` and ' +
+            '`git config user.email "you@example.com"` before joining.');
+    }
+    // Idempotency: same email already registered -> return existing record.
+    const existing = resolveSelf();
+    if (existing)
+        return existing;
+    const dir = getMembersDir();
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    const base = deriveUid(ident.email);
+    const uid = allocateUid(base, ident.email);
+    // Role: explicit wins. Otherwise first-joiner is admin.
+    const role = opts?.role ?? (listMembers().length === 0 ? 'admin' : 'member');
+    const record = {
+        uid,
+        name: ident.name,
+        email: ident.email,
+        host: getHost(),
+        role,
+        joinedAt: new Date().toISOString(),
+    };
+    writeFileSync(getMemberFilePath(uid), JSON.stringify(record, null, 2), 'utf-8');
+    return record;
+}
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+function readMemberFile(path) {
+    try {
+        const raw = readFileSync(path, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.uid === 'string' &&
+            typeof parsed.name === 'string' &&
+            typeof parsed.email === 'string' &&
+            typeof parsed.host === 'string' &&
+            (parsed.role === 'admin' || parsed.role === 'member') &&
+            typeof parsed.joinedAt === 'string') {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Allocate a free uid derived from `base`.
+ *
+ * - If `{base}.json` does not exist, use it.
+ * - If `{base}.json` exists AND belongs to the same email, reuse it
+ *   (this path is normally caught earlier by `resolveSelf`, but we keep
+ *   the safety net in case files got out of sync).
+ * - Otherwise try `{base}-2`, `{base}-3`, ... until a free slot is found.
+ */
+function allocateUid(base, email) {
+    const ownEmail = email.toLowerCase();
+    const firstPath = getMemberFilePath(base);
+    if (!existsSync(firstPath))
+        return base;
+    const existing = readMemberFile(firstPath);
+    if (existing && existing.email.toLowerCase() === ownEmail)
+        return base;
+    for (let n = 2; n < 1000; n++) {
+        const candidate = `${base}-${n}`;
+        const candidatePath = getMemberFilePath(candidate);
+        if (!existsSync(candidatePath))
+            return candidate;
+        const rec = readMemberFile(candidatePath);
+        if (rec && rec.email.toLowerCase() === ownEmail)
+            return candidate;
+    }
+    throw new Error(`Could not allocate uid for email ${email} after 1000 attempts`);
+}
+//# sourceMappingURL=team-members.js.map

package/dist/src/tools/team-members.js.map

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

package/dist/src/tools/team-msg.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Team Message Bus - JSONL-based persistent message log for Agent Teams
+ *
+ * Operations:
+ * - log:       Append a message (to defaults to "coordinator", summary auto-generated if omitted)
+ * - read:      Read message(s) by ID
+ * - list:      List recent messages with optional filters (from/to/type/last N)
+ * - status:    Summarize team member activity from message history
+ * - delete:    Delete a specific message by ID
+ * - clear:     Clear all messages for a team
+ * - broadcast: Log a message with to="all"
+ * - get_state: Read role state from meta.json
+ */
+import type { ToolSchema, CcwToolResult } from '../types/tool-schema.js';
+export interface TeamMeta {
+    status: 'active' | 'completed' | 'archived';
+    created_at: string;
+    updated_at: string;
+    archived_at?: string;
+    pipeline_mode?: string;
+    pipeline_stages?: string[];
+    team_name?: string;
+    task_description?: string;
+    roles?: string[];
+    role_state?: Record<string, Record<string, unknown>>;
+}
+export declare function getMetaPath(team: string): string;
+export declare function readTeamMeta(team: string): TeamMeta | null;
+export declare function writeTeamMeta(team: string, meta: TeamMeta): void;
+export declare function inferTeamStatus(team: string): TeamMeta['status'];
+export declare function getEffectiveTeamMeta(team: string): TeamMeta;
+export interface TeamMessage {
+    id: string;
+    ts: string;
+    from: string;
+    to: string;
+    type: string;
+    summary: string;
+    data?: Record<string, unknown>;
+}
+export interface StatusEntry {
+    member: string;
+    lastSeen: string;
+    lastAction: string;
+    messageCount: number;
+}
+export declare const schema: ToolSchema;
+export declare function getLogDir(sessionId: string): string;
+export declare function getLogDirWithFallback(sessionId: string): string;
+export declare function readAllMessages(teamId: string): TeamMessage[];
+export declare function handler(params: Record<string, unknown>): Promise<CcwToolResult>;
+//# sourceMappingURL=team-msg.d.ts.map

package/dist/src/tools/team-msg.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"team-msg.d.ts","sourceRoot":"","sources":["../../../src/tools/team-msg.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAOzE,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,QAAQ,GAAG,WAAW,GAAG,UAAU,CAAC;IAC5C,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACtD;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAQ1D;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,IAAI,CAMhE;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAKhE;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CA4C3D;AA+CD,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;CACtB;AA4BD,eAAO,MAAM,MAAM,EAAE,UAmEpB,CAAC;AAIF,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAGnD;AAED,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAO/D;AAkBD,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,EAAE,CAc7D;AAoMD,wBAAsB,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC,CAyBrF"}