coder-xieshijie/dev-skills / skills/repo-readiness/assets/verify-skill
verify-<app>
FlaggedStarts isolated <app> instances, drives them through <entry points> and reports one result per sub-feature and entry with evidence. Use when verifying a change, reproducing a bug, or running, writing or checking feature maps and their scenario scripts.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.7 KB |
| features/README.md | markdown | 1.4 KB |
| references/maps.md | markdown | 11.4 KB |
| scripts/config.mjs | script | 5.2 KB |
| scripts/contract.mjs | script | 16.6 KB |
| scripts/map-check.mjs | script | 22.2 KB |
| scripts/primitives.mjs | script | 7.2 KB |
| scripts/runner.mjs | script | 24.0 KB |
| scripts/test/contract-check.test.mjs | script | 3.7 KB |
| scripts/test/contract.test.mjs | script | 1.4 KB |
| scripts/test/fixture/notes-entry.mjs | script | 3.5 KB |
| scripts/test/fixture/proc-app.mjs | script | 1.3 KB |
| scripts/test/fixture/proc-entry.mjs | script | 5.5 KB |
| scripts/test/fixture/web-entry.mjs | script | 535 B |
| scripts/test/helpers.mjs | script | 5.0 KB |
| scripts/test/map-check.test.mjs | script | 9.5 KB |
| scripts/test/primitives.test.mjs | script | 4.1 KB |
| scripts/test/runner.test.mjs | script | 17.3 KB |
| scripts/verify.mjs | script | 9.7 KB |
| verify.config.json | config | 1016 B |
scripts/verify.mjs
View on GitHub#!/usr/bin/env node
// The verification CLI. Every command prints one JSON object on stdout; `ok: false` exits non-zero.
// check structural check of the feature maps (CI runs it)
// contract [--entry <e>] run an entry's adapter (default: every entry) against the
// adapter contract; test/contract.test.mjs runs the same
// run [target...] [--entry <e>] [--jobs N] [--evidence-dir D] [--launch '<json>'] [--detach]
// wait <evidence dir> [--timeout S] blocks until a detached run ends, prints its summary
// look <evidence dir> <criterion id> pass|fail --why "<what the capture shows>"
// record <evidence dir> <criterion id> pass|fail|confirm --why "<what was observed>" [--file <capture>]
// a criterion judged by hand, into that directory's summary;
// a --file from elsewhere is copied into it
// up --entry <e> [--launch '<json>'] start an instance by hand (for entries driven by hand)
// doctor [--run <id>] is this instance worth driving?
// do <tool> [--run <id>] ['<json args>'] call one of the entry adapter's tools on the instance;
// {field} in a string argument is that field of the instance
// down [--run <id>] [--keep-data] stop what this run started; keeps the evidence
// list instances started by hand on this machine, by every session:
// pass --run <runId> from your own up to doctor, do and down
// --skill-dir <dir> any command: the verification Skill to use (default: above this script)
// --help this list, and `kit`: the hash of the kit's own scripts as copied
import { mkdirSync, readFileSync, readdirSync, realpathSync, writeFileSync } from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { entryByName, kitFilesHash, loadConfig } from './config.mjs';
import { checkContract } from './contract.mjs';
import { checkMaps } from './map-check.mjs';
import { defaultEvidenceDir, detach, loadAdapter, recordHand, recordLook, runScenarios, waitRun } from './runner.mjs';
const HELP = readFileSync(fileURLToPath(import.meta.url), 'utf8')
.split('\n')
.filter((line) => line.startsWith('// '))
.map((line) => line.slice(5));
function parse(argv) {
const positional = [];
const flags = {};
for (let i = 0; i < argv.length; i += 1) {
const arg = argv[i];
if (!arg.startsWith('--')) positional.push(arg);
else if (['--detach', '--keep-data', '--help'].includes(arg)) flags[arg.slice(2)] = true;
else flags[arg.slice(2)] = argv[(i += 1)];
}
return { positional, flags };
}
const json = (value) => (value === undefined ? undefined : JSON.parse(value));
// {field} in strings (deeply) becomes that field of the instance when it is a string or a number.
function expandFields(value, instance) {
if (typeof value === 'string')
return value.replace(/\{([A-Za-z0-9_]+)\}/g, (whole, name) =>
['string', 'number'].includes(typeof instance[name]) ? String(instance[name]) : whole,
);
if (Array.isArray(value)) return value.map((item) => expandFields(item, instance));
if (value && typeof value === 'object')
return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, expandFields(item, instance)]));
return value;
}
// What `up` prints: the instance without its environment (that stays in the record file).
const shown = ({ env, ...instance }) => instance;
function runsRootOf(config) {
const root = config.runsRoot
? path.resolve(config.root, config.runsRoot)
: path.join(os.tmpdir(), `verify-${path.basename(config.root)}`);
mkdirSync(path.join(root, 'instances'), { recursive: true });
return path.join(root, 'instances');
}
function records(config) {
const dir = runsRootOf(config);
return readdirSync(dir)
.filter((file) => file.endsWith('.json'))
.map((file) => JSON.parse(readFileSync(path.join(dir, file), 'utf8')))
.sort((a, b) => a.startedAt.localeCompare(b.startedAt));
}
function target(config, runId) {
const all = records(config);
if (runId) {
const found = all.find((record) => record.runId === runId);
if (!found) throw new Error(`no instance ${runId}; run list`);
return found;
}
const live = all.filter((record) => !record.stoppedAt);
if (live.length === 0) throw new Error('no live instance; run up --entry <entry>');
if (live.length > 1) throw new Error(`${live.length} live instances: pass --run <runId> (see list)`);
return live[0];
}
const save = (config, record) =>
writeFileSync(path.join(runsRootOf(config), `${record.runId}.json`), `${JSON.stringify(record, null, 2)}\n`);
async function main() {
const [command, ...rest] = process.argv.slice(2);
const { positional, flags } = parse(rest);
if (!command || ['--help', '-h', 'help'].includes(command) || flags.help) return { ok: true, usage: HELP, kit: kitFilesHash() };
const config = loadConfig({ skillDir: flags['skill-dir'] ? path.resolve(flags['skill-dir']) : undefined });
if (command === 'check') return checkMaps(config);
if (command === 'contract') {
const entries = flags.entry ? [entryByName(config, flags.entry)] : config.entryList;
if (entries.includes(undefined)) throw new Error(`no entry ${flags.entry} in verify.config.json`);
const results = [];
for (const entry of entries) results.push(await checkContract({ config, slug: entry.slug }));
return { ok: results.every((item) => item.ok), entries: results };
}
if (command === 'run') {
const evidenceDir = path.resolve(flags['evidence-dir'] ?? defaultEvidenceDir(config));
if (flags.detach) {
const args = process.argv.slice(2).filter((arg) => arg !== '--detach');
if (!flags['evidence-dir']) args.push('--evidence-dir', evidenceDir);
return detach({ cliPath: fileURLToPath(import.meta.url), args, evidenceDir });
}
const entry = flags.entry && entryByName(config, flags.entry);
if (flags.entry && !entry) throw new Error(`no entry ${flags.entry} in verify.config.json`);
return runScenarios({
config,
targets: positional,
entry: entry?.name,
jobs: flags.jobs ? Number(flags.jobs) : undefined,
evidenceDir,
launchOverride: json(flags.launch),
});
}
if (command === 'wait') return waitRun(path.resolve(positional[0]), Number(flags.timeout ?? 1800));
if (command === 'look') {
const [dir, id, verdict] = positional;
return recordLook({ evidenceDir: path.resolve(dir), id, verdict, why: flags.why });
}
if (command === 'record') {
const [dir, id, verdict] = positional;
if (!dir) throw new Error('record <evidence dir> <criterion id> pass|fail|confirm --why "..."');
mkdirSync(path.resolve(dir), { recursive: true });
return recordHand({ config, evidenceDir: realpathSync(path.resolve(dir)), id, verdict, why: flags.why, file: flags.file });
}
if (command === 'up') {
const entry = entryByName(config, flags.entry ?? '');
if (!entry) throw new Error(`--entry is one of ${config.entryList.map((e) => e.slug).join(', ')}`);
const { adapter, options } = await loadAdapter(config, entry.slug);
const runId = `${entry.slug}-${Date.now().toString(36)}`;
let runDir = path.join(path.dirname(runsRootOf(config)), 'manual', runId);
mkdirSync(runDir, { recursive: true });
runDir = realpathSync(runDir);
const ctx = { runId, runDir, launch: json(flags.launch) ?? {}, options, root: config.root, log: () => {} };
const instance = await adapter.up(ctx);
const record = { runId, entry: entry.slug, runDir, launch: ctx.launch, instance, startedAt: new Date().toISOString() };
save(config, record);
return { ok: true, runId, runDir, instance: shown(instance) };
}
if (['doctor', 'do', 'down'].includes(command)) {
const record = target(config, flags.run);
const { adapter, options } = await loadAdapter(config, record.entry);
const ctx = { runId: record.runId, runDir: record.runDir, launch: record.launch, options, root: config.root, log: () => {} };
if (command === 'doctor') return { runId: record.runId, ...(await adapter.doctor(record.instance, ctx)) };
if (command === 'down') {
if (record.stoppedAt) return { ok: true, runId: record.runId, already: 'stopped', kept: record.kept ?? [] };
const down = await adapter.down(record.instance, { ...ctx, keepData: flags['keep-data'] });
// Stopped only when down says so: a down that left processes stays live, and the next down tries again.
Object.assign(record, down.ok ? { stoppedAt: new Date().toISOString(), kept: down.kept ?? [] } : { lastDown: down });
save(config, record);
return { runId: record.runId, ...down };
}
const [tool, args] = positional;
const { observationWindow, strictReader } = await import('./primitives.mjs');
const window = observationWindow();
const tools = adapter.tools(record.instance, { ...ctx, window, read: strictReader({ window, sideEffect: adapter.sideEffect }) });
if (typeof tools[tool] !== 'function') throw new Error(`tools: ${Object.keys(tools).join(', ')}`);
return { ok: true, runId: record.runId, value: await tools[tool](...expandFields(json(args) ?? [], record.instance)) };
}
if (command === 'list') return { ok: true, instances: records(config) };
throw new Error(`unknown command ${command}; --help lists them`);
}
main()
.then((result) => {
process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
if (result?.ok === false) process.exitCode = 1;
})
.catch((error) => {
process.stdout.write(`${JSON.stringify({ ok: false, error: error.message })}\n`);
process.exitCode = 1;
});
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |