@shrkcrft/inspector 0.1.0-alpha.1

package/dist/adoption-check.js

@@ -0,0 +1,181 @@
+/**
+ * Validate adoption-patch applicability without applying it. For unified diffs
+ * we delegate to `git apply --check` when git is on PATH; for pseudo diffs we
+ * validate referenced files exist and target hashes still match.
+ *
+ * Read-only. We never run `git apply` without `--check`, and we never modify
+ * any target file.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { adoptionDir, readAdoptionState } from "./adoption-state.js";
+import { validatePatchTargets } from "./onboarding-adoption.js";
+export var AdoptionCheckResult;
+(function (AdoptionCheckResult) {
+    AdoptionCheckResult["CanApply"] = "can-apply";
+    AdoptionCheckResult["CannotApply"] = "cannot-apply";
+    AdoptionCheckResult["Unknown"] = "unknown";
+})(AdoptionCheckResult || (AdoptionCheckResult = {}));
+function detectPatchFormat(body) {
+    if (/^# Format: unified/m.test(body) || /^new file mode/m.test(body) || /^@@ -\d+,\d+ \+\d+,\d+ @@/m.test(body)) {
+        return 'unified';
+    }
+    if (/^@@ append @@/m.test(body))
+        return 'pseudo';
+    return 'unknown';
+}
+function gitAvailable() {
+    try {
+        const res = spawnSync('git', ['--version'], { stdio: 'pipe', encoding: 'utf8' });
+        return res.status === 0;
+    }
+    catch {
+        return false;
+    }
+}
+function gitApplyCheck(projectRoot, patchPath) {
+    const res = spawnSync('git', ['apply', '--check', patchPath], {
+        cwd: projectRoot,
+        stdio: 'pipe',
+        encoding: 'utf8',
+        timeout: 30_000,
+    });
+    return { passed: (res.status ?? -1) === 0, stderr: res.stderr ?? '' };
+}
+export function buildAdoptionCheck(input) {
+    const state = readAdoptionState(input.projectRoot);
+    const dir = adoptionDir(input.projectRoot);
+    const patchPath = input.patchPath ?? nodePath.join(dir, 'adopt.patch');
+    const checks = [];
+    const warnings = [];
+    if (!existsSync(patchPath)) {
+        checks.push({
+            id: 'patch-exists',
+            passed: false,
+            severity: 'error',
+            message: `adopt.patch not found at ${patchPath}`,
+        });
+        return {
+            schema: 'sharkcraft.adoption-check/v1',
+            projectRoot: input.projectRoot,
+            patchPath: null,
+            patchFormat: 'unknown',
+            canApply: AdoptionCheckResult.CannotApply,
+            checks,
+            warnings,
+            nextCommand: 'shrk onboard adopt --write-patch --diff-format unified',
+        };
+    }
+    checks.push({
+        id: 'patch-exists',
+        passed: true,
+        severity: 'info',
+        message: `adopt.patch present at ${patchPath}`,
+    });
+    const body = readFileSync(patchPath, 'utf8');
+    const format = detectPatchFormat(body);
+    checks.push({
+        id: 'patch-format-detected',
+        passed: format !== 'unknown',
+        severity: format === 'unknown' ? 'warning' : 'info',
+        message: format === 'unknown' ? 'patch format could not be detected' : `patch format: ${format}`,
+    });
+    let targetCheckPassed = true;
+    if (state) {
+        const targets = state.targetFiles.map((t) => ({
+            relativePath: t.relativePath,
+            existed: t.hash !== '(missing)',
+            ...(t.hash !== '(missing)' ? { beforeHash: t.hash } : {}),
+            bytesAdded: 0,
+        }));
+        const v = validatePatchTargets(input.projectRoot, targets);
+        if (v.changed.length > 0) {
+            targetCheckPassed = false;
+            checks.push({
+                id: 'target-hashes-stable',
+                passed: false,
+                severity: 'warning',
+                message: `${v.changed.length} target file(s) changed since the patch was generated: ${v.changed.map((c) => c.relativePath).join(', ')}`,
+            });
+            warnings.push('regenerate the patch with `shrk onboard adopt regenerate` before applying');
+        }
+        else {
+            checks.push({
+                id: 'target-hashes-stable',
+                passed: true,
+                severity: 'info',
+                message: 'every target file matches the hash recorded in adoption-state.json',
+            });
+        }
+    }
+    else {
+        checks.push({
+            id: 'adoption-state-present',
+            passed: false,
+            severity: 'warning',
+            message: 'no adoption-state.json — target hash validation skipped',
+        });
+        warnings.push('run with --write-patch to write a fresh adoption state');
+    }
+    let gitOk = 'skipped';
+    let gitMsg = '';
+    if (format === 'unified') {
+        if (gitAvailable()) {
+            const r = gitApplyCheck(input.projectRoot, patchPath);
+            gitOk = r.passed ? 'ok' : 'fail';
+            gitMsg = r.stderr.slice(0, 800);
+            checks.push({
+                id: 'git-apply-check',
+                passed: r.passed,
+                severity: r.passed ? 'info' : 'error',
+                message: r.passed ? 'git apply --check succeeded' : `git apply --check failed: ${gitMsg.split('\n').slice(0, 3).join(' | ')}`,
+            });
+        }
+        else {
+            checks.push({
+                id: 'git-apply-check',
+                passed: false,
+                severity: 'info',
+                message: 'git not available — skipping git apply --check',
+            });
+        }
+    }
+    else if (format === 'pseudo') {
+        checks.push({
+            id: 'pseudo-format-info',
+            passed: true,
+            severity: 'info',
+            message: 'pseudo-patch format — git apply is not expected to succeed; copy blocks manually',
+        });
+    }
+    // Final verdict.
+    let canApply = AdoptionCheckResult.Unknown;
+    if (format === 'unified' && gitOk === 'ok' && targetCheckPassed) {
+        canApply = AdoptionCheckResult.CanApply;
+    }
+    else if (format === 'unified' && gitOk === 'fail') {
+        canApply = AdoptionCheckResult.CannotApply;
+    }
+    else if (format === 'pseudo') {
+        canApply = AdoptionCheckResult.Unknown;
+    }
+    else if (!targetCheckPassed) {
+        canApply = AdoptionCheckResult.CannotApply;
+    }
+    const nextCommand = canApply === AdoptionCheckResult.CanApply
+        ? `git apply ${patchPath}`
+        : canApply === AdoptionCheckResult.CannotApply
+            ? 'shrk onboard adopt regenerate'
+            : 'shrk onboard adopt merge-preview --format markdown';
+    return {
+        schema: 'sharkcraft.adoption-check/v1',
+        projectRoot: input.projectRoot,
+        patchPath,
+        patchFormat: format,
+        canApply,
+        checks,
+        warnings,
+        nextCommand,
+    };
+}

package/dist/adoption-checkpoint.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Shared adoption checkpoint state.
+ *
+ * Tracks the latest diff/patch/target/draft hash for both onboard adoption
+ * (`sharkcraft/onboarding/adoption/`) and construct adoption
+ * (`sharkcraft/construct-drafts/adoption/`). Used by `status` and `diff`
+ * commands to answer: "is the persisted state still up-to-date?"
+ */
+export declare const ADOPTION_CHECKPOINT_SCHEMA = "sharkcraft.adoption-checkpoint/v1";
+export type AdoptionCheckpointKind = 'onboard' | 'construct';
+export declare enum AdoptionCheckpointStatus {
+    Fresh = "fresh",
+    UpToDate = "up-to-date",
+    StaleDraft = "stale-draft",
+    StaleTarget = "stale-target",
+    StaleDiff = "stale-diff",
+    StaleAge = "stale-age",
+    NeedsRegenerate = "needs-regenerate",
+    Missing = "missing"
+}
+/** Default max age in days before an otherwise up-to-date checkpoint is
+ *  flagged as stale-age. */
+export declare const DEFAULT_CHECKPOINT_MAX_AGE_DAYS = 30;
+export interface IAdoptionCheckpoint {
+    schema: typeof ADOPTION_CHECKPOINT_SCHEMA;
+    kind: AdoptionCheckpointKind;
+    generatedAt: string;
+    command: string;
+    diffHash: string;
+    patchHash?: string;
+    /** target relative path → sha256 hex of contents at checkpoint time. */
+    targetHashes: Record<string, string>;
+    /** draft relative path → sha256 hex of contents at checkpoint time. */
+    draftHashes: Record<string, string>;
+}
+export interface IAdoptionCheckpointReadResult {
+    exists: boolean;
+    path: string | null;
+    checkpoint: IAdoptionCheckpoint | null;
+    parseError?: string;
+}
+export declare function adoptionCheckpointPath(projectRoot: string, kind: AdoptionCheckpointKind): string;
+export declare function readAdoptionCheckpoint(projectRoot: string, kind: AdoptionCheckpointKind): IAdoptionCheckpointReadResult;
+export declare function hashContent(s: string): string;
+/** Hash a rendered diff body for checkpoint comparison. Equivalent to
+ *  `hashContent` but strips volatile fields like `generatedAt` first. */
+export declare function hashDiffBody(jsonBody: string): string;
+export declare function hashFileIfExists(file: string): string | null;
+export interface IWriteAdoptionCheckpointInput {
+    projectRoot: string;
+    kind: AdoptionCheckpointKind;
+    command: string;
+    /** Hash of the rendered diff body. */
+    diffHash: string;
+    /** Optional hash of the rendered patch body. */
+    patchHash?: string;
+    /** Files (relative to project root) the adoption would touch. */
+    targets: readonly string[];
+    /** Draft files (relative to project root) used to produce the plan. */
+    drafts: readonly string[];
+}
+export declare function writeAdoptionCheckpoint(input: IWriteAdoptionCheckpointInput): IAdoptionCheckpoint;
+export interface IAdoptionCheckpointEvaluation {
+    status: AdoptionCheckpointStatus;
+    reasons: readonly string[];
+    /** Targets whose hash diverged from the checkpoint. */
+    changedTargets: readonly string[];
+    /** Drafts whose hash diverged from the checkpoint. */
+    changedDrafts: readonly string[];
+    /** Diff hash on disk (if different). */
+    currentDiffHash?: string;
+    /** Age of the checkpoint in whole days. */
+    ageDays?: number;
+    /** True when content hashes still match but the checkpoint is
+     *  older than maxAgeDays. */
+    ageWarning?: boolean;
+}
+export interface IAdoptionCheckpointEvaluateOptions {
+    targets?: readonly string[];
+    drafts?: readonly string[];
+    /** Max age in days before stale-age status. Default 30. */
+    maxAgeDays?: number;
+    /** Override current date (mainly for tests). */
+    now?: Date;
+}
+export declare function evaluateAdoptionCheckpoint(projectRoot: string, checkpoint: IAdoptionCheckpoint | null, currentDiffHash: string, options?: IAdoptionCheckpointEvaluateOptions): IAdoptionCheckpointEvaluation;
+export interface IRecordAdoptionCheckpointInput {
+    projectRoot: string;
+    kind: AdoptionCheckpointKind;
+    command: string;
+    diffHash: string;
+    patchHash?: string;
+    targets: readonly string[];
+    drafts: readonly string[];
+}
+export declare function recordAdoptionCheckpoint(input: IRecordAdoptionCheckpointInput): IAdoptionCheckpoint;
+//# sourceMappingURL=adoption-checkpoint.d.ts.map

package/dist/adoption-checkpoint.d.ts.map

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

package/dist/adoption-checkpoint.js

@@ -0,0 +1,209 @@
+/**
+ * Shared adoption checkpoint state.
+ *
+ * Tracks the latest diff/patch/target/draft hash for both onboard adoption
+ * (`sharkcraft/onboarding/adoption/`) and construct adoption
+ * (`sharkcraft/construct-drafts/adoption/`). Used by `status` and `diff`
+ * commands to answer: "is the persisted state still up-to-date?"
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+export const ADOPTION_CHECKPOINT_SCHEMA = 'sharkcraft.adoption-checkpoint/v1';
+export var AdoptionCheckpointStatus;
+(function (AdoptionCheckpointStatus) {
+    AdoptionCheckpointStatus["Fresh"] = "fresh";
+    AdoptionCheckpointStatus["UpToDate"] = "up-to-date";
+    AdoptionCheckpointStatus["StaleDraft"] = "stale-draft";
+    AdoptionCheckpointStatus["StaleTarget"] = "stale-target";
+    AdoptionCheckpointStatus["StaleDiff"] = "stale-diff";
+    AdoptionCheckpointStatus["StaleAge"] = "stale-age";
+    AdoptionCheckpointStatus["NeedsRegenerate"] = "needs-regenerate";
+    AdoptionCheckpointStatus["Missing"] = "missing";
+})(AdoptionCheckpointStatus || (AdoptionCheckpointStatus = {}));
+/** Default max age in days before an otherwise up-to-date checkpoint is
+ *  flagged as stale-age. */
+export const DEFAULT_CHECKPOINT_MAX_AGE_DAYS = 30;
+function checkpointDir(projectRoot, kind) {
+    if (kind === 'onboard') {
+        return nodePath.join(projectRoot, 'sharkcraft', 'onboarding', 'adoption');
+    }
+    return nodePath.join(projectRoot, 'sharkcraft', 'construct-drafts', 'adoption');
+}
+export function adoptionCheckpointPath(projectRoot, kind) {
+    return nodePath.join(checkpointDir(projectRoot, kind), 'adoption-checkpoint.json');
+}
+export function readAdoptionCheckpoint(projectRoot, kind) {
+    const path = adoptionCheckpointPath(projectRoot, kind);
+    if (!existsSync(path)) {
+        return { exists: false, path, checkpoint: null };
+    }
+    try {
+        const data = JSON.parse(readFileSync(path, 'utf8'));
+        if (data.schema !== ADOPTION_CHECKPOINT_SCHEMA) {
+            return {
+                exists: true,
+                path,
+                checkpoint: null,
+                parseError: `Unexpected schema: ${data.schema ?? '(none)'}`,
+            };
+        }
+        return { exists: true, path, checkpoint: data };
+    }
+    catch (e) {
+        return { exists: true, path, checkpoint: null, parseError: e.message };
+    }
+}
+export function hashContent(s) {
+    return createHash('sha256').update(s).digest('hex');
+}
+/**
+ * Strip non-deterministic fields (`generatedAt`, `schema`-changes) from a
+ * rendered diff so the hash is stable across runs that produce semantically
+ * equivalent output.
+ */
+function stripVolatileFields(jsonBody) {
+    try {
+        const parsed = JSON.parse(jsonBody);
+        delete parsed['generatedAt'];
+        // Sort keys for deterministic serialization.
+        return JSON.stringify(parsed, Object.keys(parsed).sort());
+    }
+    catch {
+        return jsonBody;
+    }
+}
+/** Hash a rendered diff body for checkpoint comparison. Equivalent to
+ *  `hashContent` but strips volatile fields like `generatedAt` first. */
+export function hashDiffBody(jsonBody) {
+    return hashContent(stripVolatileFields(jsonBody));
+}
+export function hashFileIfExists(file) {
+    if (!existsSync(file))
+        return null;
+    try {
+        return hashContent(readFileSync(file, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function writeAdoptionCheckpoint(input) {
+    const targetHashes = {};
+    for (const rel of input.targets) {
+        const hash = hashFileIfExists(nodePath.resolve(input.projectRoot, rel));
+        targetHashes[rel] = hash ?? '(missing)';
+    }
+    const draftHashes = {};
+    for (const rel of input.drafts) {
+        const hash = hashFileIfExists(nodePath.resolve(input.projectRoot, rel));
+        draftHashes[rel] = hash ?? '(missing)';
+    }
+    const checkpoint = {
+        schema: ADOPTION_CHECKPOINT_SCHEMA,
+        kind: input.kind,
+        generatedAt: new Date().toISOString(),
+        command: input.command,
+        diffHash: input.diffHash,
+        ...(input.patchHash ? { patchHash: input.patchHash } : {}),
+        targetHashes,
+        draftHashes,
+    };
+    const path = adoptionCheckpointPath(input.projectRoot, input.kind);
+    mkdirSync(nodePath.dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(checkpoint, null, 2) + '\n', 'utf8');
+    return checkpoint;
+}
+function computeAgeDays(checkpoint, now) {
+    const generated = Date.parse(checkpoint.generatedAt);
+    if (!Number.isFinite(generated))
+        return 0;
+    const diffMs = now.getTime() - generated;
+    return Math.max(0, Math.floor(diffMs / (1000 * 60 * 60 * 24)));
+}
+export function evaluateAdoptionCheckpoint(projectRoot, checkpoint, currentDiffHash, options = {}) {
+    if (!checkpoint) {
+        return {
+            status: AdoptionCheckpointStatus.Missing,
+            reasons: ['no adoption checkpoint on disk yet — run with --record-checkpoint'],
+            changedTargets: [],
+            changedDrafts: [],
+        };
+    }
+    const reasons = [];
+    const changedTargets = [];
+    const changedDrafts = [];
+    for (const [rel, recorded] of Object.entries(checkpoint.targetHashes)) {
+        if (options.targets && !options.targets.includes(rel))
+            continue;
+        const current = hashFileIfExists(nodePath.resolve(projectRoot, rel)) ?? '(missing)';
+        if (current !== recorded) {
+            changedTargets.push(rel);
+        }
+    }
+    for (const [rel, recorded] of Object.entries(checkpoint.draftHashes)) {
+        if (options.drafts && !options.drafts.includes(rel))
+            continue;
+        const current = hashFileIfExists(nodePath.resolve(projectRoot, rel)) ?? '(missing)';
+        if (current !== recorded) {
+            changedDrafts.push(rel);
+        }
+    }
+    const diffChanged = checkpoint.diffHash !== currentDiffHash;
+    const now = options.now ?? new Date();
+    const ageDays = computeAgeDays(checkpoint, now);
+    const maxAgeDays = options.maxAgeDays ?? DEFAULT_CHECKPOINT_MAX_AGE_DAYS;
+    const tooOld = maxAgeDays > 0 && ageDays > maxAgeDays;
+    if (changedDrafts.length === 0 && changedTargets.length === 0 && !diffChanged) {
+        if (tooOld) {
+            return {
+                status: AdoptionCheckpointStatus.StaleAge,
+                reasons: [
+                    `hashes match but checkpoint is ${ageDays} day(s) old (max ${maxAgeDays}) — consider re-recording`,
+                ],
+                changedTargets,
+                changedDrafts,
+                currentDiffHash,
+                ageDays,
+                ageWarning: true,
+            };
+        }
+        return {
+            status: AdoptionCheckpointStatus.UpToDate,
+            reasons: ['drafts, targets and diff hash all match the checkpoint'],
+            changedTargets,
+            changedDrafts,
+            currentDiffHash,
+            ageDays,
+            ageWarning: false,
+        };
+    }
+    if (changedDrafts.length > 0) {
+        reasons.push(`${changedDrafts.length} draft(s) changed since checkpoint`);
+    }
+    if (changedTargets.length > 0) {
+        reasons.push(`${changedTargets.length} target(s) changed since checkpoint`);
+    }
+    if (diffChanged) {
+        reasons.push('diff hash no longer matches the checkpoint');
+    }
+    let status = AdoptionCheckpointStatus.NeedsRegenerate;
+    if (changedDrafts.length > 0)
+        status = AdoptionCheckpointStatus.StaleDraft;
+    else if (changedTargets.length > 0)
+        status = AdoptionCheckpointStatus.StaleTarget;
+    else if (diffChanged)
+        status = AdoptionCheckpointStatus.StaleDiff;
+    return {
+        status,
+        reasons,
+        changedTargets,
+        changedDrafts,
+        currentDiffHash,
+        ageDays,
+        ageWarning: tooOld,
+    };
+}
+export function recordAdoptionCheckpoint(input) {
+    return writeAdoptionCheckpoint(input);
+}

package/dist/adoption-merge-preview.d.ts

@@ -0,0 +1,28 @@
+import { type IAdoptionItem, type IAdoptionPlan } from './onboarding-adoption.js';
+import { type IAdoptionState, type IComputeFreshnessResult } from './adoption-state.js';
+import { type IThreeWayPreviewBatchResult } from './adoption-three-way.js';
+export type AdoptionMergePreviewFormat = 'text' | 'markdown' | 'html' | 'json';
+export interface IAdoptionMergePreview {
+    schema: 'sharkcraft.adoption-merge-preview/v1';
+    projectRoot: string;
+    state: IAdoptionState | null;
+    freshness: IComputeFreshnessResult;
+    threeWay: IThreeWayPreviewBatchResult;
+    safeAppend: readonly IAdoptionItem[];
+    manualReview: readonly IAdoptionItem[];
+    lowConfidence: readonly IAdoptionItem[];
+    alreadyCovered: readonly IAdoptionItem[];
+    conflicts: readonly IAdoptionItem[];
+    recommendedCommands: readonly string[];
+}
+export interface IBuildMergePreviewInput {
+    projectRoot: string;
+    plan: IAdoptionPlan;
+}
+export declare function buildAdoptionMergePreview(input: IBuildMergePreviewInput): IAdoptionMergePreview;
+export declare function renderAdoptionMergePreviewText(p: IAdoptionMergePreview): string;
+export declare function renderAdoptionMergePreviewMarkdown(p: IAdoptionMergePreview): string;
+export declare function renderAdoptionMergePreviewHtml(p: IAdoptionMergePreview): string;
+/** Reusable: read the unified patch body if it exists. */
+export declare function loadAdoptPatchBody(projectRoot: string): string | null;
+//# sourceMappingURL=adoption-merge-preview.d.ts.map

package/dist/adoption-merge-preview.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adoption-merge-preview.d.ts","sourceRoot":"","sources":["../src/adoption-merge-preview.ts"],"names":[],"mappings":"AAMA,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,aAAa,EACnB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,uBAAuB,EAC7B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAGL,KAAK,2BAA2B,EACjC,MAAM,yBAAyB,CAAC;AAEjC,MAAM,MAAM,0BAA0B,GAAG,MAAM,GAAG,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AAE/E,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,sCAAsC,CAAC;IAC/C,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,cAAc,GAAG,IAAI,CAAC;IAC7B,SAAS,EAAE,uBAAuB,CAAC;IACnC,QAAQ,EAAE,2BAA2B,CAAC;IACtC,UAAU,EAAE,SAAS,aAAa,EAAE,CAAC;IACrC,YAAY,EAAE,SAAS,aAAa,EAAE,CAAC;IACvC,aAAa,EAAE,SAAS,aAAa,EAAE,CAAC;IACxC,cAAc,EAAE,SAAS,aAAa,EAAE,CAAC;IACzC,SAAS,EAAE,SAAS,aAAa,EAAE,CAAC;IACpC,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAED,MAAM,WAAW,uBAAuB;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,aAAa,CAAC;CACrB;AAED,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,uBAAuB,GAC7B,qBAAqB,CAwBvB;AA4CD,wBAAgB,8BAA8B,CAAC,CAAC,EAAE,qBAAqB,GAAG,MAAM,CA+B/E;AAED,wBAAgB,kCAAkC,CAAC,CAAC,EAAE,qBAAqB,GAAG,MAAM,CA4CnF;AA8CD,wBAAgB,8BAA8B,CAAC,CAAC,EAAE,qBAAqB,GAAG,MAAM,CA6C/E;AAiBD,0DAA0D;AAC1D,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAIrE"}