Skip to content

amanpal3/Dr-SKILLs / .agent/skills/archify

archify

Unverified

Create validated architecture, workflow, sequence, data-flow, lifecycle/state, ERD, class, tree, timeline, and waterfall diagrams as explorable standalone HTML with dark/light themes, motion and image/SVG/WebM export. Accept requirements or Mermaid; inspect repository evidence for code-backed diagrams. Use when visualizing systems, API calls, pipelines, schemas, histories, timings, or everyday steps, parts, relationships and states. Also turn an answer into a one-page explainer, with the conclusion first, structured panels, native diagrams and charts, when the user asks for a page, an explainer or an answer to share (做成一页, 用页面讲), or proactively when the user's rules opt in with an [archify explainer: ...] line. Not for dashboards.

FileKindSize
LICENSEother11.1 KB
LICENSE-MITother1.1 KB
NOTICEother1.3 KB
SKILL.mdskill md18.4 KB
THIRD_PARTY_NOTICES.mdmarkdown5.5 KB
assets/JetBrainsMono-OFL.txtmarkdown4.3 KB
assets/template.htmlother768.9 KB
bin/archify.mjsscript282.0 KB
bin/delivery-update.mjsscript3.6 KB
bin/finalize.mjsscript48.9 KB
bin/open-artifact.mjsscript4.0 KB
bin/preview.mjsscript35.8 KB
bin/recover-output.mjsscript1.3 KB
bin/visual-check.mjsscript117.7 KB
brand-marks/README.mdmarkdown1.4 KB
brand-marks/catalog.jsonconfig13.8 KB
delta/architecture-delta.mjsscript77.2 KB
examples/agent-run.lifecycle.jsonconfig3.2 KB
examples/agent-tool-call.workflow.jsonconfig4.8 KB
examples/archify-dev-activity.timeline.jsonconfig4.4 KB
examples/archify-repository.tree.jsonconfig4.3 KB
examples/async-job-roundtrip.sequence.jsonconfig3.7 KB
examples/brand-aware-delivery.architecture.jsonconfig2.7 KB
examples/cache-miss-request.sequence.jsonconfig3.7 KB
examples/checkout-platform.base.architecture.jsonconfig2.2 KB
examples/checkout-platform.head.architecture.jsonconfig2.4 KB
examples/checkout-request.waterfall.jsonconfig1.2 KB
examples/class-payment-processors-rendered.htmlother854.5 KB
examples/class-payments-rendered.htmlother821.1 KB
examples/dataflow-product-analytics.htmlother824.1 KB
examples/delivery.explainer.jsonconfig4.5 KB
examples/deployment-release.lifecycle.jsonconfig4.1 KB
examples/erd-orders-rendered.htmlother841.1 KB
examples/event-stream.dataflow.jsonconfig4.7 KB
examples/example-rebuild.waterfall.jsonconfig4.5 KB
examples/holiday-planning.workflow.jsonconfig2.9 KB
examples/incident-response.workflow.jsonconfig4.6 KB
examples/lifecycle-agent-run.htmlother827.8 KB
examples/locales/de.jsonconfig27.8 KB
examples/locales/fr.jsonconfig28.6 KB
examples/locales/fr.partial.jsonconfig959 B
examples/locales/it.jsonconfig28.1 KB
examples/locales/ja.jsonconfig31.7 KB
examples/locales/pt.jsonconfig27.8 KB
examples/locales/ru.jsonconfig36.1 KB
examples/orders.erd.jsonconfig7.1 KB
examples/payment-incident.timeline.jsonconfig1.4 KB
examples/payment-platform.tree.jsonconfig1.2 KB
examples/payment-processors.class.jsonconfig7.1 KB
examples/payments.class.jsonconfig2.8 KB
examples/product-analytics.dataflow.jsonconfig4.9 KB
examples/production-deployment.architecture.jsonconfig4.6 KB
examples/release-delivery.workflow.jsonconfig4.4 KB
examples/sequence-cache-miss-request.htmlother821.8 KB
examples/subscription-billing-rendered.htmlother863.5 KB
examples/subscription-billing.erd.jsonconfig11.5 KB
examples/timeline-archify-dev-activity-rendered.htmlother846.2 KB
examples/timeline-payment-incident-rendered.htmlother814.5 KB
examples/tree-archify-repository-rendered.htmlother856.8 KB
examples/tree-payment-platform-rendered.htmlother820.0 KB
examples/waterfall-checkout-request-rendered.htmlother813.9 KB
examples/waterfall-example-rebuild-rendered.htmlother843.0 KB
examples/web-app-rendered.htmlother826.4 KB
examples/web-app.architecture.jsonconfig3.1 KB
examples/workflow-agent-tool-call-rendered.htmlother831.3 KB
explainer/browser-check.mjsscript30.0 KB
explainer/charts.mjsscript5.9 KB
explainer/check.mjsscript14.5 KB
explainer/diagrams.mjsscript37.8 KB
explainer/diff.mjsscript8.3 KB
explainer/inline.mjsscript8.5 KB
explainer/layout.mjsscript2.5 KB
explainer/page-bundle.mjsscript1.1 KB
explainer/parse.mjsscript26.6 KB
explainer/patch.mjsscript11.8 KB
explainer/prepare.mjsscript9.6 KB
explainer/reader.cssother46.1 KB
explainer/reader.jsscript50.5 KB
explainer/render.mjsscript33.2 KB
explainer/revision.mjsscript1.9 KB
explainer/sources.mjsscript20.4 KB
explainer/validate.mjsscript14.2 KB
explainer/writing.mjsscript11.1 KB
locales/README.mdmarkdown2.2 KB
locales/ar.jsonconfig33.0 KB
locales/en.jsonconfig26.7 KB
locales/es.jsonconfig28.8 KB
locales/ko.jsonconfig30.1 KB
locales/manifest.jsonconfig293 B
locales/zh-CN.jsonconfig26.4 KB
locales/zh-TW.jsonconfig26.5 KB
migrations/workflow-v2.mjsscript9.0 KB
package.jsonmanifest400 B
recipes/scenarios.mjsscript40.5 KB
references/architecture-layout-repair.mdmarkdown4.3 KB
references/authoring-contract.mdmarkdown41.7 KB
references/authoring-defaults.mdmarkdown12.6 KB
references/brand-marks.mdmarkdown5.6 KB
references/delivery-contract.mdmarkdown48.7 KB
references/explainer-authoring.mdmarkdown18.5 KB
references/repository-authoring.mdmarkdown7.8 KB
references/update-awareness.mdmarkdown1.9 KB
references/viewer-runtime.mdmarkdown5.6 KB
renderers/architecture/grid.mjsscript2.0 KB
renderers/architecture/labels.mjsscript155 B
renderers/architecture/render-architecture.mjsscript57.2 KB
renderers/architecture/routing.mjsscript72.7 KB
renderers/class/README.mdmarkdown6.6 KB
renderers/class/render-class.mjsscript52.3 KB
renderers/dataflow/README.mdmarkdown9.0 KB
renderers/dataflow/dataflow-compiler.mjsscript89.1 KB
renderers/dataflow/joint-label-routing.mjsscript10.6 KB
renderers/dataflow/label-capacity.mjsscript4.3 KB
renderers/dataflow/render-dataflow.mjsscript960 B
renderers/erd/README.mdmarkdown14.2 KB
renderers/erd/grid.mjsscript6.9 KB
renderers/erd/render-erd.mjsscript78.6 KB
renderers/explainer/render-explainer.mjsscript3.2 KB
renderers/lifecycle/README.mdmarkdown6.0 KB
renderers/lifecycle/render-lifecycle.mjsscript59.9 KB
renderers/sequence/README.mdmarkdown8.5 KB
renderers/sequence/render-sequence.mjsscript55.8 KB
renderers/shared/atomic-output.mjsscript68.7 KB
renderers/shared/automatic-labels.mjsscript14.4 KB
renderers/shared/brand-marks.mjsscript28.3 KB
renderers/shared/cli.mjsscript18.6 KB
renderers/shared/desktop-readability.mjsscript6.8 KB
renderers/shared/diagnostics.mjsbinary8.1 KB
renderers/shared/engineering-profiles.mjsscript6.8 KB
renderers/shared/generated-brand-marks.mjsscript159.8 KB
renderers/shared/generated-validators.mjsscript996.1 KB
renderers/shared/geometry.mjsscript87.8 KB
renderers/shared/i18n.mjsscript13.5 KB
renderers/shared/layout-report.mjsscript1.5 KB
renderers/shared/legend.mjsscript9.0 KB
renderers/shared/node-card-style.mjsscript2.4 KB
renderers/shared/output-path.mjsscript18.6 KB
renderers/shared/owned-temp-directory.mjsscript3.1 KB
renderers/shared/path-semantics.mjsscript31.6 KB
renderers/shared/portable-path.mjsscript12.2 KB
renderers/shared/repository-evidence.mjsscript19.9 KB
renderers/shared/repository-location.mjsscript4.2 KB
renderers/shared/route-quality.mjsscript26.3 KB
renderers/shared/sidecar-path.mjsscript1.2 KB
renderers/shared/software-notices.mjsscript506 B
renderers/shared/spatial-grid.mjsscript2.4 KB
renderers/shared/svg-path-analysis.mjsscript5.3 KB
renderers/shared/text-fit.mjsscript5.1 KB
renderers/shared/utils.mjsscript12.7 KB
renderers/shared/validator.mjsscript3.3 KB
renderers/timeline/README.mdmarkdown4.0 KB
renderers/timeline/render-timeline.mjsscript29.6 KB
renderers/tree/README.mdmarkdown4.2 KB
renderers/tree/render-tree.mjsscript29.9 KB
renderers/waterfall/README.mdmarkdown3.4 KB
renderers/waterfall/render-waterfall.mjsscript22.5 KB
renderers/workflow/README.mdmarkdown17.3 KB
renderers/workflow/render-workflow.mjsscript1.6 KB
renderers/workflow/workflow-compiler.mjsscript244.3 KB
renderers/workflow/workflow-migration-geometry.mjsscript6.2 KB
renderers/workflow/workflow-placement-repair.mjsscript4.7 KB
schemas/README.mdmarkdown14.7 KB
schemas/architecture.schema.jsonconfig5.9 KB
schemas/class.schema.jsonconfig7.9 KB
schemas/common.schema.jsonconfig5.6 KB
schemas/dataflow.schema.jsonconfig6.2 KB
schemas/erd.schema.jsonconfig9.1 KB
schemas/explainer.schema.jsonconfig18.8 KB
schemas/lifecycle.schema.jsonconfig5.2 KB
schemas/sequence.schema.jsonconfig6.0 KB
schemas/timeline.schema.jsonconfig3.9 KB
schemas/tree.schema.jsonconfig3.1 KB
schemas/waterfall.schema.jsonconfig3.4 KB
schemas/workflow.schema.jsonconfig9.9 KB
scripts/check-render-output.mjsscript66.9 KB
scripts/check-update.mjsscript57.9 KB
scripts/delivery-update-child.mjsscript1.3 KB
scripts/render-examples.mjsscript2.0 KB
scripts/update-contract.mjsscript6.7 KB
skill-release.jsonconfig260 B

renderers/shared/output-path.mjs

View on GitHub
import path from 'node:path';
import {
  containedBy,
  isValidWindowsSmbShareName,
  isWindowsIpcShare,
  resolvePhysicalLocation,
  sameLocation,
} from './path-semantics.mjs';
import { PortablePathError, validatePortablePath } from './portable-path.mjs';

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,
    );
  }
  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 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: { 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 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 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 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 rejectWindowsIpcShare(rawOutput, share) {
  if (isWindowsIpcShare(share)) {
    throwNativeOutputDiagnostic(rawOutput, 'windows-ipc-namespace', { share });
  }
}

function validateWindowsNativeComponent(
  rawOutput,
  component,
  componentIndex,
  { allowReservedName = false } = {},
) {
  try {
    // 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 } : {}),
    });
  }
}

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 });
}

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');
  }

  const drive = rawOutput.match(/^\\\\\?\\[A-Za-z]:\\/u);
  if (drive) {
    return windowsExtendedTailComponents(rawOutput, rawOutput.slice(drive[0].length));
  }

  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');
}

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]);
}

function windowsPathComponents(rawOutput, normalized) {
  const authoredUncPrefix = /^[\\/]{2}/u.test(rawOutput);
  if (/^\\\\\.\\/u.test(normalized)) {
    throwNativeOutputDiagnostic(rawOutput, 'windows-device-namespace');
  }
  if (/^\\\\\?\\/u.test(normalized)) {
    throwNativeOutputDiagnostic(rawOutput, 'windows-extended-root');
  }
  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 !== '..');
}

/**
 * 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;
}

/** 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 {
  constructor(message, diagnostic) {
    super(message);
    this.name = 'OutputPathError';
    this.archifyDiagnostics = [{
      severity: 'error',
      subject: {},
      evidence: {},
      supportedFixes: [],
      ...diagnostic,
    }];
  }
}

export function resolveOutputPath({
  requestedOutput,
  authoredOutput,
  defaultOutput,
  inputPaths = [],
  inputDescription = 'an input',
  otherOutputPaths = [],
  cwd = process.cwd(),
  requiredExtension = '.html',
  platform = process.platform,
}) {
  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);
  for (const inputPath of inputPaths) {
    if (!pathsAlias(outputPath, inputPath)) continue;
    throw new OutputPathError(`Output must not replace ${inputDescription}.`, {
      code: 'output/input-alias',
      message: `Output must not replace ${inputDescription}, including through a symbolic-link or future-path alias.`,
      subject: { output: outputPath, input: path.resolve(inputPath) },
      supportedFixes: ['choose an output path that is distinct from every input path'],
    });
  }
  for (const otherOutputPath of otherOutputPaths) {
    if (!pathsAlias(outputPath, otherOutputPath)) continue;
    throw new OutputPathError('Output targets must use distinct paths.', {
      code: 'output/target-alias',
      message: 'Output targets must use distinct paths, including symbolic-link and future-path aliases.',
      subject: { output: outputPath, conflictingOutput: path.resolve(otherOutputPath) },
      supportedFixes: ['choose distinct paths for every generated output'],
    });
  }

  // Keep explicit CLI directories unrestricted, but reject mistaken file types.
  // Alias checks above retain priority when a target would overwrite an input.
  if (source === 'cli') {
    const resolvedOutput = canonicalFuturePath(outputPath);
    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.`;
      throw new OutputPathError(message, {
        code: authoredMatches ? 'output/cli-resolved-extension' : 'output/cli-extension',
        message,
        subject: { output: rawOutput },
        evidence: { resolvedOutput, requiredExtension },
        supportedFixes: [`choose a path ending in ${requiredExtension} whose symbolic-link target also ends in ${requiredExtension}`],
      });
    }
  }

  return {
    outputPath,
    source,
  };
}
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall