DataArt/artisyn-implementation-harness / skills/implementation-harness
implementation-harness
FlaggedInstall the portable AI-dev harness, rebuild its operational graph standalone, harvest project skill improvements into its canonical templates, package direct canonical edits into a portable bundle, or apply canonical updates to an existing project. Use /implementation-harness launch, /implementation-harness reindex-graph, or /implementation-harness patch harvest|prepare|apply.
canonical/docs/.og/utils.mjs
View on GitHub// Generic helpers for the operational-graph tool. No dependency on cli.mjs,
// constants.mjs, or edges.mjs — matches utils.mjs's role in the timing.mjs convention.
import fs from 'node:fs';
import path from 'node:path';
import { createHash, randomBytes } from 'node:crypto';
/** Throw `message` if `condition` is falsy; otherwise return `condition`. */
export function need(condition, message) {
if (!condition) throw new Error(message);
return condition;
}
/** Write `content` to `file` via a same-directory temp file + rename (atomic on POSIX). */
export function atomicWrite(file, content) {
const tmp = path.join(
path.dirname(file),
`.${path.basename(file)}.${randomBytes(4).toString('hex')}.tmp`
);
fs.writeFileSync(tmp, content);
fs.renameSync(tmp, file);
}
/** @returns {string} An 8-hex-char hash of `seed`, stable across runs. */
export function shortHash(seed) {
return createHash('sha1').update(seed).digest('hex').slice(0, 8);
}
/**
* @returns {string} A short hash of `seed`, suffixed only on collision against `used`.
* Deterministic for a given seed/used-set pair, never reassigns an existing ID.
*/
export function collisionSafeId(seed, used) {
const base = shortHash(seed);
if (!used.has(base)) return base;
let n = 2;
while (used.has(`${base}-${n}`)) n += 1;
return `${base}-${n}`;
}
const FRONTMATTER = /^---\n([\s\S]*?)\n---\n?/;
/** @returns {{data: Record<string,string>, body: string, raw: string|null}} Parsed frontmatter. */
export function readFrontmatter(content) {
const match = content.match(FRONTMATTER);
if (!match) return { data: {}, body: content, raw: null };
const data = {};
for (const line of match[1].split('\n')) {
const i = line.indexOf(':');
if (i === -1) continue;
data[line.slice(0, i).trim()] = line
.slice(i + 1)
.trim()
.replace(/^["']|["']$/g, '');
}
return { data, body: content.slice(match[0].length), raw: match[1] };
}
/**
* Insert `id` as a frontmatter key, additive-only: never touches an existing
* key, never reassigns an existing id. A no-op (returns false) when `id` is
* already present.
* @returns {boolean} Whether the file was actually written.
*/
export function writeAdditiveId(file, id) {
const content = fs.readFileSync(file, 'utf8');
const { data, raw } = readFrontmatter(content);
if (data.id) return false;
const next =
raw === null
? `---\nid: ${id}\n---\n\n${content}`
: content.replace(FRONTMATTER, `---\nid: ${id}\n${raw}\n---\n`);
atomicWrite(file, next);
return true;
}
/** @returns {string|null} The text of the doc's first `# ` heading, or null if absent. */
export function firstHeading(body) {
const match = body.match(/^#\s+(.+)$/m);
return match ? match[1].trim() : null;
}
/**
* Read `<docsRoot>/.ogignore`: one project-relative path prefix per line
* (`docs/vendor/`, `docs/agents/issue-tracker.md`), `#` comments allowed.
* Docs matching a prefix are never indexed and never receive a frontmatter `id`,
* for files under `docs/` that another tool owns. Empty when the file is absent.
* @returns {string[]} POSIX prefixes relative to the project root
*/
export function readIgnoreList(docsRoot) {
const file = path.join(docsRoot, '.ogignore');
if (!fs.existsSync(file)) return [];
return fs
.readFileSync(file, 'utf8')
.split(/\r?\n/)
.map((line) => line.trim())
.filter((line) => line && !line.startsWith('#'))
.map((line) => line.replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/+$/, ''));
}
/** Recursively list every `.md` file under `root` (the `docs/` folder), skipping
* `docs/.og/` and any path in `ignore` (project-relative POSIX prefixes, see
* `readIgnoreList`). Empty if `root` is absent. */
export function listMarkdownFiles(root, ignore = []) {
if (!fs.existsSync(root)) return [];
const project = path.dirname(root);
const ignored = (full) => {
const rel = path.relative(project, full).split(path.sep).join('/');
return ignore.some((prefix) => rel === prefix || rel.startsWith(prefix + '/'));
};
const out = [];
const walk = (dir) => {
for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
const full = path.join(dir, entry.name);
if (ignored(full)) continue;
if (entry.isDirectory()) {
if (path.relative(root, full) === '.og') continue;
walk(full);
} else if (entry.isFile() && entry.name.endsWith('.md')) out.push(full);
}
};
walk(root);
return out;
}
/** @returns {string} `file`'s path relative to `dir`, POSIX-separated. */
export function toPosixRelative(dir, file) {
return path.relative(dir, file).split(path.sep).join('/');
}
/**
* Parse a frontmatter `keywords:` value into normalized tokens — accepts
* either YAML flow-sequence style (`[a, b]`) or a bare comma list (`a, b`),
* since `readFrontmatter()` stores the raw string as written, unparsed.
* @param {string|null} raw
* @returns {string[]} Lowercased, trimmed, deduplicated; empty if `raw` is null/empty.
*/
export function parseKeywords(raw) {
if (!raw) return [];
const stripped = raw.trim().replace(/^\[/, '').replace(/\]$/, '');
return [
...new Set(
stripped
.split(',')
.map((word) => word.trim().toLowerCase())
.filter(Boolean)
),
];
}
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 470k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |