mewkit 1.14.1 → 1.16.0

package/dist/visual-plan/infrastructure/receipt-repository.js

@@ -0,0 +1,59 @@
+/**
+ * Resolution-receipt storage under `<plan-dir>/visual-plan/resolutions/`.
+ *
+ * A receipt records the per-operation outcome of applying a feedback batch
+ * (applied | rejected | unresolved). Receipt EXISTENCE is the "batch resolved"
+ * marker — the batch file itself stays byte-immutable. `writeReceipt` is
+ * write-once (a second apply of the same batch is refused). The batch/receipt id
+ * is validated against the strict pattern BEFORE any path join (red-team M8).
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { isValidFeedbackBatchId } from "../domain/ids.js";
+import { ResolutionReceiptSchema } from "../domain/feedback-schemas.js";
+import { atomicWriteFileSync } from "./atomic-write.js";
+const RESOLUTIONS_DIR = path.join("visual-plan", "resolutions");
+/** Receipt path for a batch id, validating the id BEFORE the join. Throws on a bad id. */
+function receiptPath(planDir, batchId) {
+    if (!isValidFeedbackBatchId(batchId))
+        throw new Error(`invalid batch id: ${JSON.stringify(batchId)}`);
+    return path.join(planDir, RESOLUTIONS_DIR, `${batchId}.json`);
+}
+/** True when a resolution receipt already exists for this batch (⇒ already applied). */
+export function receiptExists(planDir, batchId) {
+    return fs.existsSync(receiptPath(planDir, batchId));
+}
+/** Persist a receipt write-once. Returns false if a receipt for this batch already exists. */
+export function writeReceipt(planDir, receipt) {
+    const file = receiptPath(planDir, receipt.batchId);
+    if (fs.existsSync(file))
+        return false; // double-apply guard
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    atomicWriteFileSync(file, `${JSON.stringify(receipt, null, 2)}\n`);
+    return true;
+}
+/** Read + validate every receipt in the plan (for approve's unresolved-check). */
+export function listReceipts(planDir) {
+    let entries;
+    try {
+        entries = fs.readdirSync(path.join(planDir, RESOLUTIONS_DIR));
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of entries) {
+        if (!name.endsWith(".json"))
+            continue;
+        try {
+            const parsed = ResolutionReceiptSchema.safeParse(JSON.parse(fs.readFileSync(path.join(planDir, RESOLUTIONS_DIR, name), "utf-8")));
+            if (parsed.success)
+                out.push(parsed.data);
+        }
+        catch {
+            // skip unreadable/invalid receipt
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=receipt-repository.js.map

package/dist/visual-plan/infrastructure/receipt-repository.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"receipt-repository.js","sourceRoot":"","sources":["../../../src/visual-plan/infrastructure/receipt-repository.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,uBAAuB,EAA0B,MAAM,+BAA+B,CAAC;AAChG,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAExD,MAAM,eAAe,GAAG,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,aAAa,CAAC,CAAC;AAEhE,0FAA0F;AAC1F,SAAS,WAAW,CAAC,OAAe,EAAE,OAAe;IACpD,IAAI,CAAC,sBAAsB,CAAC,OAAO,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,qBAAqB,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IACtG,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,OAAO,OAAO,CAAC,CAAC;AAC/D,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,aAAa,CAAC,OAAe,EAAE,OAAe;IAC7D,OAAO,EAAE,CAAC,UAAU,CAAC,WAAW,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;AACrD,CAAC;AAED,8FAA8F;AAC9F,MAAM,UAAU,YAAY,CAAC,OAAe,EAAE,OAA0B;IACvE,MAAM,IAAI,GAAG,WAAW,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IACnD,IAAI,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC,CAAC,qBAAqB;IAC5D,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACtD,mBAAmB,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;IACnE,OAAO,IAAI,CAAC;AACb,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,YAAY,CAAC,OAAe;IAC3C,IAAI,OAAiB,CAAC;IACtB,IAAI,CAAC;QACJ,OAAO,GAAG,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC;IAC/D,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,EAAE,CAAC;IACX,CAAC;IACD,MAAM,GAAG,GAAwB,EAAE,CAAC;IACpC,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC;YAAE,SAAS;QACtC,IAAI,CAAC;YACJ,MAAM,MAAM,GAAG,uBAAuB,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,eAAe,EAAE,IAAI,CAAC,EAAE,OAAO,CAAC,CAAY,CAAC,CAAC;YAC7I,IAAI,MAAM,CAAC,OAAO;gBAAE,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAC3C,CAAC;QAAC,MAAM,CAAC;YACR,kCAAkC;QACnC,CAAC;IACF,CAAC;IACD,OAAO,GAAG,CAAC;AACZ,CAAC"}

package/dist/visual-plan/infrastructure/visual-plan-repository.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Filesystem gateway for the canonical visual artifact.
+ *
+ * The artifact always lives at `<plan-dir>/visual-plan/plan.json`. All access
+ * goes through realpath containment: the resolved artifact path MUST stay
+ * inside the resolved plan directory, so a symlinked `visual-plan/` cannot
+ * redirect reads/writes outside the plan (non-functional requirement: no path
+ * escapes the plan directory). Writes are atomic (same-dir tmp + rename).
+ */
+import { type ValidationError } from "../domain/errors.js";
+/** Artifact location relative to the plan directory. */
+export declare const ARTIFACT_REL_PATH: string;
+/** Thrown when a plan directory or artifact path fails containment/existence checks. */
+export declare class PlanPathError extends Error {
+    constructor(message: string);
+}
+/** Resolve `input` to an existing directory's realpath. Throws `PlanPathError` otherwise. */
+export declare function resolvePlanDir(input: string): string;
+/** Absolute artifact path, guaranteed contained within `planDir` (realpath checks). */
+export declare function artifactPath(planDir: string): string;
+/** True when an artifact file exists for this plan directory. */
+export declare function artifactExists(planDir: string): boolean;
+export interface RawArtifactRead {
+    raw?: unknown;
+    error?: ValidationError;
+}
+/** Read + JSON-parse the artifact. Missing/invalid file yields a typed error, never a throw. */
+export declare function readArtifactRaw(planDir: string): RawArtifactRead;
+/**
+ * Canonical on-disk serialization for the artifact (pretty JSON + trailing
+ * newline). Exposed so a caller can hash the EXACT bytes a subsequent
+ * `writeArtifact` will persist (used by prepare-feedback for a crash-safe
+ * batch-then-artifact write order).
+ */
+export declare function serializeArtifact(artifact: unknown): string;
+/** Atomically write the artifact as canonical pretty JSON. */
+export declare function writeArtifact(planDir: string, artifact: unknown): void;
+//# sourceMappingURL=visual-plan-repository.d.ts.map

package/dist/visual-plan/infrastructure/visual-plan-repository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visual-plan-repository.d.ts","sourceRoot":"","sources":["../../../src/visual-plan/infrastructure/visual-plan-repository.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,EAAkB,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAG3E,wDAAwD;AACxD,eAAO,MAAM,iBAAiB,QAAwC,CAAC;AAEvE,wFAAwF;AACxF,qBAAa,aAAc,SAAQ,KAAK;gBAC3B,OAAO,EAAE,MAAM;CAI3B;AAED,6FAA6F;AAC7F,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAYpD;AAQD,uFAAuF;AACvF,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAiBpD;AAED,iEAAiE;AACjE,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED,MAAM,WAAW,eAAe;IAC/B,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,KAAK,CAAC,EAAE,eAAe,CAAC;CACxB;AAED,gGAAgG;AAChG,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,CAchE;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,CAE3D;AAED,8DAA8D;AAC9D,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,IAAI,CAEtE"}

package/dist/visual-plan/infrastructure/visual-plan-repository.js

@@ -0,0 +1,97 @@
+/**
+ * Filesystem gateway for the canonical visual artifact.
+ *
+ * The artifact always lives at `<plan-dir>/visual-plan/plan.json`. All access
+ * goes through realpath containment: the resolved artifact path MUST stay
+ * inside the resolved plan directory, so a symlinked `visual-plan/` cannot
+ * redirect reads/writes outside the plan (non-functional requirement: no path
+ * escapes the plan directory). Writes are atomic (same-dir tmp + rename).
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { err, ErrorCode } from "../domain/errors.js";
+import { atomicWriteFileSync } from "./atomic-write.js";
+/** Artifact location relative to the plan directory. */
+export const ARTIFACT_REL_PATH = path.join("visual-plan", "plan.json");
+/** Thrown when a plan directory or artifact path fails containment/existence checks. */
+export class PlanPathError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PlanPathError";
+    }
+}
+/** Resolve `input` to an existing directory's realpath. Throws `PlanPathError` otherwise. */
+export function resolvePlanDir(input) {
+    const abs = path.resolve(input);
+    let real;
+    try {
+        real = fs.realpathSync(abs);
+    }
+    catch {
+        throw new PlanPathError(`plan directory not found: ${abs}`);
+    }
+    if (!fs.statSync(real).isDirectory()) {
+        throw new PlanPathError(`not a directory: ${real}`);
+    }
+    return real;
+}
+/** True when `candidate`'s realpath is `planDir` itself or strictly inside it. */
+function isContained(candidate, realPlan) {
+    const real = fs.realpathSync(candidate);
+    return real === realPlan || real.startsWith(realPlan + path.sep);
+}
+/** Absolute artifact path, guaranteed contained within `planDir` (realpath checks). */
+export function artifactPath(planDir) {
+    const full = path.resolve(planDir, ARTIFACT_REL_PATH);
+    const rel = path.relative(planDir, full);
+    if (rel.startsWith("..") || path.isAbsolute(rel)) {
+        throw new PlanPathError(`artifact path escapes plan directory: ${full}`);
+    }
+    const realPlan = fs.realpathSync(planDir);
+    // Guard against a symlinked visual-plan/ directory redirecting outside the plan dir.
+    const dir = path.dirname(full);
+    if (fs.existsSync(dir) && !isContained(dir, realPlan)) {
+        throw new PlanPathError(`visual-plan directory resolves outside the plan directory: ${fs.realpathSync(dir)}`);
+    }
+    // Guard against a symlinked plan.json file redirecting reads outside the plan dir.
+    if (fs.existsSync(full) && !isContained(full, realPlan)) {
+        throw new PlanPathError(`artifact file resolves outside the plan directory: ${fs.realpathSync(full)}`);
+    }
+    return full;
+}
+/** True when an artifact file exists for this plan directory. */
+export function artifactExists(planDir) {
+    return fs.existsSync(artifactPath(planDir));
+}
+/** Read + JSON-parse the artifact. Missing/invalid file yields a typed error, never a throw. */
+export function readArtifactRaw(planDir) {
+    const full = artifactPath(planDir);
+    let text;
+    try {
+        text = fs.readFileSync(full, "utf-8");
+    }
+    catch {
+        return { error: err(ARTIFACT_REL_PATH, ErrorCode.ARTIFACT_MISSING, `no visual artifact at ${ARTIFACT_REL_PATH}`) };
+    }
+    try {
+        return { raw: JSON.parse(text) };
+    }
+    catch (e) {
+        const detail = e instanceof Error ? e.message : String(e);
+        return { error: err(ARTIFACT_REL_PATH, ErrorCode.ARTIFACT_INVALID_JSON, `artifact is not valid JSON: ${detail}`) };
+    }
+}
+/**
+ * Canonical on-disk serialization for the artifact (pretty JSON + trailing
+ * newline). Exposed so a caller can hash the EXACT bytes a subsequent
+ * `writeArtifact` will persist (used by prepare-feedback for a crash-safe
+ * batch-then-artifact write order).
+ */
+export function serializeArtifact(artifact) {
+    return `${JSON.stringify(artifact, null, 2)}\n`;
+}
+/** Atomically write the artifact as canonical pretty JSON. */
+export function writeArtifact(planDir, artifact) {
+    atomicWriteFileSync(artifactPath(planDir), serializeArtifact(artifact));
+}
+//# sourceMappingURL=visual-plan-repository.js.map

package/dist/visual-plan/infrastructure/visual-plan-repository.js.map

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

package/dist/visual-plan/infrastructure/wireframe-sanitizer.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Save-time wireframe sanitizer (Node side, jsdom-backed DOMPurify).
+ *
+ * Engine decision (red-team H2): ONE vetted engine — DOMPurify — on both sides.
+ * MeowKit has no HTML parser in runtime deps today; DOMPurify + jsdom are added
+ * as runtime deps precisely for this. Regex-only sanitization is forbidden.
+ *
+ * Reject, not repair: we normalize the input through the DOM (so pure formatting
+ * differences — quote style, self-closing, whitespace — do NOT count), then
+ * sanitize with the SHARED allowlist config. If the sanitized output differs
+ * from the normalized input, the sanitizer removed something unsafe/unlisted and
+ * we REJECT with a JSON path. The Phase-4 browser renderer re-runs the identical
+ * engine + config; the shared adversarial corpus runs in both environments.
+ */
+/** Result of a reject-mode sanitize check. `safe:false` carries a short reason. */
+export interface SanitizeCheck {
+    safe: boolean;
+    reason?: string;
+}
+/**
+ * True when `html` is safe under the shared allowlist. Any content DOMPurify
+ * would strip (disallowed tag/attr, unsafe URL scheme, event handler, inline
+ * style, SVG/MathML) makes it unsafe — the artifact is rejected, never repaired.
+ */
+export declare function checkWireframeHtml(html: string): SanitizeCheck;
+/**
+ * Return the SANITIZED wireframe HTML (safe to embed). Used by the HTML export
+ * to inline wireframes offline. The artifact was already reject-validated at
+ * save time; this re-sanitize is the export's own boundary.
+ */
+export declare function sanitizeWireframeHtml(html: string): string;
+/**
+ * Replace the TEXT content of a schema-backed wireframe field (Phase 5 edit).
+ * The field is targeted by a `wf-field-<fieldId>` class (class is allowlisted, so
+ * no sanitizer-config change is needed). `textContent` assignment escapes the
+ * new value, so an edit can never introduce markup. `fieldId` is charset-safe
+ * (ENTITY_ID_RE) so it is a valid class token. Returns null if the field is
+ * absent (the caller rejects the patch).
+ */
+export declare function editWireframeField(html: string, fieldId: string, text: string): string | null;
+//# sourceMappingURL=wireframe-sanitizer.d.ts.map

package/dist/visual-plan/infrastructure/wireframe-sanitizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wireframe-sanitizer.d.ts","sourceRoot":"","sources":["../../../src/visual-plan/infrastructure/wireframe-sanitizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAWH,mFAAmF;AACnF,MAAM,WAAW,aAAa;IAC7B,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAaD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAQ9D;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAO7F"}

package/dist/visual-plan/infrastructure/wireframe-sanitizer.js

@@ -0,0 +1,72 @@
+/**
+ * Save-time wireframe sanitizer (Node side, jsdom-backed DOMPurify).
+ *
+ * Engine decision (red-team H2): ONE vetted engine — DOMPurify — on both sides.
+ * MeowKit has no HTML parser in runtime deps today; DOMPurify + jsdom are added
+ * as runtime deps precisely for this. Regex-only sanitization is forbidden.
+ *
+ * Reject, not repair: we normalize the input through the DOM (so pure formatting
+ * differences — quote style, self-closing, whitespace — do NOT count), then
+ * sanitize with the SHARED allowlist config. If the sanitized output differs
+ * from the normalized input, the sanitizer removed something unsafe/unlisted and
+ * we REJECT with a JSON path. The Phase-4 browser renderer re-runs the identical
+ * engine + config; the shared adversarial corpus runs in both environments.
+ */
+import createDOMPurify from "dompurify";
+import { JSDOM } from "jsdom";
+import { WIREFRAME_SANITIZE_CONFIG } from "../domain/sanitizer-config.js";
+// One jsdom window + DOMPurify instance for the process. jsdom is heavy to
+// construct; reuse is safe because sanitize() is stateless per call.
+const jsdomWindow = new JSDOM("").window;
+const purify = createDOMPurify(jsdomWindow);
+/**
+ * DOM-normalize `html` so the reject-diff ignores cosmetic reformatting: set it
+ * as innerHTML on a detached element and read it back. Both the normalized input
+ * and the DOMPurify output pass through this same DOM serialization path.
+ */
+function domNormalize(html) {
+    const el = jsdomWindow.document.createElement("div");
+    el.innerHTML = html;
+    return el.innerHTML;
+}
+/**
+ * True when `html` is safe under the shared allowlist. Any content DOMPurify
+ * would strip (disallowed tag/attr, unsafe URL scheme, event handler, inline
+ * style, SVG/MathML) makes it unsafe — the artifact is rejected, never repaired.
+ */
+export function checkWireframeHtml(html) {
+    const normalized = domNormalize(html);
+    const clean = purify.sanitize(html, WIREFRAME_SANITIZE_CONFIG);
+    if (clean === normalized)
+        return { safe: true };
+    return {
+        safe: false,
+        reason: "wireframe HTML contains disallowed or unsafe markup (sanitizer would strip content — reject, not repair)",
+    };
+}
+/**
+ * Return the SANITIZED wireframe HTML (safe to embed). Used by the HTML export
+ * to inline wireframes offline. The artifact was already reject-validated at
+ * save time; this re-sanitize is the export's own boundary.
+ */
+export function sanitizeWireframeHtml(html) {
+    return purify.sanitize(html, WIREFRAME_SANITIZE_CONFIG);
+}
+/**
+ * Replace the TEXT content of a schema-backed wireframe field (Phase 5 edit).
+ * The field is targeted by a `wf-field-<fieldId>` class (class is allowlisted, so
+ * no sanitizer-config change is needed). `textContent` assignment escapes the
+ * new value, so an edit can never introduce markup. `fieldId` is charset-safe
+ * (ENTITY_ID_RE) so it is a valid class token. Returns null if the field is
+ * absent (the caller rejects the patch).
+ */
+export function editWireframeField(html, fieldId, text) {
+    const el = jsdomWindow.document.createElement("div");
+    el.innerHTML = html;
+    const target = el.querySelector(`.wf-field-${fieldId}`);
+    if (!target)
+        return null;
+    target.textContent = text;
+    return el.innerHTML;
+}
+//# sourceMappingURL=wireframe-sanitizer.js.map

package/dist/visual-plan/infrastructure/wireframe-sanitizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wireframe-sanitizer.js","sourceRoot":"","sources":["../../../src/visual-plan/infrastructure/wireframe-sanitizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,eAAe,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC;AAC9B,OAAO,EAAE,yBAAyB,EAAE,MAAM,+BAA+B,CAAC;AAE1E,2EAA2E;AAC3E,qEAAqE;AACrE,MAAM,WAAW,GAAG,IAAI,KAAK,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC;AACzC,MAAM,MAAM,GAAG,eAAe,CAAC,WAA+D,CAAC,CAAC;AAQhG;;;;GAIG;AACH,SAAS,YAAY,CAAC,IAAY;IACjC,MAAM,EAAE,GAAG,WAAW,CAAC,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;IACrD,EAAE,CAAC,SAAS,GAAG,IAAI,CAAC;IACpB,OAAO,EAAE,CAAC,SAAS,CAAC;AACrB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC9C,MAAM,UAAU,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IACtC,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,yBAAyB,CAAC,CAAC;IAC/D,IAAI,KAAK,KAAK,UAAU;QAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAChD,OAAO;QACN,IAAI,EAAE,KAAK;QACX,MAAM,EAAE,0GAA0G;KAClH,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAY;IACjD,OAAO,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,yBAAyB,CAAC,CAAC;AACzD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAY,EAAE,OAAe,EAAE,IAAY;IAC7E,MAAM,EAAE,GAAG,WAAW,CAAC,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;IACrD,EAAE,CAAC,SAAS,GAAG,IAAI,CAAC;IACpB,MAAM,MAAM,GAAG,EAAE,CAAC,aAAa,CAAC,aAAa,OAAO,EAAE,CAAC,CAAC;IACxD,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IACzB,MAAM,CAAC,WAAW,GAAG,IAAI,CAAC;IAC1B,OAAO,EAAE,CAAC,SAAS,CAAC;AACrB,CAAC"}

package/dist/visual-plan/interface/cli.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `mewkit visual-plan <subcommand>` dispatch + reporter.
+ *
+ * Subcommands: validate | status | approve | rehash | export | prepare-feedback
+ * (sync) and edit | view (long-running studio). Each resolves
+ * the plan directory, runs the matching application function, and reports in
+ * human or `--json` form. Exit codes: 0 ok, 1 contract/precondition failure,
+ * 2 usage/path error. Sets `process.exitCode` (never calls `process.exit`) so
+ * the surface stays unit-testable.
+ */
+export interface VisualPlanCliArgs {
+    subcommand?: string;
+    planDir?: string;
+    revision?: string | number;
+    json?: boolean;
+    open?: boolean;
+    noOpen?: boolean;
+    force?: boolean;
+    port?: number;
+    format?: string;
+    ops?: string;
+    batch?: string;
+    check?: boolean;
+    receipt?: string;
+    op?: string;
+}
+/** Dispatch a `visual-plan` subcommand. Returns a promise for the long-running studio commands. */
+export declare function visualPlanCommand(args: VisualPlanCliArgs): void | Promise<void>;
+//# sourceMappingURL=cli.d.ts.map

package/dist/visual-plan/interface/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../../src/visual-plan/interface/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAmBH,MAAM,WAAW,iBAAiB;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,EAAE,CAAC,EAAE,MAAM,CAAC;CACZ;AAoMD,mGAAmG;AACnG,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,iBAAiB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAkC/E"}

package/dist/visual-plan/interface/cli.js

@@ -0,0 +1,280 @@
+/**
+ * `mewkit visual-plan <subcommand>` dispatch + reporter.
+ *
+ * Subcommands: validate | status | approve | rehash | export | prepare-feedback
+ * (sync) and edit | view (long-running studio). Each resolves
+ * the plan directory, runs the matching application function, and reports in
+ * human or `--json` form. Exit codes: 0 ok, 1 contract/precondition failure,
+ * 2 usage/path error. Sets `process.exitCode` (never calls `process.exit`) so
+ * the surface stays unit-testable.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import pc from "picocolors";
+import { validatePlan } from "../application/validate-plan.js";
+import { planStatus } from "../application/status.js";
+import { approvePlan } from "../application/approve.js";
+import { rehashPlan } from "../application/rehash.js";
+import { exportPlanHtml } from "../application/export-plan.js";
+import { prepareFeedback } from "../application/prepare-feedback.js";
+import { checkBatchFresh, recordResolution } from "../application/apply-feedback.js";
+import { patchPlan } from "../application/patch-plan.js";
+import { PatchOpSchema } from "../domain/patches.js";
+import { runStudio } from "./studio.js";
+import { resolvePlanDir, PlanPathError } from "../infrastructure/visual-plan-repository.js";
+import { atomicWriteFileSync } from "../infrastructure/atomic-write.js";
+const emit = (value) => console.log(JSON.stringify(value, null, 2));
+function printErrors(errors) {
+    for (const e of errors)
+        console.error(`  ${pc.red("✗")} ${pc.bold(e.path)} — ${e.message} ${pc.dim(`[${e.code}]`)}`);
+}
+function runValidate(planDir, json) {
+    const r = validatePlan(planDir);
+    if (json) {
+        emit({ ok: r.ok, coverage: r.coverage ?? null, errors: r.errors });
+    }
+    else if (r.ok) {
+        const c = r.coverage;
+        const cov = c ? ` (coverage ${c.resolved} resolved / ${c.planned} planned / ${c.omitted} omitted / ${c.unresolved} unresolved)` : "";
+        console.log(`${pc.green("✓")} visual-plan valid${cov}`);
+    }
+    else {
+        console.error(`${pc.red("✗")} visual-plan invalid — ${r.errors.length} error(s):`);
+        printErrors(r.errors);
+    }
+    process.exitCode = r.ok ? 0 : 1;
+}
+function runStatus(planDir, json) {
+    const s = planStatus(planDir);
+    if (json) {
+        emit(s);
+    }
+    else if (!s.exists) {
+        console.log(pc.dim("no visual artifact for this plan"));
+    }
+    else {
+        const c = s.coverage;
+        console.log(`${s.valid ? pc.green("valid") : pc.red("invalid")} · rev ${s.revision} · review ${pc.bold(s.reviewStatus ?? "?")}` +
+            (c ? ` · coverage ${c.resolved}/${c.planned}/${c.omitted}/${c.unresolved} (R/P/O/U)` : "") +
+            (s.errorCount ? ` · ${s.errorCount} error(s)` : ""));
+    }
+    // Contract violation exits non-zero (phase Requirements). An absent artifact
+    // is NOT a violation — nothing to gate on — so it stays 0.
+    process.exitCode = s.exists && !s.valid ? 1 : 0;
+}
+function runApprove(planDir, revisionArg, json) {
+    const raw = String(revisionArg ?? "");
+    // Strict: reject trailing garbage / floats rather than silently coercing
+    // (e.g. "3abc" or "3.5"). Approval is pinned to an exact revision.
+    if (!/^\d+$/.test(raw)) {
+        console.error(pc.red("approve requires --revision <n> (non-negative integer)"));
+        process.exitCode = 2;
+        return;
+    }
+    const revision = parseInt(raw, 10);
+    const r = approvePlan(planDir, revision);
+    if (json) {
+        emit(r);
+    }
+    else if (r.ok) {
+        console.log(`${pc.green("✓")} approved revision ${revision}`);
+    }
+    else {
+        console.error(`${pc.red("✗")} approval refused (${r.failedPreconditions.length} precondition(s)):`);
+        for (const p of r.failedPreconditions)
+            console.error(`  ${pc.red("✗")} ${p}`);
+    }
+    process.exitCode = r.ok ? 0 : 1;
+}
+function runExport(planDir, format, json) {
+    if (format !== undefined && format !== "html") {
+        console.error(pc.red(`export --format ${format} not supported (only 'html')`));
+        process.exitCode = 2;
+        return;
+    }
+    const r = exportPlanHtml(planDir);
+    if (!r.ok || !r.html) {
+        if (json)
+            emit(r);
+        else
+            console.error(`${pc.red("✗")} export failed — ${r.error ?? "unknown"}`);
+        process.exitCode = 1;
+        return;
+    }
+    const out = path.join(planDir, "plan.html");
+    atomicWriteFileSync(out, r.html);
+    if (json)
+        emit({ ok: true, path: out });
+    else
+        console.log(`${pc.green("✓")} exported ${out}`);
+    process.exitCode = 0;
+}
+function readJsonFile(file) {
+    return JSON.parse(fs.readFileSync(file, "utf-8"));
+}
+/** `patch <dir> --op <file>` — apply one typed visual op (single-writer; no If-Match). */
+function runPatch(planDir, opFile, json) {
+    if (!opFile) {
+        console.error(pc.red("patch requires --op <op.json> (a single typed patch op)"));
+        process.exitCode = 2;
+        return;
+    }
+    let opJson;
+    try {
+        opJson = readJsonFile(opFile);
+    }
+    catch (e) {
+        console.error(pc.red(`could not read --op file: ${e instanceof Error ? e.message : String(e)}`));
+        process.exitCode = 2;
+        return;
+    }
+    const op = PatchOpSchema.safeParse(opJson);
+    if (!op.success) {
+        console.error(pc.red(`invalid patch op: ${op.error.issues[0]?.message ?? "schema"}`));
+        process.exitCode = 2;
+        return;
+    }
+    const r = patchPlan(planDir, op.data);
+    if (json)
+        emit(r);
+    else if (r.status === "ok")
+        console.log(`${pc.green("✓")} patched → revision ${r.revision}`);
+    else
+        console.error(`${pc.red("✗")} ${r.status}${r.message ? `: ${r.message}` : ""}`);
+    process.exitCode = r.status === "ok" ? 0 : 1;
+}
+/** `apply-feedback <dir> --batch <id> [--check | --receipt <file>]` — deterministic loop mechanics. */
+function runApplyFeedback(planDir, args, json) {
+    if (!args.batch) {
+        console.error(pc.red("apply-feedback requires --batch <batch-id>"));
+        process.exitCode = 2;
+        return;
+    }
+    if (args.check) {
+        const r = checkBatchFresh(planDir, args.batch);
+        if (json)
+            emit(r);
+        else if (r.ok)
+            console.log(`${pc.green("✓")} batch ${args.batch} is fresh — safe to apply`);
+        else
+            console.error(`${pc.red("✗")} ${r.stale ? "STALE" : "cannot apply"}: ${r.reason}`);
+        process.exitCode = r.ok ? 0 : 1;
+        return;
+    }
+    if (args.receipt) {
+        let entries;
+        try {
+            entries = readJsonFile(args.receipt);
+        }
+        catch (e) {
+            console.error(pc.red(`could not read --receipt file: ${e instanceof Error ? e.message : String(e)}`));
+            process.exitCode = 2;
+            return;
+        }
+        const r = recordResolution(planDir, args.batch, entries);
+        if (json)
+            emit(r);
+        else if (r.ok) {
+            console.log(`${pc.green("✓")} receipt written: ${r.receiptPath}`);
+            console.log(`  reopen: ${pc.cyan(r.reopenCommand ?? "")}`);
+        }
+        else
+            console.error(`${pc.red("✗")} ${r.error}`);
+        process.exitCode = r.ok ? 0 : 1;
+        return;
+    }
+    console.error(pc.red("apply-feedback requires --check (pre-apply gate) or --receipt <file> (record outcomes)"));
+    process.exitCode = 2;
+}
+function runPrepareFeedback(planDir, opsFile, json) {
+    if (!opsFile) {
+        console.error(pc.red("prepare-feedback requires --ops <operations.json> (a JSON array of feedback operations)"));
+        process.exitCode = 2;
+        return;
+    }
+    let operations;
+    try {
+        operations = JSON.parse(fs.readFileSync(opsFile, "utf-8"));
+    }
+    catch (e) {
+        console.error(pc.red(`could not read --ops file: ${e instanceof Error ? e.message : String(e)}`));
+        process.exitCode = 2;
+        return;
+    }
+    if (!Array.isArray(operations)) {
+        console.error(pc.red("--ops file must contain a JSON array of operations"));
+        process.exitCode = 2;
+        return;
+    }
+    const r = prepareFeedback(planDir, operations);
+    if (json) {
+        emit(r);
+    }
+    else if (r.ok) {
+        console.log(`${pc.green("✓")} feedback batch ${pc.bold(r.batchId ?? "")}`);
+        console.log(`  copy: ${pc.cyan(r.copyCommand ?? "")}`);
+    }
+    else {
+        console.error(`${pc.red("✗")} ${r.error ?? "prepare failed"}`);
+    }
+    process.exitCode = r.ok ? 0 : 1;
+}
+function runRehash(planDir, json) {
+    const r = rehashPlan(planDir);
+    if (json) {
+        emit(r);
+    }
+    else if (r.ok) {
+        console.log(`${pc.green("✓")} source hashes refreshed${r.clearedApproval ? pc.yellow(" — prior approval cleared") : ""}`);
+    }
+    else {
+        printErrors(r.errors);
+    }
+    process.exitCode = r.ok ? 0 : 1;
+}
+/** Dispatch a `visual-plan` subcommand. Returns a promise for the long-running studio commands. */
+export function visualPlanCommand(args) {
+    const sub = args.subcommand;
+    // Long-running studio commands (own their plan-dir resolution + browser lifecycle).
+    if (sub === "edit" || sub === "view") {
+        return runStudio({ mode: sub, planDir: args.planDir, open: args.open, noOpen: args.noOpen, force: args.force, port: args.port });
+    }
+    const known = new Set(["validate", "status", "approve", "rehash", "export", "prepare-feedback", "apply-feedback", "patch"]);
+    if (!sub || !known.has(sub)) {
+        console.error(pc.red(`visual-plan: expected one of validate|status|approve|rehash|export|prepare-feedback|apply-feedback|patch|edit|view (got ${sub ?? "nothing"})`));
+        process.exitCode = 2;
+        return;
+    }
+    if (!args.planDir) {
+        console.error(pc.red(`visual-plan ${sub}: missing <plan-dir>`));
+        process.exitCode = 2;
+        return;
+    }
+    let planDir;
+    try {
+        planDir = resolvePlanDir(args.planDir);
+    }
+    catch (e) {
+        console.error(pc.red(e instanceof PlanPathError ? e.message : String(e)));
+        process.exitCode = 2;
+        return;
+    }
+    const json = args.json === true;
+    if (sub === "validate")
+        runValidate(planDir, json);
+    else if (sub === "status")
+        runStatus(planDir, json);
+    else if (sub === "approve")
+        runApprove(planDir, args.revision, json);
+    else if (sub === "export")
+        runExport(planDir, args.format, json);
+    else if (sub === "prepare-feedback")
+        runPrepareFeedback(planDir, args.ops, json);
+    else if (sub === "apply-feedback")
+        runApplyFeedback(planDir, args, json);
+    else if (sub === "patch")
+        runPatch(planDir, args.op, json);
+    else
+        runRehash(planDir, json);
+}
+//# sourceMappingURL=cli.js.map