@allstak/wizard 0.1.3

package/dist/transaction/tx.js

@@ -0,0 +1,170 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync } from 'node:fs';
+import { dirname, relative, resolve } from 'node:path';
+import { TransactionAbortedError, PatchSyntaxError } from '../util/errors.js';
+import { log } from '../util/log.js';
+/**
+ * Atomic file-mutation transaction. Every mutation is snapshotted before the write;
+ * on any failure (including a post-write syntax-validation failure) the entire
+ * transaction is rolled back in reverse order.
+ *
+ * Idempotency contract: callers writing into a file that already contains the same
+ * content should detect that and skip — Transaction does NOT dedupe writes for you.
+ */
+export class Transaction {
+    snapshots = [];
+    diffs = [];
+    written = new Set();
+    options;
+    committed = false;
+    rolledBack = false;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    get dryRun() {
+        return this.options.dryRun === true;
+    }
+    /**
+     * Stage a write. Snapshots the file (if it exists) and writes the new content.
+     * Pass a syntax validator to fail-fast on broken output.
+     */
+    async write(filePath, content, validator) {
+        if (this.committed || this.rolledBack) {
+            throw new Error('Cannot write after commit/rollback');
+        }
+        const abs = resolve(filePath);
+        if (!this.written.has(abs)) {
+            const existed = existsSync(abs);
+            const beforeContent = existed ? readFileSync(abs, 'utf8') : null;
+            this.snapshots.push({ path: abs, existed, content: beforeContent });
+            this.written.add(abs);
+            this.options.snapshotWriter?.capture({
+                path: abs,
+                kind: existed ? 'modify' : 'create',
+                before: beforeContent,
+            });
+        }
+        const before = existsSync(abs) ? readFileSync(abs, 'utf8') : null;
+        this.diffs.push({
+            path: abs,
+            before,
+            after: content,
+            kind: before === null ? 'create' : 'modify',
+        });
+        if (this.dryRun) {
+            log.debug(`(dry-run) would write ${abs} (${content.length} bytes)`);
+            return;
+        }
+        mkdirSync(dirname(abs), { recursive: true });
+        writeFileSync(abs, content, 'utf8');
+        if (validator) {
+            try {
+                await validator(abs, content);
+            }
+            catch (err) {
+                await this.rollback();
+                const detail = err instanceof Error ? err.message : String(err);
+                throw new PatchSyntaxError(abs, detail);
+            }
+        }
+    }
+    /**
+     * Stage a deletion (with snapshot for restore on rollback).
+     */
+    async delete(filePath) {
+        if (this.committed || this.rolledBack) {
+            throw new Error('Cannot delete after commit/rollback');
+        }
+        const abs = resolve(filePath);
+        if (!existsSync(abs))
+            return;
+        if (!this.written.has(abs)) {
+            const beforeContent = readFileSync(abs, 'utf8');
+            this.snapshots.push({ path: abs, existed: true, content: beforeContent });
+            this.written.add(abs);
+            this.options.snapshotWriter?.capture({ path: abs, kind: 'delete', before: beforeContent });
+        }
+        this.diffs.push({
+            path: abs,
+            before: readFileSync(abs, 'utf8'),
+            after: '',
+            kind: 'delete',
+        });
+        if (this.dryRun)
+            return;
+        rmSync(abs);
+    }
+    async commit() {
+        if (this.rolledBack)
+            throw new Error('Cannot commit after rollback');
+        this.committed = true;
+        if (this.options.snapshotWriter) {
+            if (this.dryRun) {
+                this.options.snapshotWriter.abort();
+            }
+            else {
+                this.options.snapshotWriter.commit();
+            }
+        }
+    }
+    async rollback() {
+        if (this.committed || this.rolledBack)
+            return;
+        this.rolledBack = true;
+        if (this.dryRun) {
+            this.options.snapshotWriter?.abort();
+            return;
+        }
+        for (let i = this.snapshots.length - 1; i >= 0; i--) {
+            const snap = this.snapshots[i];
+            try {
+                if (!snap.existed) {
+                    if (existsSync(snap.path))
+                        rmSync(snap.path);
+                }
+                else {
+                    mkdirSync(dirname(snap.path), { recursive: true });
+                    writeFileSync(snap.path, snap.content ?? '', 'utf8');
+                }
+            }
+            catch (err) {
+                log.error(`Rollback failed for ${snap.path}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        this.options.snapshotWriter?.abort();
+    }
+    /**
+     * Run a unit of work inside this transaction. If the function throws, the transaction
+     * is rolled back and the original error is wrapped in TransactionAbortedError.
+     */
+    async run(work) {
+        try {
+            const result = await work();
+            await this.commit();
+            return result;
+        }
+        catch (err) {
+            await this.rollback();
+            if (err instanceof Error && err.name === 'TransactionAbortedError')
+                throw err;
+            throw new TransactionAbortedError(err);
+        }
+    }
+    describeDiffs(cwd) {
+        const root = cwd ?? this.options.cwd ?? process.cwd();
+        return this.diffs.map((d) => {
+            const rel = relative(root, d.path) || d.path;
+            switch (d.kind) {
+                case 'create':
+                    return `+ create ${rel} (${d.after.length} bytes)`;
+                case 'delete':
+                    return `- delete ${rel}`;
+                case 'modify':
+                    return `~ modify ${rel} (${(d.before?.length ?? 0)} → ${d.after.length} bytes)`;
+            }
+        });
+    }
+    get plannedDiffs() {
+        return this.diffs;
+    }
+}
+//# sourceMappingURL=tx.js.map

package/dist/transaction/tx.js.map

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

package/dist/util/error-codes.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Centralised error catalog. Every `WizardError` thrown anywhere in the
+ * codebase MUST use one of these canonical codes. Internal-detail strings live
+ * in `WizardError.subcode` (free-form, for grep-ability in logs); user-facing
+ * code lives in `WizardError.code` (stable, surfaced in JSON output and
+ * telemetry).
+ *
+ * If you need a new category, ADD IT HERE FIRST. Don't sneak in ad-hoc codes
+ * — telemetry and the public docs depend on this enumeration.
+ */
+export declare const WIZARD_ERROR_CODES: readonly ["E_AUTH_REQUIRED", "E_AUTH_FAILED", "E_AUTH_EXPIRED", "E_BACKEND_CONTRACT_MISSING", "E_PROJECT_NOT_FOUND", "E_PROJECT_CREATE_FAILED", "E_API_KEY_CREATE_FAILED", "E_UNSUPPORTED_FRAMEWORK", "E_UNSUPPORTED_VERSION", "E_PACKAGE_MANAGER_CONFLICT", "E_PATCH_FAILED", "E_PATCH_ROLLBACK_FAILED", "E_RESTORE_FAILED", "E_CONFIG_INVALID", "E_CONFIG_MIGRATION_FAILED", "E_DOCTOR_FAILED", "E_INGEST_VERIFY_FAILED", "E_SOURCEMAP_VERIFY_FAILED", "E_NETWORK_FAILED", "E_PERMISSION_DENIED", "E_USER_CANCELLED", "E_UNKNOWN"];
+export type WizardErrorCode = (typeof WIZARD_ERROR_CODES)[number];
+export declare const WIZARD_STAGES: readonly ["auth", "reachability", "config", "detect", "install", "patch", "rollback", "validate", "event-ingest", "release-linkage", "source-maps", "restore", "cli"];
+export type WizardStage = (typeof WIZARD_STAGES)[number];
+export interface WizardErrorMeta {
+    code: WizardErrorCode;
+    /** One-line description shown at the top of `docs/errors.md`. */
+    description: string;
+    /** Default fix shown if a thrower passes none. */
+    defaultFix: string;
+    /** Logical stage where this code most often originates. */
+    stage: WizardStage;
+}
+export declare const WIZARD_ERROR_META: Record<WizardErrorCode, WizardErrorMeta>;
+/** Type-guard for the canonical code union. */
+export declare function isWizardErrorCode(s: string): s is WizardErrorCode;
+/** Lookup a metadata record, falling back to E_UNKNOWN. */
+export declare function lookupErrorMeta(code: WizardErrorCode): WizardErrorMeta;
+//# sourceMappingURL=error-codes.d.ts.map

package/dist/util/error-codes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-codes.d.ts","sourceRoot":"","sources":["../../src/util/error-codes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,eAAO,MAAM,kBAAkB,sgBAuBrB,CAAC;AAEX,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAElE,eAAO,MAAM,aAAa,uKAchB,CAAC;AAEX,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,eAAe,CAAC;IACtB,iEAAiE;IACjE,WAAW,EAAE,MAAM,CAAC;IACpB,kDAAkD;IAClD,UAAU,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,KAAK,EAAE,WAAW,CAAC;CACpB;AAED,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,eAAe,EAAE,eAAe,CAqItE,CAAC;AAEF,+CAA+C;AAC/C,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,GAAG,CAAC,IAAI,eAAe,CAEjE;AAED,2DAA2D;AAC3D,wBAAgB,eAAe,CAAC,IAAI,EAAE,eAAe,GAAG,eAAe,CAEtE"}

package/dist/util/error-codes.js

@@ -0,0 +1,192 @@
+/**
+ * Centralised error catalog. Every `WizardError` thrown anywhere in the
+ * codebase MUST use one of these canonical codes. Internal-detail strings live
+ * in `WizardError.subcode` (free-form, for grep-ability in logs); user-facing
+ * code lives in `WizardError.code` (stable, surfaced in JSON output and
+ * telemetry).
+ *
+ * If you need a new category, ADD IT HERE FIRST. Don't sneak in ad-hoc codes
+ * — telemetry and the public docs depend on this enumeration.
+ */
+export const WIZARD_ERROR_CODES = [
+    'E_AUTH_REQUIRED',
+    'E_AUTH_FAILED',
+    'E_AUTH_EXPIRED',
+    'E_BACKEND_CONTRACT_MISSING',
+    'E_PROJECT_NOT_FOUND',
+    'E_PROJECT_CREATE_FAILED',
+    'E_API_KEY_CREATE_FAILED',
+    'E_UNSUPPORTED_FRAMEWORK',
+    'E_UNSUPPORTED_VERSION',
+    'E_PACKAGE_MANAGER_CONFLICT',
+    'E_PATCH_FAILED',
+    'E_PATCH_ROLLBACK_FAILED',
+    'E_RESTORE_FAILED',
+    'E_CONFIG_INVALID',
+    'E_CONFIG_MIGRATION_FAILED',
+    'E_DOCTOR_FAILED',
+    'E_INGEST_VERIFY_FAILED',
+    'E_SOURCEMAP_VERIFY_FAILED',
+    'E_NETWORK_FAILED',
+    'E_PERMISSION_DENIED',
+    'E_USER_CANCELLED',
+    'E_UNKNOWN',
+];
+export const WIZARD_STAGES = [
+    'auth',
+    'reachability',
+    'config',
+    'detect',
+    'install',
+    'patch',
+    'rollback',
+    'validate',
+    'event-ingest',
+    'release-linkage',
+    'source-maps',
+    'restore',
+    'cli',
+];
+export const WIZARD_ERROR_META = {
+    E_AUTH_REQUIRED: {
+        code: 'E_AUTH_REQUIRED',
+        description: 'A command needs credentials but none were available.',
+        defaultFix: 'Run `allstak login`, or pass --api-key for ingest-only commands.',
+        stage: 'auth',
+    },
+    E_AUTH_FAILED: {
+        code: 'E_AUTH_FAILED',
+        description: 'Provided credentials were rejected by the AllStak backend.',
+        defaultFix: 'Verify the email and OTP are correct; check `allstak.config.*` host setting.',
+        stage: 'auth',
+    },
+    E_AUTH_EXPIRED: {
+        code: 'E_AUTH_EXPIRED',
+        description: 'Stored credentials are no longer valid (token revoked or refresh failed).',
+        defaultFix: 'Run `allstak login` to refresh.',
+        stage: 'auth',
+    },
+    E_BACKEND_CONTRACT_MISSING: {
+        code: 'E_BACKEND_CONTRACT_MISSING',
+        description: 'The wizard requires a backend endpoint that does not exist on the configured host.',
+        defaultFix: 'Confirm --host points at a current AllStak deployment, or open an issue.',
+        stage: 'reachability',
+    },
+    E_PROJECT_NOT_FOUND: {
+        code: 'E_PROJECT_NOT_FOUND',
+        description: 'The specified project could not be found in the user\'s accessible orgs.',
+        defaultFix: 'Run `allstak projects list` to see available projects.',
+        stage: 'config',
+    },
+    E_PROJECT_CREATE_FAILED: {
+        code: 'E_PROJECT_CREATE_FAILED',
+        description: 'Backend rejected the project-create call.',
+        defaultFix: 'Check the slug is unique, the org has quota remaining, and you have permission.',
+        stage: 'config',
+    },
+    E_API_KEY_CREATE_FAILED: {
+        code: 'E_API_KEY_CREATE_FAILED',
+        description: 'Backend refused to mint a new API key for the project.',
+        defaultFix: 'Check API-key quota for the org\'s plan; rotate an existing key if needed.',
+        stage: 'config',
+    },
+    E_UNSUPPORTED_FRAMEWORK: {
+        code: 'E_UNSUPPORTED_FRAMEWORK',
+        description: 'No registered integration matches the detected project shape, or detection was ambiguous.',
+        defaultFix: 'Pass `-i <integration>` explicitly. Run `allstak list` to see registered ids.',
+        stage: 'detect',
+    },
+    E_UNSUPPORTED_VERSION: {
+        code: 'E_UNSUPPORTED_VERSION',
+        description: 'The detected framework version is below the wizard\'s supported minimum.',
+        defaultFix: 'Upgrade the framework, or pin to a wizard version that supports your range.',
+        stage: 'detect',
+    },
+    E_PACKAGE_MANAGER_CONFLICT: {
+        code: 'E_PACKAGE_MANAGER_CONFLICT',
+        description: 'Multiple lockfiles present; wizard refuses to guess which package manager owns the project.',
+        defaultFix: 'Delete the unused lockfile (e.g. `package-lock.json` if you use pnpm) and re-run.',
+        stage: 'install',
+    },
+    E_PATCH_FAILED: {
+        code: 'E_PATCH_FAILED',
+        description: 'A wizard patch threw mid-transaction; all changes from this run have been rolled back.',
+        defaultFix: 'Re-run with --debug to see the failing patcher, then run `allstak doctor`.',
+        stage: 'patch',
+    },
+    E_PATCH_ROLLBACK_FAILED: {
+        code: 'E_PATCH_ROLLBACK_FAILED',
+        description: 'A patch failed AND the in-process rollback could not restore one or more files.',
+        defaultFix: 'Use `allstak restore list` to find the most recent persistent snapshot, then `allstak restore apply <id>`.',
+        stage: 'rollback',
+    },
+    E_RESTORE_FAILED: {
+        code: 'E_RESTORE_FAILED',
+        description: 'A `restore` operation could not complete (snapshot corrupt, missing pre-image, or write failure).',
+        defaultFix: 'Inspect `.allstak-wizard/backups/<snapshot>/manifest.json`. Ask support if the snapshot itself is corrupt.',
+        stage: 'restore',
+    },
+    E_CONFIG_INVALID: {
+        code: 'E_CONFIG_INVALID',
+        description: '`allstak.config.*` failed schema validation.',
+        defaultFix: 'Run `allstak config validate` to see exact path-to-blame.',
+        stage: 'config',
+    },
+    E_CONFIG_MIGRATION_FAILED: {
+        code: 'E_CONFIG_MIGRATION_FAILED',
+        description: 'A config-schema migration threw or refused to apply.',
+        defaultFix: 'Run `allstak config migrate --dry-run` to see what would change before applying.',
+        stage: 'config',
+    },
+    E_DOCTOR_FAILED: {
+        code: 'E_DOCTOR_FAILED',
+        description: 'One or more `doctor` stages failed.',
+        defaultFix: 'Read the per-stage `fix:` lines in the doctor output.',
+        stage: 'validate',
+    },
+    E_INGEST_VERIFY_FAILED: {
+        code: 'E_INGEST_VERIFY_FAILED',
+        description: 'Live event probe could not be confirmed in `/api/v1/errors` within the timeout.',
+        defaultFix: 'Verify the API key has ingest scope and the project id matches. Increase --live-probe-timeout if ingestion is backlogged.',
+        stage: 'event-ingest',
+    },
+    E_SOURCEMAP_VERIFY_FAILED: {
+        code: 'E_SOURCEMAP_VERIFY_FAILED',
+        description: 'Source-map upload or symbolication round-trip failed.',
+        defaultFix: 'Run `allstak doctor` to inspect provider state, then `allstak repair` to re-wire.',
+        stage: 'source-maps',
+    },
+    E_NETWORK_FAILED: {
+        code: 'E_NETWORK_FAILED',
+        description: 'A network call to the AllStak backend timed out, refused, or hit DNS failure.',
+        defaultFix: 'Check connectivity and the configured --host.',
+        stage: 'reachability',
+    },
+    E_PERMISSION_DENIED: {
+        code: 'E_PERMISSION_DENIED',
+        description: 'OS-level permission was denied (file write, keychain access, secret-tool, etc).',
+        defaultFix: 'Check filesystem permissions and that your OS keychain is unlocked.',
+        stage: 'cli',
+    },
+    E_USER_CANCELLED: {
+        code: 'E_USER_CANCELLED',
+        description: 'The user cancelled the operation (Ctrl-C, declined a confirmation prompt, etc).',
+        defaultFix: 'No action needed.',
+        stage: 'cli',
+    },
+    E_UNKNOWN: {
+        code: 'E_UNKNOWN',
+        description: 'An unexpected error not yet categorised.',
+        defaultFix: 'Re-run with --debug and open an issue with the stack trace.',
+        stage: 'cli',
+    },
+};
+/** Type-guard for the canonical code union. */
+export function isWizardErrorCode(s) {
+    return WIZARD_ERROR_CODES.includes(s);
+}
+/** Lookup a metadata record, falling back to E_UNKNOWN. */
+export function lookupErrorMeta(code) {
+    return WIZARD_ERROR_META[code];
+}
+//# sourceMappingURL=error-codes.js.map

package/dist/util/error-codes.js.map

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

package/dist/util/errors.d.ts

@@ -0,0 +1,83 @@
+import type { WizardErrorCode, WizardStage } from './error-codes.js';
+/**
+ * Single error type for everything thrown out of wizard code.
+ *
+ * Required fields:
+ *   - `code`     canonical code from src/util/error-codes.ts (drives JSON output, telemetry, docs).
+ *
+ * Optional fields:
+ *   - `subcode`  free-form internal id for finer granularity (e.g. "E_KEYCHAIN_NOT_FOUND").
+ *                Never used by JSON output / telemetry — only for debug logs.
+ *   - `stage`    overrides the default stage for this code.
+ *   - `hint`     actionable fix shown to the user. Falls back to the catalog default.
+ *   - `context`  small bag of safe-to-log details (no secrets, no source code).
+ *                Only emitted under --debug; NEVER sent to telemetry.
+ */
+export interface WizardErrorOptions {
+    hint?: string;
+    subcode?: string;
+    stage?: WizardStage;
+    /** Underlying cause, kept for stack-trace chaining only. */
+    cause?: unknown;
+    /** Safe-to-log context. Keys/values must not contain secrets or PII. */
+    context?: Record<string, string | number | boolean | null>;
+}
+export declare class WizardError extends Error {
+    readonly code: WizardErrorCode;
+    readonly subcode?: string;
+    readonly hint: string;
+    readonly stage: WizardStage;
+    readonly context?: Record<string, string | number | boolean | null>;
+    readonly originalCause?: unknown;
+    constructor(code: WizardErrorCode, message: string, options?: WizardErrorOptions);
+    /**
+     * Stable JSON representation — used by the `--json` reporter and by
+     * telemetry. Intentionally narrow: never serialises `originalCause`,
+     * stack traces, or unknown fields.
+     */
+    toPublicJSON(): {
+        code: WizardErrorCode;
+        stage: WizardStage;
+        subcode: string | null;
+        message: string;
+        hint: string;
+    };
+}
+/**
+ * `NotValidatedError` — thrown when a scaffolded integration runs without
+ * `--experimental`. Maps to `E_UNSUPPORTED_FRAMEWORK` so the JSON output is
+ * categorised consistently with the rest of the catalog.
+ */
+export declare class NotValidatedError extends WizardError {
+    constructor(integrationId: string, reason: string);
+}
+/**
+ * `UnsupportedFrameworkError` — thrown when a framework has been intentionally
+ * refused (e.g. bare React Native).
+ */
+export declare class UnsupportedFrameworkError extends WizardError {
+    constructor(integrationId: string, detail: string);
+}
+/**
+ * `PatchSyntaxError` — a patcher's syntax validator rejected the new content.
+ * Always wraps to `E_PATCH_FAILED` (the rollback already happened by the time
+ * this is thrown).
+ */
+export declare class PatchSyntaxError extends WizardError {
+    readonly file: string;
+    constructor(file: string, detail: string);
+}
+/**
+ * `TransactionAbortedError` — the transaction layer rolled back a multi-file
+ * mutation. The original cause is preserved on `originalCause`.
+ */
+export declare class TransactionAbortedError extends WizardError {
+    constructor(cause: unknown);
+}
+/**
+ * Coerce an arbitrary thrown value into a `WizardError`. Used at top-level
+ * try/catch boundaries (CLI, telemetry sink) so non-WizardError throws are
+ * still categorised as `E_UNKNOWN`.
+ */
+export declare function toWizardError(err: unknown): WizardError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/util/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/util/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAGrE;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,4DAA4D;IAC5D,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC,CAAC;CAC5D;AAED,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC,CAAC;IACpE,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;gBAErB,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB;IAWpF;;;;OAIG;IACH,YAAY,IAAI;QACd,IAAI,EAAE,eAAe,CAAC;QACtB,KAAK,EAAE,WAAW,CAAC;QACnB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;QACvB,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;KACd;CASF;AAED;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,WAAW;gBACpC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAalD;AAED;;;GAGG;AACH,qBAAa,yBAA0B,SAAQ,WAAW;gBAC5C,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAQlD;AAED;;;;GAIG;AACH,qBAAa,gBAAiB,SAAQ,WAAW;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBACV,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAUzC;AAED;;;GAGG;AACH,qBAAa,uBAAwB,SAAQ,WAAW;gBAC1C,KAAK,EAAE,OAAO;CAS3B;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,WAAW,CAUvD"}

package/dist/util/errors.js

@@ -0,0 +1,110 @@
+import { WIZARD_ERROR_META, isWizardErrorCode } from './error-codes.js';
+export class WizardError extends Error {
+    code;
+    subcode;
+    hint;
+    stage;
+    context;
+    originalCause;
+    constructor(code, message, options = {}) {
+        super(message);
+        this.name = 'WizardError';
+        this.code = code;
+        this.subcode = options.subcode;
+        this.stage = options.stage ?? WIZARD_ERROR_META[code].stage;
+        this.hint = options.hint ?? WIZARD_ERROR_META[code].defaultFix;
+        this.context = options.context;
+        this.originalCause = options.cause;
+    }
+    /**
+     * Stable JSON representation — used by the `--json` reporter and by
+     * telemetry. Intentionally narrow: never serialises `originalCause`,
+     * stack traces, or unknown fields.
+     */
+    toPublicJSON() {
+        return {
+            code: this.code,
+            stage: this.stage,
+            subcode: this.subcode ?? null,
+            message: this.message,
+            hint: this.hint,
+        };
+    }
+}
+/**
+ * `NotValidatedError` — thrown when a scaffolded integration runs without
+ * `--experimental`. Maps to `E_UNSUPPORTED_FRAMEWORK` so the JSON output is
+ * categorised consistently with the rest of the catalog.
+ */
+export class NotValidatedError extends WizardError {
+    constructor(integrationId, reason) {
+        super('E_UNSUPPORTED_FRAMEWORK', `Integration "${integrationId}" is scaffolded but not validated end-to-end.`, {
+            subcode: 'E_NOT_VALIDATED',
+            hint: `${reason} Pass --experimental to bypass at your own risk.`,
+            context: { integrationId },
+            stage: 'detect',
+        });
+        this.name = 'NotValidatedError';
+    }
+}
+/**
+ * `UnsupportedFrameworkError` — thrown when a framework has been intentionally
+ * refused (e.g. bare React Native).
+ */
+export class UnsupportedFrameworkError extends WizardError {
+    constructor(integrationId, detail) {
+        super('E_UNSUPPORTED_FRAMEWORK', `Unsupported configuration for "${integrationId}": ${detail}`, { subcode: 'E_UNSUPPORTED_REFUSED', context: { integrationId }, stage: 'detect' });
+        this.name = 'UnsupportedFrameworkError';
+    }
+}
+/**
+ * `PatchSyntaxError` — a patcher's syntax validator rejected the new content.
+ * Always wraps to `E_PATCH_FAILED` (the rollback already happened by the time
+ * this is thrown).
+ */
+export class PatchSyntaxError extends WizardError {
+    file;
+    constructor(file, detail) {
+        super('E_PATCH_FAILED', `Patched file is not syntactically valid: ${file}`, {
+            subcode: 'E_PATCH_SYNTAX',
+            hint: detail,
+            context: { file },
+            stage: 'patch',
+        });
+        this.name = 'PatchSyntaxError';
+        this.file = file;
+    }
+}
+/**
+ * `TransactionAbortedError` — the transaction layer rolled back a multi-file
+ * mutation. The original cause is preserved on `originalCause`.
+ */
+export class TransactionAbortedError extends WizardError {
+    constructor(cause) {
+        const causeMsg = cause instanceof Error ? cause.message : String(cause);
+        super('E_PATCH_FAILED', `Transaction aborted, all changes rolled back: ${causeMsg}`, {
+            subcode: 'E_TX_ABORT',
+            cause,
+            stage: 'rollback',
+        });
+        this.name = 'TransactionAbortedError';
+    }
+}
+/**
+ * Coerce an arbitrary thrown value into a `WizardError`. Used at top-level
+ * try/catch boundaries (CLI, telemetry sink) so non-WizardError throws are
+ * still categorised as `E_UNKNOWN`.
+ */
+export function toWizardError(err) {
+    if (err instanceof WizardError)
+        return err;
+    if (err instanceof Error) {
+        const maybeCode = err.code;
+        if (typeof maybeCode === 'string' && isWizardErrorCode(maybeCode)) {
+            return new WizardError(maybeCode, err.message, { cause: err });
+        }
+        return new WizardError('E_UNKNOWN', err.message, { cause: err });
+    }
+    return new WizardError('E_UNKNOWN', String(err));
+}
+//# sourceMappingURL=errors.js.map

package/dist/util/errors.js.map

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

package/dist/util/log.d.ts

@@ -0,0 +1,11 @@
+export declare function setDebug(v: boolean): void;
+export declare const log: {
+    info: (msg: string) => void;
+    step: (msg: string) => void;
+    success: (msg: string) => void;
+    warn: (msg: string) => void;
+    error: (msg: string) => void;
+    debug: (msg: string) => void;
+    plain: (msg: string) => void;
+};
+//# sourceMappingURL=log.d.ts.map

package/dist/util/log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.d.ts","sourceRoot":"","sources":["../../src/util/log.ts"],"names":[],"mappings":"AAGA,wBAAgB,QAAQ,CAAC,CAAC,EAAE,OAAO,GAAG,IAAI,CAEzC;AAED,eAAO,MAAM,GAAG;gBACF,MAAM,KAAG,IAAI;gBACb,MAAM,KAAG,IAAI;mBACV,MAAM,KAAG,IAAI;gBAChB,MAAM,KAAG,IAAI;iBACZ,MAAM,KAAG,IAAI;iBACb,MAAM,KAAG,IAAI;iBAGb,MAAM,KAAG,IAAI;CAC3B,CAAC"}

package/dist/util/log.js

@@ -0,0 +1,18 @@
+import pc from 'picocolors';
+let DEBUG = false;
+export function setDebug(v) {
+    DEBUG = v;
+}
+export const log = {
+    info: (msg) => console.log(pc.cyan('›'), msg),
+    step: (msg) => console.log(pc.bold(pc.blue('»')), msg),
+    success: (msg) => console.log(pc.green('✓'), msg),
+    warn: (msg) => console.warn(pc.yellow('!'), msg),
+    error: (msg) => console.error(pc.red('✗'), msg),
+    debug: (msg) => {
+        if (DEBUG)
+            console.log(pc.dim(`[debug] ${msg}`));
+    },
+    plain: (msg) => console.log(msg),
+};
+//# sourceMappingURL=log.js.map

package/dist/util/log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.js","sourceRoot":"","sources":["../../src/util/log.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,YAAY,CAAC;AAE5B,IAAI,KAAK,GAAG,KAAK,CAAC;AAClB,MAAM,UAAU,QAAQ,CAAC,CAAU;IACjC,KAAK,GAAG,CAAC,CAAC;AACZ,CAAC;AAED,MAAM,CAAC,MAAM,GAAG,GAAG;IACjB,IAAI,EAAE,CAAC,GAAW,EAAQ,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC;IAC3D,IAAI,EAAE,CAAC,GAAW,EAAQ,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC;IACpE,OAAO,EAAE,CAAC,GAAW,EAAQ,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC;IAC/D,IAAI,EAAE,CAAC,GAAW,EAAQ,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC;IAC9D,KAAK,EAAE,CAAC,GAAW,EAAQ,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC;IAC7D,KAAK,EAAE,CAAC,GAAW,EAAQ,EAAE;QAC3B,IAAI,KAAK;YAAE,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,WAAW,GAAG,EAAE,CAAC,CAAC,CAAC;IACnD,CAAC;IACD,KAAK,EAAE,CAAC,GAAW,EAAQ,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC;CAC/C,CAAC"}