@buckeyestudio/pi-wire 18.4.13

package/src/skillshare.ts

@@ -0,0 +1,323 @@
+/**
+ * Wire contract for Skillshare (`skills.omp.sh`): an npm-style registry for
+ * omp skills. Shared by the omp CLI (`omp skill …`), the Go server
+ * (`stencil/apps/skills`), and its web UI (which mirrors this file).
+ *
+ * Packages are scoped: `@scope/name`. A scope is a Stencil username claimed on
+ * first publish and bound to the account's immutable `sub` forever (usernames
+ * can be renamed and recycled; scopes cannot). `name` is the SKILL.md
+ * frontmatter `name`. Published versions are immutable.
+ *
+ * Registry fields ride in SKILL.md `metadata` (the Agent Skills frontmatter is
+ * closed to name/description/license/compatibility/metadata/allowed-tools):
+ * `metadata.version` (semver, required to publish), `metadata.keywords`
+ * (comma-separated), `metadata.repository`, `metadata.homepage`.
+ */
+
+/** Default registry; `skills.registryUrl` overrides it. */
+export const DEFAULT_SKILLS_URL = "https://skills.omp.sh";
+
+/** Scopes are Stencil usernames (or registry orgs): lowercase letters, digits, underscores; 3–32 chars. */
+export const SKILL_SCOPE_RE = /^[a-z0-9][a-z0-9_]{2,31}$/;
+/** Registry skill names: ASCII kebab-case, 1–64 chars, no leading/trailing/double hyphens. */
+export const SKILL_NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+export const SKILL_NAME_MAX = 64;
+/** `@scope/name`, optionally `@version-or-range-or-tag`. */
+export const SKILL_SPEC_RE = /^@([a-z0-9][a-z0-9_]{2,31})\/([a-z0-9]+(?:-[a-z0-9]+)*)(?:@(.+))?$/;
+
+/** Publish limits, enforced by both the CLI and the server. */
+export const SKILL_LIMITS = {
+	/** Compressed `.tgz` upload. */
+	tarballBytes: 5 * 1024 * 1024,
+	/** Sum of all file sizes after unpacking. */
+	unpackedBytes: 20 * 1024 * 1024,
+	files: 1000,
+	/** Longest path inside the package. */
+	pathLength: 255,
+	descriptionLength: 1024,
+	keywords: 20,
+	keywordLength: 50,
+	deprecationLength: 500,
+} as const;
+
+/** Paths excluded from packs in addition to `.skillignore` entries. */
+export const SKILL_DEFAULT_IGNORES = [
+	".git",
+	".DS_Store",
+	"node_modules",
+	"__pycache__",
+	"*.pyc",
+	"evals",
+	".skillignore",
+] as const;
+
+/**
+ * Publish request: `PUT SKILLS_ROUTES.publish(scope, name, version)`, body is
+ * the `.tgz` (gzip tar; entries are paths relative to the skill root, regular
+ * files only, sorted, mtime 0, mode 0644 or 0755). Auth: `Authorization:
+ * Bearer <Stencil access token | registry publish token>`.
+ */
+export const SKILL_HEADERS = {
+	/** Required: SRI `sha512-<base64>` of the body. */
+	integrity: "X-Skill-Integrity",
+	/** Optional dist-tag to point at the new version (default `latest` for stable, none for prereleases). */
+	tag: "X-Skill-Tag",
+	/** Optional base64(JSON {@link SkillReportedProvenance}); shown as "reported". */
+	provenance: "X-Skill-Provenance",
+	/** Optional GitHub Actions OIDC token (audience {@link SKILLS_OIDC_AUDIENCE}); verified server-side. */
+	githubOidc: "X-Skill-GitHub-OIDC",
+} as const;
+
+/** Audience CI must request for GitHub Actions OIDC tokens. */
+export const SKILLS_OIDC_AUDIENCE = "skills.omp.sh";
+
+/** Env var holding a registry publish token for CI (`sks_…`); wins over the Stencil login. */
+export const SKILLS_TOKEN_ENV = "SKILLS_TOKEN";
+
+/** Public identity of an account: current username + avatar seed (hash of the immutable sub). */
+export interface SkillUser {
+	username: string;
+	/** Hex seed for the generated dither avatar; never the raw sub. */
+	avatar: string;
+}
+
+export interface SkillReportedProvenance {
+	ompVersion: string;
+	gitRemote?: string;
+	gitCommit?: string;
+}
+
+/** Provenance proven by a verified GitHub Actions OIDC token. */
+export interface SkillVerifiedProvenance {
+	kind: "github-actions";
+	repository: string;
+	workflow: string;
+	ref: string;
+	sha: string;
+	runUrl: string;
+}
+
+export interface SkillProvenance {
+	publisher: SkillUser;
+	/** Publish came from a registry token rather than an interactive login. */
+	viaToken: boolean;
+	reported?: SkillReportedProvenance;
+	verified?: SkillVerifiedProvenance;
+}
+
+export interface SkillFile {
+	/** POSIX path relative to the skill root. */
+	path: string;
+	size: number;
+	/** Hex SHA-256 of the content. */
+	sha256: string;
+	executable: boolean;
+}
+
+/** One version as listed in a packument. */
+export interface SkillVersionSummary {
+	version: string;
+	publishedAt: number;
+	publisher: SkillUser;
+	integrity: string;
+	size: number;
+	unpackedSize: number;
+	fileCount: number;
+	/** Ships executables or anything under `scripts/`. */
+	hasScripts: boolean;
+	yanked: boolean;
+	deprecated?: string;
+}
+
+/** Daily download counts, oldest first: `[YYYY-MM-DD, count]`. */
+export type SkillDownloadSeries = [day: string, count: number][];
+
+/** `GET SKILLS_ROUTES.packument`: everything about a package. */
+export interface SkillPackument {
+	scope: string;
+	name: string;
+	/** From the `latest` version. */
+	description: string;
+	keywords: string[];
+	license?: string;
+	repository?: string;
+	homepage?: string;
+	owners: SkillUser[];
+	/** e.g. `{ latest: "1.2.0", next: "2.0.0-beta.1" }`. */
+	distTags: Record<string, string>;
+	versions: Record<string, SkillVersionSummary>;
+	createdAt: number;
+	updatedAt: number;
+	downloads: { weekly: number; total: number; daily: SkillDownloadSeries };
+	/** Signed-in viewer may publish, tag, yank, deprecate, and manage owners. */
+	canManage: boolean;
+}
+
+/** `GET SKILLS_ROUTES.version`: one immutable version. `:version` may be a dist-tag. */
+export interface SkillVersionManifest extends SkillVersionSummary {
+	scope: string;
+	name: string;
+	description: string;
+	license?: string;
+	compatibility?: string;
+	allowedTools?: string;
+	/** SKILL.md `metadata` verbatim. */
+	metadata: Record<string, string>;
+	keywords: string[];
+	repository?: string;
+	homepage?: string;
+	files: SkillFile[];
+	/** Package path rendered as the README (`README.md` if present, else `SKILL.md`). */
+	readmePath: string;
+	provenance: SkillProvenance;
+}
+
+/** `GET SKILLS_ROUTES.readme`: sanitized HTML rendered at publish time. */
+export interface SkillReadme {
+	html: string;
+}
+
+/** `GET SKILLS_ROUTES.source`: one file for the code viewer. */
+export interface SkillSource {
+	path: string;
+	size: number;
+	/** Binary or over the view limit: no `html`, offer `SKILLS_ROUTES.file` instead. */
+	binary: boolean;
+	tooLarge: boolean;
+	/** Server-highlighted, sanitized HTML: one `<span class="line">` per line. */
+	html?: string;
+	lines?: number;
+}
+
+export interface SkillSearchHit {
+	scope: string;
+	name: string;
+	description: string;
+	keywords: string[];
+	version: string;
+	publisher: SkillUser;
+	updatedAt: number;
+	weeklyDownloads: number;
+	deprecated?: string;
+}
+
+export type SkillSearchSort = "relevance" | "downloads" | "recent";
+
+/** `GET SKILLS_ROUTES.search?q=&sort=&page=`. `q` accepts `owner:<scope>` and `keyword:<kw>` filters. */
+export interface SkillSearchResponse {
+	total: number;
+	page: number;
+	perPage: number;
+	hits: SkillSearchHit[];
+}
+
+/** `GET SKILLS_ROUTES.home`. */
+export interface SkillHome {
+	stats: { packages: number; versions: number; publishers: number; weeklyDownloads: number };
+	recent: SkillSearchHit[];
+	popular: SkillSearchHit[];
+	trending: SkillSearchHit[];
+	keywords: [keyword: string, count: number][];
+}
+
+/** `GET SKILLS_ROUTES.user`: a user or org scope page. */
+export interface SkillProfile {
+	user: SkillUser;
+	kind: "user" | "org";
+	scopes: string[];
+	packages: SkillSearchHit[];
+	/** Orgs only. */
+	members?: { user: SkillUser; role: SkillOrgRole }[];
+}
+
+export type SkillOrgRole = "owner" | "member";
+
+export interface SkillPublishResponse {
+	scope: string;
+	name: string;
+	version: string;
+	integrity: string;
+	/** Package page. */
+	url: string;
+	/** Dist-tags now pointing at this version. */
+	tags: string[];
+}
+
+/** Registry publish token (CI). The secret is shown once, at creation. */
+export interface SkillToken {
+	id: string;
+	name: string;
+	/** `@scope/name` packages the token may publish; empty = all packages the creator manages. */
+	packages: string[];
+	createdAt: number;
+	expiresAt?: number;
+	lastUsedAt?: number;
+}
+
+export interface SkillTokenCreated extends SkillToken {
+	/** `sks_…`; never retrievable again. */
+	token: string;
+}
+
+/** `GET SKILLS_ROUTES.me`. */
+export interface SkillSession {
+	user: SkillUser | null;
+	/** Sign-in is configured on this server. */
+	login: boolean;
+	admin: boolean;
+}
+
+/** Error body of every non-2xx JSON response. */
+export interface SkillError {
+	error: string;
+}
+
+const pkg = (scope: string, name: string) => `/api/v1/skills/@${scope}/${name}`;
+
+/**
+ * HTTP routes, relative to the registry base URL. Mutations with a JSON body
+ * use the documented request shapes:
+ * - `tag` PUT `{ version }`, DELETE to remove (never `latest`)
+ * - `yank` POST `{ yanked: boolean }`
+ * - `deprecate` POST `{ message: string | null }`
+ * - `owner` PUT / DELETE (no body)
+ * - `tokens` POST `{ name, packages?: string[], expiresInDays?: number }`
+ * - `report` POST `{ reason: string }`
+ * - `takedown` POST `{ reason: string }` (admins)
+ * - `orgs` POST `{ name }`; `orgMember` PUT `{ role }` / DELETE
+ * - `importSkill` POST body = Claude `.skill` zip (bearer) → {@link SkillPublishResponse}
+ */
+export const SKILLS_ROUTES = {
+	home: "/api/v1/home",
+	search: "/api/v1/search",
+	packument: (scope: string, name: string) => pkg(scope, name),
+	version: (scope: string, name: string, version: string) => `${pkg(scope, name)}/versions/${version}`,
+	readme: (scope: string, name: string, version: string) => `${pkg(scope, name)}/versions/${version}/readme`,
+	/** 302 to a signed R2 link; counts one download. */
+	tarball: (scope: string, name: string, version: string) => `${pkg(scope, name)}/versions/${version}/tarball`,
+	/** Raw file, same-origin: text as text/plain, sniffed raster images inline, everything else as an attachment. */
+	file: (scope: string, name: string, version: string, path: string) =>
+		`${pkg(scope, name)}/versions/${version}/files/${path}`,
+	source: (scope: string, name: string, version: string, path: string) =>
+		`${pkg(scope, name)}/versions/${version}/source/${path}`,
+	publish: (scope: string, name: string, version: string) => `${pkg(scope, name)}/versions/${version}`,
+	tag: (scope: string, name: string, tag: string) => `${pkg(scope, name)}/tags/${tag}`,
+	yank: (scope: string, name: string, version: string) => `${pkg(scope, name)}/versions/${version}/yank`,
+	deprecate: (scope: string, name: string, version: string) => `${pkg(scope, name)}/versions/${version}/deprecate`,
+	owner: (scope: string, name: string, username: string) => `${pkg(scope, name)}/owners/${username}`,
+	report: (scope: string, name: string) => `${pkg(scope, name)}/report`,
+	takedown: (scope: string, name: string) => `/api/v1/admin/skills/@${scope}/${name}/takedown`,
+	user: (username: string) => `/api/v1/users/${username}`,
+	tokens: "/api/v1/tokens",
+	token: (id: string) => `/api/v1/tokens/${id}`,
+	orgs: "/api/v1/orgs",
+	orgMember: (org: string, username: string) => `/api/v1/orgs/${org}/members/${username}`,
+	importSkill: "/api/v1/import",
+	me: "/api/me",
+	/** Web pages. */
+	pages: {
+		package: (scope: string, name: string) => `/@${scope}/${name}`,
+		user: (username: string) => `/~${username}`,
+		search: (query: string) => `/search?q=${encodeURIComponent(query)}`,
+	},
+} as const;

package/src/stream.ts

@@ -0,0 +1,169 @@
+/**
+ * Wire types for `omp stream`: Twitch-style live screen sharing at
+ * `live.omp.sh/<username>`.
+ *
+ * Independent from collab. A publisher (`omp stream`) sends plaintext JSON
+ * screen deltas for one or more panes (one pane per omp session attached in
+ * the same working directory); the stream server materializes each pane
+ * (viewport + bounded history) so late viewers receive a snapshot without
+ * touching the publisher, fans frames out to viewers, and hosts chat.
+ *
+ * Rows are terminal lines carrying only SGR and OSC 8 escapes; the publisher
+ * strips every other sequence, truncates to the pane width, and redacts
+ * secrets before a row leaves the session process.
+ */
+
+/** Default stream server; its host route derives the channel from the bearer identity. */
+export const DEFAULT_STREAM_URL = "https://live.omp.sh";
+
+/** Protocol version carried in `hello`/`snapshot`; the server rejects mismatches. */
+export const STREAM_PROTO = 1;
+
+/** Channel names are Stencil usernames: lowercase letters, numbers, and underscores; 3–32 chars. */
+export const STREAM_CHANNEL_NAME_RE = /^[a-z0-9][a-z0-9_]{2,31}$/;
+
+/** Longest accepted stream and pane title. */
+export const STREAM_TITLE_MAX = 120;
+/** Longest accepted chat display name. */
+export const STREAM_CHAT_NAME_MAX = 24;
+/** Longest accepted chat message. */
+export const STREAM_CHAT_TEXT_MAX = 500;
+/** History rows the server retains per pane; older rows fall off the top. */
+export const STREAM_HISTORY_LIMIT = 2000;
+
+/** One terminal row: ANSI text limited to SGR + OSC 8, width-truncated. */
+export type StreamRow = string;
+
+/**
+ * Per-pane screen deltas. `pane` ids are assigned by the publisher and are
+ * unique for the lifetime of one host connection.
+ *
+ * - `history` appends rows committed above the viewport (append-only).
+ * - `viewport` replaces the whole live viewport.
+ * - `patch` rewrites individual viewport rows; `rows` is the new viewport
+ *   length (shrinks drop trailing rows, growth fills with empty rows before
+ *   ops apply).
+ * - `reset` clears history and viewport (the session cleared its screen).
+ */
+export type StreamPaneFrame =
+	| { t: "pane-open"; pane: number; title: string; cols: number; rows: number }
+	| { t: "pane-close"; pane: number }
+	| { t: "resize"; pane: number; cols: number; rows: number }
+	| { t: "history"; pane: number; rows: StreamRow[] }
+	| { t: "viewport"; pane: number; rows: StreamRow[] }
+	| { t: "patch"; pane: number; ops: [index: number, row: StreamRow][]; rows: number }
+	| { t: "reset"; pane: number }
+	| { t: "paused"; pane: number; paused: boolean };
+
+/** Publisher → server. `hello` is the first frame on the socket. */
+export type StreamHostFrame =
+	| { t: "hello"; proto: number; title: string }
+	| { t: "title"; title: string }
+	/** Message typed by the streamer; broadcast with `host: true`. */
+	| { t: "chat"; text: string }
+	| StreamPaneFrame;
+
+export interface StreamChatMessage {
+	/** Monotonic per channel-session; viewers use it for de-duplication. */
+	id: number;
+	name: string;
+	text: string;
+	/** Unix milliseconds. */
+	ts: number;
+	/** Set when the streamer sent it. */
+	host?: boolean;
+}
+
+/** Server → publisher. */
+export type StreamServerToHost =
+	/** `user` is the stencil.so username the bearer resolved to; shown as the host's chat name. */
+	| { t: "welcome"; proto: number; channel: string; url: string; user?: string }
+	| { t: "viewers"; n: number }
+	| { t: "chat"; msg: StreamChatMessage }
+	| { t: "error"; message: string };
+
+/** Directory entry served by `GET /api/channels` and `GET /api/channels/<name>`. */
+export interface StreamChannelInfo {
+	name: string;
+	title: string;
+	live: boolean;
+	viewers: number;
+	panes: number;
+	/** stencil.so username of the channel owner (the first authenticated host). */
+	owner?: string;
+	/** Unix milliseconds of the current live session; absent when offline. */
+	startedAt?: number;
+}
+
+/** Materialized pane state delivered to a joining viewer. */
+export interface StreamPaneSnapshot {
+	id: number;
+	title: string;
+	cols: number;
+	rows: number;
+	history: StreamRow[];
+	viewport: StreamRow[];
+	paused: boolean;
+}
+
+/**
+ * Server → viewer. `snapshot` is the first frame after connect and again
+ * whenever the publisher reconnects; `offline` means the publisher left and
+ * the viewer should keep the socket open for the next `snapshot`.
+ */
+export type StreamServerToViewer =
+	| {
+			t: "snapshot";
+			proto: number;
+			channel: StreamChannelInfo;
+			panes: StreamPaneSnapshot[];
+			chat: StreamChatMessage[];
+	  }
+	| { t: "offline" }
+	| { t: "title"; title: string }
+	| { t: "viewers"; n: number }
+	| { t: "chat"; msg: StreamChatMessage }
+	| StreamPaneFrame;
+
+/** Viewer → server. The display name travels with each message until accounts exist. */
+export type StreamViewerFrame = { t: "chat"; name: string; text: string };
+
+/** WebSocket close codes used by the stream server. */
+export const STREAM_CLOSE_HOST_CONFLICT = 4009;
+export const STREAM_CLOSE_BAD_CHANNEL = 4004;
+export const STREAM_CLOSE_PROTO_MISMATCH = 4010;
+/** Host bearer token missing, expired, or not issued by the stencil.so issuer. */
+export const STREAM_CLOSE_UNAUTHORIZED = 4401;
+/** Channel is owned by a different stencil.so account. */
+export const STREAM_CLOSE_FORBIDDEN = 4403;
+
+/** Provider id under which `/login` stores the stencil.so credential; `STENCIL_API_KEY` overrides it. */
+export const STREAM_AUTH_PROVIDER = "stencil";
+export const STREAM_AUTH_ENV = "STENCIL_API_KEY";
+
+/** Longest accepted clip description (runes). Titles share `STREAM_TITLE_MAX`. */
+export const CLIP_DESCRIPTION_MAX = 5000;
+
+/**
+ * `POST /api/clips` answer. The body is an `.ompcast` recording (optionally
+ * `Content-Encoding: gzip`) whose header may carry `title` and `description`;
+ * the bearer identifies the uploading Stencil account.
+ */
+export interface ClipUploadResponse {
+	id: string;
+	/** Public clip page, `<server>/c/<id>`. */
+	url: string;
+}
+
+/** HTTP/WS route layout of the stream server, relative to `DEFAULT_STREAM_URL`. */
+export const STREAM_ROUTES = {
+	channels: "/api/channels",
+	channel: (name: string) => `/api/channels/${name}`,
+	/** The server derives the host channel from the authenticated username. */
+	host: "/ws/host",
+	watch: (name: string) => `/ws/watch/${name}`,
+	page: (name: string) => `/${name}`,
+	/** Clip upload (bearer-authenticated `POST`). */
+	clips: "/api/clips",
+	clipPage: (id: string) => `/c/${id}`,
+} as const;