@1aboveio/skills 0.0.0-stage → 1.0.0

package/skills/engineering/resolve-release/scripts/apply.test.mjs

@@ -0,0 +1,99 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { applyRelease, bumpPyproject, insertChangelog } from './apply.mjs'
+
+test('insertChangelog cuts Unreleased and keeps handwritten notes', () => {
+  const before = `# Changelog\n\n## [Unreleased]\n\n- operator note\n\n## [1.0.0] - 2026-01-01\n`
+  const after = insertChangelog(before, {
+    version: '1.1.0',
+    date: '2026-08-24',
+    section: '## [1.1.0] - 2026-08-24\n\n### Added\n- export csv\n',
+  })
+  assert.match(after, /## \[Unreleased\]\n\n## \[1\.1\.0\] - 2026-08-24/)
+  assert.match(after, /export csv/)
+  assert.match(after, /operator note/)
+  assert.match(after, /## \[1\.0\.0\]/)
+  assert.equal((after.match(/## \[1\.1\.0\]/g) || []).length, 1)
+})
+
+test('insertChangelog is idempotent only when the recorded section is present', () => {
+  const section = '## [1.1.0] - 2026-08-24\n\n### Added\n- export csv'
+  const md = `# Changelog\n\n${section}\n`
+  assert.equal(insertChangelog(md, { version: '1.1.0', date: '2026-08-24', section }), md)
+  assert.throws(
+    () => insertChangelog(md, {
+      version: '1.1.0',
+      date: '2026-08-24',
+      section: '## [1.1.0] - 2026-08-24\n\n### Added\n- missing entry',
+    }),
+    /does not match the recorded plan/,
+  )
+})
+
+test('bumpPyproject replaces [project] version only', () => {
+  const text = '[build-system]\nrequires = ["setuptools"]\n\n[project]\nname = "demo"\nversion = "0.1.0"\n'
+  assert.match(bumpPyproject(text, '0.2.0'), /\[project\]\nname = "demo"\nversion = "0\.2\.0"/)
+})
+
+test('applyRelease writes changelog and identity files', () => {
+  const cwd = mkdtempSync(join(tmpdir(), 'rush-release-apply-'))
+  writeFileSync(join(cwd, 'package.json'), `${JSON.stringify({ name: 'demo', version: '1.2.0' }, null, 2)}\n`)
+  writeFileSync(join(cwd, 'package-lock.json'), `${JSON.stringify({ name: 'demo', version: '1.2.0', packages: { '': { name: 'demo', version: '1.2.0' } } }, null, 2)}\n`)
+  writeFileSync(join(cwd, 'VERSION'), '1.2.0\n')
+  writeFileSync(join(cwd, 'CHANGELOG.md'), '# Changelog\n\n## [Unreleased]\n\n')
+  const result = applyRelease({
+    version: '1.3.0',
+    date: '2026-08-24',
+    cwd,
+    changelogSection: '## [1.3.0] - 2026-08-24\n\n### Added\n- export csv\n',
+  })
+  assert.deepEqual(result.changed.sort(), ['CHANGELOG.md', 'VERSION', 'package-lock.json', 'package.json'])
+  assert.equal(JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf8')).version, '1.3.0')
+  assert.equal(JSON.parse(readFileSync(join(cwd, 'package-lock.json'), 'utf8')).packages[''].version, '1.3.0')
+  assert.equal(readFileSync(join(cwd, 'VERSION'), 'utf8'), '1.3.0\n')
+  assert.match(readFileSync(join(cwd, 'CHANGELOG.md'), 'utf8'), /export csv/)
+})
+
+test('applyRelease refuses to discard the recorded plan changelog', () => {
+  assert.throws(
+    () => applyRelease({ version: '1.3.0', date: '2026-08-24' }),
+    /requires the recorded plan changelog/,
+  )
+})
+
+test('applyRelease delegates a distribution release without adding a version to the private root package', () => {
+  const cwd = mkdtempSync(join(tmpdir(), 'rush-release-distribution-apply-'))
+  mkdirSync(join(cwd, 'skills/distribution'), { recursive: true })
+  writeFileSync(join(cwd, 'package.json'), `${JSON.stringify({ name: 'private-root', private: true }, null, 2)}\n`)
+  writeFileSync(join(cwd, 'skills/distribution/manifest.json'), `${JSON.stringify({
+    releaseVersion: '0.19.0',
+    sources: [{ renderTargets: [{ id: 'private-checkout', revision: 'main' }] }],
+  }, null, 2)}\n`)
+  writeFileSync(join(cwd, 'CHANGELOG.md'), '# Changelog\n\n')
+  const calls = []
+
+  const result = applyRelease({
+    version: '0.19.1',
+    date: '2026-08-30',
+    cwd,
+    changelogSection: '## [0.19.1] - 2026-08-30\n\n### Changed\n- manual trigger only\n',
+    cutDistribution: (options) => {
+      calls.push(options)
+      return ['skills/distribution/manifest.json', 'skills/engineering/engineering-runtime/coherence/workflow.json']
+    },
+  })
+
+  assert.deepEqual(calls, [{ version: '0.19.1', cwd }])
+  assert.deepEqual(result.changed, [
+    'CHANGELOG.md',
+    'skills/distribution/manifest.json',
+    'skills/engineering/engineering-runtime/coherence/workflow.json',
+  ])
+  assert.deepEqual(JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf8')), {
+    name: 'private-root',
+    private: true,
+  })
+})

package/skills/engineering/resolve-release/scripts/dark-flags.mjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+// Dark launch: which flags ship switched off in this release, and are they still off live.
+//
+// Usage:
+//   node dark-flags.mjs list --registry <path> --sha <sha> [--base <tag>] [--json]
+//   node dark-flags.mjs check --flags <list.json> --observed <observed.json> [--json]
+//
+// A registry is JSON or YAML: { flags: { <name>: { default: false, description: "..." } } }.
+// A flag ships dark when it is in the registry at <sha> but not at <base>, or when a commit
+// in <base>..<sha> carries a `Dark-Launch: <name>` trailer.
+//
+// Exit: 0 ok · 1 invalid registry / flag not off / git failed · 2 usage
+import { readFileSync } from 'node:fs'
+import { spawnSync } from 'node:child_process'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+import { parseYamlMapping } from '../../engineering-runtime/scripts/yaml-mapping.mjs'
+
+const OFF_VALUES = new Set([false, 0, 'off', 'false', 'disabled', '0'])
+
+export function isOff(value) {
+  return OFF_VALUES.has(typeof value === 'string' ? value.trim().toLowerCase() : value)
+}
+
+export function parseRegistry(text, label = 'flag registry') {
+  const root = parseYamlMapping(text, label)
+  const flags = root.flags
+  if (!flags || typeof flags !== 'object' || Array.isArray(flags)) throw new Error(`${label} needs a "flags" mapping`)
+  for (const [name, entry] of Object.entries(flags)) {
+    if (!entry || typeof entry !== 'object' || !('default' in entry)) throw new Error(`${label}: flag ${name} needs a default`)
+  }
+  return flags
+}
+
+export function darkFlags({ registryAtSha, registryAtBase = {}, trailerNames = [] }) {
+  const errors = []
+  const names = new Set(Object.keys(registryAtSha).filter((name) => !(name in registryAtBase)))
+  for (const name of trailerNames) {
+    if (!(name in registryAtSha)) errors.push(`Dark-Launch trailer names ${name}, which is not in the flag registry`)
+    else names.add(name)
+  }
+  const flags = [...names].sort().map((name) => {
+    const entry = registryAtSha[name]
+    const summary = String(entry.description || name).trim()
+    if (!isOff(entry.default)) errors.push(`flag ${name} ships with default ${JSON.stringify(entry.default)}; a dark flag defaults to off`)
+    return { name, summary, default: entry.default }
+  })
+  return { flags, errors }
+}
+
+export function checkLive(flags, observed) {
+  const failures = []
+  for (const { name } of flags) {
+    if (!(name in observed)) failures.push(`${name}: no live reading`)
+    else if (!isOff(observed[name])) failures.push(`${name}: live value ${JSON.stringify(observed[name])} is not off`)
+  }
+  return { ok: failures.length === 0, failures }
+}
+
+function git(args, cwd, allowFail = false) {
+  const result = spawnSync('git', args, { encoding: 'utf8', cwd })
+  if (result.status !== 0) {
+    if (allowFail) return null
+    const err = new Error(result.stderr.trim() || `git ${args.join(' ')} failed`)
+    err.exitCode = 1
+    throw err
+  }
+  return result.stdout
+}
+
+export function listDarkFlags({ registry, sha, base = null, cwd = process.cwd() }) {
+  const atSha = git(['show', `${sha}:${registry}`], cwd, true)
+  if (atSha === null) {
+    const err = new Error(`flag registry ${registry} does not exist at ${sha}`)
+    err.exitCode = 1
+    throw err
+  }
+  const atBase = base ? git(['show', `${base}:${registry}`], cwd, true) : null
+  const range = base ? `${base}..${sha}` : sha
+  const trailerNames = git(['log', range, '--format=%(trailers:key=Dark-Launch,valueonly,separator=%x0a)'], cwd)
+    .split('\n').map((line) => line.trim()).filter(Boolean)
+  return darkFlags({
+    registryAtSha: parseRegistry(atSha, `${registry}@${sha}`),
+    registryAtBase: atBase === null ? {} : parseRegistry(atBase, `${registry}@${base}`),
+    trailerNames: [...new Set(trailerNames)],
+  })
+}
+
+function usage(message) {
+  const err = new Error(message)
+  err.exitCode = 2
+  return err
+}
+
+function parseArgs(argv) {
+  const [command, ...rest] = argv
+  const opts = { command, json: false }
+  for (let i = 0; i < rest.length; i += 1) {
+    const arg = rest[i]
+    if (arg === '--json') opts.json = true
+    else if (['--registry', '--sha', '--base', '--flags', '--observed'].includes(arg)) {
+      if (rest[i + 1] === undefined) throw usage(`${arg} needs a value`)
+      opts[arg.slice(2)] = rest[++i]
+    } else throw usage(`unknown argument: ${arg}`)
+  }
+  if (command === 'list' && (!opts.registry || !opts.sha)) throw usage('list needs --registry and --sha')
+  if (command === 'check' && (!opts.flags || !opts.observed)) throw usage('check needs --flags and --observed')
+  if (!['list', 'check'].includes(command)) throw usage('usage: dark-flags.mjs list|check [options]')
+  return opts
+}
+
+export function main(argv = process.argv.slice(2), { cwd = process.cwd() } = {}) {
+  const opts = parseArgs(argv)
+  if (opts.command === 'list') {
+    const result = listDarkFlags({ registry: opts.registry, sha: opts.sha, base: opts.base || null, cwd })
+    process.stdout.write(opts.json
+      ? `${JSON.stringify(result, null, 2)}\n`
+      : `${result.flags.map((flag) => `${flag.name}: ${flag.summary}`).join('\n') || 'no dark flags'}\n${result.errors.map((e) => `error: ${e}`).join('\n')}`)
+    return result.errors.length ? 1 : 0
+  }
+  const listed = JSON.parse(readFileSync(opts.flags, 'utf8'))
+  const flags = Array.isArray(listed) ? listed : listed.flags
+  const result = checkLive(flags, JSON.parse(readFileSync(opts.observed, 'utf8')))
+  process.stdout.write(opts.json ? `${JSON.stringify(result, null, 2)}\n` : `${result.ok ? 'all dark flags off' : result.failures.join('\n')}\n`)
+  return result.ok ? 0 : 1
+}
+
+if (isMainModule(import.meta.url)) {
+  try {
+    process.exitCode = main()
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`)
+    process.exitCode = error.exitCode || 1
+  }
+}

package/skills/engineering/resolve-release/scripts/dark-flags.test.mjs

@@ -0,0 +1,100 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { checkLive, darkFlags, isOff, listDarkFlags, parseRegistry } from './dark-flags.mjs'
+
+const SCRIPT = join(import.meta.dirname, 'dark-flags.mjs')
+
+function git(cwd, args) {
+  const result = spawnSync('git', args, { cwd, encoding: 'utf8' })
+  assert.equal(result.status, 0, result.stderr)
+  return result.stdout
+}
+
+function registry(cwd, flags) {
+  writeFileSync(join(cwd, 'config', 'flags.json'), `${JSON.stringify({ flags }, null, 2)}\n`)
+  git(cwd, ['add', 'config/flags.json'])
+}
+
+function repo() {
+  const cwd = mkdtempSync(join(tmpdir(), 'resolve-release-dark-'))
+  git(cwd, ['init', '-b', 'main'])
+  git(cwd, ['config', 'user.email', 'dev@example.com'])
+  git(cwd, ['config', 'user.name', 'Dev'])
+  git(cwd, ['config', 'commit.gpgsign', 'false'])
+  mkdirSync(join(cwd, 'config'))
+  registry(cwd, { 'old-search': { default: true, description: 'Search (launched)' } })
+  git(cwd, ['commit', '-m', 'chore: init'])
+  git(cwd, ['tag', 'v1.0.0'])
+  return cwd
+}
+
+test('off means off, and nothing else does', () => {
+  for (const value of [false, 0, 'off', 'OFF', 'false', 'disabled', '0']) assert.equal(isOff(value), true, String(value))
+  for (const value of [true, 1, 'on', 'true', 'enabled', null, undefined, '']) assert.equal(isOff(value), false, String(value))
+})
+
+test('a registry needs a flags mapping and a default per flag', () => {
+  assert.throws(() => parseRegistry('{"flags": []}'), /"flags" mapping/)
+  assert.throws(() => parseRegistry('flags:\n  x: {description: y}\n'), /flag x needs a default/)
+  assert.deepEqual(Object.keys(parseRegistry('flags:\n  x: {default: off}\n')), ['x'])
+})
+
+test('new registry entries and Dark-Launch trailers ship dark; each must default off', () => {
+  const result = darkFlags({
+    registryAtBase: { launched: { default: true } },
+    registryAtSha: {
+      launched: { default: true },
+      'bulk-refunds': { default: false, description: 'Bulk refunds' },
+      'new-nav': { default: 'on' },
+    },
+    trailerNames: ['launched', 'ghost'],
+  })
+  assert.deepEqual(result.flags.map((flag) => flag.name), ['bulk-refunds', 'launched', 'new-nav'])
+  assert.equal(result.flags[0].summary, 'Bulk refunds')
+  assert.deepEqual(result.errors.sort(), [
+    'Dark-Launch trailer names ghost, which is not in the flag registry',
+    'flag launched ships with default true; a dark flag defaults to off',
+    'flag new-nav ships with default "on"; a dark flag defaults to off',
+  ])
+})
+
+test('the live check fails on a flag that is on or unread', () => {
+  const flags = [{ name: 'a' }, { name: 'b' }, { name: 'c' }]
+  assert.deepEqual(checkLive(flags, { a: false, b: 'off', c: 0 }), { ok: true, failures: [] })
+  assert.deepEqual(checkLive(flags, { a: false, b: 'on' }).failures, ['b: live value "on" is not off', 'c: no live reading'])
+})
+
+test('listing reads the registry at both refs and the trailers in between', () => {
+  const cwd = repo()
+  registry(cwd, {
+    'old-search': { default: true, description: 'Search (launched)' },
+    'bulk-refunds': { default: false, description: 'Bulk refunds' },
+  })
+  git(cwd, ['commit', '-m', 'feat: bulk refunds\n\nDark-Launch: bulk-refunds'])
+  const result = listDarkFlags({ registry: 'config/flags.json', sha: 'HEAD', base: 'v1.0.0', cwd })
+  assert.deepEqual(result, { flags: [{ name: 'bulk-refunds', summary: 'Bulk refunds', default: false }], errors: [] })
+
+  const cli = spawnSync('node', [SCRIPT, 'list', '--registry', 'config/flags.json', '--sha', 'HEAD', '--base', 'v1.0.0', '--json'], { cwd, encoding: 'utf8' })
+  assert.equal(cli.status, 0, cli.stderr)
+  assert.equal(JSON.parse(cli.stdout).flags[0].name, 'bulk-refunds')
+
+  const missing = spawnSync('node', [SCRIPT, 'list', '--registry', 'nope.json', '--sha', 'HEAD'], { cwd, encoding: 'utf8' })
+  assert.equal(missing.status, 1)
+  assert.match(missing.stderr, /does not exist at HEAD/)
+})
+
+test('the check CLI exits non-zero when a dark flag is live', () => {
+  const cwd = mkdtempSync(join(tmpdir(), 'resolve-release-dark-check-'))
+  writeFileSync(join(cwd, 'list.json'), JSON.stringify({ flags: [{ name: 'bulk-refunds', summary: 'Bulk refunds' }] }))
+  writeFileSync(join(cwd, 'off.json'), JSON.stringify({ 'bulk-refunds': false }))
+  writeFileSync(join(cwd, 'on.json'), JSON.stringify({ 'bulk-refunds': true }))
+  const check = (observed) => spawnSync('node', [SCRIPT, 'check', '--flags', 'list.json', '--observed', observed], { cwd, encoding: 'utf8' })
+  assert.equal(check('off.json').status, 0)
+  const live = check('on.json')
+  assert.equal(live.status, 1)
+  assert.match(live.stdout, /bulk-refunds: live value true is not off/)
+})