@seanmars/tospec 0.19.0-beta.7 → 0.20.0

package/dist/core/local-server.js

@@ -1,14 +1,10 @@
 /**
  * Plumbing shared by every local web command (`dashboard`, `metrics`).
  *
- * Two of these are trust boundaries, and that is the reason this module exists
- * rather than each command carrying its own copy: `isAllowedHostHeader` is a
- * DNS-rebinding guard and `serveAsset` is a path-escape guard. A second
- * implementation of either is a hole that survives fixing the first one.
- *
- * `serveAsset` takes its root directory as an argument — the commands serve
- * different asset trees, and parameterising the directory is what lets one
- * implementation serve both.
+ * Shared rather than copied per command because several of these are trust
+ * boundaries — `isAllowedHostHeader` (DNS rebinding), `serveAsset` (path
+ * escape), `assertBindableHost` (bind policy). A second implementation of any of
+ * them is a hole that survives fixing the first.
  */
 import { promises as fs } from 'node:fs';
 import * as path from 'node:path';
@@ -21,21 +17,12 @@ const ASSET_CONTENT_TYPES = {
 };
 /**
  * Canonical form of a bind address or Host-header name, so the sets below hold
- * addresses rather than spellings.
- *
- * `::`, `::0` and `0:0:0:0:0:0:0:0` are one address, and every one of them is
- * something a user can legitimately type after `--host`. Matching spellings
- * means the next one nobody thought to list silently takes the wrong branch —
- * which is how `--allow-remote --host ::0` bound every interface and then 403'd
- * every request that arrived on one.
+ * addresses rather than spellings: `::`, `::0` and `0:0:0:0:0:0:0:0` are one
+ * address a user may type after `--host`.
  *
- * The WHATWG URL parser is the normalizer because it is the only IPv6/IPv4
- * canonicalizer already in Node's core: it collapses every spelling above to
- * `::`, and the brackets it adds back are stripped here.
- *
- * Anything that does not parse as a host is returned lowercased and otherwise
- * untouched. Every check in this module treats an unrecognized value as neither
- * loopback nor wildcard, which is the refusing side of each of them.
+ * The WHATWG URL parser is the normalizer because it is Node's only built-in
+ * IPv6/IPv4 canonicalizer. An unparseable value is returned lowercased, and
+ * every check here treats it as neither loopback nor wildcard.
  */
 export function normalizeHost(host) {
     const bare = host.trim().toLowerCase().replace(/^\[|\]$/g, '');
@@ -55,64 +42,55 @@ export function normalizeHost(host) {
  */
 export const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '::1']);
 /**
- * Bind addresses that mean "every interface", canonical forms only. These are
- * not names any client sends as a Host header, which is what makes them the one
- * case the literal match in `isAllowedHostHeader` can never satisfy.
- *
- * `::ffff:0:0` is the IPv4-mapped spelling of the same unspecified address; it
- * is listed because it survives normalization as a distinct string, not because
- * it means anything different.
+ * Bind addresses meaning "every interface", canonical forms only. No client
+ * sends these as a Host header, which is why `isAllowedHostHeader`'s literal
+ * match can never satisfy them. `::ffff:0:0` is listed because it survives
+ * normalization as a distinct string.
  */
 export const WILDCARD_HOSTS = new Set(['0.0.0.0', '::', '::ffff:0:0']);
 /**
- * The bind guard, in one place because it is the third trust boundary this
- * module owns.
- *
- * It lived inline in `startDashboardServer`, so the metrics server — which takes
- * the same `host`, goes through the same `listenFrom`, and shares
- * `isAllowedHostHeader` and `serveAsset` from this module — had nothing to call
- * and bound `0.0.0.0` without objecting. That is exactly the hole this file's
- * header warns about: a guard with one implementation site cannot protect the
- * second caller that never reaches it.
+ * A URL a browser can actually open for a server bound to `host`. A wildcard
+ * bind has no connectable spelling — `http://0.0.0.0:5620` is not visitable —
+ * and `dashboard --list` reconstructs the loopback URL the same way.
+ */
+export function connectableUrl(host, port) {
+    // Normalized like every other check here: `::0` is a wildcard bind that
+    // `acceptsAnyHostHeader` recognises, so printing `http://[::0]:5620` for it
+    // handed the user a URL no browser can open.
+    const displayHost = WILDCARD_HOSTS.has(normalizeHost(host)) ? '127.0.0.1' : host;
+    // IPv6 literals need brackets in a URL; a bare `::1` parses as host `` with a
+    // port of `:1`.
+    const bracketed = displayHost.includes(':') ? `[${displayHost}]` : displayHost;
+    return `http://${bracketed}:${port}`;
+}
+/**
+ * The bind guard, shared so a new local server cannot silently bind `0.0.0.0`.
  *
- * `serverName` appears in the message so the refusal still names what refused,
- * and `remedy` is supplied by the caller for the same reason one step further:
- * the text used to hard-code "Pass `--allow-remote`", a flag `skill-metrics`
- * does not register, so the one command that could not act on the advice was the
- * one being told to. Making it a parameter means a new local server has to state
- * its own escape hatch rather than silently inherit one it may not have.
+ * `remedy` is the caller's: `--allow-remote` is a dashboard flag that
+ * `skill-metrics` does not register, so each server states its own escape hatch.
  */
 export function assertBindableHost(host, serverName, allowRemote, remedy) {
     if (LOOPBACK_HOSTS.has(normalizeHost(host)) || allowRemote)
         return;
     throw new Error(`Refusing to bind non-loopback host '${host}': the ${serverName} would be readable by anyone who can reach this machine. ${remedy}`);
 }
-// -----------------------------------------------------------------------------
-// Responses
-// -----------------------------------------------------------------------------
 export function sendJson(res, status, payload) {
     res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' });
     res.end(JSON.stringify(payload));
 }
 /**
- * Absolute path to a shipped asset tree (`assets/<name>`), resolved relative to
- * this module's own URL.
- *
- * The depth is load-bearing: compiled to `dist/core/`, two levels up is the
- * package root, which is also what `dist/commands/` yields. Assets are shipped
- * as package `files` and never compiled, so moving this module to a different
- * depth would silently resolve outside the package. Every caller goes through
- * here so that constraint has exactly one home.
+ * Absolute path to a shipped asset tree (`assets/<name>`), resolved from this
+ * module's own URL. The depth is load-bearing: compiled to `dist/core/`, two
+ * levels up is the package root, so moving this module resolves outside it.
  */
 export function packageAssetsDir(name) {
     const here = path.dirname(fileURLToPath(import.meta.url));
     return path.join(here, '..', '..', 'assets', name);
 }
 /**
- * Serves one file from `dir`. The requested name is confined to that directory:
- * URL parsing already normalises `..`, but a resolved path outside `dir` is
- * refused regardless, since this is the only thing standing between a crafted
- * request and the rest of the filesystem.
+ * Serves one file from `dir`. URL parsing already normalises `..`, but a
+ * resolved path outside `dir` is refused regardless: this is the only thing
+ * between a crafted request and the rest of the filesystem.
  */
 export async function serveAsset(res, dir, rawName) {
     const name = decodeURIComponent(rawName);
@@ -134,15 +112,11 @@ export async function serveAsset(res, dir, rawName) {
     res.writeHead(200, { 'content-type': `${type}; charset=utf-8` });
     res.end(content);
 }
-// -----------------------------------------------------------------------------
-// Trust boundary
-// -----------------------------------------------------------------------------
 /**
  * DNS-rebinding guard: only requests whose Host header names loopback (or the
  * explicitly bound non-loopback address) are served. A malicious page can make
  * a victim's browser resolve an attacker domain to 127.0.0.1 and read the
- * server's endpoints; the attacker domain in the Host header is what gives that
- * away.
+ * server's endpoints; the attacker domain in the Host header gives that away.
  */
 export function isAllowedHostHeader(hostHeader, boundHost, acceptAnyHost = false) {
     if (!hostHeader)
@@ -152,38 +126,31 @@ export function isAllowedHostHeader(hostHeader, boundHost, acceptAnyHost = false
     if (!match)
         return false;
     // Normalized on both sides so the comparison is between addresses, not
-    // between the spelling the client sent and the spelling the operator typed.
+    // between the client's spelling and the operator's.
     const name = normalizeHost(match[1]);
     if (LOOPBACK_HOSTS.has(name))
         return true;
-    // Still parsed and still last: an unparseable Host header is refused even
-    // here, so the opt-in widens who may be named, not what counts as a name.
+    // Last, and after parsing: the opt-in widens who may be named, not what counts
+    // as a name.
     if (acceptAnyHost)
         return true;
     return name === normalizeHost(boundHost);
 }
 /**
- * The Host-header policy, resolved once at startup rather than re-derived per
- * request — see decisions/20260910_150312-allow-remote-wildcard-host-policy.md.
+ * The Host-header policy, resolved once at startup rather than per request —
+ * see decisions/20260910_150312-allow-remote-wildcard-host-policy.md.
  *
  * A wildcard bind has no Host header that can literally match it, so
- * `--allow-remote --host 0.0.0.0` used to listen on every interface and then
- * 403 every request that arrived on one. Only that combination is relaxed: with
- * a concrete address the operator named the host worth accepting, and the
- * literal match is both free and still correct.
- *
- * Kept out of `isAllowedHostHeader` on purpose. That predicate cannot see
- * whether `--allow-remote` was passed, and burying "wildcard means trust
- * everyone" inside it would make the assumption invisible at the call site.
+ * `--allow-remote --host 0.0.0.0` would listen on every interface then 403 every
+ * request. Only that combination is relaxed; a concrete address names the host
+ * worth accepting. Kept out of `isAllowedHostHeader` so "wildcard means trust
+ * everyone" stays visible at the call site.
  */
 export function acceptsAnyHostHeader(boundHost, allowRemote) {
     if (!allowRemote)
         return false;
     return WILDCARD_HOSTS.has(normalizeHost(boundHost));
 }
-// -----------------------------------------------------------------------------
-// Lifecycle
-// -----------------------------------------------------------------------------
 /** Resolves once the server is listening, or rejects with the listen error. */
 export function listenOnce(server, port, host) {
     return new Promise((resolve, reject) => {
@@ -201,17 +168,12 @@ export function listenOnce(server, port, host) {
     });
 }
 /**
- * Binds `basePort`, advancing to the next port on `EADDRINUSE` until one is
- * free, and returns the port actually bound. Every local command wants the same
- * rule — a predictable port you can keep in your head, that still yields rather
- * than failing when something already holds it.
+ * Binds `basePort`, advancing on `EADDRINUSE` until one is free, and returns the
+ * port actually bound.
  *
- * `port: 0` is passed straight through: the OS picks a free port itself, so
- * there is nothing to retry and incrementing from whatever it chose would be
- * meaningless.
- *
- * The attempt bound is a backstop, not a policy: without it a machine that
- * refuses every bind for some other reason would spin through 65k ports.
+ * `port: 0` passes straight through — the OS picks a free port, so there is
+ * nothing to retry. `maxAttempts` stops a machine that refuses every bind from
+ * spinning through 65k ports.
  */
 export async function listenFrom(server, basePort, host, maxAttempts = 200) {
     let port = basePort;
@@ -232,14 +194,7 @@ export async function listenFrom(server, basePort, host, maxAttempts = 200) {
     const address = server.address();
     return typeof address === 'object' && address ? address.port : port;
 }
-// -----------------------------------------------------------------------------
-// Browser
-// -----------------------------------------------------------------------------
-/**
- * Builds the platform command that opens `url` in the default browser.
- * Pure (no side effects) so the platform branching is testable without
- * launching anything.
- */
+/** Pure, so the platform branching is testable without launching anything. */
 export function browserOpenCommand(url, platform = process.platform) {
     if (platform === 'win32')
         return `start "" "${url}"`;

package/dist/core/local-server.js.map

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

package/dist/core/markdown-render.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Markdown → HTML for the dashboard's `/api/render`, and a trust boundary rather
+ * than a formatting detail: the output is assigned with `innerHTML`, so it runs
+ * in the same origin that answers `POST /api/task`. The CSRF defence on
+ * `handleTaskUpdate` only stops *cross-origin* callers, so a handler smuggled in
+ * through a markdown file would sit inside it.
+ *
+ * Raw HTML is escaped, not allowlisted: an allowlist has to stay ahead of every
+ * attribute and scheme that can execute, and these documents need no markup
+ * markdown cannot express.
+ */
+/**
+ * The URL when it is safe to emit as an attribute, otherwise null. Two rules,
+ * both against spellings a naive scheme regex waves through:
+ *
+ * 1. Tabs and newlines are stripped first. `java	script:alert(1)` matches no
+ *    `^javascript:` regex, but the URL parser — and the browser — strips them
+ *    and is left with `javascript:`.
+ * 2. The scheme comes from `URL`, not the raw text, so case variants and
+ *    percent-encoded forms normalize before comparison.
+ */
+export declare function safeUrl(href: string): string | null;
+/** Renders markdown to HTML with raw HTML escaped and URL schemes restricted. */
+export declare function renderMarkdownSafe(markdown: string): Promise<string>;
+//# sourceMappingURL=markdown-render.d.ts.map

package/dist/core/markdown-render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown-render.d.ts","sourceRoot":"","sources":["../../src/core/markdown-render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AA6BH;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAenD;AA+BD,iFAAiF;AACjF,wBAAsB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAE1E"}

package/dist/core/markdown-render.js

@@ -0,0 +1,94 @@
+/**
+ * Markdown → HTML for the dashboard's `/api/render`, and a trust boundary rather
+ * than a formatting detail: the output is assigned with `innerHTML`, so it runs
+ * in the same origin that answers `POST /api/task`. The CSRF defence on
+ * `handleTaskUpdate` only stops *cross-origin* callers, so a handler smuggled in
+ * through a markdown file would sit inside it.
+ *
+ * Raw HTML is escaped, not allowlisted: an allowlist has to stay ahead of every
+ * attribute and scheme that can execute, and these documents need no markup
+ * markdown cannot express.
+ */
+import { Marked } from 'marked';
+/**
+ * Schemes a link or image may keep. Relative paths and fragments carry no
+ * scheme and are allowed by falling through the `URL` parse below.
+ *
+ * `data:` is excluded: `data:text/html` navigates to attacker markup in this
+ * origin, and no spec document needs an inline blob.
+ */
+const SAFE_URL_SCHEMES = new Set(['http:', 'https:', 'mailto:']);
+function escapeHtml(text) {
+    return text
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+/**
+ * Base for resolving relative hrefs: a relative URL inherits this scheme, so
+ * `parsed.protocol` lands in the allowlist and one check covers both absolute
+ * and relative inputs. The host is never emitted.
+ */
+const RELATIVE_BASE = 'https://tospec.invalid/';
+/**
+ * The URL when it is safe to emit as an attribute, otherwise null. Two rules,
+ * both against spellings a naive scheme regex waves through:
+ *
+ * 1. Tabs and newlines are stripped first. `java&#9;script:alert(1)` matches no
+ *    `^javascript:` regex, but the URL parser — and the browser — strips them
+ *    and is left with `javascript:`.
+ * 2. The scheme comes from `URL`, not the raw text, so case variants and
+ *    percent-encoded forms normalize before comparison.
+ */
+export function safeUrl(href) {
+    // The same normalization the URL parser applies: C0 controls and space
+    // trimmed from both ends, tab/LF/CR removed throughout.
+    const cleaned = href.replace(/[\x00- ]+$/, '').replace(/^[\x00- ]+/, '').replace(/[\t\n\r]/g, '');
+    if (cleaned === '')
+        return null;
+    let parsed;
+    try {
+        parsed = new URL(cleaned, RELATIVE_BASE);
+    }
+    catch {
+        return null;
+    }
+    if (!SAFE_URL_SCHEMES.has(parsed.protocol))
+        return null;
+    // The cleaned form, not the input: what was validated has to be what is
+    // emitted, or the browser re-reads the characters removed above.
+    return cleaned;
+}
+const renderer = new Marked({
+    renderer: {
+        // Both block-level and inline raw HTML arrive here.
+        html({ text }) {
+            return escapeHtml(text);
+        },
+        link(token) {
+            const body = this.parser.parseInline(token.tokens);
+            const href = safeUrl(token.href);
+            // A rejected scheme keeps the text and loses the link; dropping the node
+            // would hide that the author wrote something the renderer refused.
+            if (href === null)
+                return body;
+            const title = token.title ? ` title="${escapeHtml(token.title)}"` : '';
+            return `<a href="${escapeHtml(href)}"${title}>${body}</a>`;
+        },
+        image(token) {
+            const src = safeUrl(token.href);
+            const alt = escapeHtml(token.text);
+            if (src === null)
+                return alt;
+            const title = token.title ? ` title="${escapeHtml(token.title)}"` : '';
+            return `<img src="${escapeHtml(src)}" alt="${alt}"${title}>`;
+        },
+    },
+});
+/** Renders markdown to HTML with raw HTML escaped and URL schemes restricted. */
+export async function renderMarkdownSafe(markdown) {
+    return renderer.parse(markdown);
+}
+//# sourceMappingURL=markdown-render.js.map

package/dist/core/markdown-render.js.map

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

package/dist/core/migrate.d.ts

@@ -1,6 +1,10 @@
+import { type CommandDiagnostic } from '../commands/shared-output.js';
 export interface MigrateOptions {
     force?: boolean;
+    json?: boolean;
 }
+/** The `--json` null-shape; mirrors the success payload with `migrate` nulled. */
+export declare const MIGRATE_FAILURE_PAYLOAD: Record<string, unknown>;
 export interface MigrateSummary {
     specs: {
         copied: number;
@@ -17,22 +21,29 @@ export interface MigrateSummary {
     context: 'carried' | 'conflict' | 'empty' | 'absent';
     /** REMOVED requirements dropped during main-spec normalization (`spec/name`). */
     removedRequirements: string[];
-    /** RENAMED requirement blocks kept as MODIFIED content (`spec/name`). */
+    /** Renames a RENAMED section asked for and normalization applied (`spec/from -> to`). */
+    renamedRequirements: string[];
+    /**
+     * RENAMED entries normalization could not act on, so the old name stands
+     * (`spec/name`). Reported for manual review rather than dropped.
+     */
     renamedKept: string[];
 }
 export declare class MigrateError extends Error {
-    diagnostic?: {
-        fix?: string;
-    } | undefined;
-    constructor(message: string, diagnostic?: {
+    /**
+     * A full `CommandDiagnostic`: `asStatus` recognises one by `typeof
+     * diagnostic.code === 'string'`, so a bare `{ fix }` is dropped.
+     */
+    readonly diagnostic: CommandDiagnostic;
+    constructor(message: string, options?: {
         fix?: string;
-    } | undefined);
+        code?: string;
+    });
 }
 /**
  * Converts an OpenSpec archive dir name (`YYYY-MM-DD-<name>`) to the tospec
- * stamp form (`YYYYMMDD_000000-<name>`). OpenSpec only recorded the date, so
- * the time part is zero-filled. Names without the date prefix pass through
- * unchanged (they already parse as `<stamp>-<name>` no worse than before).
+ * stamp form (`YYYYMMDD_000000-<name>`). OpenSpec only recorded the date, so the
+ * time part is zero-filled. Names without the date prefix pass through.
  */
 export declare function convertArchiveDirName(dirName: string): string;
 /**
@@ -45,7 +56,12 @@ export declare function normalizeMainSpec(content: string, capabilityName: strin
     fixed: 'delta' | 'headerless';
     /** Names of requirements a REMOVED section dropped (recorded, not silent). */
     removed: string[];
-    /** Names of RENAMED requirement blocks whose content was kept as MODIFIED. */
+    /** Renames a RENAMED section asked for and this rebuild applied. */
+    renamed: Array<{
+        from: string;
+        to: string;
+    }>;
+    /** RENAMED entries nothing could be applied for; the old name stands. */
     renamedKept: string[];
 } | null;
 export declare class MigrateCommand {
@@ -61,10 +77,9 @@ export declare class MigrateCommand {
      */
     private migrateMetadata;
     /**
-     * Promote the fully-built staging tree into the target. When the target
-     * doesn't exist, one move does it; when an (verified content-free) tospec/
-     * dir exists — e.g. from `tospec init` — each staged top-level entry
-     * replaces its counterpart. Reuses archive's EPERM/EXDEV-safe move helpers.
+     * Promotes the built staging tree into the target: one move when the target is
+     * absent, else entry-by-entry replacement into the content-free tospec/ that
+     * `tospec init` leaves. Uses archive's EPERM/EXDEV-safe helpers.
      */
     private promoteStaging;
 }

package/dist/core/migrate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../src/core/migrate.ts"],"names":[],"mappings":"AAmCA,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,CAAC;QAAC,oBAAoB,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC;IACvG,OAAO,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,CAAA;KAAE,CAAC;IACvE,kDAAkD;IAClD,OAAO,EAAE,SAAS,GAAG,UAAU,GAAG,OAAO,GAAG,QAAQ,CAAC;IACrD,iFAAiF;IACjF,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,yEAAyE;IACzE,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,qBAAa,YAAa,SAAQ,KAAK;IAG5B,UAAU,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE;IAFtC,YACE,OAAO,EAAE,MAAM,EACR,UAAU,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,YAAA,EAIrC;CACF;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAO7D;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,MAAM,GACrB;IACD,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,GAAG,YAAY,CAAC;IAC9B,8EAA8E;IAC9E,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,8EAA8E;IAC9E,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB,GAAG,IAAI,CA4GP;AAqCD,qBAAa,cAAc;IACnB,OAAO,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CA6IzE;IAED,mGAAmG;YACrF,aAAa;IA+B3B;;;;;;OAMG;YACW,eAAe;IAe7B;;;;;OAKG;YACW,cAAc;CAiB7B"}
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../src/core/migrate.ts"],"names":[],"mappings":"AAQA,OAAO,EAAe,KAAK,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAkCnF,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,kFAAkF;AAClF,eAAO,MAAM,uBAAuB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAiC,CAAC;AAE9F,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,CAAC;QAAC,oBAAoB,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC;IACvG,OAAO,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,CAAA;KAAE,CAAC;IACvE,kDAAkD;IAClD,OAAO,EAAE,SAAS,GAAG,UAAU,GAAG,OAAO,GAAG,QAAQ,CAAC;IACrD,iFAAiF;IACjF,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,yFAAyF;IACzF,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B;;;OAGG;IACH,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,qBAAa,YAAa,SAAQ,KAAK;IACrC;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,iBAAiB,CAAC;IAEvC,YAAY,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,EASrE;CACF;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAO7D;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,MAAM,GACrB;IACD,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,GAAG,YAAY,CAAC;IAC9B,8EAA8E;IAC9E,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,oEAAoE;IACpE,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC7C,yEAAyE;IACzE,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB,GAAG,IAAI,CAqFP;AAqED,qBAAa,cAAc;IACnB,OAAO,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAiLzE;IAED,mGAAmG;YACrF,aAAa;IA6B3B;;;;;;OAMG;YACW,eAAe;IAe7B;;;;OAIG;YACW,cAAc;CAiB7B"}