warden-core

Shared Warden engine: the user-lifecycle library behind the warden Salesforce CLI plugin and the Warden VS Code extension, with a possible future Warden SFDX package.

warden-core is a plain Node/TypeScript library with no CLI framework dependency. Call its functions directly from a script, an editor extension, a CI job, or any other Node codebase.

The domain guides describe the implemented workflows and data contracts for callable command use cases, human and CSV rendering, access auditing, lifecycle operations, provisioning, related records, user matching, file-format schemas, and conformance fixtures.

Install

npm install @syntax-syllogism/warden-core

Requires Node.js 22 or later.

API

| Export | Purpose | | --- | --- | | WardenError | Base class for every error warden-core throws on purpose. Carries a stable code, optional structured data, and a default English message. | | isWardenError(error) | Structural type guard for WardenError; safe across duplicate copies of this package. | | AccessError, UserAccessError | Typed access-audit errors. | | LifecycleError | Typed lifecycle-operation errors. | | ProvisioningError, DefinitionError | Typed provisioning and definition-reading errors. | | RelatedRecordsError | Typed related-record catalog errors. | | commandDescriptors | Metadata and Zod option schemas for the eight callable command use cases. uiHints(schema) reads the front-end input hints without coupling callers to Zod internals. | | provision, freeze, unfreeze, strip, restore | Write use cases exposing plan() and apply(). Plans are plain JSON-safe data and carry warnings for the caller to present before confirmation. | | access, diff, snapshot | Read use cases exposing run(). Diff accepts verify for persona conformance results; snapshot returns the file object and the caller owns serialization and filesystem output. | | File-format schemas and parsers | Zod schemas, JSON-text validators, and inferred types for persona, users, related-catalog, and snapshot files. | | conformanceFixtureSchema, planFromState | The versioned fixture contract and pure v1 additive reconciliation planner. | | Lifecycle, access, provisioning, CSV, snapshot, and rendering functions | Framework-free domain operations used by Warden consumers. | | renderMessages, renderMessagesFor(commandId), MessageLookup | Default English text for renderer keys, with command-specific summary wording for diff and provision. Callers can supply another lookup. | | renderProvisionHuman, renderAccessResult | Pure human output matching the CLI's provision and access displays. | | snapshotToLifecycleResult | Adapts a captured snapshot for renderLifecycleResult and renderSnapshotCsv. |

import { isWardenError } from '@syntax-syllogism/warden-core';

try {
  // call a warden-core function
} catch (error) {
  if (isWardenError(error)) {
    console.error(`${error.code}: ${error.message}`);
  } else {
    throw error;
  }
}

Write commands keep confirmation in the front end and make the state boundary explicit:

const plan = await freeze.plan(connection, options, { onProgress });
// Show plan.warnings and plan.users, then confirm in the caller.
const result = await freeze.apply(connection, JSON.parse(JSON.stringify(plan)));

Provision options accept personasSupplied to override whether persona definitions were supplied; this internal option has no UI hint. Provision previews and apply summaries count reference warnings and planned license shortfalls. Related records support before/after phases, before-only linkUser, and per-user relatedContext lookups; see related records.

Provision options and the legacy ProvisionUserRequest accept optional cleanupOnFailure (default false). ProvisionPlan stores this setting; missing settings on older plans mean false. Cleanup appends deleted and deleteFailed actions to RelatedRecordResult for eligible creations on failed users, while keeping records referenced by saved Users. See cleanup semantics.

JSON users files now validate related and relatedContext structurally.

Errors

Errors are reported as WardenError instances (or area-specific subclasses). The code and the shape of data are part of the public API; the message text is not and may be reworded in any release. Provision user-row errors retain CSV source path and line prefixes in both previews and apply results. Context lookup failures and conflicting before links are per-user errors. Structurally empty linking field names fail with schema-invalid; whitespace-only names fail runtime catalog validation with errorRelationshipInvalidLinkUser. The legacy errorPhaseBeforeUnsupported code remains in the type contract for compatibility, but before relationships are now supported.

| Code | Thrown by | | --- | --- | | errorUnsupportedAccessType, errorInvalidTarget, errorFieldTargetMustBeQualified, errorObjectNotFound, errorFieldNotFound, errorApexClassNotFound, errorVisualforcePageNotFound, errorCustomPermissionNotFound, errorTabNotFound, errorRecordTypeTargetMustBeQualified, errorMasterRecordTypeUnsupported, errorRecordTypeNotFound, errorRecordTypeAmbiguous, errorRecordTypeInactive, errorRecordTypeMetadataReadFailed, errorAccessQueryFailed | Access audit and target resolution. | | errorInvalidCsv, errorInvalidJson, errorInvalidPersonaDefinition, errorMissingUserFieldMap, errorPersonasWithoutDefinition | Definition readers. | | errorInvalidJson, errorInvalidUserMatchField, errorInvalidUserValue, errorInvalidAgainstValue, errorInvalidAgainstMatchField, errorInvalidSnapshot, errorPromptDeclined, errorAccessScopesMutuallyExclusive, errorVerifyUserMode | Lifecycle targeting, snapshot validation, access scope validation, and diff verification. | | errorInvalidRelatedCatalog, errorRelationshipInvalidDefinition, errorRelationshipInvalidSobject, errorRelationshipMissingPhase, errorRelationshipInvalidPhase, errorPhaseBeforeUnsupported, errorLinkUserUnsupported, errorRelationshipInvalidLinkUser, errorRelatedContextUnsupported, errorRelationshipInvalidMatch, errorRelationshipMatchFromUserId, errorRelationshipInvalidFields, errorRelationshipInvalidSource, errorRelationshipInvalidFrom, errorRelationshipUnknownUserField, errorRelationshipUnwritableField, errorRelationshipInvalidMode, errorRelationshipInvalidRecordType | Related-record catalog validation. | | errorDuplicateExternalIdMatch, errorMissingRequiredFields, errorMissingSaveId, errorPromptDeclined, errorInvalidJson, errorInvalidPersonaDefinition, errorPersonasWithoutDefinition | Provisioning execution and planning. | | schema-invalid, schema-version-unsupported | Structural file-format validation. data.issues contains { path, message } entries. |

File formats and schemas

The five JSON file formats are defined by the exported Zod schemas and the generated Draft 2020-12 schemas. See the detailed file-format schema guide for the full structural contract, parser results, versioning behavior, and artifact-generation workflow.

• persona definitions: { personas: Record<string, Persona> }.
• users definitions: { users: UserInput[] }, where User fields are an open record and personas is an optional string array.
• related catalog: { relationships: Record<string, RelationshipDef> }.
• snapshot: the lifecycle snapshot with snapshotVersion: 1.
• conformance fixture: the engine-neutral definitions + simulated org state + expected plan contract.

The canonical conformance fixtures are published under conformance/. They are the executable spec shared by the TypeScript planning engine and any future engine, such as a potential Apex implementation.

Versioning

warden-core follows Semantic Versioning. Removing or renaming an export, changing a signature or result shape, changing an error code, or rejecting input that was previously valid is a major change. Consumers should pin an exact version and upgrade deliberately.

Development

npm install
npm run build
npm test          # typecheck, lint, prettier, mocha + coverage
npm run pack:check

Contributing

See CONTRIBUTING.md and the Code of Conduct.

Security

See SECURITY.md for how to report vulnerabilities.

License

MIT © Jake Richter