@stacksjs/defaults 0.75.361 → 0.75.362

package/ai/skills/stacks-technical-diagrams/renderers/shared/output-path.mjs

@@ -1,236 +1,359 @@
-import fs from 'node:fs';
 import path from 'node:path';
+import {
+  containedBy,
+  isValidWindowsSmbShareName,
+  isWindowsIpcShare,
+  resolvePhysicalLocation,
+  sameLocation,
+} from './path-semantics.mjs';
+import { PortablePathError, validatePortablePath } from './portable-path.mjs';
 
-const MAX_SYMLINK_DEPTH = 64;
-const directorySemanticsCache = new Map();
-let semanticsProbeSequence = 0;
-
-function splitAbsolute(absolutePath) {
-  const root = path.parse(absolutePath).root;
-  return {
-    root,
-    segments: absolutePath.slice(root.length).split(path.sep).filter(Boolean),
-  };
-}
-
-function canonicalize(targetPath, depth) {
-  const absolutePath = path.resolve(targetPath);
-  const { root, segments } = splitAbsolute(absolutePath);
-  let current = root;
-
-  for (let index = 0; index < segments.length; index += 1) {
-    const candidate = path.join(current, segments[index]);
-    let stat;
-    try {
-      stat = fs.lstatSync(candidate);
-    } catch (error) {
-      if (error.code === 'ENOENT' || error.code === 'ENOTDIR') {
-        return path.resolve(current, ...segments.slice(index));
-      }
-      throw error;
-    }
-
-    if (stat.isSymbolicLink()) {
-      if (depth >= MAX_SYMLINK_DEPTH) {
-        const error = new Error(`Could not resolve path because a symbolic-link cycle includes "${candidate}".`);
-        error.code = 'ELOOP';
-        error.path = candidate;
-        throw error;
-      }
-      const link = fs.readlinkSync(candidate);
-      const linkTarget = path.isAbsolute(link) ? link : path.resolve(path.dirname(candidate), link);
-      return canonicalize(path.join(linkTarget, ...segments.slice(index + 1)), depth + 1);
-    }
-
-    current = fs.realpathSync.native(candidate);
+export function canonicalFuturePath(targetPath) {
+  const resolution = resolvePhysicalLocation(targetPath);
+  if (resolution.status === 'resolved') {
+    if (resolution.location.kind === 'existing') return resolution.location.path;
+    return path.join(
+      resolution.location.ancestorPath,
+      ...resolution.location.unresolved,
+    );
   }
-
-  return path.normalize(current);
+  const output = path.resolve(targetPath);
+  if (resolution.reason.code === 'symlink-cycle') {
+    throw new OutputPathError(`Output path contains a symbolic-link cycle: "${output}".`, {
+      code: 'output/symlink-cycle',
+      message: 'Output path could not be resolved because it contains a symbolic-link cycle.',
+      subject: { output },
+      evidence: { relation: resolution.reason },
+      supportedFixes: ['remove the symbolic-link cycle or choose an output path outside it'],
+    });
+  }
+  throw new OutputPathError('Output path could not be resolved safely.', {
+    code: 'output/path-resolution-indeterminate',
+    message: 'Output path could not be resolved safely for the requested filesystem location.',
+    subject: { output },
+    evidence: { relation: resolution.reason },
+    supportedFixes: ['use an ordinary local filesystem path that can be resolved safely, then retry'],
+  });
 }
 
-export function canonicalFuturePath(targetPath) {
-  try {
-    return canonicalize(targetPath, 0);
-  } catch (error) {
-    if (error?.code !== 'ELOOP') throw error;
-    const output = path.resolve(targetPath);
+export function pathsAlias(leftPath, rightPath) {
+  const relation = sameLocation(leftPath, rightPath);
+  if (relation.status === 'match') return true;
+  if (relation.status === 'different') return false;
+  if (relation.reason.code === 'ancestor-not-directory') return false;
+  if (relation.reason.code === 'symlink-cycle') {
+    const output = path.resolve(relation.reason.side === 'right' ? rightPath : leftPath);
     throw new OutputPathError(`Output path contains a symbolic-link cycle: "${output}".`, {
       code: 'output/symlink-cycle',
       message: 'Output path could not be resolved because it contains a symbolic-link cycle.',
       subject: { output },
-      evidence: {
-        systemCode: 'ELOOP',
-        ...(error.path ? { cycleAt: path.resolve(error.path) } : {}),
-      },
+      evidence: { relation: relation.reason },
       supportedFixes: ['remove the symbolic-link cycle or choose an output path outside it'],
     });
   }
+  throw new OutputPathError('Path identity could not be determined safely.', {
+    code: 'output/path-identity-indeterminate',
+    message: 'Path identity could not be determined safely for the requested filesystem location.',
+    subject: { left: path.resolve(leftPath), right: path.resolve(rightPath) },
+    evidence: { relation: relation.reason },
+    supportedFixes: ['use ordinary local filesystem paths whose identity can be verified, then retry'],
+  });
 }
 
-function hasFileIdentity(stat) {
-  return stat.ino !== 0 && stat.ino !== 0n;
+function pathIsInside(directoryPath, targetPath) {
+  const relation = containedBy(directoryPath, targetPath);
+  if (relation.status === 'match') return true;
+  if (relation.status === 'different') return false;
+  throw new OutputPathError('Output containment could not be determined safely.', {
+    code: 'output/containment-indeterminate',
+    message: 'Output containment could not be determined safely for the requested filesystem location.',
+    subject: { output: path.resolve(targetPath), cwd: path.resolve(directoryPath) },
+    evidence: { relation: relation.reason },
+    supportedFixes: ['use an output beneath an ordinary local directory whose identity can be verified'],
+  });
 }
 
-function sameFileIdentity(left, right) {
-  return hasFileIdentity(left)
-    && hasFileIdentity(right)
-    && left.dev === right.dev
-    && left.ino === right.ino;
+function authoredOutputDiagnostic(error, rawOutput) {
+  const absolute = error?.reason === 'absolute';
+  const code = absolute ? 'output/meta-absolute' : 'output/meta-path-syntax';
+  const message = absolute
+    ? 'meta.output must be a relative path resolved from the current working directory.'
+    : 'meta.output must be a portable POSIX-relative path.';
+  return {
+    code,
+    message,
+    subject: { output: rawOutput, path: '/meta/output' },
+    evidence: {
+      reason: error?.reason || 'invalid',
+      ...(error?.segmentIndex !== undefined ? { segmentIndex: error.segmentIndex } : {}),
+      ...(error?.segment !== undefined ? { segment: error.segment } : {}),
+      ...(error?.utf8Bytes !== undefined ? { utf8Bytes: error.utf8Bytes } : {}),
+      ...(error?.utf16CodeUnits !== undefined ? { utf16CodeUnits: error.utf16CodeUnits } : {}),
+      ...(error?.limit !== undefined ? { limit: error.limit } : {}),
+    },
+    supportedFixes: ['set meta.output to a portable relative .html path such as reports/diagram.html'],
+  };
 }
 
-function nearestExistingDirectory(targetPath) {
-  let directory = path.dirname(targetPath);
-  while (true) {
-    try {
-      const stat = fs.statSync(directory);
-      if (stat.isDirectory()) {
-        return {
-          path: fs.realpathSync.native(directory),
-          stat,
-        };
-      }
-    } catch (error) {
-      if (error.code !== 'ENOENT' && error.code !== 'ENOTDIR') return null;
-    }
-    const parent = path.dirname(directory);
-    if (parent === directory) return null;
-    directory = parent;
+function nativeOutputDiagnostic(rawOutput, reason, details = {}) {
+  return {
+    code: 'output/native-path-syntax',
+    message: 'The output path is not a valid native filesystem path on this host.',
+    subject: { output: rawOutput },
+    evidence: { reason, ...details },
+    supportedFixes: ['choose an ordinary filesystem path without device names, alternate data streams, trailing dots or spaces, or overlong components'],
+  };
+}
+
+function throwNativeOutputDiagnostic(rawOutput, reason, details = {}) {
+  const diagnostic = nativeOutputDiagnostic(rawOutput, reason, details);
+  throw new OutputPathError(diagnostic.message, diagnostic);
+}
+
+function windowsExtendedTailComponents(rawOutput, tail) {
+  const authoredComponents = tail.split('\\');
+  // Preserve one trailing separator for directory arguments, but never repair
+  // an empty component inside the raw extended namespace.
+  if (authoredComponents.slice(0, -1).some((component) => component.length === 0)) {
+    throwNativeOutputDiagnostic(rawOutput, 'windows-extended-root');
   }
+  return authoredComponents.filter(Boolean);
 }
 
-function directoryIdentityKey(directory) {
-  if (!hasFileIdentity(directory.stat)) return null;
-  return `${directory.stat.dev}:${directory.stat.ino}`;
+function rejectWindowsIpcShare(rawOutput, share) {
+  if (isWindowsIpcShare(share)) {
+    throwNativeOutputDiagnostic(rawOutput, 'windows-ipc-namespace', { share });
+  }
 }
 
-function probeNamesAlias(directoryPath, authoredName, lookupName) {
-  let fileDescriptor;
-  let created = false;
-  let result = null;
-  let cleaned = true;
-  const authoredPath = path.join(directoryPath, authoredName);
-  const lookupPath = path.join(directoryPath, lookupName);
+function validateWindowsNativeComponent(
+  rawOutput,
+  component,
+  componentIndex,
+  { allowReservedName = false } = {},
+) {
   try {
-    fileDescriptor = fs.openSync(authoredPath, 'wx', 0o600);
-    created = true;
-    fs.closeSync(fileDescriptor);
-    fileDescriptor = undefined;
-
-    let authored;
-    let lookup;
-    try {
-      authored = fs.statSync(authoredPath);
-      lookup = fs.statSync(lookupPath);
-    } catch (error) {
-      if (error.code === 'ENOENT') result = false;
-    }
-    if (authored && lookup) {
-      if (sameFileIdentity(authored, lookup)) {
-        result = true;
-      } else {
-        try {
-          result = fs.realpathSync.native(authoredPath) === fs.realpathSync.native(lookupPath);
-        } catch {
-          result = null;
-        }
-      }
-    }
-  } catch {
-    result = null;
-  } finally {
-    if (fileDescriptor !== undefined) {
-      try {
-        fs.closeSync(fileDescriptor);
-      } catch {
-        cleaned = false;
-      }
-    }
-    if (created) {
-      try {
-        fs.unlinkSync(authoredPath);
-      } catch {
-        cleaned = false;
-      }
+    // Prefix the component so a colon is classified as an ADS separator,
+    // rather than allowing the generic URI detector to claim it first.
+    validatePortablePath(`native/${component}`, { profile: 'output' });
+  } catch (error) {
+    if (!(error instanceof PortablePathError)) throw error;
+    if (allowReservedName && error.reason === 'windows-reserved-name') return;
+    // Native Windows arguments may intentionally name an existing 8.3 alias.
+    // Portable authored/archive paths reject that ambiguous spelling, while
+    // native resolution lets the filesystem prove the existing target.
+    if (error.reason === 'windows-short-name') {
+      if (component.length <= 255) return;
+      throwNativeOutputDiagnostic(rawOutput, 'component-too-long', {
+        component,
+        componentIndex,
+        utf16CodeUnits: component.length,
+        limit: 255,
+      });
     }
+    // Native Windows filesystems bound components in UTF-16 code units. The
+    // stricter UTF-8 bound belongs to portable authored/archive names only.
+    if (error.reason === 'component-too-long' && error.utf16CodeUnits <= 255) return;
+    throwNativeOutputDiagnostic(rawOutput, error.reason, {
+      component,
+      componentIndex,
+      ...(error.character !== undefined ? { character: error.character } : {}),
+      ...(error.utf8Bytes !== undefined ? { utf8Bytes: error.utf8Bytes } : {}),
+      ...(error.utf16CodeUnits !== undefined ? { utf16CodeUnits: error.utf16CodeUnits } : {}),
+      ...(error.limit !== undefined ? { limit: error.limit } : {}),
+    });
   }
-  return cleaned ? result : null;
 }
 
-function probeDirectorySemantics(directory) {
-  const cacheKey = directoryIdentityKey(directory);
-  if (cacheKey && directorySemanticsCache.has(cacheKey)) {
-    return directorySemanticsCache.get(cacheKey);
+function validateWindowsUncRootComponents(rawOutput, server, share) {
+  rejectWindowsIpcShare(rawOutput, share);
+  if (!isValidWindowsSmbShareName(share)) {
+    throwNativeOutputDiagnostic(rawOutput, 'windows-unc-share-name', {
+      share,
+      utf16CodeUnits: share.length,
+      limit: 80,
+    });
   }
+  // UNC servers and shares are root components, not DOS file names. Keep the
+  // server's ordinary native syntax checks while allowing names such as CON.
+  validateWindowsNativeComponent(rawOutput, server, 0, { allowReservedName: true });
+}
 
-  semanticsProbeSequence += 1;
-  const suffix = `${process.pid}-${Date.now().toString(36)}-${semanticsProbeSequence}`;
-  const caseAuthored = `.archify-Case-Probe-${suffix}`;
-  const normalizationAuthored = `.archify-norm-\u00e9-probe-${suffix}`;
-  const semantics = {
-    caseInsensitive: probeNamesAlias(
-      directory.path,
-      caseAuthored,
-      caseAuthored.toLowerCase(),
-    ),
-    normalizationInsensitive: probeNamesAlias(
-      directory.path,
-      normalizationAuthored,
-      normalizationAuthored.normalize('NFD'),
-    ),
-  };
-  if (
-    cacheKey
-    && semantics.caseInsensitive !== null
-    && semantics.normalizationInsensitive !== null
-  ) {
-    directorySemanticsCache.set(cacheKey, semantics);
+function windowsExtendedPathComponents(rawOutput) {
+  // The extended-length namespace deliberately bypasses Win32 normalization.
+  // Inspect its original spelling so a dot segment cannot retarget a UNC share.
+  if (rawOutput.includes('/')) {
+    throwNativeOutputDiagnostic(rawOutput, 'windows-extended-separator', { character: '/' });
+  }
+  if (/^\\\\\?\\(?:GLOBALROOT|Device)(?:\\|$)/iu.test(rawOutput)) {
+    throwNativeOutputDiagnostic(rawOutput, 'windows-device-namespace');
   }
-  return semantics;
-}
 
-function sameDirectory(left, right) {
-  return left.path === right.path || sameFileIdentity(left.stat, right.stat);
-}
+  const drive = rawOutput.match(/^\\\\\?\\[A-Za-z]:\\/u);
+  if (drive) {
+    return windowsExtendedTailComponents(rawOutput, rawOutput.slice(drive[0].length));
+  }
 
-function futurePathsAlias(leftPath, rightPath) {
-  const left = canonicalFuturePath(leftPath);
-  const right = canonicalFuturePath(rightPath);
-  if (left === right) return true;
+  const uncPrefix = rawOutput.match(/^\\\\\?\\UNC\\/iu);
+  if (uncPrefix) {
+    const authoredTail = rawOutput.slice(uncPrefix[0].length);
+    const components = authoredTail.split('\\');
+    if (components.length < 2 || components[0].length === 0 || components[1].length === 0) {
+      throwNativeOutputDiagnostic(rawOutput, 'windows-extended-root');
+    }
+    validateWindowsUncRootComponents(rawOutput, components[0], components[1]);
+    return windowsExtendedTailComponents(rawOutput, components.slice(2).join('\\'));
+  }
+
+  throwNativeOutputDiagnostic(rawOutput, 'windows-extended-root');
+}
 
-  const leftDirectory = nearestExistingDirectory(left);
-  const rightDirectory = nearestExistingDirectory(right);
-  if (!leftDirectory || !rightDirectory || !sameDirectory(leftDirectory, rightDirectory)) {
-    return false;
+function validateWindowsRawUncRoot(rawOutput) {
+  if (!/^[\\/]{2}/u.test(rawOutput) || /^[\\/]{2}[.?][\\/]/u.test(rawOutput)) return;
+  // Validate the raw server/share boundary before win32.normalize can collapse
+  // an empty share or mix the two UNC separator spellings.
+  const unc = rawOutput.match(/^([\\/])\1([^\\/]+)\1([^\\/]+)(?:[\\/]|$)/u);
+  if (!unc) {
+    throwNativeOutputDiagnostic(rawOutput, 'windows-unc-root');
   }
+  validateWindowsUncRootComponents(rawOutput, unc[2], unc[3]);
+}
 
-  const semantics = probeDirectorySemantics(leftDirectory);
-  let comparableLeft = path.relative(leftDirectory.path, left);
-  let comparableRight = path.relative(rightDirectory.path, right);
-  if (semantics.normalizationInsensitive !== false) {
-    comparableLeft = comparableLeft.normalize('NFC');
-    comparableRight = comparableRight.normalize('NFC');
+function windowsPathComponents(rawOutput, normalized) {
+  const authoredUncPrefix = /^[\\/]{2}/u.test(rawOutput);
+  if (/^\\\\\.\\/u.test(normalized)) {
+    throwNativeOutputDiagnostic(rawOutput, 'windows-device-namespace');
   }
-  if (semantics.caseInsensitive !== false) {
-    comparableLeft = comparableLeft.toLowerCase();
-    comparableRight = comparableRight.toLowerCase();
+  if (/^\\\\\?\\/u.test(normalized)) {
+    throwNativeOutputDiagnostic(rawOutput, 'windows-extended-root');
   }
-  return comparableLeft === comparableRight;
+  if (normalized.startsWith('\\\\')) {
+    const unc = normalized.match(/^\\\\([^\\]+)\\([^\\]+)(?:\\|$)/u);
+    if (!unc) throwNativeOutputDiagnostic(rawOutput, 'windows-unc-root');
+    return normalized.slice(unc[0].length).split('\\').filter(Boolean);
+  }
+  if (authoredUncPrefix) throwNativeOutputDiagnostic(rawOutput, 'windows-unc-root');
+  if (normalized.startsWith('\\')) {
+    throwNativeOutputDiagnostic(rawOutput, 'current-drive-rooted');
+  }
+  const root = path.win32.parse(normalized).root;
+  return normalized
+    .slice(root.length)
+    .split(/[\\/]+/u)
+    // normalize() retains leading navigation for a relative path. Those dot
+    // segments are path syntax, not filename components subject to name rules.
+    .filter((component) => component && component !== '.' && component !== '..');
 }
 
-export function pathsAlias(leftPath, rightPath) {
-  if (futurePathsAlias(leftPath, rightPath)) return true;
-  try {
-    const left = fs.statSync(leftPath);
-    const right = fs.statSync(rightPath);
-    return sameFileIdentity(left, right);
-  } catch {
-    return false;
+/**
+ * Validate command-line/default output paths using the active host's native
+ * syntax. Unlike authored portable paths, absolute paths and native separators
+ * remain supported. File outputs reject a trailing separator before native
+ * resolution can erase it; directory callers must opt in explicitly. The
+ * component bound also protects derived sidecars from failing after an
+ * operation has already started mutating the destination.
+ */
+export function validateNativeOutputPath(
+  rawOutput,
+  { platform = process.platform, kind = 'file' } = {},
+) {
+  if (kind !== 'file' && kind !== 'directory') {
+    throw new TypeError(`Unsupported native output path kind: ${JSON.stringify(kind)}`);
+  }
+  if (typeof rawOutput !== 'string' || rawOutput.length === 0) {
+    throwNativeOutputDiagnostic(rawOutput, 'empty');
+  }
+  if (rawOutput.includes('\0')) throwNativeOutputDiagnostic(rawOutput, 'nul-character');
+  if (/[\uD800-\uDFFF]/u.test(rawOutput)) {
+    throwNativeOutputDiagnostic(rawOutput, 'unpaired-surrogate');
+  }
+  const hasTrailingSeparator = platform === 'win32'
+    ? /[\\/]$/u.test(rawOutput)
+    : rawOutput.endsWith(path.posix.sep);
+  if (kind === 'file' && hasTrailingSeparator) {
+    throwNativeOutputDiagnostic(rawOutput, 'trailing-separator', { kind });
+  }
+
+  let normalized;
+  let components;
+  if (platform === 'win32') {
+    if (/^[A-Za-z]:(?:$|[^\\/])/u.test(rawOutput)) {
+      throwNativeOutputDiagnostic(rawOutput, 'drive-relative');
+    }
+    const extendedPrefix = rawOutput.startsWith('\\\\?\\');
+    if (extendedPrefix) {
+      components = windowsExtendedPathComponents(rawOutput);
+    } else {
+      validateWindowsRawUncRoot(rawOutput);
+      normalized = path.win32.normalize(rawOutput);
+      components = windowsPathComponents(rawOutput, normalized);
+    }
+    for (const [componentIndex, component] of components.entries()) {
+      validateWindowsNativeComponent(rawOutput, component, componentIndex);
+    }
+  } else {
+    normalized = path.resolve(rawOutput);
+    const root = path.parse(normalized).root;
+    components = normalized.slice(root.length).split(path.sep).filter(Boolean);
+    for (const [componentIndex, component] of components.entries()) {
+      const utf8Bytes = Buffer.byteLength(component, 'utf8');
+      if (utf8Bytes > 255) {
+        throwNativeOutputDiagnostic(rawOutput, 'component-too-long', {
+          component,
+          componentIndex,
+          utf8Bytes,
+          limit: 255,
+        });
+      }
+    }
   }
+  return rawOutput;
 }
 
-function pathIsInside(directoryPath, targetPath) {
-  const relative = path.relative(canonicalFuturePath(directoryPath), canonicalFuturePath(targetPath));
-  return relative === '' || (!path.isAbsolute(relative) && relative !== '..' && !relative.startsWith(`..${path.sep}`));
+/** Validate a CLI directory argument before native resolution can normalize away its raw syntax. */
+export function resolveNativeOutputDirectory(
+  rawDirectory,
+  { platform = process.platform, cwd = process.cwd() } = {},
+) {
+  validateNativeOutputPath(rawDirectory, { platform, kind: 'directory' });
+  const pathApi = platform === 'win32' ? path.win32 : path.posix;
+  return pathApi.resolve(cwd, rawDirectory);
+}
+
+export function validateAuthoredOutputPath(rawOutput, { cwd = process.cwd() } = {}) {
+  try {
+    validatePortablePath(rawOutput, { profile: 'output' });
+  } catch (error) {
+    if (!(error instanceof PortablePathError)) throw error;
+    const diagnostic = authoredOutputDiagnostic(error, rawOutput);
+    throw new OutputPathError(diagnostic.message, diagnostic);
+  }
+  if (path.posix.extname(rawOutput).toLowerCase() !== '.html') {
+    throw new OutputPathError('meta.output must target an .html file.', {
+      code: 'output/meta-extension',
+      message: 'meta.output must target an .html file.',
+      subject: { output: rawOutput, path: '/meta/output' },
+      supportedFixes: ['change meta.output to a portable path ending in .html'],
+    });
+  }
+  const outputPath = path.resolve(cwd, rawOutput);
+  if (path.extname(canonicalFuturePath(outputPath)).toLowerCase() !== '.html') {
+    throw new OutputPathError('meta.output must resolve to an .html file.', {
+      code: 'output/meta-resolved-extension',
+      message: 'meta.output must resolve to an .html file after symbolic links are followed.',
+      subject: { output: rawOutput },
+      supportedFixes: ['remove the symbolic-link alias or point it to an .html target inside the current working directory'],
+    });
+  }
+  if (!pathIsInside(cwd, outputPath)) {
+    throw new OutputPathError('meta.output must stay inside the current working directory.', {
+      code: 'output/meta-outside-cwd',
+      message: 'meta.output must stay inside the current working directory after symbolic links are resolved.',
+      subject: { output: rawOutput, cwd: path.resolve(cwd) },
+      supportedFixes: ['set meta.output to a relative .html path inside the current working directory'],
+    });
+  }
+  return rawOutput;
 }
 
 export class OutputPathError extends Error {
@@ -256,46 +379,17 @@ export function resolveOutputPath({
   otherOutputPaths = [],
   cwd = process.cwd(),
   requiredExtension = '.html',
+  platform = process.platform,
 }) {
-  const rawOutput = requestedOutput || authoredOutput || defaultOutput;
-  const source = requestedOutput ? 'cli' : (authoredOutput ? 'meta' : 'default');
-  if (
-    source === 'meta'
-    && (path.isAbsolute(rawOutput) || path.posix.isAbsolute(rawOutput) || path.win32.isAbsolute(rawOutput))
-  ) {
-    throw new OutputPathError('meta.output must be a relative path.', {
-      code: 'output/meta-absolute',
-      message: 'meta.output must be a relative path resolved from the current working directory.',
-      subject: { output: rawOutput },
-      supportedFixes: ['set meta.output to a relative .html path inside the current working directory'],
-    });
-  }
-  if (source === 'meta' && path.extname(rawOutput).toLowerCase() !== '.html') {
-    throw new OutputPathError('meta.output must target an .html file.', {
-      code: 'output/meta-extension',
-      message: 'meta.output must target an .html file.',
-      subject: { output: rawOutput },
-      supportedFixes: ['change meta.output to a path ending in .html'],
-    });
-  }
+  if (authoredOutput !== undefined) validateAuthoredOutputPath(authoredOutput, { cwd });
+  const source = requestedOutput !== undefined
+    ? 'cli'
+    : (authoredOutput !== undefined ? 'meta' : 'default');
+  const rawOutput = source === 'cli'
+    ? requestedOutput
+    : (source === 'meta' ? authoredOutput : defaultOutput);
+  if (source !== 'meta') validateNativeOutputPath(rawOutput, { platform, kind: 'file' });
   const outputPath = path.resolve(cwd, rawOutput);
-  if (source === 'meta' && path.extname(canonicalFuturePath(outputPath)).toLowerCase() !== '.html') {
-    throw new OutputPathError('meta.output must resolve to an .html file.', {
-      code: 'output/meta-resolved-extension',
-      message: 'meta.output must resolve to an .html file after symbolic links are followed.',
-      subject: { output: rawOutput },
-      supportedFixes: ['remove the symbolic-link alias or point it to an .html target inside the current working directory'],
-    });
-  }
-  if (source === 'meta' && !pathIsInside(cwd, outputPath)) {
-    throw new OutputPathError('meta.output must stay inside the current working directory.', {
-      code: 'output/meta-outside-cwd',
-      message: 'meta.output must stay inside the current working directory after symbolic links are resolved.',
-      subject: { output: rawOutput, cwd: path.resolve(cwd) },
-      supportedFixes: ['set meta.output to a relative .html path inside the current working directory'],
-    });
-  }
-
   for (const inputPath of inputPaths) {
     if (!pathsAlias(outputPath, inputPath)) continue;
     throw new OutputPathError(`Output must not replace ${inputDescription}.`, {
@@ -319,7 +413,13 @@ export function resolveOutputPath({
   // Alias checks above retain priority when a target would overwrite an input.
   if (source === 'cli') {
     const resolvedOutput = canonicalFuturePath(outputPath);
-    const authoredMatches = path.extname(rawOutput).toLowerCase() === requiredExtension;
+    const authoredExtension = path.extname(rawOutput).toLowerCase();
+    const existingWindowsHtmlAlias = platform === 'win32'
+      && requiredExtension === '.html'
+      && authoredExtension === '.htm'
+      && path.extname(resolvedOutput).toLowerCase() === requiredExtension
+      && pathsAlias(outputPath, resolvedOutput);
+    const authoredMatches = authoredExtension === requiredExtension || existingWindowsHtmlAlias;
     const resolvedMatches = path.extname(resolvedOutput).toLowerCase() === requiredExtension;
     if (!authoredMatches || !resolvedMatches) {
       const message = `CLI output must ${authoredMatches ? 'resolve to' : 'target'} a ${requiredExtension} file.`;