* feat(#1430): versioned capability manifest + native stamping (ADR-1244 Phase 1) Make the capability manifest versioned — the data substrate the Capability Ecosystem (ADR-1244) keys off: - capability.json gains a REQUIRED semver `version` plus the optional ecosystem envelope (`engines.gsd`, `compatVersions`, `integrity`, `provenance`); the build-time conformance validator enforces them via a new `validateVersionEnvelope()` (exported for the Phase 2 runtime overlay). - All 32 native capabilities stamped with `version` (= package version, lockstep) + `engines.gsd`; `sync-manifest-versions.cjs` gains a glob sweep that keeps them in sync, and the issue-844 regression guard is extended. - Strict SemVer 2.0.0 grammar blocks metacharacter/space/unicode smuggling in version strings; range/integrity fields are shape-validated (satisfaction and the load-time gate are deferred to Phase 2/4). - Capability rel-paths emitted forward-slash for cross-platform git correctness. Closes #1430 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(#1430): add changeset for versioned capability manifest Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
@@ -236,6 +236,96 @@ const VALID_TIERS = new Set(['core', 'standard', 'full']);
|
||||
const VALID_ON_ERROR = new Set(['skip', 'halt']);
|
||||
const RUNTIME_COMPAT_WILDCARD = '*';
|
||||
|
||||
// ── ADR-1244 D1: versioned-manifest envelope ─────────────────────────────────
|
||||
// Official strict SemVer 2.0.0 grammar (https://semver.org). Rejects partials
|
||||
// ("1.0"), prefixes ("v1.0.0"), leading-zero segments ("01.2.3"), numeric
|
||||
// prerelease identifiers with leading zeros ("1.2.3-01"), empty identifiers
|
||||
// ("1.2.3-..") and — critically — prerelease/build identifiers containing
|
||||
// anything outside [0-9A-Za-z-] (so a version can never smuggle shell
|
||||
// metacharacters, spaces or unicode into a downstream `git tag v<version>` or
|
||||
// path). Accepts "1.2.3-dev.0", "1.2.3-rc.1", "1.2.3+build.5".
|
||||
const SEMVER_RE = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/;
|
||||
// Permissive *shape* check for a semver range (engines.gsd / compatVersions
|
||||
// values). Range SATISFACTION is enforced by the runtime overlay (ADR-1244 D2);
|
||||
// here we only reject empty/garbage and shell metacharacters.
|
||||
const SEMVER_RANGE_RE = /^[0-9A-Za-z.\-+ |<>=~^*()]+$/;
|
||||
// Subresource-integrity hash: "sha512-" + base64 of a 64-byte digest (86 base64
|
||||
// chars + "==" padding). Exact length so malformed pins ("sha512-abc") fail.
|
||||
const SHA512_INTEGRITY_RE = /^sha512-[A-Za-z0-9+/]{86}==$/;
|
||||
|
||||
// A syntactically plausible semver range (shape-only — see SEMVER_RANGE_RE).
|
||||
// Requires a digit or a bare wildcard so pure-alpha garbage ("abcx", "()x") is
|
||||
// rejected; full range satisfaction is the runtime overlay's job (ADR-1244 D2).
|
||||
function isPlausibleRange(s) {
|
||||
if (typeof s !== 'string') return false;
|
||||
const t = s.trim();
|
||||
if (t.length === 0 || !SEMVER_RANGE_RE.test(s)) return false;
|
||||
return /\d/.test(t) || t === '*' || t === 'x' || t === 'X';
|
||||
}
|
||||
|
||||
/**
|
||||
* ADR-1244 D1: validate the versioned-manifest envelope.
|
||||
* - version REQUIRED semver string (the registry rejects a manifest
|
||||
* without one).
|
||||
* - engines optional object; engines.gsd optional semver-range string.
|
||||
* - compatVersions optional object mapping a capability version (semver) to a
|
||||
* gsd version range.
|
||||
* - integrity optional "sha512-<base64>" string.
|
||||
* - provenance optional { sourceRepo, commit } strings.
|
||||
*
|
||||
* Shape only — range satisfaction and integrity verification are enforced by
|
||||
* the source resolver / runtime overlay (ADR-1244 D2/D3).
|
||||
*
|
||||
* @param {object} cap The parsed JSON object.
|
||||
* @returns {string[]} Array of error strings; empty = valid.
|
||||
*/
|
||||
function validateVersionEnvelope(cap) {
|
||||
const errors = [];
|
||||
|
||||
if (typeof cap.version !== 'string' || !SEMVER_RE.test(cap.version)) {
|
||||
errors.push('version must be a semver string (e.g. "1.2.3"); got: ' + JSON.stringify(cap.version));
|
||||
}
|
||||
|
||||
if (cap.engines !== undefined) {
|
||||
if (typeof cap.engines !== 'object' || cap.engines === null || Array.isArray(cap.engines)) {
|
||||
errors.push('engines must be an object (e.g. { "gsd": ">=1.6.0" })');
|
||||
} else if (cap.engines.gsd !== undefined && !isPlausibleRange(cap.engines.gsd)) {
|
||||
errors.push('engines.gsd must be a semver range string; got: ' + JSON.stringify(cap.engines.gsd));
|
||||
}
|
||||
}
|
||||
|
||||
if (cap.compatVersions !== undefined) {
|
||||
if (typeof cap.compatVersions !== 'object' || cap.compatVersions === null || Array.isArray(cap.compatVersions)) {
|
||||
errors.push('compatVersions must be an object mapping capability versions to gsd version ranges');
|
||||
} else {
|
||||
for (const [k, v] of Object.entries(cap.compatVersions)) {
|
||||
if (!SEMVER_RE.test(k)) errors.push('compatVersions key "' + k + '" must be a semver string');
|
||||
if (!isPlausibleRange(v)) errors.push('compatVersions["' + k + '"] must be a semver range string');
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if (cap.integrity !== undefined && (typeof cap.integrity !== 'string' || !SHA512_INTEGRITY_RE.test(cap.integrity))) {
|
||||
errors.push('integrity must be a "sha512-<base64>" string');
|
||||
}
|
||||
|
||||
if (cap.provenance !== undefined) {
|
||||
const p = cap.provenance;
|
||||
if (typeof p !== 'object' || p === null || Array.isArray(p)) {
|
||||
errors.push('provenance must be an object { sourceRepo, commit }');
|
||||
} else {
|
||||
if (typeof p.sourceRepo !== 'string' || p.sourceRepo.length === 0) {
|
||||
errors.push('provenance.sourceRepo must be a non-empty string');
|
||||
}
|
||||
if (typeof p.commit !== 'string' || p.commit.length === 0) {
|
||||
errors.push('provenance.commit must be a non-empty string');
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return errors;
|
||||
}
|
||||
|
||||
/**
|
||||
* Validate a single capability declaration.
|
||||
*
|
||||
@@ -285,6 +375,9 @@ function validateCapability(cap, folderId) {
|
||||
}
|
||||
}
|
||||
|
||||
// ── Versioned-manifest envelope (ADR-1244 D1) ──────────────────────────────
|
||||
errors.push(...validateVersionEnvelope(cap));
|
||||
|
||||
// ── Role-specific body ────────────────────────────────────────────────────
|
||||
|
||||
if (cap.role === 'feature') {
|
||||
@@ -2580,6 +2673,11 @@ function main() {
|
||||
|
||||
module.exports = {
|
||||
validateCapability,
|
||||
// ADR-1244 D1: versioned-manifest envelope validation (reused by the runtime overlay, D2)
|
||||
validateVersionEnvelope,
|
||||
SEMVER_RE,
|
||||
SEMVER_RANGE_RE,
|
||||
SHA512_INTEGRITY_RE,
|
||||
validateAgainstContract,
|
||||
validateConsumesGlobal,
|
||||
validateCrossCapability,
|
||||
|
||||
@@ -68,6 +68,66 @@ function findDrift(opts) {
|
||||
return drift;
|
||||
}
|
||||
|
||||
// ─── ADR-1244 D6: native capability manifests ────────────────────────────────
|
||||
//
|
||||
// Native capabilities (capabilities/<id>/capability.json) carry a `version`
|
||||
// stamped in lockstep with the package version at release. Unlike
|
||||
// VERSIONED_MANIFESTS (fixed paths), capabilities are discovered by glob so a
|
||||
// new capability is auto-covered without editing this file. The version-sync
|
||||
// regression guard (issue #844) treats every swept capability manifest as
|
||||
// registered.
|
||||
|
||||
// Discover capabilities/<id>/capability.json under `root`, sorted for stable
|
||||
// staging order. Returns [] when there is no capabilities/ directory.
|
||||
function listCapabilityManifests(opts) {
|
||||
const root = (opts && opts.root) || ROOT;
|
||||
const dir = path.join(root, 'capabilities');
|
||||
let entries;
|
||||
try {
|
||||
entries = fs.readdirSync(dir, { withFileTypes: true });
|
||||
} catch {
|
||||
return [];
|
||||
}
|
||||
return entries
|
||||
.filter((e) => e.isDirectory())
|
||||
// Forward-slash rel paths (NOT path.join) so they match `git ls-files`
|
||||
// output, git pathspecs, and the forward-slash VERSIONED_MANIFESTS on every
|
||||
// platform — path.join would emit backslashes on Windows and break the
|
||||
// issue-844 regression guard's ALLOWED-set comparison.
|
||||
.map((e) => 'capabilities/' + e.name + '/capability.json')
|
||||
.filter((rel) => fs.existsSync(path.join(root, rel)))
|
||||
.sort();
|
||||
}
|
||||
|
||||
// Stamp `version` into each native capability manifest. Returns changed rel paths.
|
||||
function syncCapabilityVersions(opts) {
|
||||
const root = (opts && opts.root) || ROOT;
|
||||
const v = (opts && opts.version) != null ? opts.version : getPackageVersion(root);
|
||||
const changed = [];
|
||||
for (const rel of listCapabilityManifests({ root })) {
|
||||
const abs = path.join(root, rel);
|
||||
const manifest = readJson(abs);
|
||||
if (manifest.version !== v) {
|
||||
manifest.version = v;
|
||||
fs.writeFileSync(abs, JSON.stringify(manifest, null, 2) + '\n');
|
||||
changed.push(rel);
|
||||
}
|
||||
}
|
||||
return changed;
|
||||
}
|
||||
|
||||
// Native capability manifests whose version != package version.
|
||||
function findCapabilityDrift(opts) {
|
||||
const root = (opts && opts.root) || ROOT;
|
||||
const v = (opts && opts.version) != null ? opts.version : getPackageVersion(root);
|
||||
const drift = [];
|
||||
for (const rel of listCapabilityManifests({ root })) {
|
||||
const found = readJson(path.join(root, rel)).version;
|
||||
if (found !== v) drift.push({ manifest: rel, found, expected: v });
|
||||
}
|
||||
return drift;
|
||||
}
|
||||
|
||||
// Best-effort outside git; fail-closed inside a work tree so a release never
|
||||
// ships a stale manifest that the working-tree test already accepted.
|
||||
function stageManifests(opts) {
|
||||
@@ -83,21 +143,32 @@ function stageManifests(opts) {
|
||||
console.warn('sync-manifest-versions: not a git work tree; skipping staging.');
|
||||
return;
|
||||
}
|
||||
const toStage = [...VERSIONED_MANIFESTS, ...listCapabilityManifests({ root })];
|
||||
try {
|
||||
execFileSync('git', ['add', '--', ...VERSIONED_MANIFESTS], { cwd: root, stdio: ['ignore', 'ignore', 'pipe'] });
|
||||
execFileSync('git', ['add', '--', ...toStage], { cwd: root, stdio: ['ignore', 'ignore', 'pipe'] });
|
||||
} catch (err) {
|
||||
const detail = err && err.stderr ? err.stderr.toString().trim() : (err && err.message) || 'unknown error';
|
||||
throw new Error(`sync-manifest-versions: failed to git-add manifests inside a work tree: ${detail}`);
|
||||
}
|
||||
}
|
||||
|
||||
module.exports = { VERSIONED_MANIFESTS, syncManifestVersions, findDrift, getPackageVersion, stageManifests };
|
||||
module.exports = {
|
||||
VERSIONED_MANIFESTS,
|
||||
syncManifestVersions,
|
||||
findDrift,
|
||||
getPackageVersion,
|
||||
stageManifests,
|
||||
// ADR-1244 D6: native capability version sweep
|
||||
listCapabilityManifests,
|
||||
syncCapabilityVersions,
|
||||
findCapabilityDrift,
|
||||
};
|
||||
|
||||
if (require.main === module) {
|
||||
const args = process.argv.slice(2);
|
||||
const version = getPackageVersion();
|
||||
if (args.includes('--check')) {
|
||||
const drift = findDrift({ version });
|
||||
const drift = [...findDrift({ version }), ...findCapabilityDrift({ version })];
|
||||
if (drift.length) {
|
||||
for (const d of drift) {
|
||||
console.error('Manifest ' + d.manifest + ' version ' + d.found + ' != package.json ' + d.expected);
|
||||
@@ -105,10 +176,11 @@ if (require.main === module) {
|
||||
console.error('Run `node scripts/sync-manifest-versions.cjs` to fix.');
|
||||
process.exitCode = 1;
|
||||
} else {
|
||||
console.log('All ' + VERSIONED_MANIFESTS.length + ' versioned manifests in sync at ' + version + '.');
|
||||
const total = VERSIONED_MANIFESTS.length + listCapabilityManifests().length;
|
||||
console.log('All ' + total + ' versioned manifests in sync at ' + version + '.');
|
||||
}
|
||||
} else {
|
||||
const changed = syncManifestVersions({ version });
|
||||
const changed = [...syncManifestVersions({ version }), ...syncCapabilityVersions({ version })];
|
||||
if (changed.length) {
|
||||
console.log('Stamped ' + version + ' into: ' + changed.join(', '));
|
||||
} else {
|
||||
|
||||
Reference in New Issue
Block a user