The design language that makes your AI harness better at design.
JavaScript
Fix Codex skill version metadata (#703)
Paul Bakaus482368511ace
diff --git a/cli/bin/commands/skills.mjs b/cli/bin/commands/skills.mjsindex faa98a572..e15904104 100644--- a/cli/bin/commands/skills.mjs+++ b/cli/bin/commands/skills.mjs@@ -557,6 +557,39 @@ async function showHelp() {// ─── version helpers ─────────────────────────────────────────────────────────+function parseSkillFrontmatterVersion(content) {+ const match = String(content).match(/^---[ \t]*\r?\n([\s\S]*?)\r?\n---(?:[ \t]*\r?\n|[ \t]*$)/);+ if (!match) return null;++ let metadataVersion = null;+ let topLevelVersion = null;+ let inMetadata = false;+ let metadataIndent = null;++ for (const line of match[1].split(/\r?\n/)) {+ if (!line.trim() || line.trimStart().startsWith('#')) continue;+ const indentText = line.match(/^[ \t]*/)[0];+ const indent = indentText.replace(/\t/g, ' ').length;++ if (indent === 0) {+ inMetadata = /^metadata:\s*(?:#.*)?$/.test(line);+ metadataIndent = null;+ const version = line.match(/^version:\s*(.+?)\s*$/);+ if (version) topLevelVersion = version[1];+ continue;+ }++ if (!inMetadata) continue;+ if (metadataIndent === null) metadataIndent = indent;+ if (indent !== metadataIndent) continue;+ const version = line.trim().match(/^version:\s*(.+?)\s*$/);+ if (version) metadataVersion = version[1];+ }++ const value = metadataVersion || topLevelVersion;+ return value ? value.trim().replace(/^(["'])(.*)\1$/, '$2') : null;+}+/*** Read the skills version from the impeccable SKILL.md frontmatter.*/@@ -566,8 +599,8 @@ function getSkillsVersion(root, scope) {const skillMd = join(skillsDir, 'impeccable', 'SKILL.md');if (!existsSync(skillMd)) continue;const content = readFileSync(skillMd, 'utf-8');- const match = content.match(/^version:\s*(.+)$/m);- if (match) return match[1].trim().replace(/^["']|["']$/g, '');+ const version = parseSkillFrontmatterVersion(content);+ if (version) return version;}}return null;@@ -2483,6 +2516,7 @@ export {expectedHookDests,extractZip,formatInstallDetectionLines,+ getSkillsVersion,isUpToDate,hermesGlobalHome,HOME_SKILLS_DIR_OVERRIDES,diff --git a/scripts/lib/transformers/factory.js b/scripts/lib/transformers/factory.jsindex 5dfc19c30..684597ff5 100644--- a/scripts/lib/transformers/factory.js+++ b/scripts/lib/transformers/factory.js@@ -241,6 +241,7 @@ export function createTransformer(config) {providerTags = [provider],writeOpenAIMetadata = false,includeVersion = true,+ versionInMetadata = false,} = config;const placeholderKey = placeholderProvider || provider;@@ -274,7 +275,9 @@ export function createTransformer(config) {name: skillName,description: skill.description,};- if (skillsVersion && includeVersion) frontmatterObj.version = skillsVersion;+ if (skillsVersion && includeVersion && !versionInMetadata) {+ frontmatterObj.version = skillsVersion;+ }for (const spec of activeFields) {if (spec.condition && !spec.condition(skill)) continue;@@ -282,6 +285,13 @@ export function createTransformer(config) {if (val) frontmatterObj[spec.yamlKey] = val;}+ if (skillsVersion && includeVersion && versionInMetadata) {+ frontmatterObj.metadata = {+ ...(frontmatterObj.metadata || {}),+ version: skillsVersion,+ };+ }+// Replace {{command_hint}} in argument-hint with command names from metadata,// grouped by category with middle dots between groups for natural line-breaking.if (frontmatterObj['argument-hint']?.includes('{{command_hint}}')) {diff --git a/scripts/lib/transformers/providers.js b/scripts/lib/transformers/providers.jsindex 4fdadc515..9a7591c17 100644--- a/scripts/lib/transformers/providers.js+++ b/scripts/lib/transformers/providers.js@@ -48,6 +48,9 @@ export const PROVIDERS = {configDir: '.codex',displayName: 'Codex',frontmatterFields: [],+ // Codex's validator rejects unknown top-level keys. Version remains+ // available to Impeccable's updater under the spec-defined metadata map.+ versionInMetadata: true,writeOpenAIMetadata: true,// No agentFormat: the Codex subagent ships nested inside the skill's own// agents/ folder (see CODEX_SKILL_PROVIDERS in factory.js), which Codex@@ -63,6 +66,7 @@ export const PROVIDERS = {displayName: 'Codex Repo Skills',placeholderProvider: 'codex',frontmatterFields: [],+ versionInMetadata: true,writeOpenAIMetadata: true,},github: {diff --git a/scripts/lib/utils.js b/scripts/lib/utils.jsindex d96eff378..faa28cdbd 100644--- a/scripts/lib/utils.js+++ b/scripts/lib/utils.js@@ -787,6 +787,9 @@ export function generateYamlFrontmatter(data) {lines.push(` - ${formatYamlScalar(item)}`);}}+ } else if (value && typeof value === 'object') {+ lines.push(`${key}:`);+ appendYamlObject(lines, value, 2);} else if (typeof value === 'boolean') {lines.push(`${key}: ${value}`);} else {diff --git a/scripts/lib/validate-plugin-versions.js b/scripts/lib/validate-plugin-versions.jsindex bfb1645fa..be40131b1 100644--- a/scripts/lib/validate-plugin-versions.js+++ b/scripts/lib/validate-plugin-versions.js@@ -25,17 +25,43 @@ import fs from 'fs';import path from 'path';/**- * Pull the `version:` value out of a SKILL.md leading frontmatter block.+ * Pull the version value out of a SKILL.md leading frontmatter block.* CRLF-tolerant (`\r?\n`) to match the shared parseFrontmatter in* scripts/lib/utils.js — a bundle saved with CRLF line endings must not read- * as a null version and trip a false mismatch. `(.+)` stops at the line- * terminator (so a trailing `\r` is excluded), and `.trim()` mops up the rest.+ * as a null version and trip a false mismatch. Codex builds carry the version+ * under `metadata.version`; legacy provider builds keep the top-level key.*/export function readSkillFrontmatterVersion(content) {- const fm = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);+ const fm = String(content).match(/^---[ \t]*\r?\n([\s\S]*?)\r?\n---(?:[ \t]*\r?\n|[ \t]*$)/);if (!fm) return null;- const line = fm[1].match(/^version:\s*(.+)/m);- return line ? line[1].trim().replace(/^['"]|['"]$/g, '') : null;++ let metadataVersion = null;+ let topLevelVersion = null;+ let inMetadata = false;+ let metadataIndent = null;++ for (const line of fm[1].split(/\r?\n/)) {+ if (!line.trim() || line.trimStart().startsWith('#')) continue;+ const indentText = line.match(/^[ \t]*/)[0];+ const indent = indentText.replace(/\t/g, ' ').length;++ if (indent === 0) {+ inMetadata = /^metadata:\s*(?:#.*)?$/.test(line);+ metadataIndent = null;+ const version = line.match(/^version:\s*(.+?)\s*$/);+ if (version) topLevelVersion = version[1];+ continue;+ }++ if (!inMetadata) continue;+ if (metadataIndent === null) metadataIndent = indent;+ if (indent !== metadataIndent) continue;+ const version = line.trim().match(/^version:\s*(.+?)\s*$/);+ if (version) metadataVersion = version[1];+ }++ const value = metadataVersion || topLevelVersion;+ return value ? value.trim().replace(/^(["'])(.*)\1$/, '$2') : null;}/**diff --git a/skill/scripts/context.mjs b/skill/scripts/context.mjsindex 41112429a..cb16553c2 100644--- a/skill/scripts/context.mjs+++ b/skill/scripts/context.mjs@@ -962,13 +962,45 @@ export function extractPlatform(product) {* (this file lives at `<skill>/scripts/context.mjs`). Returns null when the* frontmatter is missing or unreadable.*/+function parseSkillFrontmatterVersion(content) {+ const match = String(content).match(/^---[ \t]*\r?\n([\s\S]*?)\r?\n---(?:[ \t]*\r?\n|[ \t]*$)/);+ if (!match) return null;++ let metadataVersion = null;+ let topLevelVersion = null;+ let inMetadata = false;+ let metadataIndent = null;++ for (const line of match[1].split(/\r?\n/)) {+ if (!line.trim() || line.trimStart().startsWith('#')) continue;+ const indentText = line.match(/^[ \t]*/)[0];+ const indent = indentText.replace(/\t/g, ' ').length;++ if (indent === 0) {+ inMetadata = /^metadata:\s*(?:#.*)?$/.test(line);+ metadataIndent = null;+ const version = line.match(/^version:\s*(.+?)\s*$/);+ if (version) topLevelVersion = version[1];+ continue;+ }++ if (!inMetadata) continue;+ if (metadataIndent === null) metadataIndent = indent;+ if (indent !== metadataIndent) continue;+ const version = line.trim().match(/^version:\s*(.+?)\s*$/);+ if (version) metadataVersion = version[1];+ }++ const value = metadataVersion || topLevelVersion;+ return value ? value.trim().replace(/^(["'])(.*)\1$/, '$2') : null;+}+function readLocalSkillVersion() {try {const here = path.dirname(fileURLToPath(import.meta.url));const skillMd = path.join(here, '..', 'SKILL.md');const content = fs.readFileSync(skillMd, 'utf-8');- const match = content.match(/^version:\s*(.+)$/m);- return match ? match[1].trim().replace(/^["']|["']$/g, '') : null;+ return parseSkillFrontmatterVersion(content);} catch {return null;}diff --git a/tests/context.test.mjs b/tests/context.test.mjsindex 76db0648d..c747164df 100644--- a/tests/context.test.mjs+++ b/tests/context.test.mjs@@ -1465,11 +1465,11 @@ describe('context.mjs update check', () => {const cachePath = () => path.join(scratch, 'update-check.json');- function setup(cacheObj, { disable = false, host } = {}) {+ function setup(cacheObj, { disable = false, host, skillFrontmatter } = {}) {const skillScript = stageContextBundle(path.join(scratch, 'skill', 'scripts'));fs.writeFileSync(path.join(scratch, 'skill', 'SKILL.md'),- `---\nname: impeccable\nversion: ${LOCAL_VERSION}\n---\n\nbody\n`,+ `---\n${skillFrontmatter || `name: impeccable\nversion: ${LOCAL_VERSION}`}\n---\n\nbody\n`,);fs.writeFileSync(cachePath(), JSON.stringify(cacheObj));const project = path.join(scratch, 'project');@@ -1522,6 +1522,22 @@ describe('context.mjs update check', () => {assert.match(res.stdout, /^# PRODUCT\.md/);});+ it('reads metadata.version and prefers it over the legacy top-level key', () => {+ const metadataOnly = run(+ { lastCheck: Date.now(), latestVersion: '2.0.0' },+ { skillFrontmatter: `name: impeccable\nmetadata:\n version: ${LOCAL_VERSION}` },+ );+ assert.equal(metadataOnly.status, 0);+ assert.match(metadataOnly.stdout, /installed v1\.0\.0, latest v2\.0\.0/);++ const both = run(+ { lastCheck: Date.now(), latestVersion: '2.0.0' },+ { skillFrontmatter: `name: impeccable\nversion: 9.0.0\nmetadata:\n version: ${LOCAL_VERSION}` },+ );+ assert.equal(both.status, 0);+ assert.match(both.stdout, /installed v1\.0\.0, latest v2\.0\.0/);+ });+// The directive used to say "ask once" and "if they agree, run it" while also// saying to continue without waiting. Nothing gated the run on an answer that// could not arrive, so the command read as the next step. It now forbidsdiff --git a/tests/lib/transformers/providers.test.js b/tests/lib/transformers/providers.test.jsindex 3906de04d..a9b2bd991 100644--- a/tests/lib/transformers/providers.test.js+++ b/tests/lib/transformers/providers.test.js@@ -68,8 +68,14 @@ for (const [key, config] of Object.entries(PROVIDERS)) {test('should emit skillsVersion in generated skill frontmatter', () => {const skills = [{ name: 'test', description: 'Test', body: 'Body' }];transform(skills, TEST_DIR, { skillsVersion: '1.2.3-test' });- const parsed = parseFrontmatter(fs.readFileSync(skillPath(config, 'test'), 'utf-8'));- expect(parsed.frontmatter.version).toBe('1.2.3-test');+ const content = fs.readFileSync(skillPath(config, 'test'), 'utf-8');+ const parsed = parseFrontmatter(content);+ if (key === 'codex' || key === 'agents') {+ expect(parsed.frontmatter.version).toBeUndefined();+ expect(content).toContain('metadata:\n version: 1.2.3-test');+ } else {+ expect(parsed.frontmatter.version).toBe('1.2.3-test');+ }});// Field-specific tests based on provider configdiff --git a/tests/lib/utils.test.js b/tests/lib/utils.test.jsindex d7e5d6ed8..93ac0a67c 100644--- a/tests/lib/utils.test.js+++ b/tests/lib/utils.test.js@@ -162,6 +162,15 @@ describe('generateYamlFrontmatter', () => {expect(result).toContain('user-invocable: true');});+ test('should generate nested metadata', () => {+ const result = generateYamlFrontmatter({+ name: 'test',+ metadata: { version: '1.2.3' },+ });++ expect(result).toContain('metadata:\n version: 1.2.3');+ });+test('should roundtrip: generate and parse back', () => {const original = {name: 'roundtrip-test',diff --git a/tests/skills-cli.test.js b/tests/skills-cli.test.jsindex 781407461..6524cea5a 100644--- a/tests/skills-cli.test.js+++ b/tests/skills-cli.test.js@@ -24,6 +24,7 @@ import {downloadFile,expectedHookDests,formatInstallDetectionLines,+ getSkillsVersion,mergeHookManifests,migrateUnprefixImpeccable,resolveInstallTargets,@@ -169,6 +170,32 @@ function createPrefixedInstall(root, { prefix = 'i-', providers = ['.claude'], f}}+describe('skills version discovery', () => {+ test('prefers metadata.version while accepting legacy top-level version', () => {+ const tmp = mkdtempSync(join(tmpdir(), 'imp-test-skill-version-'));+ const skillDir = join(tmp, '.agents', 'skills', 'impeccable');+ mkdirSync(skillDir, { recursive: true });+ writeFileSync(join(skillDir, 'SKILL.md'), [+ '---',+ 'name: impeccable',+ 'version: 0.9.0',+ 'metadata:',+ ' version: 1.2.3',+ '---',+ '',+ 'Body.',+ ].join('\n'));++ try {+ expect(getSkillsVersion(tmp, 'project')).toBe('1.2.3');+ writeFileSync(join(skillDir, 'SKILL.md'), '---\nname: impeccable\nversion: 0.9.0\n---\nBody.\n');+ expect(getSkillsVersion(tmp, 'project')).toBe('0.9.0');+ } finally {+ rmSync(tmp, { recursive: true, force: true });+ }+ });+});+// ─── Already-installed detection ─────────────────────────────────────────────// Remote e2e blocks (real bundle downloads from impeccable.style) run onlydiff --git a/tests/validate-plugin-versions.test.js b/tests/validate-plugin-versions.test.jsindex 128e88903..efea502dc 100644--- a/tests/validate-plugin-versions.test.js+++ b/tests/validate-plugin-versions.test.js@@ -157,6 +157,16 @@ describe('readSkillFrontmatterVersion', () => {expect(readSkillFrontmatterVersion('---\nversion: "3.7.1"\n---\n')).toBe('3.7.1');});+ test('prefers metadata.version while accepting the legacy top-level key', () => {+ const content = '---\nname: impeccable\nversion: 3.0.0\nmetadata:\n version: 3.7.1\n---\n';+ expect(readSkillFrontmatterVersion(content)).toBe('3.7.1');+ });++ test('reads metadata.version after nested metadata fields', () => {+ const content = '---\nname: impeccable\nmetadata:\n interface:\n display_name: Impeccable\n version: "3.7.1"\n---\n';+ expect(readSkillFrontmatterVersion(content)).toBe('3.7.1');+ });+test('returns null when there is no frontmatter block', () => {expect(readSkillFrontmatterVersion('no frontmatter here')).toBeNull();});