@syntax-syllogism/warden-core 0.2.0

package/lib/spec/parse.js

@@ -0,0 +1,77 @@
+import { DefinitionError } from '../provisioning/errors.js';
+import { personaDefinitionsFileSchema } from './personaDefinitions.js';
+import { relatedCatalogSchema } from './relatedCatalog.js';
+import { snapshotFileSchema } from './snapshot.js';
+import { usersDefinitionFileSchema } from './usersDefinition.js';
+const issuesFrom = (issues) => issues.map(({ path, message }) => ({
+    path: path.filter((part) => typeof part === 'string' || typeof part === 'number'),
+    message,
+}));
+const issueText = (issues) => issues.map(({ path, message }) => `${path.length > 0 ? path.join('.') : '$'}: ${message}`).join('\n');
+const versionIssue = (path) => ({
+    path,
+    message: 'Unsupported schemaVersion; this reader supports version 1.',
+});
+const unsupportedSchemaVersion = (input) => {
+    if (!input || typeof input !== 'object' || !('schemaVersion' in input))
+        return undefined;
+    const schemaVersion = input.schemaVersion;
+    if (typeof schemaVersion !== 'number' || !Number.isInteger(schemaVersion) || schemaVersion <= 1)
+        return undefined;
+    const issues = [versionIssue(['schemaVersion'])];
+    return {
+        ok: false,
+        issues,
+        error: new DefinitionError('schema-version-unsupported', issueText(issues), { issues }),
+    };
+};
+const parseSchema = (schema, input) => {
+    const parsed = schema.safeParse(input);
+    if (!parsed.success) {
+        const issues = issuesFrom(parsed.error.issues);
+        return {
+            ok: false,
+            issues,
+            error: new DefinitionError('schema-invalid', issueText(issues), { issues }),
+        };
+    }
+    return { ok: true, data: parsed.data, issues: [] };
+};
+const parseVersionedSchema = (schema, input) => {
+    const unsupported = unsupportedSchemaVersion(input);
+    return unsupported ?? parseSchema(schema, input);
+};
+const parseOrThrow = (result) => {
+    if (!result.ok)
+        throw result.error;
+    return result.data;
+};
+const parseText = (parse, text, label) => {
+    try {
+        return parse(JSON.parse(text));
+    }
+    catch (error) {
+        if (error instanceof SyntaxError) {
+            const issues = [{ path: [], message: `Invalid JSON: ${error.message}` }];
+            return {
+                ok: false,
+                issues,
+                error: new DefinitionError('schema-invalid', `${label}: ${issueText(issues)}`, { issues }),
+            };
+        }
+        throw error;
+    }
+};
+export const safeParsePersonaDefinitions = (input) => parseVersionedSchema(personaDefinitionsFileSchema, input);
+export const parsePersonaDefinitions = (input) => parseOrThrow(safeParsePersonaDefinitions(input));
+export const validatePersonaDefinitionsText = (text) => parseText((input) => parseVersionedSchema(personaDefinitionsFileSchema, input), text, 'Persona definitions');
+export const safeParseUsersDefinition = (input) => parseVersionedSchema(usersDefinitionFileSchema, input);
+export const parseUsersDefinition = (input) => parseOrThrow(safeParseUsersDefinition(input));
+export const validateUsersDefinitionText = (text) => parseText((input) => parseVersionedSchema(usersDefinitionFileSchema, input), text, 'Users definition');
+export const safeParseRelatedCatalog = (input) => parseVersionedSchema(relatedCatalogSchema, input);
+export const parseRelatedCatalog = (input) => parseOrThrow(safeParseRelatedCatalog(input));
+export const validateRelatedCatalogText = (text) => parseText((input) => parseVersionedSchema(relatedCatalogSchema, input), text, 'Related catalog');
+export const safeParseSnapshot = (input) => parseSchema(snapshotFileSchema, input);
+export const parseSnapshot = (input) => parseOrThrow(safeParseSnapshot(input));
+export const validateSnapshotText = (text) => parseText((input) => parseSchema(snapshotFileSchema, input), text, 'Snapshot');
+//# sourceMappingURL=parse.js.map

package/lib/spec/parse.js.map

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

package/lib/spec/personaDefinitions.d.ts

@@ -0,0 +1,56 @@
+import { z } from 'zod';
+export declare const personaSchema: z.ZodObject<{
+    profile: z.ZodOptional<z.ZodString>;
+    role: z.ZodOptional<z.ZodString>;
+    permissionSetMode: z.ZodOptional<z.ZodEnum<{
+        additive: "additive";
+        sync: "sync";
+    }>>;
+    permissionSetGroupMode: z.ZodOptional<z.ZodEnum<{
+        additive: "additive";
+        sync: "sync";
+    }>>;
+    publicGroupMode: z.ZodOptional<z.ZodEnum<{
+        additive: "additive";
+        sync: "sync";
+    }>>;
+    queueMode: z.ZodOptional<z.ZodEnum<{
+        additive: "additive";
+        sync: "sync";
+    }>>;
+    permissionSets: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    permissionSetGroups: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    publicGroups: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    queues: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    userAttributes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$loose>;
+export declare const personaDefinitionsFileSchema: z.ZodObject<{
+    schemaVersion: z.ZodOptional<z.ZodLiteral<1>>;
+    personas: z.ZodRecord<z.ZodString, z.ZodObject<{
+        profile: z.ZodOptional<z.ZodString>;
+        role: z.ZodOptional<z.ZodString>;
+        permissionSetMode: z.ZodOptional<z.ZodEnum<{
+            additive: "additive";
+            sync: "sync";
+        }>>;
+        permissionSetGroupMode: z.ZodOptional<z.ZodEnum<{
+            additive: "additive";
+            sync: "sync";
+        }>>;
+        publicGroupMode: z.ZodOptional<z.ZodEnum<{
+            additive: "additive";
+            sync: "sync";
+        }>>;
+        queueMode: z.ZodOptional<z.ZodEnum<{
+            additive: "additive";
+            sync: "sync";
+        }>>;
+        permissionSets: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        permissionSetGroups: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        publicGroups: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        queues: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        userAttributes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+export type PersonaDefinition = z.infer<typeof personaSchema>;
+export type PersonaDefinitionsFile = z.infer<typeof personaDefinitionsFileSchema>;

package/lib/spec/personaDefinitions.js

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+const schemaVersionSchema = z.literal(1).optional().describe('Supported file schema version. Omit it for version 1.');
+const assignmentModeSchema = z.enum(['additive', 'sync']).describe('How assignments are applied.');
+export const personaSchema = z
+    .looseObject({
+    profile: z.string().optional().describe('Profile name or Salesforce Id.'),
+    role: z.string().optional().describe('Role name or Salesforce Id.'),
+    permissionSetMode: assignmentModeSchema.optional().describe('Permission Set assignment mode.'),
+    permissionSetGroupMode: assignmentModeSchema.optional().describe('Permission Set Group assignment mode.'),
+    publicGroupMode: assignmentModeSchema.optional().describe('Public Group assignment mode.'),
+    queueMode: assignmentModeSchema.optional().describe('Queue assignment mode.'),
+    permissionSets: z.array(z.string()).optional().describe('Permission Set names or Salesforce Ids.'),
+    permissionSetGroups: z.array(z.string()).optional().describe('Permission Set Group names or Salesforce Ids.'),
+    publicGroups: z.array(z.string()).optional().describe('Public Group names or Salesforce Ids.'),
+    queues: z.array(z.string()).optional().describe('Queue names or Salesforce Ids.'),
+    userAttributes: z.record(z.string(), z.unknown()).optional().describe('User fields applied by this persona.'),
+})
+    .describe('A reusable set of User fields and assignments. Unknown metadata keys are preserved.');
+export const personaDefinitionsFileSchema = z
+    .looseObject({
+    schemaVersion: schemaVersionSchema,
+    personas: z.record(z.string(), personaSchema).describe('Persona definitions keyed by persona name.'),
+})
+    .describe('A Warden persona definitions file.');
+//# sourceMappingURL=personaDefinitions.js.map

package/lib/spec/personaDefinitions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"personaDefinitions.js","sourceRoot":"","sources":["../../src/spec/personaDefinitions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,mBAAmB,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,uDAAuD,CAAC,CAAC;AAEtH,MAAM,oBAAoB,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,8BAA8B,CAAC,CAAC;AAEnG,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC;KAC3B,WAAW,CAAC;IACX,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,gCAAgC,CAAC;IACzE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,6BAA6B,CAAC;IACnE,iBAAiB,EAAE,oBAAoB,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,iCAAiC,CAAC;IAC9F,sBAAsB,EAAE,oBAAoB,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,uCAAuC,CAAC;IACzG,eAAe,EAAE,oBAAoB,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,+BAA+B,CAAC;IAC1F,SAAS,EAAE,oBAAoB,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,wBAAwB,CAAC;IAC7E,cAAc,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,yCAAyC,CAAC;IAClG,mBAAmB,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,+CAA+C,CAAC;IAC7G,YAAY,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,uCAAuC,CAAC;IAC9F,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,gCAAgC,CAAC;IACjF,cAAc,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,sCAAsC,CAAC;CAC9G,CAAC;KACD,QAAQ,CAAC,qFAAqF,CAAC,CAAC;AAEnG,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC;KAC1C,WAAW,CAAC;IACX,aAAa,EAAE,mBAAmB;IAClC,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,aAAa,CAAC,CAAC,QAAQ,CAAC,4CAA4C,CAAC;CACrG,CAAC;KACD,QAAQ,CAAC,oCAAoC,CAAC,CAAC"}

package/lib/spec/relatedCatalog.d.ts

@@ -0,0 +1,61 @@
+import { z } from 'zod';
+declare const sourceExprSchema: z.ZodUnion<readonly [z.ZodObject<{
+    from: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    value: z.ZodUnknown;
+}, z.core.$strict>]>;
+export declare const relationshipDefSchema: z.ZodObject<{
+    sobject: z.ZodString;
+    phase: z.ZodEnum<{
+        before: "before";
+        after: "after";
+    }>;
+    recordType: z.ZodNullable<z.ZodOptional<z.ZodObject<{
+        developerName: z.ZodString;
+    }, z.core.$loose>>>;
+    match: z.ZodObject<{
+        field: z.ZodString;
+        from: z.ZodString;
+    }, z.core.$loose>;
+    fields: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+        from: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        value: z.ZodUnknown;
+    }, z.core.$strict>]>>;
+    mode: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        sync: "sync";
+        setIfEmpty: "setIfEmpty";
+    }>>>;
+}, z.core.$loose>;
+export declare const relatedCatalogSchema: z.ZodObject<{
+    schemaVersion: z.ZodOptional<z.ZodLiteral<1>>;
+    relationships: z.ZodRecord<z.ZodString, z.ZodObject<{
+        sobject: z.ZodString;
+        phase: z.ZodEnum<{
+            before: "before";
+            after: "after";
+        }>;
+        recordType: z.ZodNullable<z.ZodOptional<z.ZodObject<{
+            developerName: z.ZodString;
+        }, z.core.$loose>>>;
+        match: z.ZodObject<{
+            field: z.ZodString;
+            from: z.ZodString;
+        }, z.core.$loose>;
+        fields: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+            from: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            value: z.ZodUnknown;
+        }, z.core.$strict>]>>;
+        mode: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+            sync: "sync";
+            setIfEmpty: "setIfEmpty";
+        }>>>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+export type SourceExpr = z.infer<typeof sourceExprSchema>;
+export type RelationshipDef = z.infer<typeof relationshipDefSchema>;
+export type RelationshipMode = NonNullable<RelationshipDef['mode']>;
+export type RelationshipPhase = RelationshipDef['phase'];
+export type RelatedCatalog = z.infer<typeof relatedCatalogSchema>;
+export {};

package/lib/spec/relatedCatalog.js

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+const schemaVersionSchema = z.literal(1).optional().describe('Supported file schema version. Omit it for version 1.');
+const sourceExprSchema = z.union([
+    z.strictObject({ from: z.string().describe('A source such as user.Department or user.Id.') }),
+    z.strictObject({ value: z.unknown().describe('A literal value.') }),
+]);
+export const relationshipDefSchema = z
+    .looseObject({
+    sobject: z.string().describe('Target Salesforce object API name.'),
+    phase: z.enum(['before', 'after']).describe('When the relationship is applied.'),
+    recordType: z
+        .looseObject({ developerName: z.string().describe('Record Type developer name.') })
+        .optional()
+        .nullable()
+        .describe('Optional target record type.'),
+    match: z
+        .looseObject({
+        field: z.string().describe('Target field used to find an existing record.'),
+        from: z.string().describe('User source used for the target match.'),
+    })
+        .describe('Target match configuration.'),
+    fields: z.record(z.string(), sourceExprSchema).describe('Target fields and their source expressions.'),
+    mode: z.enum(['setIfEmpty', 'sync']).nullish().describe('How configured fields are updated.'),
+})
+    .describe('A reusable related-record relationship.');
+export const relatedCatalogSchema = z
+    .looseObject({
+    schemaVersion: schemaVersionSchema,
+    relationships: z.record(z.string(), relationshipDefSchema).describe('Relationships keyed by name.'),
+})
+    .describe('A Warden related-record catalog.');
+//# sourceMappingURL=relatedCatalog.js.map

package/lib/spec/relatedCatalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relatedCatalog.js","sourceRoot":"","sources":["../../src/spec/relatedCatalog.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,mBAAmB,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,uDAAuD,CAAC,CAAC;AAEtH,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC;IAC/B,CAAC,CAAC,YAAY,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,8CAA8C,CAAC,EAAE,CAAC;IAC7F,CAAC,CAAC,YAAY,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAAC;CACpE,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC;KACnC,WAAW,CAAC;IACX,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,oCAAoC,CAAC;IAClE,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,mCAAmC,CAAC;IAChF,UAAU,EAAE,CAAC;SACV,WAAW,CAAC,EAAE,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,6BAA6B,CAAC,EAAE,CAAC;SAClF,QAAQ,EAAE;SACV,QAAQ,EAAE;SACV,QAAQ,CAAC,8BAA8B,CAAC;IAC3C,KAAK,EAAE,CAAC;SACL,WAAW,CAAC;QACX,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,+CAA+C,CAAC;QAC3E,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,wCAAwC,CAAC;KACpE,CAAC;SACD,QAAQ,CAAC,6BAA6B,CAAC;IAC1C,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,gBAAgB,CAAC,CAAC,QAAQ,CAAC,6CAA6C,CAAC;IACtG,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,CAAC,oCAAoC,CAAC;CAC9F,CAAC;KACD,QAAQ,CAAC,yCAAyC,CAAC,CAAC;AAEvD,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC;KAClC,WAAW,CAAC;IACX,aAAa,EAAE,mBAAmB;IAClC,aAAa,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,qBAAqB,CAAC,CAAC,QAAQ,CAAC,8BAA8B,CAAC;CACpG,CAAC;KACD,QAAQ,CAAC,kCAAkC,CAAC,CAAC"}

package/lib/spec/snapshot.d.ts

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+export declare const userSnapshotEntrySchema: z.ZodObject<{
+    match: z.ZodString;
+    matchValue: z.ZodString;
+    userId: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    username: z.ZodOptional<z.ZodString>;
+    email: z.ZodOptional<z.ZodString>;
+    profile: z.ZodOptional<z.ZodString>;
+    role: z.ZodOptional<z.ZodString>;
+    IsActive: z.ZodBoolean;
+    IsFrozen: z.ZodBoolean;
+    permissionSets: z.ZodArray<z.ZodString>;
+    permissionSetGroups: z.ZodArray<z.ZodString>;
+    publicGroups: z.ZodArray<z.ZodString>;
+    queues: z.ZodArray<z.ZodString>;
+    permissionSetLicenses: z.ZodArray<z.ZodString>;
+}, z.core.$loose>;
+export declare const snapshotFileSchema: z.ZodObject<{
+    snapshotVersion: z.ZodLiteral<1>;
+    capturedAt: z.ZodOptional<z.ZodString>;
+    org: z.ZodOptional<z.ZodString>;
+    users: z.ZodArray<z.ZodObject<{
+        match: z.ZodString;
+        matchValue: z.ZodString;
+        userId: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        username: z.ZodOptional<z.ZodString>;
+        email: z.ZodOptional<z.ZodString>;
+        profile: z.ZodOptional<z.ZodString>;
+        role: z.ZodOptional<z.ZodString>;
+        IsActive: z.ZodBoolean;
+        IsFrozen: z.ZodBoolean;
+        permissionSets: z.ZodArray<z.ZodString>;
+        permissionSetGroups: z.ZodArray<z.ZodString>;
+        publicGroups: z.ZodArray<z.ZodString>;
+        queues: z.ZodArray<z.ZodString>;
+        permissionSetLicenses: z.ZodArray<z.ZodString>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+export type UserSnapshotEntry = z.infer<typeof userSnapshotEntrySchema>;
+export type UserSnapshotFile = z.infer<typeof snapshotFileSchema>;

package/lib/spec/snapshot.js

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+const optionalSnapshotText = z.string().optional();
+export const userSnapshotEntrySchema = z
+    .looseObject({
+    match: z.string().min(1).describe('User field used to identify the snapshot entry.'),
+    matchValue: z.string().min(1).describe('Value used with the match field.'),
+    userId: z.string().min(1).describe('Salesforce User Id.'),
+    name: optionalSnapshotText.describe('User name at capture time.'),
+    username: optionalSnapshotText.describe('User username at capture time.'),
+    email: optionalSnapshotText.describe('User email at capture time.'),
+    profile: optionalSnapshotText.describe('User profile at capture time.'),
+    role: optionalSnapshotText.describe('User role at capture time.'),
+    IsActive: z.boolean().describe('Whether the User was active at capture time.'),
+    IsFrozen: z.boolean().describe('Whether the User login was frozen at capture time.'),
+    permissionSets: z.array(z.string()).describe('Permission Set names.'),
+    permissionSetGroups: z.array(z.string()).describe('Permission Set Group names.'),
+    publicGroups: z.array(z.string()).describe('Public Group names.'),
+    queues: z.array(z.string()).describe('Queue names.'),
+    permissionSetLicenses: z.array(z.string()).describe('Permission Set License names.'),
+})
+    .describe('A User assignment snapshot entry.');
+export const snapshotFileSchema = z
+    .looseObject({
+    snapshotVersion: z.literal(1).describe('Snapshot format version.'),
+    // Optional: version-1 JSON snapshots written before this schema existed
+    // were accepted without it, and the reader must keep accepting them.
+    capturedAt: z.string().optional().describe('Capture timestamp in ISO format.'),
+    org: z.string().optional().describe('Optional org alias or username.'),
+    users: z.array(userSnapshotEntrySchema).describe('Captured User state.'),
+})
+    .describe('A Warden User snapshot file.');
+//# sourceMappingURL=snapshot.js.map

package/lib/spec/snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../../src/spec/snapshot.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC;AAEnD,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC;KACrC,WAAW,CAAC;IACX,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,iDAAiD,CAAC;IACpF,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,kCAAkC,CAAC;IAC1E,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,qBAAqB,CAAC;IACzD,IAAI,EAAE,oBAAoB,CAAC,QAAQ,CAAC,4BAA4B,CAAC;IACjE,QAAQ,EAAE,oBAAoB,CAAC,QAAQ,CAAC,gCAAgC,CAAC;IACzE,KAAK,EAAE,oBAAoB,CAAC,QAAQ,CAAC,6BAA6B,CAAC;IACnE,OAAO,EAAE,oBAAoB,CAAC,QAAQ,CAAC,+BAA+B,CAAC;IACvE,IAAI,EAAE,oBAAoB,CAAC,QAAQ,CAAC,4BAA4B,CAAC;IACjE,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,CAAC,8CAA8C,CAAC;IAC9E,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,CAAC,oDAAoD,CAAC;IACpF,cAAc,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,CAAC,uBAAuB,CAAC;IACrE,mBAAmB,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,CAAC,6BAA6B,CAAC;IAChF,YAAY,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,CAAC,qBAAqB,CAAC;IACjE,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,CAAC,cAAc,CAAC;IACpD,qBAAqB,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,CAAC,+BAA+B,CAAC;CACrF,CAAC;KACD,QAAQ,CAAC,mCAAmC,CAAC,CAAC;AAEjD,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC;KAChC,WAAW,CAAC;IACX,eAAe,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,0BAA0B,CAAC;IAClE,wEAAwE;IACxE,qEAAqE;IACrE,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,kCAAkC,CAAC;IAC9E,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,iCAAiC,CAAC;IACtE,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,uBAAuB,CAAC,CAAC,QAAQ,CAAC,sBAAsB,CAAC;CACzE,CAAC;KACD,QAAQ,CAAC,8BAA8B,CAAC,CAAC"}

package/lib/spec/usersDefinition.d.ts

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+export declare const userInputSchema: z.ZodObject<{
+    personas: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$loose>;
+export declare const usersDefinitionFileSchema: z.ZodObject<{
+    schemaVersion: z.ZodOptional<z.ZodLiteral<1>>;
+    users: z.ZodArray<z.ZodObject<{
+        personas: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+/**
+ * CSV has no JSON Schema because its User columns come from Salesforce describe metadata.
+ * The fixed metadata columns are `personas`, `match`, and `fuzzyUsername`; all other
+ * columns are User API names. `personas` is a semicolon-delimited list by default,
+ * configurable with `csvListDelimiter`.
+ */
+export declare const USERS_CSV_COLUMNS: readonly ["personas", "match", "fuzzyUsername"];
+export type UserInput = z.infer<typeof userInputSchema>;
+export type UsersDefinitionFile = z.infer<typeof usersDefinitionFileSchema>;

package/lib/spec/usersDefinition.js

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+const schemaVersionSchema = z.literal(1).optional().describe('Supported file schema version. Omit it for version 1.');
+export const userInputSchema = z
+    .looseObject({
+    personas: z.array(z.string()).optional().describe('Persona names to merge for this user.'),
+})
+    .describe('A User field record with optional Warden metadata.');
+export const usersDefinitionFileSchema = z
+    .looseObject({
+    schemaVersion: schemaVersionSchema,
+    users: z.array(userInputSchema).describe('User definitions.'),
+})
+    .describe('A Warden JSON users definition file.');
+/**
+ * CSV has no JSON Schema because its User columns come from Salesforce describe metadata.
+ * The fixed metadata columns are `personas`, `match`, and `fuzzyUsername`; all other
+ * columns are User API names. `personas` is a semicolon-delimited list by default,
+ * configurable with `csvListDelimiter`.
+ */
+export const USERS_CSV_COLUMNS = ['personas', 'match', 'fuzzyUsername'];
+//# sourceMappingURL=usersDefinition.js.map

package/lib/spec/usersDefinition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usersDefinition.js","sourceRoot":"","sources":["../../src/spec/usersDefinition.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,mBAAmB,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,uDAAuD,CAAC,CAAC;AAEtH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC;KAC7B,WAAW,CAAC;IACX,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,uCAAuC,CAAC;CAC3F,CAAC;KACD,QAAQ,CAAC,oDAAoD,CAAC,CAAC;AAElE,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC;KACvC,WAAW,CAAC;IACX,aAAa,EAAE,mBAAmB;IAClC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC,QAAQ,CAAC,mBAAmB,CAAC;CAC9D,CAAC;KACD,QAAQ,CAAC,sCAAsC,CAAC,CAAC;AAEpD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,UAAU,EAAE,OAAO,EAAE,eAAe,CAAU,CAAC"}

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@syntax-syllogism/warden-core",
+  "description": "Shared Warden engine: the user-lifecycle library behind the warden CLI, VS Code extension, and SFDX package.",
+  "version": "0.2.0",
+  "author": "Jake Richter <j.p.richter@gmail.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/Syntax-Syllogism/warden-core#readme",
+  "bugs": "https://github.com/Syntax-Syllogism/warden-core/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Syntax-Syllogism/warden-core.git"
+  },
+  "keywords": [
+    "salesforce",
+    "sf",
+    "sfdx",
+    "warden",
+    "user lifecycle"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "files": [
+    "/lib",
+    "/schemas",
+    "/conformance",
+    "/CHANGELOG.md",
+    "/LICENSE"
+  ],
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./schemas/*": "./schemas/*"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p . && node scripts/gen-json-schema.mjs",
+    "clean": "rm -rf lib",
+    "lint": "eslint src test",
+    "format": "prettier --write \"+(src|test|scripts)/**/*.+(ts|js|mjs|json)\"",
+    "format:check": "prettier --check \"+(src|test|scripts)/**/*.+(ts|js|mjs|json)\"",
+    "schemas:check": "npm run build && git diff --exit-code -- schemas/",
+    "typecheck": "tsc -p . --noEmit && tsc -p test --noEmit",
+    "test:only": "TS_NODE_PROJECT=test/tsconfig.json mocha \"test/**/*.test.ts\"",
+    "test": "npm run typecheck && npm run lint && npm run format:check && c8 npm run test:only",
+    "pack:check": "node scripts/check-pack.mjs",
+    "prepack": "npm run clean && npm run build"
+  },
+  "dependencies": {
+    "@salesforce/core": "^8",
+    "zod": "^4"
+  },
+  "devDependencies": {
+    "@salesforce/dev-config": "^4.1.0",
+    "@salesforce/prettier-config": "^0.0.4",
+    "ajv": "^8.18.0",
+    "@types/chai": "^4.3.14",
+    "@types/mocha": "^10.0.6",
+    "@types/node": "^22",
+    "@types/sinon": "^10.0.20",
+    "c8": "^11.0.0",
+    "chai": "^4.3.10",
+    "eslint": "^8.57.0",
+    "eslint-config-salesforce-typescript": "^3.3.0",
+    "mocha": "^10.4.0",
+    "prettier": "^2.8.8",
+    "sinon": "^10.0.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.4.5"
+  }
+}

package/schemas/persona-definitions.schema.json

@@ -0,0 +1,108 @@
+{
+  "$id": "https://raw.githubusercontent.com/Syntax-Syllogism/warden-core/release/schemas/persona-definitions.schema.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": {},
+  "description": "A Warden persona definitions file.",
+  "properties": {
+    "personas": {
+      "additionalProperties": {
+        "additionalProperties": {},
+        "description": "A reusable set of User fields and assignments. Unknown metadata keys are preserved.",
+        "properties": {
+          "permissionSetGroupMode": {
+            "description": "Permission Set Group assignment mode.",
+            "enum": [
+              "additive",
+              "sync"
+            ],
+            "type": "string"
+          },
+          "permissionSetGroups": {
+            "description": "Permission Set Group names or Salesforce Ids.",
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "permissionSetMode": {
+            "description": "Permission Set assignment mode.",
+            "enum": [
+              "additive",
+              "sync"
+            ],
+            "type": "string"
+          },
+          "permissionSets": {
+            "description": "Permission Set names or Salesforce Ids.",
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "profile": {
+            "description": "Profile name or Salesforce Id.",
+            "type": "string"
+          },
+          "publicGroupMode": {
+            "description": "Public Group assignment mode.",
+            "enum": [
+              "additive",
+              "sync"
+            ],
+            "type": "string"
+          },
+          "publicGroups": {
+            "description": "Public Group names or Salesforce Ids.",
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "queueMode": {
+            "description": "Queue assignment mode.",
+            "enum": [
+              "additive",
+              "sync"
+            ],
+            "type": "string"
+          },
+          "queues": {
+            "description": "Queue names or Salesforce Ids.",
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "role": {
+            "description": "Role name or Salesforce Id.",
+            "type": "string"
+          },
+          "userAttributes": {
+            "additionalProperties": {},
+            "description": "User fields applied by this persona.",
+            "propertyNames": {
+              "type": "string"
+            },
+            "type": "object"
+          }
+        },
+        "type": "object"
+      },
+      "description": "Persona definitions keyed by persona name.",
+      "propertyNames": {
+        "type": "string"
+      },
+      "type": "object"
+    },
+    "schemaVersion": {
+      "const": 1,
+      "description": "Supported file schema version. Omit it for version 1.",
+      "type": "number"
+    }
+  },
+  "required": [
+    "personas"
+  ],
+  "title": "Warden persona definitions schema",
+  "type": "object"
+}