create-yss-spec 3.0.0 → 3.0.1

package/template/.hermes/skills/archify/renderers/shared/cli.mjs

@@ -1,218 +0,0 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import { applyTemplate, renderCards, esc } from './utils.mjs';
-import { validateSchema } from './validator.mjs';
-import { verifyRepositoryEvidence } from './repository-evidence.mjs';
-import { installRendererDiagnosticBoundary, throwDiagnosticProblems } from './diagnostics.mjs';
-import { validateEngineeringProfile } from './engineering-profiles.mjs';
-import { resolveOutputPath } from './output-path.mjs';
-import { prepareDiagramBrandMarks } from './brand-marks.mjs';
-import { resolveLocale, translateMessage } from './i18n.mjs';
-
-installRendererDiagnosticBoundary();
-
-const outputPathGuards = new Map();
-
-// Common CLI head: node render-<type>.mjs [input.json] [output.html]
-// Keep this synchronous because callers also use it to establish the guarded
-// output path before testing a last-moment filesystem alias change.
-export function loadDiagram({ rendererDir, diagramType, defaultExample, argv = process.argv }) {
-  const skillRoot = path.resolve(rendererDir, '../..');
-  const inputPath = path.resolve(argv[2] || path.join(skillRoot, 'examples', defaultExample));
-  const diagram = JSON.parse(fs.readFileSync(inputPath, 'utf8'));
-  validateSchema(diagramType, diagram);
-  validateGuidedViews(diagramType, diagram);
-  validateRelationshipIds(diagramType, diagram);
-  validateEngineeringProfile(diagramType, diagram);
-  const sourceEvidence = verifyRepositoryEvidence(diagramType, diagram, process.env.ARCHIFY_REPO_ROOT);
-  const template = fs.readFileSync(path.join(skillRoot, 'assets/template.html'), 'utf8');
-  const outputRequest = {
-    requestedOutput: argv[3],
-    authoredOutput: diagram.meta?.output,
-    defaultOutput: `${diagramType}.html`,
-    inputPaths: [inputPath],
-    cwd: process.cwd(),
-  };
-  const { outputPath: outPath } = resolveOutputPath(outputRequest);
-  outputPathGuards.set(outPath, outputRequest);
-  return { diagram, template, outPath, sourceEvidence };
-}
-
-// Brand URL capture is the only asynchronous authoring step. Typed renderers
-// opt into it through this wrapper without changing loadDiagram's long-lived
-// synchronous safety contract.
-export async function loadDiagramWithBrandMarks(options) {
-  const loaded = loadDiagram(options);
-  await prepareDiagramBrandMarks(options.diagramType, loaded.diagram);
-  return loaded;
-}
-
-const START_TYPES = new Set(['architecture', 'workflow', 'sequence', 'dataflow', 'lifecycle']);
-
-// Common CLI tail: fill the template and write the standalone HTML file.
-export function writeDiagram({ outPath, template, diagramType, meta, svg, cards, sourceEvidence = null }) {
-  if (!START_TYPES.has(diagramType)) throw new Error(`writeDiagram: unknown diagram type ${JSON.stringify(diagramType)}`);
-  const outputGuard = outputPathGuards.get(outPath);
-  if (outputGuard) resolveOutputPath(outputGuard);
-  fs.mkdirSync(path.dirname(outPath), { recursive: true });
-  fs.writeFileSync(outPath, applyTemplate(template, {
-    title: meta.title,
-    subtitle: meta.subtitle,
-    svg,
-    cards: renderCards(cards),
-    locale: meta.locale,
-    visualPreset: meta.visual_preset || 'classic',
-    guidedViews: meta.views || [],
-    sourceEvidence,
-  }));
-  outputPathGuards.delete(outPath);
-  console.log(outPath);
-}
-
-const SEMANTIC_COLLECTIONS = {
-  architecture: 'components',
-  workflow: 'nodes',
-  sequence: 'participants',
-  dataflow: 'nodes',
-  lifecycle: 'states',
-};
-
-const RELATIONSHIP_COLLECTIONS = {
-  architecture: 'connections',
-  workflow: 'edges',
-  sequence: 'messages',
-  dataflow: 'flows',
-  lifecycle: 'transitions',
-};
-
-// Relationship IDs are optional for backwards compatibility, but once an
-// author supplies one it becomes the durable identity used by viewer links.
-// Keep uniqueness enforcement in the shared zero-install path so every typed
-// renderer fails the same way even when development dependencies are absent.
-export function validateRelationshipIds(diagramType, diagram) {
-  const collection = RELATIONSHIP_COLLECTIONS[diagramType];
-  const relationships = collection && Array.isArray(diagram[collection]) ? diagram[collection] : [];
-  const seen = new Set();
-  const problems = [];
-
-  relationships.forEach((relationship, index) => {
-    if (relationship.id === undefined || relationship.id === null || relationship.id === '') return;
-    if (seen.has(relationship.id)) {
-      problems.push(`/${collection}/${index}/id duplicates relationship id ${JSON.stringify(relationship.id)}`);
-    }
-    seen.add(relationship.id);
-  });
-
-  if (problems.length) {
-    throwDiagnosticProblems('Relationship identity validation failed', problems, {
-      code: 'relationship/duplicate-id',
-      subject: { diagramType, collection },
-    });
-  }
-}
-
-// JSON Schema keeps the view object bounded; this pass checks facts that span
-// collections. Keeping it here makes the same contract apply to all five
-// renderers, including the zero-install standalone-validator path.
-export function validateGuidedViews(diagramType, diagram) {
-  const views = diagram.meta?.views;
-  if (!Array.isArray(views) || views.length === 0) return;
-  const collection = SEMANTIC_COLLECTIONS[diagramType];
-  const semanticIds = new Set((diagram[collection] || []).map((item) => item.id));
-  const seen = new Set();
-  const problems = [];
-
-  views.forEach((view, index) => {
-    if (seen.has(view.id)) problems.push(`/meta/views/${index}/id duplicates view id ${JSON.stringify(view.id)}`);
-    seen.add(view.id);
-    const seenFocus = new Set();
-    (view.focus || []).forEach((id, focusIndex) => {
-      if (seenFocus.has(id)) {
-        problems.push(`/meta/views/${index}/focus/${focusIndex} duplicates semantic id ${JSON.stringify(id)}`);
-      }
-      seenFocus.add(id);
-      if (!semanticIds.has(id)) {
-        problems.push(`/meta/views/${index}/focus/${focusIndex} references unknown semantic id ${JSON.stringify(id)}`);
-      }
-    });
-  });
-
-  if (problems.length) {
-    throwDiagnosticProblems('Guided view validation failed', problems, {
-      code: 'guided-view/invalid',
-      subject: { diagramType, collection: 'meta.views' },
-    });
-  }
-}
-
-// Accessible name for the generated diagram SVG.
-export function svgRootAttrs(meta) {
-  const animation = meta.animation === 'trace' ? ' data-animation="trace"' : '';
-  const preset = ` data-preset="${esc(meta.visual_preset || 'classic')}"`;
-  const engineeringProfile = meta.engineering_profile
-    ? ` data-engineering-profile="${esc(meta.engineering_profile)}"`
-    : '';
-  const requestedProfile = process.env.ARCHIFY_QUALITY_PROFILE || meta.quality_profile;
-  const qualityProfile = requestedProfile === 'showcase' ? 'showcase' : 'standard';
-  const advisory = requestedProfile ? '' : ' data-quality-gates="advisory"';
-  return `role="img" lang="${esc(resolveLocale(meta.locale))}" aria-labelledby="archify-diagram-title archify-diagram-description"${animation}${preset}${engineeringProfile} data-quality-profile="${esc(qualityProfile)}"${advisory}`;
-}
-
-// Keep the accessible name inside the SVG so it survives standalone SVG
-// export and embedding. The fixed IDs are deterministic because an Archify
-// artifact intentionally contains one primary diagram SVG.
-export function svgAccessibleText(meta, kind) {
-  const description = meta.subtitle || translateMessage(meta.locale, `diagram.description.${kind}`);
-  return `        <title id="archify-diagram-title">${esc(meta.title)}</title>\n        <desc id="archify-diagram-description">${esc(description)}</desc>`;
-}
-
-export function animateAttr(meta, kind, step) {
-  if (meta.animation !== 'trace') return '';
-  // Ambient trace must finish inside the fixed six-second WebM capture. The
-  // cap affects visual delay only; authored order and semantic identity stay
-  // untouched in the JSON, DOM, Story, and relationship contracts.
-  const safeStep = Number.isFinite(step) && step >= 0 ? Math.min(12, Math.floor(step)) : 0;
-  return ` data-animate="${kind}" style="--step:${safeStep}"`;
-}
-
-// Stable semantic hooks for the standalone HTML explorer. IDs already pass
-// the schema's conservative identifier pattern; escape again at the markup
-// boundary so these helpers remain safe if that contract expands later.
-export function focusNodeAttrs(id, label, metadata = {}, locale) {
-  const optional = [
-    ['data-node-kind', metadata.kind],
-    ['data-node-sublabel', metadata.sublabel],
-    ['data-node-tag', metadata.tag],
-    ['data-node-context', metadata.context],
-    ['data-node-brand', metadata.brand],
-    ['data-node-brand-id', metadata.brandId],
-    ['data-node-brand-status', metadata.brandStatus],
-    ['data-node-brand-source', metadata.brandSource],
-  ].filter(([, value]) => value !== undefined && value !== null && String(value).trim() !== '')
-    .map(([name, value]) => ` ${name}="${esc(String(value))}"`)
-    .join('');
-  const detail = [metadata.sublabel, metadata.context, metadata.brand]
-    .filter((value) => value !== undefined && value !== null && String(value).trim() !== '')
-    .join(', ');
-  const aria = detail
-    ? translateMessage(locale, 'node.focus.detail', { label, detail })
-    : translateMessage(locale, 'node.focus', { label });
-  return `id="node-${esc(id)}" data-node-id="${esc(id)}" data-node-label="${esc(label)}" tabindex="0" role="button" aria-label="${esc(aria)}" aria-pressed="false"${optional}`;
-}
-
-// Native SVG titles preserve a compact details-on-demand fallback when the
-// canonical SVG is embedded inline outside the full Archify viewer.
-export function focusNodeTitle(label, metadata = {}) {
-  const parts = [label, metadata.sublabel, metadata.context, metadata.tag, metadata.brand]
-    .filter((value) => value !== undefined && value !== null && String(value).trim() !== '');
-  return `<title>${esc(parts.join(' · '))}</title>`;
-}
-
-export function focusEdgeAttrs(from, to, label, key, id) {
-  const named = label ? ` data-edge-label="${esc(label)}"` : '';
-  const keyed = key !== undefined && key !== null ? ` data-edge-key="${esc(String(key))}"` : '';
-  const identified = id !== undefined && id !== null && String(id).trim() !== ''
-    ? ` data-edge-id="${esc(String(id))}"`
-    : '';
-  return `data-edge-from="${esc(from)}" data-edge-to="${esc(to)}"${named}${keyed}${identified}`;
-}

package/template/.hermes/skills/archify/renderers/shared/desktop-readability.mjs

@@ -1,26 +0,0 @@
-export const DESKTOP_READABILITY_VIEWPORT = Object.freeze({ width: 1440, height: 900 });
-export const DESKTOP_READER_MIN_WIDTH = 960;
-export const DESKTOP_READER_HORIZONTAL_CHROME = 30;
-export const DESKTOP_READER_DIAGRAM_WIDTH = DESKTOP_READER_MIN_WIDTH - DESKTOP_READER_HORIZONTAL_CHROME;
-export const MIN_PROJECTED_NODE_TEXT_PX = 6;
-
-export function projectedNodeTextPx(sourceFontPx, viewBoxWidth, diagramWidth = DESKTOP_READER_DIAGRAM_WIDTH) {
-  if (![sourceFontPx, viewBoxWidth, diagramWidth].every(Number.isFinite) || viewBoxWidth <= 0 || diagramWidth <= 0) {
-    return Number.NaN;
-  }
-  return sourceFontPx * Math.min(1, diagramWidth / viewBoxWidth);
-}
-
-export function minimumReadableSourceTextPx(
-  viewBoxWidth,
-  diagramWidth = DESKTOP_READER_DIAGRAM_WIDTH,
-  minimumProjectedPx = MIN_PROJECTED_NODE_TEXT_PX,
-) {
-  if (![viewBoxWidth, diagramWidth, minimumProjectedPx].every(Number.isFinite)
-    || viewBoxWidth <= 0
-    || diagramWidth <= 0
-    || minimumProjectedPx <= 0) {
-    return Number.NaN;
-  }
-  return minimumProjectedPx / Math.min(1, diagramWidth / viewBoxWidth);
-}

package/template/.hermes/skills/archify/renderers/shared/diagnostics.mjs

@@ -1,127 +0,0 @@
-import fs from 'node:fs';
-import path from 'node:path';
-
-const DIAGNOSTIC_MODE = process.env.ARCHIFY_DIAGNOSTIC_FORMAT === 'json';
-const recorded = [];
-const recordedMessages = new Set();
-const boundaryKey = Symbol.for('archify.renderer-diagnostic-boundary');
-let recordingSuppressionDepth = 0;
-
-function plainObject(value) {
-  if (!value || typeof value !== 'object' || Array.isArray(value)) return {};
-  return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
-}
-
-function normalizedDiagnostic(diagnostic) {
-  const message = String(diagnostic?.message || 'Archify could not classify this failure.').trim();
-  return {
-    code: String(diagnostic?.code || 'internal/unclassified'),
-    severity: diagnostic?.severity === 'warning' ? 'warning' : 'error',
-    message,
-    subject: plainObject(diagnostic?.subject),
-    evidence: plainObject(diagnostic?.evidence),
-    supportedFixes: Array.isArray(diagnostic?.supportedFixes)
-      ? [...new Set(diagnostic.supportedFixes.map((fix) => String(fix).trim()).filter(Boolean))]
-      : [],
-    ...(Array.isArray(diagnostic?.suppresses) ? {
-      suppresses: [...new Set(diagnostic.suppresses.map((code) => String(code).trim()).filter(Boolean))],
-    } : {}),
-  };
-}
-
-export function recordDiagnostic(diagnostic) {
-  if (!DIAGNOSTIC_MODE || recordingSuppressionDepth > 0) return;
-  const normalized = normalizedDiagnostic(diagnostic);
-  if (recordedMessages.has(normalized.message)) return;
-  recordedMessages.add(normalized.message);
-  recorded.push(normalized);
-}
-
-export function withDiagnosticRecordingSuppressed(callback) {
-  recordingSuppressionDepth += 1;
-  try {
-    return callback();
-  } finally {
-    recordingSuppressionDepth -= 1;
-  }
-}
-
-export function throwDiagnosticError(message, diagnostics) {
-  for (const diagnostic of diagnostics || []) recordDiagnostic(diagnostic);
-  const error = new Error(message);
-  error.archifyDiagnostics = (diagnostics || []).map(normalizedDiagnostic);
-  throw error;
-}
-
-export function throwDiagnosticProblems(prefix, problems, { code = 'layout/constraint', subject = {} } = {}) {
-  const messages = (problems || []).map((problem) => String(problem));
-  const diagnostics = messages.map((message) => normalizedDiagnostic({
-      code,
-      severity: 'error',
-      message,
-      subject,
-      evidence: {},
-      supportedFixes: [],
-    }));
-  throwDiagnosticError(`${prefix}:\n- ${messages.join('\n- ')}`, diagnostics);
-}
-
-function fallbackDiagnostic(error) {
-  const input = process.argv[2] ? path.resolve(process.argv[2]) : undefined;
-  if (error instanceof SyntaxError) {
-    return normalizedDiagnostic({
-      code: 'input/json-parse',
-      severity: 'error',
-      message: `Input JSON could not be parsed: ${error.message}`,
-      subject: { input },
-      evidence: { reason: error.message },
-      supportedFixes: ['repair the JSON syntax and run validation again'],
-    });
-  }
-  if (error?.code === 'ENOENT' || error?.code === 'EACCES' || error?.code === 'EISDIR') {
-    return normalizedDiagnostic({
-      code: 'input/read',
-      severity: 'error',
-      message: `Input could not be read: ${error.message}`,
-      subject: { input },
-      evidence: { systemCode: error.code, reason: error.message },
-      supportedFixes: ['provide one readable JSON input file'],
-    });
-  }
-  return normalizedDiagnostic({
-    code: 'internal/unclassified',
-    severity: 'error',
-    message: error?.message || 'Renderer failed without a diagnostic.',
-    subject: { input },
-    evidence: { errorName: error?.name || 'Error' },
-    supportedFixes: [],
-  });
-}
-function rendererFailure(error) {
-  const attached = Array.isArray(error?.archifyDiagnostics)
-    ? error.archifyDiagnostics.map(normalizedDiagnostic)
-    : [];
-  const diagnostics = recorded.length ? recorded : (attached.length ? attached : [fallbackDiagnostic(error)]);
-  return {
-    schemaVersion: 1,
-    ok: false,
-    source: 'renderer',
-    error: error?.message || 'Renderer failed without a diagnostic.',
-    diagnostics,
-  };
-}
-
-export function installRendererDiagnosticBoundary() {
-  if (!DIAGNOSTIC_MODE || globalThis[boundaryKey]) return;
-  globalThis[boundaryKey] = true;
-  process.on('uncaughtException', (error) => {
-    const payload = `${JSON.stringify(rendererFailure(error))}\n`;
-    try {
-      fs.writeSync(process.stderr.fd, payload);
-    } catch {
-      // The renderer is already failing. Avoid replacing its real error with a
-      // secondary stream failure; the parent CLI still has the exit status.
-    }
-    process.exit(1);
-  });
-}

package/template/.hermes/skills/archify/renderers/shared/engineering-profiles.mjs

@@ -1,157 +0,0 @@
-import { throwDiagnosticError } from './diagnostics.mjs';
-
-const DEPLOYMENT_PROFILE = 'deployment-ownership';
-const DEPLOYMENT_BOUNDARY_KINDS = new Set(['region', 'security-group']);
-const PRIVATE_STATE_TYPES = new Set(['database']);
-
-function subject(collection, index, item = {}) {
-  return {
-    diagramType: 'architecture',
-    profile: DEPLOYMENT_PROFILE,
-    collection,
-    index,
-    ...(item.id ? { id: item.id } : {}),
-  };
-}
-
-function membership(boundaries, componentId, kind) {
-  return boundaries
-    .map((boundary, index) => ({ boundary, index }))
-    .filter(({ boundary }) => boundary.kind === kind && boundary.wraps.includes(componentId));
-}
-
-export function deploymentOwnershipDiagnostics(diagram) {
-  const components = Array.isArray(diagram.components) ? diagram.components : [];
-  const boundaries = (Array.isArray(diagram.boundaries) ? diagram.boundaries : [])
-    .map((boundary) => ({ ...boundary, wraps: Array.isArray(boundary.wraps) ? boundary.wraps : [] }));
-  const connections = Array.isArray(diagram.connections) ? diagram.connections : [];
-  const diagnostics = [];
-
-  for (const kind of DEPLOYMENT_BOUNDARY_KINDS) {
-    const count = boundaries.filter((boundary) => boundary.kind === kind).length;
-    if (count > 0) continue;
-    diagnostics.push({
-      code: 'engineering/deployment-boundary-kind',
-      severity: 'error',
-      message: `Deployment ownership requires at least one ${kind} boundary.`,
-      subject: subject('boundaries', -1),
-      evidence: { requiredKind: kind, found: count },
-      supportedFixes: [`add one ${kind} boundary with an explicit wraps list`],
-    });
-  }
-
-  components.forEach((component, index) => {
-    if (component.type === 'external') return;
-    if (typeof component.tag !== 'string' || component.tag.trim() === '') {
-      diagnostics.push({
-        code: 'engineering/deployment-owner-missing',
-        severity: 'error',
-        message: `Deployment component ${JSON.stringify(component.id)} does not name its owner in tag.`,
-        subject: subject('components', index, component),
-        evidence: { componentType: component.type, ownerField: 'tag' },
-        supportedFixes: [`set /components/${index}/tag to the responsible team or owner`],
-      });
-    }
-
-    const regions = membership(boundaries, component.id, 'region');
-    if (regions.length === 0) {
-      diagnostics.push({
-        code: 'engineering/deployment-region-scope',
-        severity: 'error',
-        message: `Deployment component ${JSON.stringify(component.id)} is not assigned to a region boundary.`,
-        subject: subject('components', index, component),
-        evidence: { componentType: component.type, regionMemberships: 0 },
-        supportedFixes: ['add the component id to the real region boundary wraps list'],
-      });
-    } else if (regions.length > 1) {
-      diagnostics.push({
-        code: 'engineering/deployment-region-ambiguous',
-        severity: 'error',
-        message: `Deployment component ${JSON.stringify(component.id)} belongs to more than one region boundary.`,
-        subject: subject('components', index, component),
-        evidence: {
-          componentType: component.type,
-          regions: regions.map(({ boundary, index: boundaryIndex }) => ({ boundaryIndex, label: boundary.label })),
-        },
-        supportedFixes: ['keep the component id in exactly one real region boundary wraps list'],
-      });
-    }
-
-    if (PRIVATE_STATE_TYPES.has(component.type)) {
-      const privateScopes = membership(boundaries, component.id, 'security-group');
-      if (privateScopes.length === 0) {
-        diagnostics.push({
-          code: 'engineering/deployment-private-state',
-          severity: 'error',
-          message: `Stateful component ${JSON.stringify(component.id)} is not assigned to a private security-group boundary.`,
-          subject: subject('components', index, component),
-          evidence: { componentType: component.type, privateMemberships: 0 },
-          supportedFixes: ['add the component id to the real private security-group boundary wraps list'],
-        });
-      }
-    }
-  });
-
-  boundaries.forEach((boundary, index) => {
-    if (boundary.kind !== 'security-group') return;
-    const members = boundary.wraps.map((id) => ({
-      id,
-      regions: membership(boundaries, id, 'region').map(({ boundary: region, index: boundaryIndex }) => ({
-        boundaryIndex,
-        label: region.label,
-      })),
-    }));
-    const regionIndexes = new Set(members.flatMap((member) => member.regions.map((region) => region.boundaryIndex)));
-    const consistent = members.length > 0
-      && members.every((member) => member.regions.length === 1)
-      && regionIndexes.size === 1;
-    if (consistent) return;
-    diagnostics.push({
-      code: 'engineering/deployment-private-region-consistency',
-      severity: 'error',
-      message: `Private boundary ${JSON.stringify(boundary.label)} must contain components from exactly one shared region.`,
-      subject: subject('boundaries', index, boundary),
-      evidence: { boundaryKind: boundary.kind, members },
-      supportedFixes: ['assign every private-boundary component to exactly one shared region boundary'],
-    });
-  });
-
-  connections.forEach((connection, index) => {
-    const crossedBoundaries = boundaries
-      .map((boundary, boundaryIndex) => ({
-        boundaryIndex,
-        kind: boundary.kind,
-        label: boundary.label,
-        fromInside: boundary.wraps.includes(connection.from),
-        toInside: boundary.wraps.includes(connection.to),
-      }))
-      .filter((boundary) => DEPLOYMENT_BOUNDARY_KINDS.has(boundary.kind) && boundary.fromInside !== boundary.toInside);
-    if (crossedBoundaries.length === 0 || (typeof connection.label === 'string' && connection.label.trim() !== '')) return;
-    diagnostics.push({
-      code: 'engineering/deployment-crossing-mechanism',
-      severity: 'error',
-      message: `Cross-boundary connection ${JSON.stringify(connection.id || `${connection.from}->${connection.to}`)} does not name its mechanism.`,
-      subject: subject('connections', index, connection),
-      evidence: {
-        from: connection.from,
-        to: connection.to,
-        crossedBoundaries: crossedBoundaries.map(({ boundaryIndex, kind, label }) => ({ boundaryIndex, kind, label })),
-      },
-      supportedFixes: [`set /connections/${index}/label to the real cross-boundary mechanism`],
-    });
-  });
-
-  return diagnostics;
-}
-
-export function validateEngineeringProfile(diagramType, diagram) {
-  const profile = diagram.meta?.engineering_profile;
-  if (!profile) return;
-  if (diagramType !== 'architecture' || profile !== DEPLOYMENT_PROFILE) return;
-  const diagnostics = deploymentOwnershipDiagnostics(diagram);
-  if (!diagnostics.length) return;
-  throwDiagnosticError(
-    `Engineering profile ${JSON.stringify(profile)} failed:\n${diagnostics.map((entry) => `- ${entry.message}`).join('\n')}`,
-    diagnostics,
-  );
-}