ccch1mneyyy/dsh-TUI / .agents/skills/review
review
VerifiedReview or de-slop concrete changes in ccch1mneyyy/dsh-TUI at maintainer level: PR numbers or URLs, branches, commit ranges, patch files, staged or unstaged worktrees, and scoped repository-hygiene requests. Use for evidence-first correctness, contract, repository-rule, process, and behavior-preserving cleanup review, including debug residue, dead or duplicate code, speculative abstractions, stale comments or tests, and unrelated diff churn. Do not use for abstract designs with no concrete repository artifact; use audit for repository-wide assessments and vuln-check for security-only checks.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.5 KB |
| references/contract-gates.md | markdown | 5.0 KB |
| references/deslop-gates.md | markdown | 5.9 KB |
| references/evidence-base.md | markdown | 7.2 KB |
| references/redlines.md | markdown | 4.8 KB |
| references/report-contract.md | markdown | 3.1 KB |
| references/verification-map.md | markdown | 5.1 KB |
| scripts/contract-snapshot.mjsexecutable | script | 15.6 KB |
| scripts/scan-diff-hygiene.mjsexecutable | script | 9.6 KB |
scripts/contract-snapshot.mjs
View on GitHub#!/usr/bin/env node
import { execFileSync } from 'node:child_process'
import { createHash } from 'node:crypto'
import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
import { basename, dirname, join, resolve } from 'node:path'
import { tmpdir } from 'node:os'
import process from 'node:process'
const SCHEMA_VERSION = 1
const CONTRACT_FILES = [
'package.json',
'AGENTS.md',
'ADAPTER.md',
'docs/contributing.md',
'src/dsh-adapter/contract.ts',
'src/plugin-host.ts',
'cordis.patch.yml',
'patch-surface.snapshot.json',
'tui-profile/protocols/tui-channel.js',
'.github/workflows/ci.yml',
]
const SUBMODULE_PATHS = [
// `dsh-auth` only exists in the self-test fixture's synthetic repo; the real
// repository no longer mounts it (and never has a directory of that name), so
// the WORKTREE probe simply finds nothing and falls back to the gitlink.
'dsh-auth',
// `tui-profile` used to be mounted here too; it is now plain in-tree files, so
// it must NOT be probed as a submodule — `git -C tui-profile rev-parse HEAD`
// would silently report the outer repository's HEAD.
'vendor/dsh-std',
]
function fail(message, code = 2) {
console.error(`contract-snapshot: ${message}`)
process.exit(code)
}
function git(repo, args, { allowFailure = false } = {}) {
try {
return execFileSync('git', ['-C', repo, ...args], {
encoding: 'utf8',
stdio: ['ignore', 'pipe', 'pipe'],
maxBuffer: 32 * 1024 * 1024,
})
} catch (error) {
if (allowFailure) return null
const stderr = error?.stderr?.toString?.().trim()
throw new Error(stderr || error.message)
}
}
function sha256(text) {
return createHash('sha256').update(text).digest('hex')
}
function stable(value) {
if (Array.isArray(value)) return value.map(stable)
if (value && typeof value === 'object') {
return Object.fromEntries(
Object.keys(value).sort().map(key => [key, stable(value[key])]),
)
}
return value
}
function readAtRevision(repo, revision, path) {
if (revision === 'WORKTREE') {
try {
return readFileSync(join(repo, path), 'utf8')
} catch {
return null
}
}
if (revision === 'INDEX') {
return git(repo, ['show', `:${path}`], { allowFailure: true })
}
return git(repo, ['show', `${revision}:${path}`], { allowFailure: true })
}
function resolvedRevision(repo, revision) {
if (revision === 'WORKTREE') {
const head = git(repo, ['rev-parse', 'HEAD'], { allowFailure: true })?.trim()
return head ? `WORKTREE@${head}` : 'WORKTREE'
}
if (revision === 'INDEX') {
const head = git(repo, ['rev-parse', 'HEAD'], { allowFailure: true })?.trim()
return head ? `INDEX@${head}` : 'INDEX'
}
return git(repo, ['rev-parse', revision]).trim()
}
function parsePackage(text) {
if (text == null) return { present: false }
try {
const pkg = JSON.parse(text)
return stable({
present: true,
name: pkg.name ?? null,
version: pkg.version ?? null,
packageManager: pkg.packageManager ?? null,
engines: pkg.engines ?? {},
imports: pkg.imports ?? {},
bin: pkg.bin ?? {},
exports: pkg.exports ?? {},
dependencies: pkg.dependencies ?? {},
peerDependencies: pkg.peerDependencies ?? {},
peerDependenciesMeta: pkg.peerDependenciesMeta ?? {},
devDependencies: pkg.devDependencies ?? {},
scripts: pkg.scripts ?? {},
files: pkg.files ?? [],
})
} catch (error) {
return {
present: true,
parseError: error.message,
sha256: sha256(text),
}
}
}
function normalizeStatement(statement) {
return statement
.replace(/\/\*[\s\S]*?\*\//g, ' ')
.replace(/\/\/[^\n]*/g, ' ')
.replace(/\s+/g, ' ')
.trim()
}
function extractExportStatements(text) {
if (!text) return []
const statements = []
const reExports = /(^|\n)\s*export\s+(?:type\s+)?\{[\s\S]*?\}\s+from\s+['"][^'"]+['"]\s*;?/g
for (const match of text.matchAll(reExports)) {
statements.push(normalizeStatement(match[0]))
}
const exportAll = /(^|\n)\s*export\s+\*\s+from\s+['"][^'"]+['"]\s*;?/g
for (const match of text.matchAll(exportAll)) {
statements.push(normalizeStatement(match[0]))
}
const declarations = /(^|\n)\s*export\s+(?:declare\s+)?(?:async\s+)?(?:const|let|var|function|class|enum|interface|type)\s+([A-Za-z_$][\w$]*)/g
for (const match of text.matchAll(declarations)) {
statements.push(`export declaration ${match[2]}`)
}
return [...new Set(statements)].sort()
}
function extractQuotedList(text, symbol) {
if (!text) return []
const escaped = symbol.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
const pattern = new RegExp(`${escaped}\\s*=\\s*(?:Object\\.freeze\\s*\\()?\\s*\\[([\\s\\S]*?)\\]`, 'm')
const match = text.match(pattern)
if (!match) return []
return [...match[1].matchAll(/['"]([^'"]+)['"]/g)].map(item => item[1]).sort()
}
function extractProtocol(text) {
if (!text) return { present: false }
const apiVersion =
text.match(/TUI_CHANNEL_API_VERSION\s*=\s*['"]([^'"]+)['"]/)?.[1] ??
text.match(/apiVersion\s*:\s*['"]([^'"]+)['"]/)?.[1] ??
null
const wireRevisionRaw = text.match(/TUI_CHANNEL_WIRE_REVISION\s*=\s*(\d+)/)?.[1]
const features = extractQuotedList(text, 'TUI_CHANNEL_FEATURES')
return {
present: true,
apiVersion,
wireRevision: wireRevisionRaw == null ? null : Number(wireRevisionRaw),
features,
}
}
function readSubmodulePointers(repo, revision) {
if (revision === 'WORKTREE') {
// The worktree revision is what is checked out on disk, so read each
// submodule's own HEAD: a staged switch and an unstaged `git submodule
// update` both move it, while `git ls-tree HEAD` keeps reporting the
// committed gitlink for either.
const recorded = parseSubmoduleOutput(git(repo, ['ls-tree', 'HEAD', '--', ...SUBMODULE_PATHS], { allowFailure: true }) ?? '')
const result = {}
for (const path of SUBMODULE_PATHS) {
const head = git(repo, ['-C', path, 'rev-parse', 'HEAD'], { allowFailure: true })?.trim()
// Uninitialized submodule: keep the recorded gitlink instead of dropping
// the key, so a missing checkout does not read as contract drift.
if (head) result[path] = head
else if (recorded[path]) result[path] = recorded[path]
}
return stable(result)
}
if (revision === 'INDEX') {
const output = git(repo, ['ls-files', '--stage', '--', ...SUBMODULE_PATHS], { allowFailure: true }) ?? ''
return parseSubmoduleOutput(output)
}
const output = git(repo, ['ls-tree', revision, '--', ...SUBMODULE_PATHS], { allowFailure: true }) ?? ''
return parseSubmoduleOutput(output)
}
function parseSubmoduleOutput(output) {
const result = {}
for (const line of output.split('\n')) {
if (!line.trim()) continue
const match = line.match(/^160000\s+(?:commit\s+)?([0-9a-f]{40})\s+\d?\s*\t?(.+)$/)
if (match) result[match[2]] = match[1]
}
return stable(result)
}
function buildSnapshot(repoInput, revisionInput) {
const repo = resolve(repoInput)
const revision = revisionInput || 'HEAD'
const resolved = resolvedRevision(repo, revision)
const contents = Object.fromEntries(
CONTRACT_FILES.map(path => [path, readAtRevision(repo, revision, path)]),
)
const files = stable(Object.fromEntries(
CONTRACT_FILES.map(path => {
const text = contents[path]
return [path, text == null
? { present: false }
: { present: true, bytes: Buffer.byteLength(text), sha256: sha256(text) }]
}),
))
return stable({
schemaVersion: SCHEMA_VERSION,
repository: basename(repo),
requestedRevision: revision,
resolvedRevision: resolved,
package: parsePackage(contents['package.json']),
pluginHost: {
present: contents['src/plugin-host.ts'] != null,
exportStatements: extractExportStatements(contents['src/plugin-host.ts']),
},
protocol: extractProtocol(contents['tui-profile/protocols/tui-channel.js']),
submodules: readSubmodulePointers(repo, revision),
files,
})
}
function comparable(snapshot) {
const {
requestedRevision: _requestedRevision,
resolvedRevision: _resolvedRevision,
repository: _repository,
...rest
} = snapshot
return rest
}
function jsonPointerToken(token) {
return String(token).replace(/~/g, '~0').replace(/\//g, '~1')
}
function diffValues(base, head, path = '') {
if (Object.is(base, head)) return []
const baseIsObject = base && typeof base === 'object'
const headIsObject = head && typeof head === 'object'
const bothPlainObjects = baseIsObject && headIsObject && !Array.isArray(base) && !Array.isArray(head)
if (bothPlainObjects) {
const keys = [...new Set([...Object.keys(base), ...Object.keys(head)])].sort()
return keys.flatMap(key => diffValues(
base[key],
head[key],
`${path}/${jsonPointerToken(key)}`,
))
}
if (Array.isArray(base) && Array.isArray(head)) {
if (JSON.stringify(base) === JSON.stringify(head)) return []
return [{ path: path || '/', base, head }]
}
return [{ path: path || '/', base: base ?? null, head: head ?? null }]
}
function compareSnapshots(baseSnapshot, headSnapshot) {
return {
schemaVersion: SCHEMA_VERSION,
baseRevision: baseSnapshot.resolvedRevision,
headRevision: headSnapshot.resolvedRevision,
differences: diffValues(comparable(baseSnapshot), comparable(headSnapshot)),
base: baseSnapshot,
head: headSnapshot,
}
}
function writeFixture(root, version, exportTarget, wireRevision) {
const files = {
'package.json': JSON.stringify({
name: 'fixture',
version,
packageManager: 'pnpm@11.0.0',
exports: { '.': { import: exportTarget, types: './lib/index.d.ts' } },
bin: { fixture: './bin.js' },
peerDependencies: { '@deepseek-ai/example': '^1.0.0' },
devDependencies: { '@deepseek-ai/example': '^1.0.0' },
scripts: { build: 'echo build' },
}, null, 2),
'AGENTS.md': '# fixture\n',
'ADAPTER.md': '# adapter\n',
'docs/contributing.md': '# contributing\n',
'src/dsh-adapter/contract.ts': `export const VERSION = '${version}'\n`,
'src/plugin-host.ts': "export { alpha, beta } from './impl.js'\nexport type { Gamma } from './types.js'\n",
'cordis.patch.yml': 'version: 1\n',
'patch-surface.snapshot.json': '{"version":1}\n',
'tui-profile/protocols/tui-channel.js': `export const TUI_CHANNEL_API_VERSION = 'tui.dsh/v1alpha1'\nexport const TUI_CHANNEL_WIRE_REVISION = ${wireRevision}\nexport const TUI_CHANNEL_FEATURES = ['commands', 'skills']\n`,
'.github/workflows/ci.yml': 'name: ci\n',
}
for (const [path, content] of Object.entries(files)) {
const destination = join(root, path)
mkdirSync(dirname(destination), { recursive: true })
writeFileSync(destination, content)
}
}
function selfTest() {
const root = mkdtempSync(join(tmpdir(), 'contract snapshot-'))
try {
git(root, ['init', '-q'])
git(root, ['config', 'user.email', 'fixture@example.invalid'])
git(root, ['config', 'user.name', 'Fixture'])
writeFixture(root, '1.0.0', './lib/index.js', 1)
git(root, ['add', '.'])
git(root, ['commit', '-qm', 'base'])
const base = git(root, ['rev-parse', 'HEAD']).trim()
writeFixture(root, '1.1.0', './lib/index-v2.js', 2)
writeFileSync(join(root, 'src/plugin-host.ts'), "export { alpha, beta, delta } from './impl.js'\n")
git(root, ['add', '.'])
git(root, ['commit', '-qm', 'head'])
const head = git(root, ['rev-parse', 'HEAD']).trim()
const result = compareSnapshots(buildSnapshot(root, base), buildSnapshot(root, head))
const paths = result.differences.map(item => item.path)
const expected = [
'/package/version',
'/package/exports/./import',
'/protocol/wireRevision',
'/pluginHost/exportStatements',
]
for (const path of expected) {
if (!paths.includes(path)) throw new Error(`missing expected diff: ${path}`)
}
writeFixture(root, '1.2.0', './lib/index-v3.js', 3)
const worktree = buildSnapshot(root, 'WORKTREE')
if (worktree.package.version !== '1.2.0') throw new Error('WORKTREE snapshot did not read filesystem')
git(root, ['add', 'package.json'])
const index = buildSnapshot(root, 'INDEX')
if (index.package.version !== '1.2.0') throw new Error('INDEX snapshot did not read staged content')
// Submodule pointers: WORKTREE reads each submodule's own HEAD, so both a
// staged and an unstaged pointer switch are visible (ls-tree HEAD reports
// the committed gitlink for either).
const subUpstream = mkdtempSync(join(tmpdir(), 'contract submodule-'))
try {
git(subUpstream, ['init', '-q'])
git(subUpstream, ['config', 'user.email', 'fixture@example.invalid'])
git(subUpstream, ['config', 'user.name', 'Fixture'])
writeFileSync(join(subUpstream, 'file.txt'), 'one\n')
git(subUpstream, ['add', '.'])
git(subUpstream, ['commit', '-qm', 'sub base'])
const subBase = git(subUpstream, ['rev-parse', 'HEAD']).trim()
writeFileSync(join(subUpstream, 'file.txt'), 'two\n')
git(subUpstream, ['commit', '-qam', 'sub head'])
const subHead = git(subUpstream, ['rev-parse', 'HEAD']).trim()
git(root, ['clone', '-q', subUpstream, 'dsh-auth'])
git(join(root, 'dsh-auth'), ['checkout', '-q', subBase])
git(root, ['update-index', '--add', '--cacheinfo', `160000,${subBase},dsh-auth`])
git(root, ['commit', '-qm', 'submodule pointer'])
if (buildSnapshot(root, 'HEAD').submodules['dsh-auth'] !== subBase) {
throw new Error('HEAD snapshot must report the committed submodule gitlink')
}
// Unstaged switch: only the submodule's own HEAD moves.
git(join(root, 'dsh-auth'), ['checkout', '-q', subHead])
if (buildSnapshot(root, 'WORKTREE').submodules['dsh-auth'] !== subHead) {
throw new Error('WORKTREE snapshot must read the submodule HEAD, not the committed gitlink')
}
// Staged switch: the index moves as well.
git(root, ['add', 'dsh-auth'])
if (buildSnapshot(root, 'INDEX').submodules['dsh-auth'] !== subHead) {
throw new Error('INDEX snapshot must read the staged submodule gitlink')
}
} finally {
rmSync(subUpstream, { recursive: true, force: true })
}
console.log(`contract-snapshot self-test: OK (${result.differences.length} differences)`)
} finally {
rmSync(root, { recursive: true, force: true })
}
}
function parseArgs(argv) {
const args = { repo: '.', revision: 'HEAD', compare: null, selfTest: false }
for (let i = 0; i < argv.length; i += 1) {
const arg = argv[i]
if (arg === '--repo') args.repo = argv[++i]
else if (arg === '--rev') args.revision = argv[++i]
else if (arg === '--compare') args.compare = [argv[++i], argv[++i]]
else if (arg === '--self-test') args.selfTest = true
else if (arg === '--help' || arg === '-h') {
console.log(`Usage:
node contract-snapshot.mjs --repo <path> --rev <revision|WORKTREE|INDEX>
node contract-snapshot.mjs --repo <path> --compare <base> <head>
node contract-snapshot.mjs --self-test
The output is evidence for review, not an automatic compatibility verdict.`)
process.exit(0)
} else fail(`unknown argument: ${arg}`)
}
if (!args.repo) fail('--repo requires a path')
if (args.compare?.some(value => !value)) fail('--compare requires two revisions')
return args
}
function main() {
const args = parseArgs(process.argv.slice(2))
if (args.selfTest) return selfTest()
try {
const output = args.compare
? compareSnapshots(
buildSnapshot(args.repo, args.compare[0]),
buildSnapshot(args.repo, args.compare[1]),
)
: buildSnapshot(args.repo, args.revision)
console.log(JSON.stringify(output, null, 2))
} catch (error) {
fail(error.message, 1)
}
}
main()
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |