create-yss-spec 2.1.5 → 2.1.6

package/template/.hermes/skills/drawio/scripts/runtime/diagrams-net-url.js

@@ -1,122 +0,0 @@
-import { readFileSync } from 'node:fs'
-import { pathToFileURL } from 'node:url'
-import { deflateRawSync } from 'node:zlib'
-
-const logger = {
-  info: (...args) => {
-    if (process.env.DRAWIO_VERBOSE === '1') {
-      console.error(...args)
-    }
-  }
-}
-
-export function encodeDrawioXmlForDiagramsNet(xml) {
-  /*
-   * ========================================================================
-   * 步骤1：校验 draw.io XML 输入
-   * ========================================================================
-   * 数据源：调用方传入的 XML 字符串
-   * 操作要点：
-   * 1) 确认输入是非空字符串
-   * 2) 确认内容看起来像 draw.io XML
-   */
-  logger.info('开始校验 draw.io XML 输入...')
-
-  // 1.1 检查输入类型和内容长度
-  if (typeof xml !== 'string' || xml.trim().length === 0) {
-    throw new Error('draw.io XML must be a non-empty string')
-  }
-
-  // 1.2 检查 draw.io 常见根节点
-  if (!xml.includes('<mxfile') && !xml.includes('<mxGraphModel')) {
-    throw new Error('Input does not look like draw.io XML')
-  }
-  logger.info('校验 draw.io XML 输入完成')
-
-  /*
-   * ========================================================================
-   * 步骤2：编码为 diagrams.net 片段
-   * ========================================================================
-   * 数据源：已校验的 draw.io XML 字符串
-   * 操作要点：
-   * 1) 使用 raw deflate 压缩 XML
-   * 2) 使用标准 base64 编码，满足 diagrams.net #R 片段要求
-   */
-  logger.info('开始编码 diagrams.net URL 片段...')
-
-  // 2.1 raw deflate 压缩，避免 zlib header
-  const compressed = deflateRawSync(Buffer.from(xml, 'utf8'), { level: 9 })
-
-  // 2.2 标准 base64 编码并移除换行
-  const encoded = compressed.toString('base64').replace(/\n/g, '')
-  logger.info('编码 diagrams.net URL 片段完成')
-
-  return encoded
-}
-
-export function buildDiagramsNetUrl(xml, options = {}) {
-  /*
-   * ========================================================================
-   * 步骤3：构建 diagrams.net 浏览器 URL
-   * ========================================================================
-   * 数据源：draw.io XML 和可选 URL 参数
-   * 操作要点：
-   * 1) 复用 XML 片段编码
-   * 2) 把图内容放入 #R fragment，避免作为请求参数发送
-   */
-  logger.info('开始构建 diagrams.net URL...')
-
-  // 3.1 读取 URL 前缀，默认使用 viewer.diagrams.net
-  const baseUrl = options.baseUrl || 'https://viewer.diagrams.net/?tags=%7B%7D&lightbox=1&edit=_blank'
-
-  // 3.2 压缩编码图内容并放入 fragment
-  const encoded = encodeDrawioXmlForDiagramsNet(xml)
-  const url = `${baseUrl}#R${encodeURIComponent(encoded)}`
-  logger.info('构建 diagrams.net URL 完成')
-
-  return url
-}
-
-function printUsageAndExit() {
-  /*
-   * ========================================================================
-   * 步骤4：输出命令行用法
-   * ========================================================================
-   * 数据源：命令行参数为空或错误
-   * 操作要点：
-   * 1) 打印最小可用命令
-   * 2) 用非零状态退出
-   */
-  logger.info('开始输出命令行用法...')
-
-  // 4.1 打印用法文本
-  console.error('Usage: node diagrams-net-url.js <input.drawio>')
-
-  // 4.2 非零退出，提示调用方参数错误
-  logger.info('输出命令行用法完成')
-  process.exit(2)
-}
-
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
-  /*
-   * ========================================================================
-   * 步骤5：处理命令行入口
-   * ========================================================================
-   * 数据源：process.argv[2] 指向的 draw.io 文件
-   * 操作要点：
-   * 1) 读取本地 .drawio 文件
-   * 2) 输出可编辑 diagrams.net URL
-   */
-  logger.info('开始处理 diagrams.net URL 命令行入口...')
-
-  // 5.1 获取输入路径
-  const inputFile = process.argv[2]
-  if (!inputFile || process.argv.includes('--help') || process.argv.includes('-h')) {
-    printUsageAndExit()
-  }
-
-  // 5.2 读取 XML 并输出 URL
-  const xml = readFileSync(inputFile, 'utf8')
-  console.log(buildDiagramsNetUrl(xml))
-  logger.info('处理 diagrams.net URL 命令行入口完成')
-}

package/template/.hermes/skills/drawio/scripts/runtime/export-stability.js

@@ -1,75 +0,0 @@
-import { stat as statFile } from 'node:fs/promises'
-import { setTimeout as delay } from 'node:timers/promises'
-
-function positiveInteger(value, name) {
-  if (!Number.isInteger(value) || value <= 0) {
-    throw new TypeError(`${name} must be a positive integer`)
-  }
-  return value
-}
-
-export async function waitForStableFile(
-  path,
-  {
-    stat = statFile,
-    now = Date.now,
-    wait = delay,
-    timeoutMs = 5000,
-    pollIntervalMs = 50,
-    stableSamples = 2,
-    maxPolls = Math.ceil(timeoutMs / pollIntervalMs) + 1
-  } = {}
-) {
-  if (typeof path !== 'string' || path.trim() === '') {
-    throw new TypeError('waitForStableFile path must be a non-empty string')
-  }
-  positiveInteger(timeoutMs, 'timeoutMs')
-  positiveInteger(pollIntervalMs, 'pollIntervalMs')
-  positiveInteger(stableSamples, 'stableSamples')
-  positiveInteger(maxPolls, 'maxPolls')
-
-  const startedAt = now()
-  let previousSize = null
-  let stableCount = 0
-  let polls = 0
-
-  while (polls < maxPolls) {
-    polls++
-    try {
-      const metadata = await stat(path)
-      const size = Number(metadata?.size)
-      if (Number.isFinite(size) && size > 0) {
-        if (size === previousSize) {
-          stableCount++
-        } else {
-          previousSize = size
-          stableCount = 1
-        }
-
-        if (stableCount >= stableSamples) {
-          return {
-            path,
-            size,
-            polls,
-            waitedMs: Math.max(0, now() - startedAt)
-          }
-        }
-      } else {
-        previousSize = null
-        stableCount = 0
-      }
-    } catch (error) {
-      if (error?.code !== 'ENOENT') {
-        throw new Error(`Could not inspect exported file "${path}": ${error.message}`, { cause: error })
-      }
-      previousSize = null
-      stableCount = 0
-    }
-
-    const elapsed = Math.max(0, now() - startedAt)
-    if (elapsed >= timeoutMs || polls >= maxPolls) break
-    await wait(Math.min(pollIntervalMs, timeoutMs - elapsed))
-  }
-
-  throw new Error(`Timed out waiting for exported file "${path}" to stabilize after ${timeoutMs}ms`)
-}

package/template/.hermes/skills/drawio/scripts/runtime/export-stability.test.js

@@ -1,81 +0,0 @@
-import test from 'node:test'
-import assert from 'node:assert/strict'
-
-import { waitForStableFile } from './export-stability.js'
-
-function deterministicClock() {
-  let value = 0
-  return {
-    now: () => value,
-    wait: async (milliseconds) => {
-      value += milliseconds
-    }
-  }
-}
-
-function missing() {
-  return Object.assign(new Error('missing'), { code: 'ENOENT' })
-}
-
-test('waitForStableFile accepts two consecutive non-zero size samples', async () => {
-  const clock = deterministicClock()
-  const sizes = [128, 128]
-  let index = 0
-
-  const result = await waitForStableFile('preview.png', {
-    stat: async () => ({ size: sizes[index++] }),
-    ...clock,
-    pollIntervalMs: 10,
-    timeoutMs: 100
-  })
-
-  assert.deepEqual(result, { path: 'preview.png', size: 128, polls: 2, waitedMs: 10 })
-})
-
-test('waitForStableFile handles delayed appearance and growing output', async () => {
-  const clock = deterministicClock()
-  const states = [missing(), missing(), { size: 16 }, { size: 32 }, { size: 32 }]
-  let index = 0
-
-  const result = await waitForStableFile('preview.png', {
-    stat: async () => {
-      const state = states[index++]
-      if (state instanceof Error) throw state
-      return state
-    },
-    ...clock,
-    pollIntervalMs: 5,
-    timeoutMs: 100
-  })
-
-  assert.deepEqual(result, { path: 'preview.png', size: 32, polls: 5, waitedMs: 20 })
-})
-
-test('waitForStableFile times out with path and duration', async () => {
-  const clock = deterministicClock()
-
-  await assert.rejects(
-    waitForStableFile('late-preview.png', {
-      stat: async () => {
-        throw missing()
-      },
-      ...clock,
-      pollIntervalMs: 10,
-      timeoutMs: 30
-    }),
-    /late-preview\.png.*30ms/i
-  )
-})
-
-test('waitForStableFile propagates non-missing filesystem failures', async () => {
-  const denied = Object.assign(new Error('access denied'), { code: 'EACCES' })
-
-  await assert.rejects(
-    waitForStableFile('preview.png', {
-      stat: async () => {
-        throw denied
-      }
-    }),
-    /access denied/i
-  )
-})

package/template/.hermes/skills/drawio/scripts/runtime/png-inspection.js

@@ -1,157 +0,0 @@
-import { randomUUID } from 'node:crypto'
-import { readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
-
-const PNG_SIGNATURE = Buffer.from('89504e470d0a1a0a', 'hex')
-const IEND_SUFFIX = Buffer.from('49454e44ae426082', 'hex')
-const IHDR_LENGTH = 13
-
-function requireBuffer(value) {
-  if (!Buffer.isBuffer(value)) {
-    throw new TypeError('PNG input must be a Buffer')
-  }
-}
-
-function assertChunkType(type) {
-  if (!/^[A-Za-z]{4}$/.test(type)) {
-    throw new Error(`PNG contains an invalid chunk type at byte boundary: ${JSON.stringify(type)}`)
-  }
-}
-
-export function inspectPng(buffer) {
-  requireBuffer(buffer)
-  if (buffer.length < PNG_SIGNATURE.length || !buffer.subarray(0, PNG_SIGNATURE.length).equals(PNG_SIGNATURE)) {
-    throw new Error('PNG signature is missing or invalid')
-  }
-
-  const chunks = []
-  let offset = PNG_SIGNATURE.length
-  let width = null
-  let height = null
-  let hasIdat = false
-  let hasIend = false
-  let knownTruncation = false
-
-  while (offset < buffer.length) {
-    const remaining = buffer.length - offset
-    if (remaining === 4 && buffer.readUInt32BE(offset) === 0) {
-      knownTruncation = chunks.length > 0 && hasIdat && !hasIend
-      if (!knownTruncation) {
-        throw new Error('PNG ends with an unknown four-byte truncated chunk')
-      }
-      break
-    }
-    if (remaining < 8) {
-      throw new Error(`PNG has a truncated chunk header at byte ${offset}`)
-    }
-
-    const length = buffer.readUInt32BE(offset)
-    const type = buffer.toString('ascii', offset + 4, offset + 8)
-    assertChunkType(type)
-    const end = offset + 12 + length
-    if (!Number.isSafeInteger(end) || end > buffer.length) {
-      throw new Error(`PNG has a truncated ${type} chunk at byte ${offset}`)
-    }
-
-    if (chunks.length === 0 && type !== 'IHDR') {
-      throw new Error('PNG first chunk must be IHDR')
-    }
-    if (type === 'IHDR') {
-      if (chunks.length !== 0 || length !== IHDR_LENGTH) {
-        throw new Error('PNG IHDR chunk must be first and contain exactly 13 bytes')
-      }
-      width = buffer.readUInt32BE(offset + 8)
-      height = buffer.readUInt32BE(offset + 12)
-      if (width === 0 || height === 0) {
-        throw new Error('PNG IHDR width and height must be greater than zero')
-      }
-    }
-    if (type === 'IDAT') hasIdat = true
-
-    chunks.push({ type, length, offset })
-    offset = end
-
-    if (type === 'IEND') {
-      if (length !== 0) throw new Error('PNG IEND chunk must have zero data length')
-      if (!hasIdat) throw new Error('PNG IEND appears before any IDAT chunk')
-      hasIend = true
-      if (offset !== buffer.length) {
-        throw new Error(`PNG contains trailing data after IEND at byte ${offset}`)
-      }
-      break
-    }
-  }
-
-  if (width === null || height === null) {
-    throw new Error('PNG is missing a valid IHDR chunk')
-  }
-  if (!hasIdat) {
-    throw new Error('PNG is missing an IDAT chunk')
-  }
-  if (!hasIend && !knownTruncation) {
-    throw new Error('PNG is missing terminal IEND data and does not match the known truncation')
-  }
-
-  return {
-    width,
-    height,
-    chunks,
-    hasIend,
-    knownTruncation,
-    byteLength: buffer.length
-  }
-}
-
-export function repairKnownIendTruncation(buffer) {
-  requireBuffer(buffer)
-  try {
-    const metadata = inspectPng(buffer)
-    if (!metadata.knownTruncation) {
-      return { status: 'unchanged', buffer, metadata }
-    }
-
-    const repaired = Buffer.concat([buffer, IEND_SUFFIX])
-    return {
-      status: 'repaired',
-      buffer: repaired,
-      metadata: inspectPng(repaired)
-    }
-  } catch (error) {
-    return { status: 'rejected', buffer, error }
-  }
-}
-
-export function repairKnownIendTruncationFile(
-  filePath,
-  {
-    readFile = readFileSync,
-    writeFile = writeFileSync,
-    rename = renameSync,
-    remove = rmSync,
-    temporaryPath = (path) => `${path}.${process.pid}.${randomUUID()}.repair.tmp`
-  } = {}
-) {
-  if (typeof filePath !== 'string' || filePath.trim() === '') {
-    throw new TypeError('PNG file path must be a non-empty string')
-  }
-
-  const result = repairKnownIendTruncation(readFile(filePath))
-  if (result.status === 'rejected') {
-    throw new Error(`PNG repair rejected "${filePath}": ${result.error.message}`, { cause: result.error })
-  }
-  if (result.status === 'unchanged') return result
-
-  const tempFile = temporaryPath(filePath)
-  try {
-    writeFile(tempFile, result.buffer)
-    rename(tempFile, filePath)
-  } catch (error) {
-    try {
-      remove(tempFile, { force: true })
-    } catch {
-      // Preserve the original write/rename error.
-    }
-    throw new Error(`Could not atomically repair PNG "${filePath}": ${error.message}`, { cause: error })
-  }
-
-  return result
-}

package/template/.hermes/skills/drawio/scripts/runtime/png-inspection.test.js

@@ -1,120 +0,0 @@
-import test from 'node:test'
-import assert from 'node:assert/strict'
-
-import {
-  inspectPng,
-  repairKnownIendTruncation,
-  repairKnownIendTruncationFile
-} from './png-inspection.js'
-
-const PNG_SIGNATURE = Buffer.from('89504e470d0a1a0a', 'hex')
-
-function chunk(type, data = Buffer.alloc(0)) {
-  const length = Buffer.alloc(4)
-  length.writeUInt32BE(data.length)
-  const crc = type === 'IEND' ? Buffer.from('ae426082', 'hex') : Buffer.alloc(4)
-  return Buffer.concat([length, Buffer.from(type, 'ascii'), data, crc])
-}
-
-function png({ width = 640, height = 480 } = {}) {
-  const ihdr = Buffer.alloc(13)
-  ihdr.writeUInt32BE(width, 0)
-  ihdr.writeUInt32BE(height, 4)
-  ihdr[8] = 8
-  ihdr[9] = 6
-  return Buffer.concat([PNG_SIGNATURE, chunk('IHDR', ihdr), chunk('IDAT', Buffer.from([1, 2, 3])), chunk('IEND')])
-}
-
-test('inspectPng returns dimensions and terminal IEND for a complete PNG', () => {
-  const metadata = inspectPng(png({ width: 2000, height: 1200 }))
-
-  assert.equal(metadata.width, 2000)
-  assert.equal(metadata.height, 1200)
-  assert.equal(metadata.hasIend, true)
-  assert.equal(metadata.knownTruncation, false)
-  assert.deepEqual(metadata.chunks.map((entry) => entry.type), ['IHDR', 'IDAT', 'IEND'])
-})
-
-test('repairKnownIendTruncation leaves complete PNG bytes unchanged', () => {
-  const complete = png()
-  const result = repairKnownIendTruncation(complete)
-
-  assert.equal(result.status, 'unchanged')
-  assert.strictEqual(result.buffer, complete)
-  assert.deepEqual(result.metadata, inspectPng(complete))
-})
-
-test('repairKnownIendTruncation repairs only the missing IEND type and CRC', () => {
-  const complete = png({ width: 1200, height: 2000 })
-  const truncated = complete.subarray(0, complete.length - 8)
-  const before = inspectPng(truncated)
-
-  assert.equal(before.hasIend, false)
-  assert.equal(before.knownTruncation, true)
-
-  const repaired = repairKnownIendTruncation(truncated)
-  assert.equal(repaired.status, 'repaired')
-  assert.equal(repaired.metadata.hasIend, true)
-  assert.deepEqual(repaired.buffer, complete)
-
-  const second = repairKnownIendTruncation(repaired.buffer)
-  assert.equal(second.status, 'unchanged')
-  assert.strictEqual(second.buffer, repaired.buffer)
-})
-
-test('inspectPng rejects non-PNG input and malformed IHDR', () => {
-  assert.throws(() => inspectPng(Buffer.from('not a png')), /signature/i)
-
-  const malformed = Buffer.concat([PNG_SIGNATURE, chunk('IHDR', Buffer.alloc(12)), chunk('IDAT'), chunk('IEND')])
-  assert.throws(() => inspectPng(malformed), /IHDR.*13/i)
-})
-
-test('inspectPng rejects a truncated non-IEND chunk', () => {
-  const ihdr = Buffer.alloc(13)
-  ihdr.writeUInt32BE(100, 0)
-  ihdr.writeUInt32BE(100, 4)
-  const claimedLength = Buffer.alloc(4)
-  claimedLength.writeUInt32BE(10)
-  const truncated = Buffer.concat([
-    PNG_SIGNATURE,
-    chunk('IHDR', ihdr),
-    claimedLength,
-    Buffer.from('IDAT', 'ascii'),
-    Buffer.from([1, 2])
-  ])
-
-  assert.throws(() => inspectPng(truncated), /truncated.*IDAT/i)
-  const repair = repairKnownIendTruncation(truncated)
-  assert.equal(repair.status, 'rejected')
-  assert.match(repair.error.message, /truncated.*IDAT/i)
-})
-
-test('inspectPng rejects trailing garbage after IEND', () => {
-  const withGarbage = Buffer.concat([png(), Buffer.from('garbage')])
-  assert.throws(() => inspectPng(withGarbage), /trailing/i)
-})
-
-test('repairKnownIendTruncationFile writes a sibling temp file before atomic rename', () => {
-  const complete = png()
-  const truncated = complete.subarray(0, complete.length - 8)
-  const events = []
-
-  const result = repairKnownIendTruncationFile('preview.png', {
-    readFile: () => truncated,
-    writeFile: (path, buffer) => events.push({ action: 'write', path, buffer }),
-    rename: (from, to) => events.push({ action: 'rename', from, to }),
-    remove: (path) => events.push({ action: 'remove', path }),
-    temporaryPath: () => 'preview.png.repair.tmp'
-  })
-
-  assert.equal(result.status, 'repaired')
-  assert.equal(events.length, 2)
-  assert.equal(events[0].action, 'write')
-  assert.equal(events[0].path, 'preview.png.repair.tmp')
-  assert.deepEqual(events[0].buffer, complete)
-  assert.deepEqual(events[1], {
-    action: 'rename',
-    from: 'preview.png.repair.tmp',
-    to: 'preview.png'
-  })
-})

package/template/.hermes/skills/drawio/scripts/runtime/vision-preview.js

@@ -1,77 +0,0 @@
-import { rmSync } from 'node:fs'
-import { extname } from 'node:path'
-import { exportWithDrawioDesktop } from './desktop.js'
-import { repairKnownIendTruncationFile } from './png-inspection.js'
-
-function positiveInteger(value, name) {
-  if (!Number.isInteger(value) || value <= 0) {
-    throw new TypeError(`${name} must be a positive integer`)
-  }
-}
-
-function validateInspection(result, maxDimension) {
-  const metadata = result?.metadata
-  if (!metadata || !Number.isInteger(metadata.width) || !Number.isInteger(metadata.height)) {
-    throw new Error('Vision preview inspection did not return integer PNG dimensions')
-  }
-  if (!metadata.hasIend) {
-    throw new Error('Vision preview PNG is missing terminal IEND after inspection and repair')
-  }
-  if (Math.max(metadata.width, metadata.height) > maxDimension) {
-    throw new Error(
-      `Vision preview longest edge is ${Math.max(metadata.width, metadata.height)}px; expected at most ${maxDimension}px`
-    )
-  }
-  return metadata
-}
-
-export async function exportVisionPreview({
-  inputFile,
-  outputFile,
-  maxDimension = 2000,
-  exportDesktop = exportWithDrawioDesktop,
-  inspectFile = repairKnownIendTruncationFile,
-  removeFile = rmSync,
-  desktopOptions = {}
-}) {
-  if (typeof inputFile !== 'string' || inputFile.trim() === '') {
-    throw new TypeError('Vision preview inputFile must be a non-empty string')
-  }
-  if (typeof outputFile !== 'string' || extname(outputFile).toLowerCase() !== '.png') {
-    throw new Error('Vision preview outputFile must end with .png')
-  }
-  positiveInteger(maxDimension, 'maxDimension')
-
-  const shared = {
-    ...desktopOptions,
-    inputFile,
-    outputFile,
-    format: 'png',
-    profile: 'vision-preview'
-  }
-  const exports = []
-
-  removeFile(outputFile, { force: true })
-  exports.push(await exportDesktop({ ...shared, width: maxDimension }))
-  let inspection = inspectFile(outputFile)
-  let reexported = false
-
-  if (inspection?.metadata?.height > maxDimension) {
-    removeFile(outputFile, { force: true })
-    exports.push(await exportDesktop({ ...shared, height: maxDimension }))
-    inspection = inspectFile(outputFile)
-    reexported = true
-  }
-
-  const metadata = validateInspection(inspection, maxDimension)
-  return {
-    profile: 'vision-preview',
-    outputFile,
-    width: metadata.width,
-    height: metadata.height,
-    maxDimension,
-    reexported,
-    repairStatus: inspection.status,
-    exports
-  }
-}