@xgent-ai/skills 0.1.0 → 0.4.0

package/skills/archify/scripts/generate-brand-marks.mjs

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import * as simpleIcons from 'simple-icons';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const root = path.resolve(here, '..');
+const catalogPath = path.join(root, 'brand-marks', 'catalog.json');
+const outputPath = path.join(root, 'renderers', 'shared', 'generated-brand-marks.mjs');
+const catalog = JSON.parse(fs.readFileSync(catalogPath, 'utf8'));
+const simpleIconsVersion = JSON.parse(fs.readFileSync(
+  path.join(root, 'node_modules', 'simple-icons', 'package.json'),
+  'utf8',
+)).version;
+const simpleBySlug = new Map(Object.values(simpleIcons)
+  .filter((icon) => icon && typeof icon === 'object' && icon.slug && icon.path)
+  .map((icon) => [icon.slug, icon]));
+
+function normalizedList(value) {
+  return [...new Set((Array.isArray(value) ? value : [])
+    .map((item) => String(item).trim())
+    .filter(Boolean))];
+}
+
+function lookupForms(value) {
+  const raw = String(value ?? '').trim().toLocaleLowerCase('en-US');
+  if (!raw) return [];
+  return [...new Set([
+    raw,
+    raw.replace(/[\s_]+/g, '-'),
+    raw.replace(/[\s_.-]+/g, ''),
+  ])];
+}
+
+function fail(message) {
+  console.error(`brand catalog: ${message}`);
+  process.exit(1);
+}
+
+if (catalog.schemaVersion !== 1 || !Array.isArray(catalog.marks) || catalog.marks.length === 0) {
+  fail('catalog.json must contain a non-empty schemaVersion 1 marks array');
+}
+
+const ids = new Set();
+const lookupKeys = new Map();
+const domains = new Map();
+const generated = catalog.marks.map((entry, index) => {
+  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(entry.id || '')) fail(`marks[${index}] has an invalid id`);
+  if (ids.has(entry.id)) fail(`duplicate id ${entry.id}`);
+  ids.add(entry.id);
+
+  const aliases = normalizedList(entry.aliases);
+  const entryDomains = normalizedList(entry.domains).map((domain) => domain.toLowerCase());
+  for (const key of [entry.id, ...aliases]) {
+    for (const form of lookupForms(key)) {
+      if (lookupKeys.has(form) && lookupKeys.get(form) !== entry.id) {
+        fail(`lookup key ${JSON.stringify(key)} is shared by ${lookupKeys.get(form)} and ${entry.id}`);
+      }
+      lookupKeys.set(form, entry.id);
+    }
+  }
+  for (const domain of entryDomains) {
+    if (domains.has(domain) && domains.get(domain) !== entry.id) {
+      fail(`domain ${domain} is shared by ${domains.get(domain)} and ${entry.id}`);
+    }
+    domains.set(domain, entry.id);
+  }
+
+  let mark;
+  if (entry.simpleIcon) {
+    const icon = simpleBySlug.get(entry.simpleIcon);
+    if (!icon) fail(`${entry.id} references missing Simple Icons slug ${entry.simpleIcon}`);
+    mark = {
+      id: entry.id,
+      title: entry.title || icon.title,
+      category: entry.category,
+      aliases,
+      domains: entryDomains,
+      viewBox: 24,
+      hex: icon.hex,
+      path: icon.path,
+      provenance: {
+        provider: 'Simple Icons',
+        providerVersion: simpleIconsVersion,
+        source: icon.source,
+        ...(icon.guidelines ? { guidelines: icon.guidelines } : {}),
+        ...(icon.license ? { license: icon.license } : {}),
+      },
+    };
+  } else if (entry.custom) {
+    const custom = entry.custom;
+    if (!entry.title || !custom.path || !custom.source || !/^[0-9A-F]{6}$/i.test(custom.hex || '')) {
+      fail(`${entry.id} custom mark requires title, path, source, and six-digit hex`);
+    }
+    mark = {
+      id: entry.id,
+      title: entry.title,
+      category: entry.category,
+      aliases,
+      domains: entryDomains,
+      viewBox: custom.viewBox || 24,
+      hex: custom.hex.toUpperCase(),
+      path: custom.path,
+      provenance: {
+        provider: 'Official brand asset',
+        source: custom.source,
+        ...(custom.guidelines ? { guidelines: custom.guidelines } : {}),
+      },
+    };
+  } else {
+    fail(`${entry.id} must provide simpleIcon or custom`);
+  }
+  if (!mark.category || !mark.title) fail(`${entry.id} is missing category or title`);
+  for (const form of lookupForms(mark.title)) {
+    if (lookupKeys.has(form) && lookupKeys.get(form) !== entry.id) {
+      fail(`title ${JSON.stringify(mark.title)} is shared by ${lookupKeys.get(form)} and ${entry.id}`);
+    }
+    lookupKeys.set(form, entry.id);
+  }
+  return mark;
+}).sort((left, right) => left.id.localeCompare(right.id));
+
+const banner = `// Generated by scripts/generate-brand-marks.mjs from brand-marks/catalog.json.\n// Simple Icons ${simpleIconsVersion}. Do not edit by hand.\n`;
+const source = `${banner}export const BRAND_MARKS = Object.freeze(${JSON.stringify(generated, null, 2)});\n`;
+
+if (process.argv.includes('--check')) {
+  const current = fs.existsSync(outputPath)
+    ? fs.readFileSync(outputPath, 'utf8').replace(/\r\n?/g, '\n')
+    : '';
+  if (current !== source) {
+    console.error('generated brand marks are stale — run npm run generate:brand-marks');
+    process.exit(1);
+  }
+} else {
+  const temporary = `${outputPath}.${process.pid}.tmp`;
+  fs.writeFileSync(temporary, source);
+  fs.renameSync(temporary, outputPath);
+  console.log(`generated ${path.relative(root, outputPath)} (${generated.length} marks)`);
+}

package/skills/archify/scripts/generate-validators.mjs

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import Ajv2020 from 'ajv/dist/2020.js';
+import standaloneCode from 'ajv/dist/standalone/index.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const root = path.resolve(__dirname, '..');
+const schemasDir = path.join(root, 'schemas');
+const output = path.join(root, 'renderers/shared/generated-validators.mjs');
+const diagramTypes = ['workflow', 'sequence', 'dataflow', 'lifecycle', 'architecture'];
+
+const ajv = new Ajv2020({
+  allErrors: true,
+  strict: true,
+  code: { source: true, esm: true },
+});
+ajv.addSchema(JSON.parse(fs.readFileSync(path.join(schemasDir, 'common.schema.json'), 'utf8')));
+
+const schemaIds = {};
+for (const type of diagramTypes) {
+  const schema = JSON.parse(fs.readFileSync(path.join(schemasDir, `${type}.schema.json`), 'utf8'));
+  ajv.addSchema(schema);
+  schemaIds[type] = schema.$id;
+}
+
+const banner = '// Generated by scripts/generate-validators.mjs. Do not edit by hand.\n';
+const ajvUcs2Import = 'require("ajv/dist/runtime/ucs2length").default';
+const inlineUcs2Length = `function ucs2length(str) {
+  const len = str.length;
+  let length = 0;
+  let pos = 0;
+  while (pos < len) {
+    length += 1;
+    const value = str.charCodeAt(pos++);
+    if (value >= 0xd800 && value <= 0xdbff && pos < len
+      && (str.charCodeAt(pos) & 0xfc00) === 0xdc00) pos += 1;
+  }
+  return length;
+}`;
+let validatorCode = standaloneCode(ajv, schemaIds);
+if (!validatorCode.includes(ajvUcs2Import)) {
+  throw new Error('AJV standalone output no longer contains the expected ucs2length helper');
+}
+validatorCode = validatorCode.replaceAll(ajvUcs2Import, inlineUcs2Length);
+if (validatorCode.includes('require(')) {
+  throw new Error('AJV standalone output contains an unexpected runtime dependency');
+}
+const generated = `${banner}${validatorCode}\n`;
+
+if (process.argv.includes('--check')) {
+  const current = fs.existsSync(output)
+    ? fs.readFileSync(output, 'utf8').replace(/\r\n?/g, '\n')
+    : '';
+  if (current !== generated) {
+    console.error('generated validators are stale — run npm run generate:validators');
+    process.exit(1);
+  }
+} else {
+  const temporary = `${output}.${process.pid}.tmp`;
+  fs.writeFileSync(temporary, generated);
+  fs.renameSync(temporary, output);
+  console.log(`generated ${path.relative(root, output)}`);
+}

package/skills/archify/scripts/render-examples.mjs

@@ -0,0 +1,26 @@
+// Re-render every bundled example from its JSON IR. Installed skills keep HTML
+// beside the JSON examples; the development script passes the golden directory.
+
+import { execFileSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const skillRoot = path.resolve(__dirname, '..');
+const outputRoot = path.resolve(process.argv[2] || path.join(skillRoot, 'examples'));
+
+const TARGETS = [
+  ['workflow', 'agent-tool-call.workflow.json', 'workflow-agent-tool-call-rendered.html'],
+  ['sequence', 'cache-miss-request.sequence.json', 'sequence-cache-miss-request.html'],
+  ['dataflow', 'product-analytics.dataflow.json', 'dataflow-product-analytics.html'],
+  ['lifecycle', 'agent-run.lifecycle.json', 'lifecycle-agent-run.html'],
+  ['architecture', 'web-app.architecture.json', 'web-app-rendered.html'],
+];
+
+for (const [mode, input, output] of TARGETS) {
+  execFileSync(process.execPath, [
+    path.join(skillRoot, `renderers/${mode}/render-${mode}.mjs`),
+    path.join(skillRoot, 'examples', input),
+    path.join(outputRoot, output),
+  ], { stdio: 'inherit' });
+}

package/skills/archify/scripts/update-contract.mjs

@@ -0,0 +1,182 @@
+export const SKILL_ID = 'archify';
+export const EXPECTED_REPOSITORY = 'https://github.com/tt-a1i/archify';
+export const DEFAULT_MANIFEST_URL = 'https://tt-a1i.github.io/archify/skill-updates/archify/stable.json';
+
+const CONTROL_OR_BIDI = /[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/u;
+const HEX_40 = /^[a-f0-9]{40}$/;
+const HEX_64 = /^[a-f0-9]{64}$/;
+const SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/;
+const UTC_SECONDS = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/;
+
+export class UpdateContractError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'UpdateContractError';
+  }
+}
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function hasExactKeys(value, expected) {
+  return isPlainObject(value)
+    && Object.keys(value).sort().join('\0') === [...expected].sort().join('\0');
+}
+
+export function parseSemver(value) {
+  if (typeof value !== 'string' || value.length > 128) {
+    throw new UpdateContractError(`invalid SemVer: ${JSON.stringify(value)}`);
+  }
+  const match = SEMVER.exec(value);
+  if (!match) throw new UpdateContractError(`invalid SemVer: ${JSON.stringify(value)}`);
+  const prerelease = match[4]?.split('.') ?? null;
+  if (prerelease?.some((identifier) => /^\d+$/.test(identifier)
+    && identifier.length > 1 && identifier.startsWith('0'))) {
+    throw new UpdateContractError(`invalid SemVer: ${JSON.stringify(value)}`);
+  }
+  return {
+    core: match.slice(1, 4),
+    prerelease,
+    build: match[5]?.split('.') ?? null,
+  };
+}
+
+function compareNumericIdentifiers(left, right) {
+  if (left.length !== right.length) return left.length < right.length ? -1 : 1;
+  if (left === right) return 0;
+  return left < right ? -1 : 1;
+}
+
+function comparePrerelease(left, right) {
+  if (left === null && right === null) return 0;
+  if (left === null) return 1;
+  if (right === null) return -1;
+  const length = Math.max(left.length, right.length);
+  for (let index = 0; index < length; index += 1) {
+    if (left[index] === undefined) return -1;
+    if (right[index] === undefined) return 1;
+    if (left[index] === right[index]) continue;
+    const leftNumeric = /^\d+$/.test(left[index]);
+    const rightNumeric = /^\d+$/.test(right[index]);
+    if (leftNumeric && rightNumeric) return compareNumericIdentifiers(left[index], right[index]);
+    if (leftNumeric !== rightNumeric) return leftNumeric ? -1 : 1;
+    return left[index] < right[index] ? -1 : 1;
+  }
+  return 0;
+}
+
+export function compareSemver(leftValue, rightValue) {
+  const left = parseSemver(leftValue);
+  const right = parseSemver(rightValue);
+  for (let index = 0; index < left.core.length; index += 1) {
+    const comparison = compareNumericIdentifiers(left.core[index], right.core[index]);
+    if (comparison !== 0) return comparison;
+  }
+  return comparePrerelease(left.prerelease, right.prerelease);
+}
+
+export function releaseChannelForVersion(value) {
+  return parseSemver(value).prerelease ? 'development' : 'stable';
+}
+
+export function isStableCoreVersion(value) {
+  try {
+    const parsed = parseSemver(value);
+    return parsed.prerelease === null && parsed.build === null;
+  } catch {
+    return false;
+  }
+}
+
+export function validateCanonicalUtcTimestamp(value) {
+  if (typeof value !== 'string' || !UTC_SECONDS.test(value)) {
+    throw new UpdateContractError('publication time must use YYYY-MM-DDTHH:mm:ssZ');
+  }
+  const timestamp = Date.parse(value);
+  if (!Number.isFinite(timestamp)
+    || new Date(timestamp).toISOString().replace('.000Z', 'Z') !== value) {
+    throw new UpdateContractError('publication time is not a real UTC calendar instant');
+  }
+  return value;
+}
+
+export function validateLocalRelease(value) {
+  if (!hasExactKeys(value, [
+    'schemaVersion', 'skillId', 'channel', 'version', 'source', 'updateManifestUrl',
+  ])
+    || value.schemaVersion !== 1
+    || value.skillId !== SKILL_ID
+    || !hasExactKeys(value.source, ['repository'])
+    || value.source.repository !== EXPECTED_REPOSITORY
+    || value.updateManifestUrl !== DEFAULT_MANIFEST_URL) {
+    throw new UpdateContractError('invalid local release identity');
+  }
+  const expectedChannel = releaseChannelForVersion(value.version);
+  if (value.channel !== expectedChannel) {
+    throw new UpdateContractError('local release channel does not match its version');
+  }
+  return {
+    schemaVersion: value.schemaVersion,
+    skillId: value.skillId,
+    channel: value.channel,
+    version: value.version,
+    source: { repository: value.source.repository },
+    updateManifestUrl: value.updateManifestUrl,
+  };
+}
+
+export function validateReleaseNotesUrl(value, version) {
+  if (!isStableCoreVersion(version)) {
+    throw new UpdateContractError('release notes require a stable core version');
+  }
+  const expected = `https://github.com/tt-a1i/archify/releases/tag/v${version}`;
+  if (value !== expected) {
+    throw new UpdateContractError('release notes URL is outside the exact trusted release path');
+  }
+  return value;
+}
+
+export function validateStableUpdateManifest(value) {
+  if (!hasExactKeys(value, [
+    'schemaVersion', 'skillId', 'channel', 'version', 'publishedAt', 'source',
+    'artifact', 'summary', 'releaseNotes', 'severity',
+  ])
+    || value.schemaVersion !== 1
+    || value.skillId !== SKILL_ID
+    || value.channel !== 'stable'
+    || !isStableCoreVersion(value.version)
+    || !hasExactKeys(value.source, ['repository', 'ref', 'treeSha'])
+    || value.source.repository !== EXPECTED_REPOSITORY
+    || value.source.ref !== `v${value.version}`
+    || !HEX_40.test(value.source.treeSha)
+    || !hasExactKeys(value.artifact, ['sha256'])
+    || !HEX_64.test(value.artifact.sha256)) {
+    throw new UpdateContractError('invalid immutable stable release identity');
+  }
+  validateCanonicalUtcTimestamp(value.publishedAt);
+  if (typeof value.summary !== 'string' || value.summary.length < 1 || value.summary.length > 160
+    || CONTROL_OR_BIDI.test(value.summary)) {
+    throw new UpdateContractError('invalid release summary');
+  }
+  validateReleaseNotesUrl(value.releaseNotes, value.version);
+  if (!['normal', 'security'].includes(value.severity)) {
+    throw new UpdateContractError('invalid update severity');
+  }
+  return {
+    schemaVersion: value.schemaVersion,
+    skillId: value.skillId,
+    channel: value.channel,
+    version: value.version,
+    publishedAt: value.publishedAt,
+    source: {
+      repository: value.source.repository,
+      ref: value.source.ref,
+      treeSha: value.source.treeSha,
+    },
+    artifact: { sha256: value.artifact.sha256 },
+    summary: value.summary,
+    releaseNotes: value.releaseNotes,
+    severity: value.severity,
+  };
+}

package/skills/archify/skill-release.json

@@ -0,0 +1,10 @@
+{
+  "schemaVersion": 1,
+  "skillId": "archify",
+  "channel": "development",
+  "version": "2.17.0-dev.1",
+  "source": {
+    "repository": "https://github.com/tt-a1i/archify"
+  },
+  "updateManifestUrl": "https://tt-a1i.github.io/archify/skill-updates/archify/stable.json"
+}

package/skills/archify/test/adaptive-reader-layout.test.mjs

@@ -0,0 +1,86 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  DESKTOP_READABILITY_VIEWPORT,
+  DESKTOP_READER_DIAGRAM_WIDTH,
+  DESKTOP_READER_HORIZONTAL_CHROME,
+  DESKTOP_READER_MIN_WIDTH,
+  MIN_PROJECTED_NODE_TEXT_PX,
+  minimumReadableSourceTextPx,
+  projectedNodeTextPx,
+} from '../renderers/shared/desktop-readability.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const skillRoot = path.resolve(__dirname, '..');
+const template = fs.readFileSync(path.join(skillRoot, 'assets', 'template.html'), 'utf8');
+const skill = fs.readFileSync(path.join(skillRoot, 'SKILL.md'), 'utf8');
+const reader = template.slice(
+  template.indexOf('Adaptive Reader Shell'),
+  template.indexOf('Archify.view = (function ()'),
+);
+
+test('wide desktop diagrams use one height-budgeted reader shell instead of breakpoint jumps', () => {
+  assert.match(template, /max-width: var\(--archify-reader-width, 1440px\)/);
+  assert.doesNotMatch(template, /@media \(min-width: 1680px\)[\s\S]{0,180}\.container/);
+  assert.doesNotMatch(template, /@media \(min-width: 1920px\)[\s\S]{0,180}\.container/);
+  assert.match(reader, /var WIDE_RATIO = 1\.55/);
+  assert.match(reader, /var MAX_READER_WIDTH = 1920/);
+  assert.match(reader, /var availableSvgHeight = Math\.max\(1, window\.innerHeight - fixedHeight\)/);
+  assert.match(reader, /var desiredWidth = availableSvgHeight \* ratio \+ chrome\.diagramX/);
+  assert.match(reader, /html\.style\.setProperty\('--archify-reader-width', rounded \+ 'px'\)/);
+});
+
+test('desktop readability budget matches the minimum adaptive reader at 1440 by 900', () => {
+  assert.deepEqual(DESKTOP_READABILITY_VIEWPORT, { width: 1440, height: 900 });
+  assert.equal(DESKTOP_READER_MIN_WIDTH, 960);
+  assert.equal(DESKTOP_READER_HORIZONTAL_CHROME, 30);
+  assert.equal(DESKTOP_READER_DIAGRAM_WIDTH, 930);
+  assert.match(reader, new RegExp(`var MIN_READER_WIDTH = ${DESKTOP_READER_MIN_WIDTH}`));
+  assert.match(template, /html\[data-nav-stage-rail="true"\] body \{ padding-block: 0\.375rem; \}/);
+  assert.match(template, /@media \(min-width: 768px\) and \(max-height: 1100px\)[\s\S]*?\.diagram-container \{[\s\S]*?padding: 0\.875rem;[\s\S]*?padding-bottom: calc\(0\.875rem \+ var\(--archify-nav-reserve\)\);/);
+  assert.match(template, /@media \(min-width: 768px\) and \(max-height: 920px\)[\s\S]*?body \{ padding-block: 1\.25rem; \}/);
+  assert.match(template, /\.diagram-container \{[\s\S]*?border: 1px solid var\(--panel-border\)/);
+});
+
+test('desktop readability source floor is the inverse of the projected-size gate', () => {
+  const sourceFloor = minimumReadableSourceTextPx(1376);
+  assert.ok(Math.abs(sourceFloor - 8.87741935483871) < 1e-12);
+  assert.ok(Math.abs(projectedNodeTextPx(sourceFloor, 1376) - MIN_PROJECTED_NODE_TEXT_PX) < 1e-12);
+  assert.equal(minimumReadableSourceTextPx(DESKTOP_READER_DIAGRAM_WIDTH), MIN_PROJECTED_NODE_TEXT_PX);
+  assert.equal(minimumReadableSourceTextPx(700), MIN_PROJECTED_NODE_TEXT_PX);
+  assert.ok(Number.isNaN(minimumReadableSourceTextPx(0)));
+});
+
+test('adaptive width preserves canonical SVG geometry and yields to specialized viewer modes', () => {
+  assert.match(reader, /window\.innerWidth >= MIN_DESKTOP_WIDTH/);
+  assert.match(reader, /html\.getAttribute\('data-embed'\) !== 'true'/);
+  assert.match(reader, /html\.getAttribute\('data-present'\) !== 'true'/);
+  assert.match(reader, /window\.matchMedia\('print'\)\.matches/);
+  assert.doesNotMatch(reader, /svg\.setAttribute\(['"](?:viewBox|width|height)/);
+  assert.doesNotMatch(reader, /svg\.style\.(?:width|height)/);
+  assert.doesNotMatch(reader, /overflow\s*=\s*['"]hidden/);
+});
+
+test('reader remeasures real content and reduces width before allowing desktop page overflow', () => {
+  assert.match(reader, /document\.fonts\.ready\.then\(schedule\)/);
+  assert.match(reader, /new ResizeObserver\(schedule\)/);
+  assert.match(reader, /new MutationObserver\(schedule\)/);
+  assert.match(reader, /document\.documentElement\.scrollHeight/);
+  assert.match(reader, /lastWidth - overflow \* ratio - 4/);
+  assert.match(skill, /1440×900, 1600×1000, and 1920×1080/);
+  assert.match(skill, /2048×1320/);
+  assert.match(skill, /Generate one responsive artifact for laptops and external displays/);
+  assert.match(skill, /preserve the authored SVG\/viewBox, proportions, semantic geometry/);
+});
+
+test('reader exposes an explicit stable-dimensions contract for browser evidence', () => {
+  assert.match(reader, /function stableSnapshot\(\)/);
+  assert.match(reader, /function whenStable\(\)/);
+  assert.match(reader, /document\.fonts && document\.fonts\.ready/);
+  assert.match(reader, /Math\.ceil\(document\.body\.scrollHeight\)/);
+  assert.match(reader, /stableFrames >= 3/);
+  assert.match(reader, /whenStable: whenStable/);
+});