@chrisjowen/wheelhouse 0.1.1 → 0.2.1

package/plugins/project-links/wheelhouse/server/index.js

@@ -0,0 +1,278 @@
+/**
+ * Project links, bundled with Wheelhouse in the installed-plugin format. It shows a
+ * project's repository, README and pull requests, using only the project
+ * clone's `origin` remote, its README and the fleet Wheelhouse already has. It
+ * reads nothing else and writes nothing. Its Harbour card is the
+ * <project-links-summary> element from ../ui/index.js.
+ *
+ * A real plugin would import the SDK's builders and bundle them in; this one
+ * writes its blocks out so it needs no build step.
+ *
+ * @typedef {import('@chrisjowen/wheelhouse-plugin-sdk').WheelhousePlugin} WheelhousePlugin
+ * @typedef {import('@chrisjowen/wheelhouse-plugin-sdk').ProviderContext} ProviderContext
+ * @typedef {import('@chrisjowen/wheelhouse-plugin-sdk').Project} Project
+ * @typedef {import('@chrisjowen/wheelhouse-plugin-sdk').Task} Task
+ * @typedef {import('@chrisjowen/wheelhouse-plugin-sdk').Block} Block
+ */
+
+/** The browser URL for a GitHub-style remote, without credentials, or null. */
+export function webUrl(remote) {
+	const s = remote.trim();
+	const scp = /^[\w.-]+@([\w.-]+):([\w.-]+\/[\w.-]+?)(?:\.git)?\/?$/.exec(s);
+	if (scp) return `https://${scp[1]}/${scp[2]}`;
+	let u;
+	try {
+		u = new URL(s);
+	} catch {
+		return null;
+	}
+	if (!['https:', 'http:', 'ssh:', 'git:'].includes(u.protocol)) return null;
+	const repo = /^\/([\w.-]+\/[\w.-]+?)(?:\.git)?\/?$/.exec(u.pathname);
+	if (!repo || !/^[\w.-]+$/.test(u.hostname)) return null;
+	return `https://${u.hostname}/${repo[1]}`;
+}
+
+const isGitHub = (url) => !!url && url.startsWith('https://github.com/');
+const segments = (ref) => ref.split('/').map(encodeURIComponent).join('/');
+
+/** The project's browser URL and README title, reused for a minute across providers. */
+const facts = new Map();
+const FACTS_TTL_MS = 60_000;
+
+/** @param {ProviderContext} ctx @param {Project | null} project */
+function projectFacts(ctx, project = ctx.project) {
+	const dir = project?.path;
+	if (!dir) return Promise.resolve({ repoUrl: null, readme: null });
+	const hit = facts.get(dir);
+	const at = Date.now();
+	if (hit && at - hit.at < FACTS_TTL_MS) return hit.value;
+	const value = (async () => {
+		const [remote, readme] = await Promise.all([
+			ctx.exec({
+				argv: ['git', 'remote', 'get-url', 'origin'],
+				cwd: 'project',
+				project: project.id,
+				timeoutMs: 2_000,
+				maxBytes: 4096
+			}),
+			ctx.readFile('README.md', { root: 'project', maxBytes: 8192, project: project.id })
+		]);
+		if (!remote.ok && facts.get(dir)?.at === at) facts.delete(dir);
+		const repoUrl = remote.ok ? webUrl(remote.stdout) : null;
+		const title = readme?.match(/^#\s+(.+)$/m)?.[1].trim() ?? 'README';
+		return {
+			repoUrl,
+			readme:
+				readme === null
+					? null
+					: { title, url: isGitHub(repoUrl) ? `${repoUrl}/blob/HEAD/README.md` : null }
+		};
+	})();
+	facts.set(dir, { at, value });
+	return value;
+}
+
+/** @param {Task[]} tasks */
+const pulls = (tasks) =>
+	tasks
+		.filter((t) => t.pr)
+		.map((t) => ({
+			title: t.title,
+			url: t.pr.url,
+			number: t.pr.number,
+			landed: t.status === 'landed'
+		}));
+
+const SOURCE = 'the project clone’s origin remote and README, and Firstmate’s fleet';
+const now = () => new Date().toISOString();
+
+/** @param {ProviderContext} ctx */
+async function summary(ctx) {
+	const f = await projectFacts(ctx);
+	return {
+		available: true,
+		value: { ...f, pulls: pulls(ctx.tasks) },
+		source: SOURCE,
+		observedAt: now()
+	};
+}
+
+/** @returns {Block[]} */
+function projectBlocks(project, s) {
+	const links = [];
+	if (s.repoUrl) links.push({ label: 'Repository', href: s.repoUrl });
+	if (s.readme?.url) links.push({ label: 'README', href: s.readme.url, note: s.readme.title });
+	if (isGitHub(s.repoUrl)) links.push({ label: 'Pull requests', href: `${s.repoUrl}/pulls` });
+	const blocks = [];
+	if (links.length) blocks.push({ block: 'links.v1', links });
+	else {
+		blocks.push({
+			block: 'text.v1',
+			text: project.path
+				? 'This project’s clone has no GitHub-style origin remote.'
+				: 'Firstmate has not recorded a clone for this project.',
+			muted: true
+		});
+	}
+	blocks.push({
+		block: 'kv.v1',
+		items: [
+			{ key: 'Clone', value: project.path ?? 'Not recorded' },
+			{ key: 'README', value: s.readme ? s.readme.title : 'None found' }
+		]
+	});
+	if (s.pulls.length) {
+		blocks.push({
+			block: 'table.v1',
+			columns: ['Task', 'Pull request', 'State'],
+			rows: s.pulls.map((p) => [
+				p.title,
+				{ text: p.number ? `#${p.number}` : 'Open', href: p.url },
+				p.landed ? 'Landed' : 'Open'
+			])
+		});
+	} else {
+		blocks.push({
+			block: 'text.v1',
+			text: 'No pull requests recorded for this project.',
+			muted: true
+		});
+	}
+	return blocks;
+}
+
+/** @type {WheelhousePlugin} */
+export default {
+	providers: [
+		{ id: 'summary', scope: 'project', ttlMs: 30_000, fetch: summary },
+		{
+			id: 'links',
+			scope: 'project',
+			ttlMs: 30_000,
+			async fetch(ctx) {
+				const s = await summary(ctx);
+				return { ...s, value: projectBlocks(ctx.project, s.value) };
+			}
+		},
+		{
+			id: 'task',
+			scope: 'task',
+			ttlMs: 15_000,
+			async fetch(ctx) {
+				const t = ctx.task;
+				const { repoUrl } = await projectFacts(ctx);
+				const links = [];
+				if (t.pr) {
+					links.push({
+						label: `Pull request${t.pr.number ? ` #${t.pr.number}` : ''}`,
+						href: t.pr.url
+					});
+				}
+				if (t.preview) links.push({ label: 'Reported preview', href: t.preview.url });
+				if (t.branch && isGitHub(repoUrl)) {
+					links.push({
+						label: 'Branch',
+						href: `${repoUrl}/tree/${segments(t.branch)}`,
+						note: t.branch
+					});
+				}
+				if (repoUrl) links.push({ label: 'Repository', href: repoUrl });
+				const blocks = [
+					t.pr
+						? {
+								block: 'status.v1',
+								tone: t.status === 'landed' ? 'ok' : 'pending',
+								label: t.status === 'landed' ? 'Pull request landed' : 'Pull request open'
+							}
+						: { block: 'status.v1', tone: 'unknown', label: 'No pull request recorded yet' }
+				];
+				if (links.length) blocks.push({ block: 'links.v1', links });
+				return { available: true, value: blocks, source: SOURCE, observedAt: now() };
+			}
+		},
+		{
+			id: 'compare',
+			scope: 'task',
+			ttlMs: 30_000,
+			async fetch(ctx) {
+				const t = ctx.task;
+				const { repoUrl } = await projectFacts(ctx);
+				if (!t.branch || !isGitHub(repoUrl)) {
+					return { available: false, reason: 'No branch on a GitHub repository to compare.' };
+				}
+				const href = `${repoUrl}/compare/${segments(t.branch)}`;
+				return {
+					available: true,
+					value: [{ block: 'links.v1', links: [{ label: `Compare ${t.branch} on GitHub`, href }] }],
+					source: SOURCE,
+					observedAt: now()
+				};
+			}
+		},
+		{
+			id: 'repos',
+			scope: 'fleet',
+			ttlMs: 60_000,
+			async fetch(ctx) {
+				const cards = [];
+				for (const p of ctx.projects) {
+					const { repoUrl, readme } = await projectFacts(ctx, p);
+					if (!repoUrl) continue;
+					const links = [{ label: 'Repository', href: repoUrl }];
+					if (readme?.url) links.push({ label: 'README', href: readme.url });
+					cards.push({
+						key: p.id,
+						title: p.name,
+						mentions: [repoUrl],
+						blocks: [
+							...(p.description ? [{ block: 'text.v1', text: p.description, muted: true }] : []),
+							{ block: 'links.v1', links }
+						]
+					});
+				}
+				return { available: true, value: cards, source: SOURCE, observedAt: now() };
+			}
+		}
+	],
+	contributions: [
+		{
+			slot: 'project.tab',
+			id: 'links',
+			title: 'Links',
+			provider: 'links',
+			render: { blocks: true }
+		},
+		{
+			slot: 'harbour.card',
+			id: 'summary',
+			title: 'Project links',
+			provider: 'summary',
+			when: 'provider-available',
+			render: { element: 'project-links-summary' }
+		},
+		{
+			slot: 'task.section',
+			id: 'task-links',
+			title: 'Links',
+			provider: 'task',
+			placement: { order: 250 },
+			render: { blocks: true }
+		},
+		{
+			slot: 'step.evidence',
+			id: 'compare',
+			title: 'Compare on GitHub',
+			provider: 'compare',
+			when: 'provider-available',
+			placement: { step: 'pr' },
+			render: { blocks: true }
+		},
+		{
+			slot: 'bridge.card',
+			id: 'repo',
+			title: 'Project',
+			provider: 'repos',
+			render: { blocks: true }
+		}
+	]
+};

package/plugins/project-links/wheelhouse/ui/index.js

@@ -0,0 +1,87 @@
+/**
+ * Project links' Harbour card as a custom element. Wheelhouse imports this
+ * bundle, then sets the provider's value on the element as `data` (and the
+ * slot entry as `entry`) each time it changes. It styles itself with
+ * Wheelhouse's CSS variables, so it follows the page's light and dark themes.
+ *
+ * @typedef {{ repoUrl: string | null; readme: { title: string; url: string | null } | null;
+ *   pulls: { title: string; url: string; number: number | null; landed: boolean }[] }} ProjectSummary
+ */
+
+const STYLE = `
+	:host { display: block; font: inherit; color: var(--foreground); }
+	.row { display: flex; flex-wrap: wrap; align-items: center; gap: 0.375rem 1.25rem; font-size: 0.875rem; }
+	a { color: var(--sea); text-decoration: none; }
+	a:hover { text-decoration: underline; }
+	.muted { color: var(--muted-foreground); }
+`;
+
+/** Only http(s) links, as Wheelhouse's own blocks allow. */
+const safe = (href) => {
+	try {
+		const u = new URL(href);
+		return u.protocol === 'https:' || u.protocol === 'http:' ? href : null;
+	} catch {
+		return null;
+	}
+};
+
+class ProjectLinksSummary extends HTMLElement {
+	#data = null;
+
+	constructor() {
+		super();
+		this.attachShadow({ mode: 'open' });
+	}
+
+	/** @param {ProjectSummary} value */
+	set data(value) {
+		this.#data = value;
+		this.render();
+	}
+
+	get data() {
+		return this.#data;
+	}
+
+	connectedCallback() {
+		this.render();
+	}
+
+	render() {
+		const s = this.#data;
+		if (!s || !this.shadowRoot) return;
+		const row = document.createElement('div');
+		row.className = 'row';
+		const repo = s.repoUrl && safe(s.repoUrl);
+		if (repo) row.append(link(repo, repo.replace(/^https:\/\//, '')));
+		else row.append(span('No repository link', 'muted'));
+		const readme = s.readme?.url && safe(s.readme.url);
+		if (readme) row.append(link(readme, s.readme.title));
+		const open = s.pulls.filter((p) => !p.landed).length;
+		row.append(span(`${open} open ${open === 1 ? 'pull request' : 'pull requests'}`, 'muted'));
+		const style = document.createElement('style');
+		style.textContent = STYLE;
+		this.shadowRoot.replaceChildren(style, row);
+	}
+}
+
+function link(href, text) {
+	const a = document.createElement('a');
+	a.href = href;
+	a.target = '_blank';
+	a.rel = 'noreferrer';
+	a.textContent = text;
+	return a;
+}
+
+function span(text, className) {
+	const s = document.createElement('span');
+	s.className = className;
+	s.textContent = text;
+	return s;
+}
+
+if (!customElements.get('project-links-summary')) {
+	customElements.define('project-links-summary', ProjectLinksSummary);
+}

package/plugins/vault/.wheelhouse-plugin/plugin.json

@@ -0,0 +1,22 @@
+{
+	"$schema": "../../../packages/plugin-sdk/plugin.schema.json",
+	"name": "vault",
+	"displayName": "Vault",
+	"version": "0.2.0",
+	"description": "The secrets wh-vault holds, which projects may use each and when they were used, by name only; never a value.",
+	"author": { "name": "Chris Owen", "url": "https://github.com/chrisjowen" },
+	"repository": "https://github.com/chrisjowen/wheelhouse",
+	"license": "MIT",
+	"keywords": ["secrets", "keychain"],
+	"wheelhouse": {
+		"apiVersion": 1,
+		"server": "wheelhouse/server/index.js",
+		"enabledByDefault": true,
+		"contributions": [
+			{ "id": "overview", "slot": "nav.page" },
+			{ "id": "secrets", "slot": "project.tab" },
+			{ "id": "used", "slot": "task.section" }
+		],
+		"services": []
+	}
+}

package/plugins/vault/README.md

@@ -0,0 +1,18 @@
+# Vault
+
+The Vault plugin, bundled with Wheelhouse in the installed-plugin format: what [`wh-vault`](../../docs/vault.md) holds, by name only. Wheelhouse ships this folder in its package and loads it at startup through the same loader as an installed plugin, shown as built in.
+
+```
+.wheelhouse-plugin/plugin.json   the manifest: id, version, contract, entries, enable rule, slots
+wheelhouse/server/index.js       providers and contributions (ESM, no dependencies)
+```
+
+It fills a **Vault** page in the menu, a **Secrets** tab on each project with grants or use, and a **Secrets used** tab on each task that ran a command with `wh-vault run`. It reads only by running `wh-vault list --all --json` and `wh-vault audit --json`, neither of which reads a value. It is on by default, and its page shows even while the vault is empty.
+
+![The Vault page: each secret by name with the projects that may use it, an Add a secret button, and the recent use of the vault by task, command and result](../../docs/screenshots/plugins/vault-page.png)
+
+![A project's Secrets tab: the secrets its commands may receive with when each value was set and last used, and the tasks that used them, including one refused](../../docs/screenshots/plugins/vault-project.png)
+
+The plugin is read-only. Its Vault page is drawn by Wheelhouse's own `vault/overview` panel, which a plugin bundled with Wheelhouse may name. The panel's **Add a secret**, project tick boxes, **Replace value** and **Remove…** go to Wheelhouse (`POST /api/vault`), not to this plugin, and Wheelhouse runs the bundled `wh-vault`. So grants can change from Wheelhouse, any local process that can reach Wheelhouse with its session token could use them, and a value typed there passes briefly through Wheelhouse's process.
+
+See [docs/vault.md](../../docs/vault.md) for `wh-vault` and [docs/plugins.md](../../docs/plugins.md#installed-plugins) for the format.