@1aboveio/skills 0.0.0-stage → 1.0.0

package/skills/engineering/engineering-runtime/engineering-runtime.test.mjs

@@ -0,0 +1,68 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const RUNTIME_DIR = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = join(RUNTIME_DIR, '..', '..', '..');
+const MANIFEST = JSON.parse(readFileSync(join(REPO_ROOT, 'skills', 'distribution', 'manifest.json'), 'utf8'));
+
+// @covers package:engineering-runtime
+// @level integration
+test('runtime parser dependency metadata lives in the installed scripts directory', () => {
+  const scripts = join(RUNTIME_DIR, 'scripts');
+  const packageJson = JSON.parse(readFileSync(join(scripts, 'package.json'), 'utf8'));
+  const packageLock = JSON.parse(readFileSync(join(scripts, 'package-lock.json'), 'utf8'));
+
+  assert.equal(existsSync(join(RUNTIME_DIR, 'package.json')), false);
+  assert.equal(existsSync(join(RUNTIME_DIR, 'package-lock.json')), false);
+  // The lockfile must install exactly the version package.json declares.
+  assert.ok(packageJson.dependencies['js-yaml'], 'the runtime parser depends on js-yaml');
+  assert.equal(packageLock.packages['node_modules/js-yaml'].version, packageJson.dependencies['js-yaml']);
+});
+
+function modules(dir) {
+  const found = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name === 'node_modules' || entry.name.endsWith('-workspace')) continue;
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) found.push(...modules(path));
+    else if (entry.name.endsWith('.mjs') && !entry.name.endsWith('.test.mjs')) found.push(path);
+  }
+  return found;
+}
+
+// @covers package:engineering-runtime
+// @level integration
+test('every first-party Workflow consumer resolves one implementation in source and flat layouts', () => {
+  const workflow = MANIFEST.groups.find((group) => group.id === 'engineering-workflow');
+  const canonical = join(RUNTIME_DIR, 'scripts', 'main-module.mjs');
+  const flatCanonical = join('/flat-skills', 'engineering-runtime', 'scripts', 'main-module.mjs');
+  const consumers = [];
+
+  for (const member of workflow.members.filter((candidate) => candidate.role === 'skill')) {
+    const skillDir = join(REPO_ROOT, member.path);
+    for (const file of modules(skillDir)) {
+      const text = readFileSync(file, 'utf8');
+      if (!/\bisMainModule\s*\(/.test(text)) continue;
+      const staticImport = /import\s+\{\s*isMainModule\s*\}\s+from\s+['"]([^'"]+)['"]/.exec(text);
+      const dynamicImport = /await import\(['"]([^'"]+)['"]\)/.exec(text);
+      const imported = staticImport ?? dynamicImport;
+      assert.ok(imported, `${relative(REPO_ROOT, file)} calls isMainModule without resolving it from the runtime package`);
+      assert.equal(resolve(dirname(file), imported[1]), canonical, `${relative(REPO_ROOT, file)} misses the source runtime`);
+
+      const installedFile = join('/flat-skills', member.installName, relative(skillDir, file));
+      assert.equal(
+        resolve(dirname(installedFile), imported[1]),
+        flatCanonical,
+        `${relative(REPO_ROOT, file)} misses the flat-installed runtime`,
+      );
+      consumers.push(relative(REPO_ROOT, file));
+    }
+  }
+
+  // Shipped members only: the archived resolve-issues/resolve-release scripts left this census when
+  // those names became aliases (they were never packaged).
+  assert.ok(consumers.length >= 17, `the Workflow consumer census found only ${consumers.length} guarded scripts`);
+});

package/skills/engineering/engineering-runtime/release-check.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const WEEK_MS = 7 * DAY_MS;
+const here = dirname(fileURLToPath(import.meta.url));
+
+function readJson(path, fallback = {}) {
+  try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return fallback; }
+}
+
+function frontmatterValue(text, key) {
+  const frontmatter = /^---\n([\s\S]*?)\n---/.exec(text)?.[1] ?? '';
+  const match = new RegExp('^' + key + ':\\s*([^\\n]+)$', 'm').exec(frontmatter);
+  return match?.[1].trim().replace(/^['"]|['"]$/g, '') ?? null;
+}
+
+function repositoryOf(source) {
+  const value = String(source ?? '').trim();
+  const match = /^(?:git@github\.com:|https:\/\/github\.com\/)?([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+?)(?:\.git)?$/.exec(value);
+  return match?.[1] ?? null;
+}
+
+function stableVersion(value) {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(String(value ?? '').trim());
+  return match ? match.slice(1).map(Number) : null;
+}
+
+function newer(left, right) {
+  for (let index = 0; index < 3; index += 1) {
+    if (left[index] !== right[index]) return left[index] > right[index];
+  }
+  return false;
+}
+
+function writeCache(path, value) {
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(value));
+  } catch { /* A read-only cache must not block skill use. */ }
+}
+
+function main(now = Date.now()) {
+  if (process.env.ONEABOVEIO_NO_UPDATE_CHECK) return;
+  const skill = readFileSync(join(here, 'SKILL.md'), 'utf8');
+  const name = frontmatterValue(skill, 'name');
+  const localVersion = stableVersion(frontmatterValue(skill, 'release-version'));
+  if (!name || !localVersion) return;
+
+  const lock = readJson(join(process.env.HOME || homedir(), '.agents', '.skill-lock.json'));
+  const entry = lock.skills?.[name];
+  const repository = repositoryOf(entry?.sourceUrl || entry?.source);
+  if (!repository) return;
+
+  const cacheRoot = process.env.XDG_CACHE_HOME || join(process.env.HOME || homedir(), '.cache');
+  const cachePath = join(cacheRoot, '1aboveio-skills', 'release-check.json');
+  const all = readJson(cachePath);
+  const cache = all[repository] && typeof all[repository] === 'object' ? all[repository] : {};
+
+  if (!cache.lastCheck || now - cache.lastCheck >= DAY_MS) {
+    const result = spawnSync('gh', ['api', 'repos/' + repository + '/releases/latest', '--jq', '.tag_name'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 1500,
+    });
+    cache.lastCheck = now;
+    if (result.status === 0 && stableVersion(result.stdout)) cache.latestTag = result.stdout.trim();
+    else delete cache.latestTag;
+    all[repository] = cache;
+    writeCache(cachePath, all);
+  }
+
+  const latestVersion = stableVersion(cache.latestTag);
+  if (!latestVersion || !newer(latestVersion, localVersion)) return;
+  if (cache.notifiedTag === cache.latestTag && cache.notifiedAt && now - cache.notifiedAt < WEEK_MS) return;
+
+  cache.notifiedTag = cache.latestTag;
+  cache.notifiedAt = now;
+  all[repository] = cache;
+  writeCache(cachePath, all);
+  const command = `npx skills@1.5.23 add '${repository}#${cache.latestTag}' --global --agent universal claude-code --skill ${name} --yes`;
+  process.stdout.write(
+    `UPDATE_AVAILABLE: A newer 1AboveIO skills release (${cache.latestTag}) is available; this skill is `
+      + `v${localVersion.join('.')}. Ask once whether to refresh ${name}. On approval run \`${command}\`. `
+      + 'The refreshed instructions apply next session. Either way, continue the current task and do not ask again this session.\n',
+  );
+}
+
+try { main(); } catch { /* Update checks are advisory and always fail silent. */ }

package/skills/engineering/engineering-runtime/scripts/exact-head-artifact.mjs

@@ -0,0 +1,131 @@
+// Shared read-only validator for exact-head CI artifacts. The mutating adapter lives
+// in resolve-issues; consumers import this contract so review and integration use the
+// same fail-closed definition of valid evidence.
+import { locallyReproducedJobs, validatePublishOnlyEvidence, validateRequiredCheckExecution, validateRequiredCheckPlan } from './required-check-plan.mjs'
+
+export const EXACT_HEAD_ARTIFACT_VERSION = 2
+export const EXACT_HEAD_COLLECTION_MODES = Object.freeze(['choreographed', 'observed-existing-run'])
+
+function isObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function stable(value) {
+  if (Array.isArray(value)) return value.map(stable)
+  if (!isObject(value)) return value
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, stable(value[key])]))
+}
+
+export function sameExactHeadState(left, right) {
+  return JSON.stringify(stable(left)) === JSON.stringify(stable(right))
+}
+
+export function providerWorkflowIdentityMatches(expected, identity) {
+  if (typeof expected !== 'string' || !expected.trim() || !isObject(identity)) return false
+  const aliases = [identity.id, identity.name, identity.path]
+    .filter((value) => (typeof value === 'string' && value.trim()) || typeof value === 'number')
+    .map(String)
+  if (typeof identity.path === 'string') aliases.push(identity.path.split('/').at(-1))
+  return aliases.includes(expected)
+}
+
+function validateProviderWorkflowIdentity(identity) {
+  const errors = []
+  if (!isObject(identity)) return ['artifact.workflow.provider must preserve provider-issued workflow identity']
+  if ((typeof identity.id !== 'string' && typeof identity.id !== 'number') || !String(identity.id).trim()) errors.push('artifact.workflow.provider.id must identify the provider workflow')
+  if (typeof identity.name !== 'string' || !identity.name.trim()) errors.push('artifact.workflow.provider.name must preserve the provider workflow name')
+  if (identity.path !== undefined && (typeof identity.path !== 'string' || !identity.path.trim())) errors.push('artifact.workflow.provider.path must be a non-empty string when present')
+  return errors
+}
+
+function classifyRawJobs(jobs, policy) {
+  const errors = []
+  if (!Array.isArray(jobs)) return { outcome: 'failure', errors: ['artifact.jobs must be an array'] }
+  if (!isObject(policy) || !Array.isArray(policy.requiredJobs) || !Array.isArray(policy.allowedSkippedJobs)) {
+    return { outcome: 'failure', errors: ['artifact.policy must preserve requiredJobs and allowedSkippedJobs arrays'] }
+  }
+  const byName = new Map()
+  for (const [index, job] of jobs.entries()) {
+    if (!isObject(job) || typeof job.name !== 'string' || !Object.hasOwn(job, 'conclusion')) {
+      errors.push(`artifact.jobs[${index}] must preserve name and conclusion`)
+      continue
+    }
+    if (byName.has(job.name)) errors.push(`artifact.jobs has duplicate/ambiguous evidence for ${job.name}`)
+    else byName.set(job.name, job)
+  }
+  const missing = policy.requiredJobs.filter((name) => !byName.has(name))
+  const notSuccessful = policy.requiredJobs.filter((name) => byName.has(name) && byName.get(name).conclusion !== 'success')
+  const allowedSkipped = new Set(policy.allowedSkippedJobs)
+  const disallowedSkipped = jobs.filter((job) => job?.conclusion === 'skipped' && !allowedSkipped.has(job.name)).map((job) => job.name)
+  const failed = jobs.filter((job) => job && !['success', 'skipped'].includes(job.conclusion)).map((job) => `${job.name} (${job.conclusion ?? 'pending'})`)
+  if (missing.length) errors.push(`required jobs missing: ${missing.join(', ')}`)
+  if (notSuccessful.length) errors.push(`required jobs not successful: ${notSuccessful.join(', ')}`)
+  if (disallowedSkipped.length) errors.push(`jobs skipped without policy allowance: ${disallowedSkipped.join(', ')}`)
+  if (failed.length) errors.push(`raw jobs contain failure states: ${failed.join(', ')}`)
+  let outcome = 'success'
+  if (jobs.length === 0) outcome = 'zero-job-workflow-failure'
+  else if (jobs.some((job) => job?.conclusion === 'cancelled')) outcome = 'cancelled'
+  else if (errors.length) outcome = 'failure'
+  else if (jobs.some((job) => job?.conclusion === 'skipped')) outcome = 'success-with-skipped'
+  return { outcome, errors }
+}
+
+export function validateExactHeadArtifact(artifact, { expectedHeadSha } = {}) {
+  const errors = []
+  if (!isObject(artifact)) return { ok: false, errors: ['exact-head artifact must be an object'] }
+  if (artifact.version !== EXACT_HEAD_ARTIFACT_VERSION) errors.push(`unsupported exact-head artifact version ${artifact.version}`)
+  if (artifact.kind !== 'exact-head-ci') errors.push('exact-head artifact kind must be "exact-head-ci"')
+  if (!EXACT_HEAD_COLLECTION_MODES.includes(artifact.collectionMode)) errors.push(`artifact.collectionMode must be one of ${EXACT_HEAD_COLLECTION_MODES.join('|')}`)
+  if (typeof artifact.repository !== 'string' || !/^[^/\s]+\/[^/\s]+$/.test(artifact.repository)) errors.push('artifact.repository must be owner/name')
+  if (!Number.isInteger(artifact.pr) || artifact.pr < 1) errors.push('artifact.pr must be a positive integer')
+  if (typeof artifact.headSha !== 'string' || !/^[0-9a-f]{40}$/i.test(artifact.headSha)) errors.push('artifact.headSha must be a full 40-character commit SHA')
+  if (expectedHeadSha && artifact.headSha !== expectedHeadSha) errors.push(`exact-head artifact is STALE: stamped ${artifact.headSha}, expected ${expectedHeadSha}`)
+  const plan = validateRequiredCheckPlan(artifact.requiredCheckPlan, { expectedHeadSha: artifact.headSha })
+  errors.push(...plan.errors)
+  if (artifact.requiredCheckPlan?.repository !== artifact.repository) errors.push('requiredCheckPlan repository does not match artifact.repository')
+  const execution = validateRequiredCheckExecution(artifact.requiredCheckPlan, artifact.jobs, { expectedHeadSha: artifact.headSha })
+  errors.push(...execution.errors.filter((error) => !plan.errors.includes(error)))
+  const publishOnly = validatePublishOnlyEvidence(artifact.requiredCheckPlan, artifact.publishOnlyEvidence, { expectedHeadSha: artifact.headSha, expectedRepository: artifact.repository, expectedPr: artifact.pr })
+  errors.push(...publishOnly.errors)
+  if (!isObject(artifact.workflow) || typeof artifact.workflow.id !== 'string' || !artifact.workflow.id.trim()) errors.push('artifact.workflow.id must identify the requested provider workflow')
+  errors.push(...validateProviderWorkflowIdentity(artifact.workflow?.provider))
+  if (isObject(artifact.workflow?.provider) && !providerWorkflowIdentityMatches(artifact.workflow?.id, artifact.workflow.provider)) errors.push('provider workflow identity does not match artifact.workflow.id')
+  if (typeof artifact.workflow?.runId !== 'string' && typeof artifact.workflow?.runId !== 'number') errors.push('artifact.workflow.runId must identify the provider run')
+  if (artifact.workflow?.headSha !== artifact.headSha) errors.push('workflow headSha does not match artifact headSha')
+  if (!Array.isArray(artifact.jobs)) errors.push('artifact.jobs must be an array')
+  else for (const [index, job] of artifact.jobs.entries()) {
+    if (!isObject(job) || typeof job.name !== 'string' || !Object.hasOwn(job, 'conclusion')) errors.push(`artifact.jobs[${index}] must preserve name and conclusion`)
+  }
+  const expectedPolicy = {
+    requiredJobs: locallyReproducedJobs(artifact.requiredCheckPlan),
+    allowedSkippedJobs: artifact.requiredCheckPlan?.allowedSkippedJobs,
+  }
+  if (!sameExactHeadState(artifact.policy, expectedPolicy)) errors.push('artifact.policy must be derived exactly from requiredCheckPlan')
+  const raw = classifyRawJobs(artifact.jobs, artifact.policy)
+  errors.push(...raw.errors)
+  if (artifact.summary?.outcome !== raw.outcome) errors.push(`summary outcome "${artifact.summary?.outcome ?? 'missing'}" contradicts raw jobs outcome "${raw.outcome}"`)
+
+  if (artifact.collectionMode === 'choreographed') {
+    if (!Array.isArray(artifact.choreography) || artifact.choreography.length === 0) errors.push('choreographed artifacts must preserve the mutation choreography')
+    if (Object.hasOwn(artifact, 'observation')) errors.push('choreographed artifacts cannot claim observed-existing-run provenance')
+    if (artifact.restoration?.proved !== true) errors.push('live restoration was not proved')
+    if (!sameExactHeadState(artifact.snapshot, artifact.restoration?.observed)) errors.push('restoration observation does not equal the original snapshot')
+  }
+  if (artifact.collectionMode === 'observed-existing-run') {
+    if (Object.hasOwn(artifact, 'choreography')) errors.push('observed-existing-run artifacts cannot claim mutation choreography')
+    if (Object.hasOwn(artifact, 'restoration')) errors.push('observed-existing-run artifacts cannot contain a restoration claim')
+    if (Object.hasOwn(artifact, 'snapshot')) errors.push('observed-existing-run artifacts must use before/after observation provenance, not a choreography snapshot')
+    if (!isObject(artifact.observation) || !isObject(artifact.observation.before) || !isObject(artifact.observation.after)) {
+      errors.push('observed-existing-run artifacts require live PR observations before and after provider evidence acquisition')
+    } else {
+      if (artifact.observation.before.headSha !== artifact.headSha) errors.push('observed-existing-run before observation does not match artifact.headSha')
+      if (artifact.observation.after.headSha !== artifact.headSha) errors.push('observed-existing-run after observation does not match artifact.headSha')
+    }
+  }
+  if (!Array.isArray(artifact.errors)) errors.push('artifact.errors must be an array')
+  else if (artifact.errors.length) errors.push('passing exact-head artifacts cannot preserve collection errors')
+  if (artifact.status !== 'pass') errors.push(`exact-head status is "${artifact.status ?? 'missing'}", needs "pass"`)
+  if (!['success', 'success-with-skipped'].includes(artifact.summary?.outcome)) errors.push(`exact-head outcome is "${artifact.summary?.outcome ?? 'missing'}", not a passing outcome`)
+  if (!['success', 'success-with-skipped'].includes(raw.outcome)) errors.push(`raw jobs outcome "${raw.outcome}" is not passing`)
+  return { ok: errors.length === 0, errors }
+}