@usermaven/wizard-core

The local, reusable engine behind Usermaven Wizard.

It also owns approval-safe apply state and Wizard-scoped checkpoint/resume recovery. It does not implement model execution or a generic agent runtime.

The first capability is bounded, read-only project inspection:

import { inspectProject } from "@usermaven/wizard-core";

const result = await inspectProject(process.cwd());

Inspection returns normalized framework and analytics evidence. It does not return source snippets, environment values, or captured event data.

The core validates and stamps a proposal generated by the calling AI agent:

import { createAiTrackingPlan } from "@usermaven/wizard-core";

const plan = createAiTrackingPlan({
  inspection: result,
  businessContext,
  aiProposal,
});

The core does not invoke a vendor model or upload source. It requires provenance, rationale, confidence, and review on every AI item. Revenue proposals require an explicit revenue model and authoritative server-capable events.

The core can also generate typed, approval-ready SDK setup plans and render them without executing operations:

import { generateSetupPlan, previewChanges } from "@usermaven/wizard-core";

const setup = await generateSetupPlan({
  projectRoot,
  workspace,
  trackingPlan: plan,
  instrumentationProposal,
});
const preview = previewChanges(setup);

The instrumentation proposal is generated by the coding-agent host. Every identity and event must be covered by one or more bounded file changes or be explicitly deferred. Edit operations are bound to exact preimage hashes.

Approved operations can then be applied through the same engine:

import { applyChanges, createChangeApproval } from "@usermaven/wizard-core";

const approval = await createChangeApproval({
  plan: setup,
  projectRoot,
  operationIds: ["install-sdk"],
  confirmedByInteractiveUser: true,
});
const result = await applyChanges({ projectRoot, plan: setup, approval });

An embedding application must collect a real interactive confirmation before calling createChangeApproval; the boolean is a procedural boundary, not user authentication or a cryptographic signature.

The core also creates short-lived verification sessions and evaluates exact local state plus normalized live evidence:

import { createVerificationSession, verifySetup } from "@usermaven/wizard-core";

const session = createVerificationSession({
  plan: setup,
  environment: "staging",
});
const verification = await verifySetup({
  projectRoot,
  plan: setup,
  session,
  evidence,
});

Evidence contains names, outcomes, and marker matching—not raw analytics payloads or property values.