zod-migration

Zod Migration

Migrate a CLI for Microsoft 365 command from the legacy #initOptions()/#initValidators()/#initTelemetry() pattern to Zod schema-based validation.

When to Use

• Command still has #initOptions(), #initValidators(), or #initTelemetry() methods
• Command does not have a schema getter or exported options Zod schema

Pre-flight

1. Read the command source file (.ts) and its test file (.spec.ts)
2. Identify: options, aliases, validators, telemetry, option sets, types
3. Check if the command has autocomplete values on any options
4. Check whether any command option representing a GUID or UPN accepts the runtime tokens @meid or @meusername

Procedure

Step 1: Define the Zod Schema (command .ts file)

Replace imports and add schema definition above the class:

import { z } from 'zod';
import { globalOptionsZod } from '../../../../Command.js';
// Remove: import GlobalOptions from '../../../../GlobalOptions.js';

export const options = z.strictObject({
  ...globalOptionsZod.shape,
  // Add command-specific options here
});

declare type Options = z.infer<typeof options>;

interface CommandArgs {
  options: Options;
}

Option Type Mapping

Critical Rules for Schema Definition

1. ALWAYS use z.strictObject() — not z.object(). Strict rejects unknown options.
2. ALWAYS spread ...globalOptionsZod.shape — includes debug, verbose, output, query.
3. ALWAYS export options — the spec file imports it for typing.
4. NEVER use z.uuid() for fields that accept @meid token — use .refine() with custom GUID validation instead (see below).
5. Preserve case-insensitive behavior — if old validator lowercased input before comparing, add .transform(v => v.toLowerCase()) or use .refine() with case-insensitive check.
6. Keep option names identical — do not rename options during migration (breaking change).
7. Use z.enum() for options with fixed autocomplete values — this preserves shell completion metadata.
8. For commands with ONLY global options (no command-specific options), use globalOptionsZod.strict() — globalOptionsZod alone is NOT strict and will allow unknown options to slip through:

// WRONG - not strict, allows unknown options
export const options = globalOptionsZod;

// CORRECT - strict, rejects unknown options
export const options = globalOptionsZod.strict();

GUID Fields That Accept @meid

// WRONG - rejects @meid token
id: z.string().uuid()

// CORRECT - allows @meid token
id: z.string().refine(val => validation.isValidGuid(val), {
  message: 'The value must be a valid GUID.'
})

Comma-Separated String Fields

When an option accepts comma-separated values (e.g., --scopes Sites.Read.All,Sites.ReadWrite.All), use .transform() to split into an array if the command processes them as arrays:

scopes: z.string().transform(value => value.split(',').map(s => s.trim())).alias('s')

Comma-Separated GUID/UPN Validation Error Messages

When validating comma-separated GUIDs or UPNs, error messages MUST report only the invalid values, not the entire input string. The full input may contain valid values mixed with invalid ones.

// WRONG - reports entire input string (misleading when it contains valid values)
ids: z.string().refine(val => validation.isValidGuidArray(val), {
  message: `'${val}' contains invalid GUIDs`  // val is "guid1,invalid,guid2"
})

// CORRECT - reports only the invalid values
ids: z.string().refine(val => {
  const items = val.split(',').map(s => s.trim());
  const invalid = items.filter(item => !validation.isValidGuid(item));
  return invalid.length === 0;
}, val => ({
  message: `The following values are not valid GUIDs: ${val.split(',').map(s => s.trim()).filter(item => !validation.isValidGuid(item)).join(', ')}`
}))

Numeric Values Received as Strings

CLI arguments are strings. If the command previously relied on yargs numeric coercion (via types.string exclusion), handle conversion explicitly in commandAction:

// In commandAction:
const pageSize = Number(args.options.value);

Step 2: Add Schema Getter to the Class

public get schema(): z.ZodType | undefined {
  return options;
}

Step 3: Remove Legacy Methods

Delete these methods entirely from the class:

• constructor() (if it only called super() + init methods)
• #initOptions()
• #initValidators()
• #initTelemetry()
• #initTypes()
• #initOptionSets()

Step 4: Add getRefinedSchema() for Cross-Field Validation

Use getRefinedSchema() when:

• Command has option sets (mutually exclusive or "one of" requirements)
• Command has conditional validation (option B required when option A is set)
• Command had validators with cross-field logic

Option Set Pattern (exactly one of N options required)

public getRefinedSchema(schema: typeof options): z.ZodObject<any> | undefined {
  return schema
    .refine(opts => [opts.id, opts.name].filter(x => x !== undefined).length === 1, {
      message: `Specify either 'id' or 'name', but not both.`,
      params: {
        customCode: 'optionSet',
        options: ['id', 'name']
      }
    });
}

Required Dependency Pattern (B required when A is provided)

public getRefinedSchema(schema: typeof options): z.ZodObject<any> | undefined {
  return schema
    .refine(opts => !opts.cardData || opts.card, {
      error: 'When you specify cardData, you must also specify card.',
      path: ['cardData'],
      params: {
        customCode: 'required'
      }
    });
}

At-Least-One-Update Pattern (set commands)

public getRefinedSchema(schema: typeof options): z.ZodObject<any> | undefined {
  return schema
    .refine(opts => opts.description || opts.status || opts.owner, {
      message: 'Specify at least one property to update.',
      params: {
        customCode: 'required'
      }
    });
}

Step 5: Handle Validators That Must Stay in Schema

CRITICAL: When a command defines schema, the CLI does NOT run this.validators. All validation MUST live in the schema or getRefinedSchema().

Move file-system checks, URL validation, and other validators into .refine() calls:

export const options = z.strictObject({
  ...globalOptionsZod.shape,
  filePath: z.string()
    .refine(val => fs.existsSync(val), {
      message: 'Specified file does not exist.'
    })
});

Step 6: Handle Loose Schemas (commands accepting unknown options)

Some commands (like user-set, user-add, groupsetting-set) accept arbitrary options passed through to the API. Use z.object() instead of z.strictObject():

export const options = z.object({
  ...globalOptionsZod.shape,
  id: z.string()
}).catchall(z.unknown());

Step 7: Migrate the Test File (.spec.ts)

CRITICAL: Update ALL spec files for ALL commands being migrated — including commands that only have global options (no command-specific options). Every spec file must get the commandOptionsSchema pattern and use commandOptionsSchema.parse() in action tests.

7a. Update imports

// Old:
import command from './command-name.js';
// New:
import command, { options } from './command-name.js';

7b. Add schema variable declaration

describe(commands.COMMAND_NAME, () => {
  let commandInfo: CommandInfo;
  let commandOptionsSchema: typeof options;  // ADD THIS

  before(() => {
    commandInfo = cli.getCommandInfo(command);
    commandOptionsSchema = commandInfo.command.getSchemaToParse() as typeof options;  // ADD THIS
    // ...
  });

7c. Convert validation tests to use safeParse

// Old:
it('fails validation if id is not valid', async () => {
  const actual = await command.validate({ options: { id: 'invalid' } }, commandInfo);
  assert.notStrictEqual(actual, true);
});

// New:
it('fails validation if id is not valid', () => {
  const actual = commandOptionsSchema.safeParse({ id: 'invalid' });
  assert.strictEqual(actual.success, false);
});

Note: Validation tests become synchronous (no async).

7d. Convert action tests to use commandOptionsSchema.parse()

CRITICAL: Always use commandOptionsSchema.parse() — NEVER use options.parse() directly. The commandOptionsSchema variable is obtained from commandInfo.command.getSchemaToParse() which returns the refined schema (including cross-field validations from getRefinedSchema()).

// WRONG - uses options.parse() directly (misses refined schema)
await command.action(logger, { options: options.parse({ id: 'abc', verbose: true }) });

// WRONG - passes raw options object (no schema validation)
await command.action(logger, { options: { id: 'abc', verbose: true } });

// CORRECT - uses commandOptionsSchema.parse()
await command.action(logger, { options: commandOptionsSchema.parse({ id: 'abc', verbose: true }) });

Exception for @meid/@meusername tokens: Tests that use runtime tokens like @meid or @meusername (which are replaced by loadValuesFromAccessToken before schema validation) must keep as any since these values intentionally bypass Zod:

// @meid is a runtime token - cannot go through parse
await command.action(logger, { options: { id: '@meid' } as any });

7e. Remove legacy "supports specifying" tests

Delete tests like:

// DELETE these — schema handles option registration
it('supports specifying id', () => {
  const options = command.options;
  let containsOption = false;
  options.forEach(o => { ... });
  assert(containsOption);
});

7f. Add required validation tests

ALWAYS add these tests:

For commands that reject unknown options:

it('fails validation with unknown options', () => {
  const actual = commandOptionsSchema.safeParse({
    id: 'valid-id',
    unknownOption: 'value'
  });
  assert.strictEqual(actual.success, false);
});

For commands where all specific options are optional:

it('passes validation with no options', () => {
  const actual = commandOptionsSchema.safeParse({});
  assert.strictEqual(actual.success, true);
});

Checklist

Before submitting, verify:

• options is exported from the command file
• Schema uses z.strictObject() (unless command accepts unknown options)
• For commands with ONLY global options, uses globalOptionsZod.strict() — not bare globalOptionsZod
• Schema spreads ...globalOptionsZod.shape
• schema getter returns options
• All old init methods (#initOptions, #initValidators, #initTelemetry, #initTypes, #initOptionSets) are removed
• Constructor removed (if it only called init methods)
• No this.validators or this.options.unshift(...) remain
• All validators moved to schema .refine() or getRefinedSchema()
• getRefinedSchema() uses params: { customCode: 'optionSet', options: [...] } for option sets
• getRefinedSchema() uses params: { customCode: 'required' } for conditional requirements
• GUID fields that accept @meid do NOT use z.uuid()
• Options with autocomplete values use z.enum() when possible
• Case-insensitive validation preserved where it existed before
• No option renames (no breaking changes)
• Comma-separated GUID/UPN validation errors report only invalid values (not the full input)
• ALL spec files updated (including for commands with only global options)
• Spec file imports { options } from the command file
• Spec declares commandOptionsSchema: typeof options
• Spec initializes commandOptionsSchema = commandInfo.command.getSchemaToParse() as typeof options
• All action tests use commandOptionsSchema.parse({...}) — NEVER options.parse({...}) directly
• All validation tests use commandOptionsSchema.safeParse({...})
• Validation tests are synchronous (no async)
• Legacy "supports specifying" tests removed
• Test added: 'fails validation with unknown options'
• Test added (when applicable): 'passes validation with no options'
• No test uses command.validate(...) — all validation goes through schema