@linxiraos/pi-wire 1.1.19 → 1.1.22

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+## [1.1.22] - 2026-09-30
+
+- 随 1.1.22 版本线发布;无面向用户的行为变化。
+
 ## [1.1.19] - 2026-09-22
 
 - 版本线推进;本版无独立用户可见变化。

package/THIRD-PARTY-NOTICES.txt

@@ -78,8 +78,8 @@ below.
 uutils coreutils (https://github.com/uutils/coreutils), MIT
 --------------------------------------------------------------------------------
 Covers: base32, base64, basename, cat, cksum (shared checksum machinery),
-b2sum, md5sum, sha1sum, sha224sum, sha256sum, sha384sum, sha512sum, comm, cut,
-date, dirname, head, hostname, ln, ls, mkdir, mktemp, mv, nproc, paste,
+b2sum, md5sum, sha1sum, sha224sum, sha256sum, sha384sum, sha512sum, comm, cp,
+cut, date, dirname, head, hostname, ln, ls, mkdir, mktemp, mv, nproc, paste,
 printenv, readlink, realpath, rm, seq, sort, stat, tac, tail, tee, touch, tr,
 truncate, uname, uniq, wc, whoami, yes.
 
@@ -293,7 +293,7 @@ MIT License
 Copyright (c) 2026 Sander Land
   (measured tokenizer vocabulary data, reconstruction model, and reference
   implementation: https://github.com/sanderland/ctok)
-Copyright (c) 2026 Can Bölük and the Oh My Pi contributors
+Copyright (c) 2026 Can Bölük and the omp contributors
 Copyright (c) 2026 Stencil Labs, Inc.
   (Rust implementation and the compact binary vocabulary encoding in
   crates/pi-natives/src/utok/claude)
@@ -335,43 +335,6 @@ This license allows the work and adaptations of it to be shared and used
 commercially, as long as it is attributed to Poppy Works. The font is bundled
 here (crates/pi-natives/src/fonts/Silver.ttf) as a CJK/Unicode bitmap fallback.
 
--------------------------------------------------------------------------------
-packages/utils/src/vendor/mermaid-ascii/NOTICE
-
-This directory contains an in-house Mermaid-diagram-to-ASCII renderer adapted
-from beautiful-mermaid (https://github.com/lukilabs/beautiful-mermaid), used
-under the MIT License.
-
-  Copyright (c) 2026 Craft Docs
-
-Only the ASCII rendering pipeline is ported (flowchart/state, sequence, class,
-ER, and xychart diagrams); the SVG renderer and its `elkjs` graph-layout
-dependency, the browser entry point, and the SVG theme/style modules were
-dropped. Terminal display width is reimplemented on `Bun.stringWidth`, and
-inline label formatting (HTML tags, markdown emphasis) is reduced to plain text
-for ASCII output. Layout and edge-routing logic is preserved faithfully so
-ASCII output matches the upstream package.
-
-MIT License
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-
 -------------------------------------------------------------------------------
 packages/coding-agent/src/markit/NOTICE
 

package/dist/types/skillshare.d.ts

@@ -0,0 +1,293 @@
+/**
+ * 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 declare const DEFAULT_SKILLS_URL = "https://skills.omp.sh";
+/** Scopes are Stencil usernames (or registry orgs): lowercase letters, digits, underscores; 3–32 chars. */
+export declare const SKILL_SCOPE_RE: RegExp;
+/** Registry skill names: ASCII kebab-case, 1–64 chars, no leading/trailing/double hyphens. */
+export declare const SKILL_NAME_RE: RegExp;
+export declare const SKILL_NAME_MAX = 64;
+/** `@scope/name`, optionally `@version-or-range-or-tag`. */
+export declare const SKILL_SPEC_RE: RegExp;
+/** Publish limits, enforced by both the CLI and the server. */
+export declare const SKILL_LIMITS: {
+    /** Compressed `.tgz` upload. */
+    readonly tarballBytes: number;
+    /** Sum of all file sizes after unpacking. */
+    readonly unpackedBytes: number;
+    readonly files: 1000;
+    /** Longest path inside the package. */
+    readonly pathLength: 255;
+    readonly descriptionLength: 1024;
+    readonly keywords: 20;
+    readonly keywordLength: 50;
+    readonly deprecationLength: 500;
+};
+/** Paths excluded from packs in addition to `.skillignore` entries. */
+export declare const SKILL_DEFAULT_IGNORES: readonly [".git", ".DS_Store", "node_modules", "__pycache__", "*.pyc", "evals", ".skillignore"];
+/**
+ * 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 declare const SKILL_HEADERS: {
+    /** Required: SRI `sha512-<base64>` of the body. */
+    readonly integrity: "X-Skill-Integrity";
+    /** Optional dist-tag to point at the new version (default `latest` for stable, none for prereleases). */
+    readonly tag: "X-Skill-Tag";
+    /** Optional base64(JSON {@link SkillReportedProvenance}); shown as "reported". */
+    readonly provenance: "X-Skill-Provenance";
+    /** Optional GitHub Actions OIDC token (audience {@link SKILLS_OIDC_AUDIENCE}); verified server-side. */
+    readonly githubOidc: "X-Skill-GitHub-OIDC";
+};
+/** Audience CI must request for GitHub Actions OIDC tokens. */
+export declare const SKILLS_OIDC_AUDIENCE = "skills.omp.sh";
+/** Env var holding a registry publish token for CI (`sks_…`); wins over the Stencil login. */
+export declare 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;
+}
+/**
+ * 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 declare const SKILLS_ROUTES: {
+    readonly home: "/api/v1/home";
+    readonly search: "/api/v1/search";
+    readonly packument: (scope: string, name: string) => string;
+    readonly version: (scope: string, name: string, version: string) => string;
+    readonly readme: (scope: string, name: string, version: string) => string;
+    /** 302 to a signed R2 link; counts one download. */
+    readonly tarball: (scope: string, name: string, version: string) => string;
+    /** Raw file, same-origin: text as text/plain, sniffed raster images inline, everything else as an attachment. */
+    readonly file: (scope: string, name: string, version: string, path: string) => string;
+    readonly source: (scope: string, name: string, version: string, path: string) => string;
+    readonly publish: (scope: string, name: string, version: string) => string;
+    readonly tag: (scope: string, name: string, tag: string) => string;
+    readonly yank: (scope: string, name: string, version: string) => string;
+    readonly deprecate: (scope: string, name: string, version: string) => string;
+    readonly owner: (scope: string, name: string, username: string) => string;
+    readonly report: (scope: string, name: string) => string;
+    readonly takedown: (scope: string, name: string) => string;
+    readonly user: (username: string) => string;
+    readonly tokens: "/api/v1/tokens";
+    readonly token: (id: string) => string;
+    readonly orgs: "/api/v1/orgs";
+    readonly orgMember: (org: string, username: string) => string;
+    readonly importSkill: "/api/v1/import";
+    readonly me: "/api/me";
+    /** Web pages. */
+    readonly pages: {
+        readonly package: (scope: string, name: string) => string;
+        readonly user: (username: string) => string;
+        readonly search: (query: string) => string;
+    };
+};

package/dist/types/stream.d.ts

@@ -179,6 +179,18 @@ export declare const STREAM_CLOSE_FORBIDDEN = 4403;
 /** Provider id under which `/login` stores the stencil.so credential; `STENCIL_API_KEY` overrides it. */
 export declare const STREAM_AUTH_PROVIDER = "stencil";
 export declare const STREAM_AUTH_ENV = "STENCIL_API_KEY";
+/** Longest accepted clip description (runes). Titles share `STREAM_TITLE_MAX`. */
+export declare 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 declare const STREAM_ROUTES: {
     readonly channels: "/api/channels";
@@ -187,4 +199,7 @@ export declare const STREAM_ROUTES: {
     readonly host: "/ws/host";
     readonly watch: (name: string) => string;
     readonly page: (name: string) => string;
+    /** Clip upload (bearer-authenticated `POST`). */
+    readonly clips: "/api/clips";
+    readonly clipPage: (id: string) => string;
 };

package/package.json

@@ -1,8 +1,8 @@
 {
 	"type": "module",
 	"name": "@linxiraos/pi-wire",
-	"version": "1.1.19",
-	"description": "Shared wire protocol types for Oh My Pi packages",
+	"version": "1.1.22",
+	"description": "Shared wire protocol types for omp packages",
 	"homepage": "https://linxira-os.github.io/zeta/",
 	"author": "Can Boluk",
 	"license": "MIT",
@@ -27,8 +27,7 @@
 		"check:types": "tsgo -p tsconfig.json --noEmit",
 		"lint": "oxlint .",
 		"fix": "oxlint --fix --fix-suggestions . && bun run fmt",
-		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'",
-		"test": "bun test --parallel"
+		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14"

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

@@ -141,6 +141,20 @@ export const STREAM_CLOSE_FORBIDDEN = 4403;
 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",
@@ -149,4 +163,7 @@ export const STREAM_ROUTES = {
 	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;