@abraca/plugin-cli 2.3.0

package/src/commands/pack.ts

@@ -0,0 +1,121 @@
+/**
+ * `abra-plugin pack [path]` — recompute the manifest's `integrity` field
+ * (SHA-256 of the entry bundle) and write the updated manifest back to disk.
+ *
+ * Authors run this after every bundle rebuild — the registry server refuses
+ * to accept a manifest whose `integrity` doesn't match the artifact, so
+ * having it as a one-shot CLI step removes a class of "I forgot to update
+ * the hash" submission rejections.
+ *
+ * The command also validates the manifest after recomputing, exiting
+ * non-zero if validation still fails (e.g. unknown capability declared).
+ */
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { validatePluginManifest } from "@abraca/schema";
+import { ansi, isFile, readJsonFile, resolveCwd, sha256OfFile } from "../io.ts";
+
+export interface PackOptions {
+	/** Path to the manifest file. Defaults to `./manifest.json`. */
+	path?: string;
+	/** If true, don't write the file — just print the new hash. */
+	dryRun?: boolean;
+}
+
+export interface PackResult {
+	exitCode: 0 | 1 | 2;
+	/** The newly-computed integrity hash, or `null` on early failure. */
+	integrity: string | null;
+	/** Whether the on-disk manifest was rewritten. */
+	rewrote: boolean;
+}
+
+export function pack(opts: PackOptions = {}): PackResult {
+	const rel = opts.path ?? "manifest.json";
+	const abs = resolveCwd(rel);
+
+	if (!isFile(abs)) {
+		console.error(ansi.red(`error: ${rel}: file not found`));
+		return { exitCode: 2, integrity: null, rewrote: false };
+	}
+
+	let parsed: Record<string, unknown>;
+	try {
+		const value = readJsonFile(abs);
+		if (typeof value !== "object" || value === null || Array.isArray(value)) {
+			throw new Error("manifest must be a JSON object");
+		}
+		parsed = value as Record<string, unknown>;
+	} catch (err) {
+		console.error(ansi.red(`error: ${(err as Error).message}`));
+		return { exitCode: 2, integrity: null, rewrote: false };
+	}
+
+	const entry = parsed.entry;
+	if (typeof entry !== "string" || entry.length === 0) {
+		console.error(
+			ansi.red("error: manifest is missing an 'entry' field (path to bundle)"),
+		);
+		return { exitCode: 2, integrity: null, rewrote: false };
+	}
+
+	const entryAbs = join(dirname(abs), entry);
+	if (!isFile(entryAbs)) {
+		console.error(
+			ansi.red(`error: entry bundle not found: ${relative(process.cwd(), entryAbs)}`),
+		);
+		return { exitCode: 2, integrity: null, rewrote: false };
+	}
+
+	const integrity = sha256OfFile(entryAbs);
+	const prev = parsed.integrity;
+	parsed.integrity = integrity;
+
+	const newJson = `${JSON.stringify(parsed, null, 2)}\n`;
+	const oldJson = readFileSync(abs, "utf8");
+
+	if (opts.dryRun) {
+		console.log(`${ansi.cyan("dry-run")}: would write integrity=${integrity}`);
+		// Still run validation against the in-memory manifest so the author
+		// sees issues even without writing.
+		const v = validatePluginManifest(parsed);
+		if (!v.ok) {
+			console.error(ansi.red(`✗ post-pack validation failed`));
+			for (const issue of v.errors) {
+				const where = issue.path.length > 0 ? issue.path.map(String).join(".") : "<root>";
+				console.error(`  ${ansi.yellow(where)}: ${issue.message}`);
+			}
+			return { exitCode: 1, integrity, rewrote: false };
+		}
+		return { exitCode: 0, integrity, rewrote: false };
+	}
+
+	const wrote = newJson !== oldJson;
+	if (wrote) {
+		writeFileSync(abs, newJson, "utf8");
+	}
+
+	const action = wrote
+		? prev === integrity
+			? "reformatted"
+			: `updated (${ansi.dim(String(prev ?? "<unset>"))} → ${integrity})`
+		: "unchanged";
+	console.log(`${ansi.green("✓")} ${rel}: ${action}`);
+
+	// Final validation pass — pack succeeds even if the rewrite was clean
+	// only when the manifest as a whole still validates.
+	const v = validatePluginManifest(parsed);
+	if (!v.ok) {
+		console.error(
+			ansi.red(`✗ but manifest fails validation — fix and re-run`),
+		);
+		for (const issue of v.errors) {
+			const where = issue.path.length > 0 ? issue.path.map(String).join(".") : "<root>";
+			console.error(`  ${ansi.yellow(where)}: ${issue.message}`);
+		}
+		return { exitCode: 1, integrity, rewrote: wrote };
+	}
+
+	return { exitCode: 0, integrity, rewrote: wrote };
+}

package/src/commands/preview-scan.ts

@@ -0,0 +1,176 @@
+/**
+ * `abra-plugin preview-scan [path]` — validate the manifest, then run a
+ * quick static check on the bundle:
+ *
+ *   - **capability/code mismatch**: if the bundle uses `fetch` / `XHR` /
+ *     `WebSocket` but the manifest doesn't declare `network[:*]`, flag it.
+ *     Symmetric: if `network:*` is declared but the bundle has no network
+ *     calls, warn (declared-but-unused).
+ *   - **declared `contributes` sanity**: every name in `manifest.contributes`
+ *     should appear somewhere in the bundle string. Cheap heuristic — a
+ *     proper AST walk lives on the registry server in Phase H.
+ *
+ * Designed to mirror what the registry's automated scanner does on
+ * submission, so authors catch issues locally.
+ *
+ * Exit code 0 = clean, 1 = warnings only, 2 = errors. Authors should
+ * resolve all errors before submitting; warnings are advisory.
+ */
+
+import { readFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { validatePluginManifest } from "@abraca/schema";
+import type { PluginManifest } from "@abraca/plugin";
+import { ansi, isFile, readJsonFile, resolveCwd } from "../io.ts";
+
+export interface PreviewScanOptions {
+	path?: string;
+}
+
+export interface PreviewScanFinding {
+	severity: "error" | "warning";
+	rule: string;
+	message: string;
+}
+
+export interface PreviewScanResult {
+	exitCode: 0 | 1 | 2;
+	findings: ReadonlyArray<PreviewScanFinding>;
+}
+
+const NETWORK_API_RE = /\b(fetch|XMLHttpRequest|WebSocket|EventSource)\b/;
+const CLIPBOARD_READ_RE = /navigator\.clipboard\.read(?!Text)?Text?\b/;
+const CLIPBOARD_WRITE_RE = /navigator\.clipboard\.write/;
+
+function declaresCap(
+	manifest: PluginManifest,
+	predicate: (cap: string) => boolean,
+): boolean {
+	const all = [
+		...(manifest.capabilities.required ?? []),
+		...(manifest.capabilities.optional ?? []),
+	];
+	return all.some(predicate);
+}
+
+export function previewScan(opts: PreviewScanOptions = {}): PreviewScanResult {
+	const rel = opts.path ?? "manifest.json";
+	const abs = resolveCwd(rel);
+	const findings: PreviewScanFinding[] = [];
+
+	if (!isFile(abs)) {
+		console.error(ansi.red(`error: ${rel}: file not found`));
+		return { exitCode: 2, findings };
+	}
+
+	let parsed: unknown;
+	try {
+		parsed = readJsonFile(abs);
+	} catch (err) {
+		console.error(ansi.red(`error: ${(err as Error).message}`));
+		return { exitCode: 2, findings };
+	}
+
+	const result = validatePluginManifest(parsed);
+	if (!result.ok) {
+		console.error(ansi.red(`✗ manifest validation failed`));
+		for (const issue of result.errors) {
+			const where = issue.path.length > 0 ? issue.path.map(String).join(".") : "<root>";
+			console.error(`  ${ansi.yellow(where)}: ${issue.message}`);
+		}
+		return { exitCode: 2, findings };
+	}
+
+	const manifest = result.value;
+	const entryAbs = join(dirname(abs), manifest.entry);
+
+	if (!isFile(entryAbs)) {
+		findings.push({
+			severity: "error",
+			rule: "missing-entry",
+			message: `entry bundle not found: ${relative(process.cwd(), entryAbs)}`,
+		});
+		printAndExit(findings);
+		return { exitCode: 2, findings };
+	}
+
+	const source = readFileSync(entryAbs, "utf8");
+
+	// Capability/code mismatch checks
+	const hasNetCalls = NETWORK_API_RE.test(source);
+	const hasNetCap = declaresCap(manifest, (c) => c === "network" || c.startsWith("network:"));
+	if (hasNetCalls && !hasNetCap) {
+		findings.push({
+			severity: "error",
+			rule: "undeclared-network",
+			message:
+				"bundle uses fetch/XHR/WebSocket but no network[:*] capability is declared — add it to capabilities.required or capabilities.optional",
+		});
+	}
+	if (hasNetCap && !hasNetCalls) {
+		findings.push({
+			severity: "warning",
+			rule: "unused-network",
+			message:
+				"network[:*] capability is declared but no fetch/XHR/WebSocket usage was found — remove the capability if unused",
+		});
+	}
+
+	const hasClipRead = CLIPBOARD_READ_RE.test(source);
+	const hasClipReadCap = declaresCap(manifest, (c) => c === "clipboard:read");
+	if (hasClipRead && !hasClipReadCap) {
+		findings.push({
+			severity: "error",
+			rule: "undeclared-clipboard-read",
+			message: "bundle reads the clipboard but clipboard:read is not declared",
+		});
+	}
+
+	const hasClipWrite = CLIPBOARD_WRITE_RE.test(source);
+	const hasClipWriteCap = declaresCap(manifest, (c) => c === "clipboard:write");
+	if (hasClipWrite && !hasClipWriteCap) {
+		findings.push({
+			severity: "error",
+			rule: "undeclared-clipboard-write",
+			message: "bundle writes the clipboard but clipboard:write is not declared",
+		});
+	}
+
+	// Declared `contributes` sanity — every name should appear in the bundle.
+	for (const [field, names] of Object.entries(manifest.contributes ?? {})) {
+		const list = (names ?? []) as readonly string[];
+		for (const name of list) {
+			if (name.length < 3) continue; // skip short noise
+			if (!source.includes(name)) {
+				findings.push({
+					severity: "warning",
+					rule: "contributes-not-in-bundle",
+					message: `'${name}' declared in contributes.${field} but not referenced in entry bundle — possible drift`,
+				});
+			}
+		}
+	}
+
+	printAndExit(findings);
+	return { exitCode: severityExitCode(findings), findings };
+}
+
+function severityExitCode(
+	findings: ReadonlyArray<PreviewScanFinding>,
+): 0 | 1 | 2 {
+	if (findings.some((f) => f.severity === "error")) return 2;
+	if (findings.length > 0) return 1;
+	return 0;
+}
+
+function printAndExit(findings: ReadonlyArray<PreviewScanFinding>): void {
+	if (findings.length === 0) {
+		console.log(`${ansi.green("✓")} clean — manifest + bundle pass preview scan`);
+		return;
+	}
+	for (const f of findings) {
+		const badge =
+			f.severity === "error" ? ansi.red("error") : ansi.yellow("warning");
+		console.error(`${badge} ${ansi.dim(`[${f.rule}]`)} ${f.message}`);
+	}
+}

package/src/commands/validate.ts

@@ -0,0 +1,73 @@
+/**
+ * `abra-plugin validate [path]` — load a manifest.json and validate it
+ * against `@abraca/schema`'s `PluginManifestSchema`. Pretty-prints every
+ * issue with its JSON path; exit code 0 on success, 1 on validation
+ * failure, 2 on read/parse error.
+ *
+ * Defaults `path` to `./manifest.json` when omitted.
+ *
+ * This is the same validator the registry server runs on submission, so a
+ * green local check is a strong signal the submission will pass static
+ * checks too.
+ */
+
+import { validatePluginManifest } from "@abraca/schema";
+import { ansi, isFile, readJsonFile, resolveCwd } from "../io.ts";
+
+export interface ValidateOptions {
+	/** Path to the manifest file. Defaults to `./manifest.json`. */
+	path?: string;
+	/** If true, suppress the success summary line. Errors are still printed. */
+	quiet?: boolean;
+}
+
+export interface ValidateResult {
+	exitCode: 0 | 1 | 2;
+	/** Issues found by the schema. Empty on success. */
+	issues: ReadonlyArray<{ path: string; message: string; code?: string }>;
+}
+
+export function validate(opts: ValidateOptions = {}): ValidateResult {
+	const rel = opts.path ?? "manifest.json";
+	const abs = resolveCwd(rel);
+
+	if (!isFile(abs)) {
+		console.error(ansi.red(`error: ${rel}: file not found`));
+		return { exitCode: 2, issues: [] };
+	}
+
+	let parsed: unknown;
+	try {
+		parsed = readJsonFile(abs);
+	} catch (err) {
+		console.error(ansi.red(`error: ${(err as Error).message}`));
+		return { exitCode: 2, issues: [] };
+	}
+
+	const result = validatePluginManifest(parsed);
+	if (result.ok) {
+		if (!opts.quiet) {
+			console.log(
+				`${ansi.green("✓")} ${rel} ${ansi.dim(`(id=${result.value.id} v${result.value.version})`)}`,
+			);
+		}
+		return { exitCode: 0, issues: [] };
+	}
+
+	const issues = result.errors.map((e) => ({
+		path: e.path.map((p) => String(p)).join("."),
+		message: e.message,
+		code: e.code,
+	}));
+
+	console.error(
+		ansi.red(`✗ ${rel}: ${issues.length} issue${issues.length === 1 ? "" : "s"}`),
+	);
+	for (const issue of issues) {
+		const where = issue.path.length > 0 ? issue.path : "<root>";
+		console.error(
+			`  ${ansi.yellow(where)}: ${issue.message}${issue.code ? ansi.dim(` [${issue.code}]`) : ""}`,
+		);
+	}
+	return { exitCode: 1, issues };
+}

package/src/index.ts

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+/**
+ * `abra-plugin` — CLI for Abracadabra plugin authors.
+ *
+ *   abra-plugin validate     [path/to/manifest.json]
+ *   abra-plugin pack         [path/to/manifest.json] [--dry-run]
+ *   abra-plugin preview-scan [path/to/manifest.json]
+ *
+ * Each command defaults the path to `./manifest.json`. Exit codes:
+ *   0  success
+ *   1  warnings (preview-scan) or manifest-still-fails-validation (pack)
+ *   2  read/parse error or hard validation failure
+ *
+ * No external dependencies — pulls only `@abraca/schema` (Zod validator)
+ * + `@abraca/plugin` (manifest types) which are zero-runtime-cost when
+ * imported as `import type`.
+ */
+
+import { validate } from "./commands/validate.ts";
+import { pack } from "./commands/pack.ts";
+import { previewScan } from "./commands/preview-scan.ts";
+import { ansi } from "./io.ts";
+
+// Public surface — small, so library consumers can call commands programmatically.
+export { validate, type ValidateOptions, type ValidateResult } from "./commands/validate.ts";
+export { pack, type PackOptions, type PackResult } from "./commands/pack.ts";
+export {
+	previewScan,
+	type PreviewScanOptions,
+	type PreviewScanResult,
+	type PreviewScanFinding,
+} from "./commands/preview-scan.ts";
+
+function help(): void {
+	const lines = [
+		`${ansi.bold("abra-plugin")} — Abracadabra plugin author toolkit`,
+		"",
+		"Usage:",
+		`  ${ansi.cyan("abra-plugin validate")}     [path]            Validate a manifest against the schema`,
+		`  ${ansi.cyan("abra-plugin pack")}         [path] [--dry-run] Recompute integrity hash, update manifest`,
+		`  ${ansi.cyan("abra-plugin preview-scan")} [path]            Validate + static-scan the bundle (registry parity)`,
+		"",
+		`Path defaults to ${ansi.dim("./manifest.json")} when omitted.`,
+	];
+	console.log(lines.join("\n"));
+}
+
+function parseFlag(args: string[], flag: string): boolean {
+	const idx = args.indexOf(flag);
+	if (idx >= 0) {
+		args.splice(idx, 1);
+		return true;
+	}
+	return false;
+}
+
+export function run(argv: ReadonlyArray<string>): number {
+	const args = [...argv];
+	const command = args.shift();
+
+	switch (command) {
+		case undefined:
+		case "help":
+		case "-h":
+		case "--help":
+			help();
+			return 0;
+
+		case "validate": {
+			const quiet = parseFlag(args, "--quiet");
+			const path = args.shift();
+			return validate({ path, quiet }).exitCode;
+		}
+
+		case "pack": {
+			const dryRun = parseFlag(args, "--dry-run");
+			const path = args.shift();
+			return pack({ path, dryRun }).exitCode;
+		}
+
+		case "preview-scan": {
+			const path = args.shift();
+			return previewScan({ path }).exitCode;
+		}
+
+		default:
+			console.error(ansi.red(`error: unknown command "${command}"`));
+			console.error(`run ${ansi.cyan("abra-plugin help")} for usage`);
+			return 2;
+	}
+}
+
+// Auto-run when invoked as a CLI (not when imported as a library).
+const isCliEntry =
+	import.meta.url === `file://${process.argv[1]}` ||
+	import.meta.url.endsWith(process.argv[1] ?? "");
+if (isCliEntry) {
+	process.exit(run(process.argv.slice(2)));
+}

package/src/io.ts

@@ -0,0 +1,67 @@
+/**
+ * Filesystem helpers used across `abra-plugin` commands. Kept tiny and
+ * dependency-free so the CLI bundle stays small.
+ */
+
+import { readFileSync, statSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { isAbsolute, resolve } from "node:path";
+
+/**
+ * Resolve a CLI-supplied path to an absolute path. Relative paths resolve
+ * against `process.cwd()`. Used so commands work no matter where the user
+ * invoked them from.
+ */
+export function resolveCwd(path: string): string {
+	return isAbsolute(path) ? path : resolve(process.cwd(), path);
+}
+
+/** Read a JSON file and return parsed content. Throws with a contextual message on failure. */
+export function readJsonFile(path: string): unknown {
+	let raw: string;
+	try {
+		raw = readFileSync(path, "utf8");
+	} catch (err) {
+		const code = (err as NodeJS.ErrnoException).code;
+		if (code === "ENOENT") {
+			throw new Error(`not found: ${path}`);
+		}
+		throw new Error(`failed to read ${path}: ${(err as Error).message}`);
+	}
+	try {
+		return JSON.parse(raw) as unknown;
+	} catch (err) {
+		throw new Error(`invalid JSON in ${path}: ${(err as Error).message}`);
+	}
+}
+
+/**
+ * SHA-256 hash of a file's bytes, formatted as `sha256-<64 hex chars>` to
+ * match the manifest's `integrity` field format.
+ */
+export function sha256OfFile(path: string): string {
+	const buf = readFileSync(path);
+	return `sha256-${createHash("sha256").update(buf).digest("hex")}`;
+}
+
+/** Return true if `path` exists and is a regular file. */
+export function isFile(path: string): boolean {
+	try {
+		return statSync(path).isFile();
+	} catch {
+		return false;
+	}
+}
+
+// ── ANSI helpers (no peer dep) ────────────────────────────────────────────────
+
+const useColor = process.stdout.isTTY && process.env.NO_COLOR === undefined;
+
+export const ansi = {
+	red: (s: string) => (useColor ? `\x1b[31m${s}\x1b[0m` : s),
+	green: (s: string) => (useColor ? `\x1b[32m${s}\x1b[0m` : s),
+	yellow: (s: string) => (useColor ? `\x1b[33m${s}\x1b[0m` : s),
+	cyan: (s: string) => (useColor ? `\x1b[36m${s}\x1b[0m` : s),
+	dim: (s: string) => (useColor ? `\x1b[2m${s}\x1b[0m` : s),
+	bold: (s: string) => (useColor ? `\x1b[1m${s}\x1b[0m` : s),
+};