cyber-sdd 0.7.0 → 0.7.2

package/skills/check-plan-safety/scripts/check-plan-safety.mts

@@ -1,148 +0,0 @@
-#!/usr/bin/env node
-// check-plan-safety — the concrete guard engine for the plan brief's safe-to-publish floor.
-// Scans the SDD plan directory (.agents/plans) for the *.md handoff artifacts a mission commits
-// — the `<cr-ref>.plan.md` brief and its sibling design docs — and flags any machine-local
-// reference that must never enter git history in a tracked, portable artifact:
-//
-//   - a home-directory absolute path (`/home/<user>/…`, `/Users/<user>/…`, `C:\Users\<user>\…`)
-//     — carries the OS username (privacy) and resolves on no other checkout (portability), and
-//   - a shell expansion of the user's home / identity (`$HOME`, `${HOME}`, `$USER`, `%USERPROFILE%`).
-//
-// A bare `~/` is deliberately NOT flagged: it carries no username and legitimately appears in
-// design prose describing home-rooted feature paths (e.g. a tool's own `~/.<tool>/` data root).
-// The floor mirrors the combat-log's "never committed: … absolute paths, OS usernames" rule
-// (combat-log-governance), extended from the ledger to the plan brief.
-//
-// Pure functions are exported for node:test; running the file directly drives the CLI. No
-// dependencies (the repo's node-≥23.6 / no-deps convention). Read-only: it writes nothing.
-// Default output is TOON (the token-efficient tabular form); --format json for a flat array.
-// --check is the CI guard: exit non-zero iff any leak is found.
-
-import { existsSync, readdirSync, readFileSync, realpathSync } from 'node:fs'
-import { join } from 'node:path'
-import { pathToFileURL } from 'node:url'
-
-export interface Leak {
-	/** Repo-relative path of the file the leak sits in. */
-	file: string
-	/** 1-indexed line number. */
-	line: number
-	/** The leak class — `home-abs-path`, `env-home`, or `env-user`. */
-	kind: string
-	/** The matched fragment (capped), so a reader can locate and scrub it. */
-	token: string
-}
-
-// The machine-local reference patterns. Each carries the leak `kind` it detects. Global flag so a
-// single line with several leaks reports each. USER/HOME env forms use a negative lookahead so
-// `$HOMEBREW` / `$USERDATA` (a different variable that merely starts with the name) is not flagged.
-export const LEAK_PATTERNS: { kind: string; re: RegExp }[] = [
-	// /home/<user>/… and /Users/<user>/… — the home-abs path the leak class is named for.
-	// Also catches a forward-slash Windows profile (`C:/Users/…` contains `/Users/…`).
-	{ kind: 'home-abs-path', re: /\/(?:home|Users)\/[^\s'"`)\]]+/g },
-	// Backslash Windows user profile — C:\Users\<user>\… (the forward-slash form is caught above).
-	{ kind: 'home-abs-path', re: /[A-Za-z]:\\Users\\[^\s'"`)\]]+/g },
-	{ kind: 'env-home', re: /\$\{?HOME\}?(?![A-Za-z])|%USERPROFILE%|%HOMEPATH%/g },
-	{ kind: 'env-user', re: /\$\{?USER\}?(?![A-Za-z])|%USERNAME%/g },
-]
-
-/** Cap a matched token so a pathological long path does not blow up the report. */
-function capToken(t: string): string {
-	return t.length > 80 ? `${t.slice(0, 77)}...` : t
-}
-
-// ── Scan one file's text ──
-// Every machine-local reference in `text`, tagged with `file` (the repo-relative path the caller
-// supplies) and its 1-indexed line. Lines are scanned independently; a line with N leaks yields N.
-export function scanText(file: string, text: string): Leak[] {
-	const out: Leak[] = []
-	const lines = text.split('\n')
-	for (let i = 0; i < lines.length; i++) {
-		const line = lines[i].replace(/\r$/, '')
-		for (const { kind, re } of LEAK_PATTERNS) {
-			re.lastIndex = 0
-			let m = re.exec(line)
-			while (m !== null) {
-				out.push({ file, line: i + 1, kind, token: capToken(m[0]) })
-				if (m.index === re.lastIndex) re.lastIndex++ // guard against a zero-width match
-				m = re.exec(line)
-			}
-		}
-	}
-	return out
-}
-
-// ── Scan the plan directory ──
-// The handoff artifacts a mission commits: every `*.md` sitting directly under <root>/.agents/plans
-// — the `<cr-ref>.plan.md` brief plus any sibling design doc. A missing plans dir yields no leaks.
-function planFiles(root: string): string[] {
-	const dir = join(root, '.agents', 'plans')
-	if (!existsSync(dir)) return []
-	let entries: import('node:fs').Dirent[]
-	try {
-		entries = readdirSync(dir, { withFileTypes: true })
-	} catch {
-		return []
-	}
-	return entries
-		.filter((e) => e.isFile() && e.name.endsWith('.md'))
-		.map((e) => e.name)
-		.sort()
-}
-
-// Collect leaks across the plan directory (default) or a caller-named file set (`--path`). File
-// paths in the returned leaks are repo-relative when scanning the plan dir, and as-passed for
-// explicit `--path` targets. Sorted by file then line for stable output.
-export function collectLeaks(root: string, paths?: string[]): Leak[] {
-	const targets: { rel: string; abs: string }[] = paths
-		? paths.map((p) => ({ rel: p, abs: p }))
-		: planFiles(root).map((name) => ({
-				rel: join('.agents', 'plans', name),
-				abs: join(root, '.agents', 'plans', name),
-			}))
-	const out: Leak[] = []
-	for (const { rel, abs } of targets) {
-		let text: string
-		try {
-			text = readFileSync(abs, 'utf8')
-		} catch {
-			continue
-		}
-		out.push(...scanText(rel, text))
-	}
-	return out.sort((a, b) => (a.file !== b.file ? (a.file < b.file ? -1 : 1) : a.line - b.line))
-}
-
-// ── Output ──
-const COLUMNS = ['file', 'line', 'kind', 'token'] as const
-
-function toonField(v: string): string {
-	if (v === '' || /[",]/.test(v) || v !== v.trim()) return `"${v.replace(/"/g, '""')}"`
-	return v
-}
-
-export function toToon(leaks: Leak[]): string {
-	const header = `leaks[${leaks.length}]{${COLUMNS.join(',')}}:`
-	const rows = leaks.map((l) => `  ${COLUMNS.map((c) => toonField(String(l[c]))).join(',')}`)
-	return [header, ...rows].join('\n')
-}
-
-export function main(argv: string[]): number {
-	const root = argv.includes('--root') ? (argv[argv.indexOf('--root') + 1] ?? '.') : '.'
-	const format = argv.includes('--format') ? argv[argv.indexOf('--format') + 1] : 'toon'
-	const check = argv.includes('--check')
-	// `--path <file>` may repeat to scan an explicit file set (e.g. the one brief a checkpoint
-	// is about to commit) instead of the whole plan directory.
-	const paths: string[] = []
-	for (let i = 0; i < argv.length; i++) if (argv[i] === '--path' && argv[i + 1]) paths.push(argv[++i])
-
-	const leaks = collectLeaks(root, paths.length ? paths : undefined)
-	const out = format === 'json' ? JSON.stringify(leaks, null, 2) : toToon(leaks)
-	process.stdout.write(`${out}\n`)
-	// --check is the CI guard: any leak fails. Audit mode (default) always exits 0.
-	return check && leaks.length > 0 ? 1 : 0
-}
-
-if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
-	process.exit(main(process.argv.slice(2)))
-}

package/skills/check-plugin-manifests/scripts/check-plugin-manifests.bundle.mjs

@@ -1,248 +0,0 @@
-#!/usr/bin/env node
-import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync } from "node:fs";
-import { dirname, join, relative, sep } from "node:path";
-import { pathToFileURL } from "node:url";
-//#region skills/check-plugin-manifests/scripts/check-plugin-manifests.mts
-/**
-* Directories that hold a manifest one level below the plugin root.
-*
-* This is a path-shape list, not a provenance one: `.plugin/` holds the **canonical** manifest and
-* the other two hold its generated vendor copies, but all three sit one level down, so a pointer
-* inside any of them resolves against the parent. Naming it for vendors would contradict the
-* spec's own vocabulary and has already misled one reader.
-*/
-const MANIFEST_DIRS = [
-	".plugin",
-	".claude-plugin",
-	".codex-plugin"
-];
-const MANIFEST_NAME = "plugin.json";
-const SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules", ".git"]);
-/**
-* Every manifest at a conventional location under `root`, repo-relative and path-sorted.
-*
-* A manifest is a `plugin.json` either inside a vendor directory, or sitting beside a
-* `package.json` (a package-root manifest). Sorted so a sweep's report order is deterministic.
-* A symlink is included: it resolves to a real manifest, and a broken one must surface as
-* unreadable rather than vanish from the sweep.
-*/
-/** Directory entries, or none where the directory cannot be read. */
-function safeReaddir(dir) {
-	try {
-		return readdirSync(dir, { withFileTypes: true });
-	} catch {
-		return [];
-	}
-}
-function discoverManifests(root) {
-	const found = [];
-	const walk = (dir) => {
-		for (const e of safeReaddir(dir)) {
-			const full = join(dir, e.name);
-			if (e.isDirectory()) {
-				if (!SKIP_DIRS.has(e.name)) walk(full);
-				continue;
-			}
-			if (e.name !== MANIFEST_NAME) continue;
-			const parent = dirname(full);
-			if (MANIFEST_DIRS.includes(parent.split(sep).pop() ?? "") || existsSync(join(parent, "package.json"))) found.push(full);
-		}
-	};
-	walk(root);
-	return found.map((f) => relative(root, f).split(sep).join("/")).sort();
-}
-/**
-* The plugin root a manifest's pointers resolve against — NOT the manifest's own directory.
-*
-* A vendor manifest sits one level down, and its `./skills` still names the plugin's skills
-* directory. A guard resolving relative to the file it just read reports every vendor manifest as
-* entirely broken.
-*/
-function pluginRootOf(manifestRelPath) {
-	const parts = manifestRelPath.split("/");
-	const parentName = parts[parts.length - 2];
-	const drop = parentName !== void 0 && MANIFEST_DIRS.includes(parentName) ? 2 : 1;
-	return parts.slice(0, parts.length - drop).join("/");
-}
-/** Every `./`-prefixed string value in the manifest, paired with the key it sits under. */
-function extractPointers(manifest) {
-	const out = [];
-	const visit = (value, key) => {
-		if (typeof value === "string") {
-			if (value.startsWith("./")) out.push({
-				key,
-				pointer: value
-			});
-			return;
-		}
-		if (Array.isArray(value)) {
-			for (const item of value) visit(item, key);
-			return;
-		}
-		if (value !== null && typeof value === "object") for (const [k, v] of Object.entries(value)) visit(v, k);
-	};
-	visit(manifest, "");
-	return out;
-}
-/**
-* The nearest `package.json` at or above the plugin root, and whether it publishes.
-*
-* A package publishes when it is not `private` AND declares a `files` allowlist. A `private`
-* package ships no tarball, so its `files` constrains nothing. A package declaring no `files` at
-* all ships everything, so there is no allowlist to be outside of — npm's own semantic, and
-* inverting it manufactures a finding against every pointer in the package.
-*/
-function owningPackage(root, pluginRoot) {
-	let dir = pluginRoot;
-	for (;;) {
-		const candidate = dir === "" ? "package.json" : `${dir}/package.json`;
-		const abs = join(root, candidate);
-		if (existsSync(abs)) try {
-			const pkg = JSON.parse(readFileSync(abs, "utf8"));
-			const files = Array.isArray(pkg.files) ? pkg.files.filter((f) => typeof f === "string") : null;
-			const packs = pkg.private !== true;
-			return {
-				path: candidate,
-				packs,
-				publishes: packs && files !== null,
-				files: files ?? []
-			};
-		} catch {
-			return {
-				path: candidate,
-				packs: false,
-				publishes: false,
-				files: []
-			};
-		}
-		if (dir === "") return null;
-		dir = dir.split("/").slice(0, -1).join("/");
-	}
-}
-/**
-* Whether a `files` allowlist covers a pointer, compared on the leading path segment.
-*
-* Both sides are normalized past a leading `./`, because an allowlist may legitimately spell an
-* entry either way and a pointer always carries the prefix — comparing them raw reports a shipped
-* component as unpublished.
-*
-* A `!`-prefixed entry is an exclusion and needs no special case: its leading `!` is part of its
-* first segment, so it can never equal a real segment and is never read as an inclusion.
-*/
-function filesCovers(files, pointer) {
-	const head = (path) => path.replace(/^\.\//, "").split("/")[0];
-	const segment = head(pointer);
-	if (segment === void 0 || segment === "") return true;
-	return files.some((entry) => {
-		const h = head(entry);
-		return h === "*" || h === "**" || h === segment;
-	});
-}
-/** Whether a package that packs a tarball ships the package-relative path `./<rel>`. */
-function ships(pkg, rel) {
-	return pkg?.packs === true && (!pkg.publishes || filesCovers(pkg.files, `./${rel}`));
-}
-/** Every symbolic link at or below `abs` — the path itself included, links never followed. */
-function findSymlinks(abs) {
-	let stat;
-	try {
-		stat = lstatSync(abs);
-	} catch {
-		return [];
-	}
-	if (stat.isSymbolicLink()) return [abs];
-	if (!stat.isDirectory()) return [];
-	return safeReaddir(abs).filter((e) => !SKIP_DIRS.has(e.name)).flatMap((e) => findSymlinks(join(abs, e.name)));
-}
-function sweep(root, manifests) {
-	const findings = [];
-	const linksSeen = /* @__PURE__ */ new Set();
-	const reportLinks = (rel, abs, key, pointer) => {
-		for (const link of findSymlinks(abs)) {
-			const linkRel = relative(root, link).split(sep).join("/");
-			if (linksSeen.has(linkRel)) continue;
-			linksSeen.add(linkRel);
-			findings.push({
-				kind: "symlink",
-				manifest: rel,
-				...key === void 0 ? {} : {
-					key,
-					pointer
-				},
-				detail: `${linkRel} is a symbolic link — the registry rejects a package that ships one`
-			});
-		}
-	};
-	for (const rel of manifests) {
-		let parsed;
-		try {
-			parsed = JSON.parse(readFileSync(join(root, rel), "utf8"));
-		} catch {
-			findings.push({
-				kind: "unreadable",
-				manifest: rel,
-				detail: "not readable as JSON"
-			});
-			continue;
-		}
-		const pluginRoot = pluginRootOf(rel);
-		const pkg = owningPackage(root, pluginRoot);
-		const pkgDir = pkg ? dirname(pkg.path) : "";
-		const fromPkg = (path) => relative(join(root, pkgDir), join(root, path)).split(sep).join("/");
-		if (ships(pkg, fromPkg(rel))) reportLinks(rel, join(root, rel));
-		for (const { key, pointer } of extractPointers(parsed)) {
-			const target = join(root, pluginRoot, pointer);
-			if (!existsSync(target)) {
-				findings.push({
-					kind: "unresolved",
-					manifest: rel,
-					key,
-					pointer,
-					detail: "names no path on disk"
-				});
-				continue;
-			}
-			if (pkg?.publishes && !filesCovers(pkg.files, pointer)) {
-				findings.push({
-					kind: "unpublished",
-					manifest: rel,
-					key,
-					pointer,
-					detail: `declared but not published — ${pkg.path} files omits it`
-				});
-				continue;
-			}
-			if (ships(pkg, fromPkg(join(pluginRoot, pointer)))) reportLinks(rel, target, key, pointer);
-		}
-	}
-	return findings;
-}
-function formatReport(manifests, findings) {
-	if (manifests.length === 0) return "check-plugin-manifests: no plugin manifest found\n";
-	if (findings.length === 0) return `check-plugin-manifests: ${manifests.length} manifest(s) OK\n`;
-	return `${findings.map((f) => `  ${f.kind.padEnd(11)} ${f.manifest}${f.key ? ` [${f.key}] ${f.pointer}` : ""} — ${f.detail}`).join("\n")}\ncheck-plugin-manifests: ${findings.length} finding(s) across ${manifests.length} manifest(s)\n`;
-}
-function main(argv) {
-	let root = ".";
-	for (let i = 0; i < argv.length; i++) {
-		const a = argv[i];
-		if (a === "--root") {
-			const next = argv[++i];
-			if (next === void 0) {
-				process.stderr.write("check-plugin-manifests: --root needs a directory\n");
-				return 1;
-			}
-			root = next;
-			continue;
-		}
-		process.stderr.write(`check-plugin-manifests: unrecognized flag ${a}\n`);
-		return 1;
-	}
-	const manifests = discoverManifests(root);
-	const findings = sweep(root, manifests);
-	process.stdout.write(formatReport(manifests, findings));
-	return findings.length === 0 ? 0 : 1;
-}
-if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) process.exit(main(process.argv.slice(2)));
-//#endregion
-export { discoverManifests, extractPointers, filesCovers, findSymlinks, formatReport, main, owningPackage, pluginRootOf, sweep };