Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

7.2 KB
Raw Blame
/**
 * Ship log: every release note joined to the commits that produced it.
 *
 *   GET /api/ship/feed
 *   GET /api/ship/feed?limit=300&audience=holder&format=markdown
 *   GET /api/ship/feed?explain=<sha>
 *
 * The changelog says what shipped in a sentence a holder can read. The commit
 * log says what shipped in code. Nothing has ever pointed the two at each
 * other, which is why the same work reaches the Telegram channel twice, in two
 * voices, with no way to tell that it is the same work. This endpoint is that
 * join, computed on demand by @three-ws/shipfeed:
 *
 *   releases[]  a changelog entry, its commits, and a confidence + reason for
 *               every link, so a wrong link is visible instead of implied
 *   ships[]     bursts of commits no entry ever claimed (the unannounced work)
 *   stats       audience mix, coverage, velocity, types, authors
 *
 * Sources are both real and both first-party-adjacent: the changelog is the
 * feed baked into this running image (public/changelog.json, regenerated by
 * every deploy), and the commits come from GitHub's REST API through
 * fetchUpstream, so the call is bounded, retried, breaker-guarded, and served
 * from last-good on an upstream blip.
 *
 * Public, no auth, cached for 5 minutes.
 *
 * Params
 *   limit     commits to read, 1..500 (default 200)
 *   audience  holder | developer | internal (default internal, i.e. everything)
 *   format    json | markdown | rss (default json)
 *   explain   a commit sha; returns that one commit's scoring and link reasons
 */

import { readFileSync } from 'node:fs';
import { join } from 'node:path';

import { cors, json, method, wrap, rateLimited, error } from '../_lib/http.js';
import { limits, clientIp } from '../_lib/rate-limit.js';
import { cacheWrapLastGood } from '../_lib/cache.js';
import { fetchUpstream } from '../_lib/upstream-fetch.js';
import {
	buildShipFeed,
	classify,
	fetchGitHubCommits,
	linkCommits,
	normalizeChangelog,
	parseCommit,
	renderMarkdown,
	renderRss,
} from '../../packages/shipfeed/src/index.js';

const REPO = 'nirholas/three.ws';
const SITE = 'https://three.ws';
const CACHE_TTL_S = 300;
const DEFAULT_LIMIT = 200;
const MAX_LIMIT = 500;
const AUDIENCES = new Set(['holder', 'developer', 'internal']);
const FORMATS = new Set(['json', 'markdown', 'rss']);

// Scopes this repo uses for parts of the product a reader has actually seen.
// Naming them is what lifts "fix(forge): ..." above "fix(build): ..." in the
// signal score; everything unnamed still scores on its own merits.
const PRODUCT_SCOPES = [
	'agent',
	'agents',
	'avatar',
	'avatars',
	'chat',
	'companion',
	'crews',
	'discover',
	'embed',
	'embeds',
	'forge',
	'launch',
	'marketplace',
	'oracle',
	'payments',
	'pump',
	'seeker',
	'studio',
	'viewer',
	'wallet',
	'x402',
];

/** The changelog baked into this image by the deploy that shipped it. */
function loadChangelog() {
	return normalizeChangelog(
		JSON.parse(readFileSync(join(process.cwd(), 'public', 'changelog.json'), 'utf8')),
	);
}

/**
 * GitHub through the shared upstream wrapper: one deadline, one retry, one
 * breaker. `okWhen` is deliberately permissive so the package sees the real
 * status and can name a rate-limit reset instead of a bare 503.
 */
const boundedFetch = (url, init) =>
	fetchUpstream(url, init, {
		name: 'github-commits',
		timeoutMs: 12_000,
		attempts: 2,
		okWhen: () => true,
	});

async function buildFeed({ limit, audience }) {
	const key = `ship:feed:${limit}:${audience}`;
	const { value, stale } = await cacheWrapLastGood(
		key,
		CACHE_TTL_S,
		async () => {
			const entries = loadChangelog();
			const commits = await fetchGitHubCommits({
				repo: REPO,
				branch: 'main',
				limit,
				token: process.env.GITHUB_TOKEN || process.env.GH_TOKEN || '',
				fetchImpl: boundedFetch,
				userAgent: 'three.ws-shipfeed',
			});

			return buildShipFeed({
				commits,
				entries,
				repo: REPO,
				siteUrl: SITE,
				minAudience: audience,
				classify: { productScopes: PRODUCT_SCOPES },
			});
		},
		{ withMeta: true },
	);
	return { ...value, cached: false, stale };
}

/**
 * One commit's full reasoning: why it scored what it scored, and why it is or
 * is not attached to a release note. This is the accountability half of the
 * feature; a heuristic nobody can interrogate is a heuristic nobody should
 * trust.
 */
async function explainCommit(sha, { limit }) {
	const entries = loadChangelog();
	const raw = await fetchGitHubCommits({
		repo: REPO,
		branch: 'main',
		limit,
		token: process.env.GITHUB_TOKEN || process.env.GH_TOKEN || '',
		fetchImpl: boundedFetch,
		userAgent: 'three.ws-shipfeed',
	});
	const commits = raw.map((c) => parseCommit(c));
	const commit = commits.find((c) => c.sha.startsWith(sha));
	if (!commit) return null;

	const classification = classify(commit, { productScopes: PRODUCT_SCOPES });
	const { byCommit } = linkCommits(entries, commits);
	const link = byCommit.get(commit.sha) || null;
	const entry = link ? entries.find((e) => `${e.date}:${e.title}` === link.entryKey) : null;

	return {
		commit: {
			sha: commit.sha,
			shortSha: commit.shortSha,
			url: commit.url,
			subject: commit.subject,
			type: commit.type,
			scope: commit.scope,
			breaking: commit.breaking,
			date: commit.committedAt,
			author: commit.author.login || commit.author.name,
		},
		classification,
		link: link
			? { confidence: link.score, reasons: link.reasons, entry, key: link.entryKey }
			: null,
	};
}

export default wrap(async (req, res) => {
	if (cors(req, res, { methods: 'GET,OPTIONS', origins: '*' })) return;
	if (!method(req, res, ['GET'])) return;

	const rl = await limits.publicIp(clientIp(req));
	if (!rl.success) return rateLimited(res, rl);

	const params = new URL(req.url, `http://${req.headers.host || 'x'}`).searchParams;
	const limit = Math.min(MAX_LIMIT, Math.max(1, Number(params.get('limit')) || DEFAULT_LIMIT));
	const audience = AUDIENCES.has(params.get('audience')) ? params.get('audience') : 'internal';
	const format = FORMATS.has(params.get('format')) ? params.get('format') : 'json';
	const explain = String(params.get('explain') || '').toLowerCase();

	if (explain) {
		if (!/^[0-9a-f]{7,40}$/.test(explain)) {
			return error(res, 400, 'bad_sha', 'explain must be a 7 to 40 character commit sha');
		}
		const result = await explainCommit(explain, { limit });
		if (!result) {
			return error(
				res,
				404,
				'commit_not_found',
				`${explain} is not in the last ${limit} commits on main`,
			);
		}
		return json(res, 200, result, { 'cache-control': `public, max-age=${CACHE_TTL_S}` });
	}

	const feed = await buildFeed({ limit, audience });

	if (format === 'markdown') {
		res.statusCode = 200;
		res.setHeader('content-type', 'text/markdown; charset=utf-8');
		res.setHeader('cache-control', `public, max-age=${CACHE_TTL_S}`);
		return res.end(renderMarkdown(feed));
	}
	if (format === 'rss') {
		res.statusCode = 200;
		res.setHeader('content-type', 'application/rss+xml; charset=utf-8');
		res.setHeader('cache-control', `public, max-age=${CACHE_TTL_S}`);
		return res.end(
			renderRss(feed, {
				title: 'three.ws ship log',
				siteUrl: `${SITE}/ship`,
				description: 'Every three.ws release note, with the commits that produced it.',
			}),
		);
	}

	return json(res, 200, feed, { 'cache-control': `public, max-age=${CACHE_TTL_S}` });
});