From 1ea2f0e2d6fab549fffbfa7e50d72717140c8cd5 Mon Sep 17 00:00:00 2001 From: Devin Foley Date: Tue, 11 Aug 2026 08:47:32 -0700 Subject: [PATCH] feat(cli): add 'paperclipai channels' to show release lanes and the current one (#11210) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - The release channels (canary → nightly → beta → stable) select by install target, and users discover them today only through maintainer-oriented docs > - A user who wants to know "which lane am I on, and what else is there" has no self-serve answer > - The channel rollout planned a read-only CLI command for exactly this > - This pull request adds `paperclipai channels`: every lane with the version its dist-tag resolves to, the install command for it, and which lane the running install follows > - The benefit is self-serve lane discovery without reading release documentation ## Linked Issues or Issue Description Refs #11008 — the user-facing discovery surface for the channel model completed there. **Subsystem affected** CLI: `cli/src/commands/channels.ts` (new), `cli/src/index.ts`, `doc/CHANNELS.md`, tests. **Problem or motivation** Channel selection is install-based (`@latest` / `@beta` / `@nightly` / `@canary`), but nothing in the product tells a user which channel their install follows or what the other lanes currently resolve to. The information lives in `doc/CHANNELS.md` and the npm registry, neither of which a running install surfaces. **Proposed solution** A read-only `paperclipai channels` command: prints each channel with the version its dist-tag currently resolves to (per-lane registry lookups that degrade to `unavailable` individually), the install command for each, and the running install's lane parsed from its version suffix — source checkouts carry the repository's placeholder version and are reported as unmapped rather than guessed. `--json` emits the same data for scripting. ## What Changed - `cli/src/commands/channels.ts` (new): channel table, lane parsing, registry resolution, human and `--json` output - `cli/src/index.ts`: registers `channels` - `doc/CHANNELS.md`: "Seeing where you are" section - `cli/src/__tests__/channels.test.ts` (new): lane parsing including unknown versions, full resolution against a fake runner, per-lane degradation, table/dist-tag sync ## Verification - `vitest run cli/src/__tests__/channels.test.ts`: 5 pass - `pnpm typecheck` in `cli/` - Live run against the real registry shows all four lanes with their current versions (`2026.722.0` / `2026.811.0-beta.0` / `2026.811.0-nightly.0` / canary) and correctly reports a source checkout as unmapped ## Risks - Low. Read-only command reusing the existing `resolvePublishedVersion` registry helper; no state, no auth, no publish surface ## Model Used Claude Fable 5 (`claude-fable-5`, Anthropic) in Claude Code, with extended thinking and full tool use. All changes model-authored under human direction. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green (pending — will confirm before merge) - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups (pending — will confirm before merge) - [x] I will address all Greptile and reviewer comments before requesting merge --- cli/src/__tests__/channels.test.ts | 81 ++++++++++++++++++++ cli/src/commands/channels.ts | 119 +++++++++++++++++++++++++++++ cli/src/index.ts | 9 +++ doc/CHANNELS.md | 10 +++ 4 files changed, 219 insertions(+) create mode 100644 cli/src/__tests__/channels.test.ts create mode 100644 cli/src/commands/channels.ts diff --git a/cli/src/__tests__/channels.test.ts b/cli/src/__tests__/channels.test.ts new file mode 100644 index 0000000000..97c0ad6222 --- /dev/null +++ b/cli/src/__tests__/channels.test.ts @@ -0,0 +1,81 @@ +import { describe, expect, it } from "vitest"; +import { + channelForVersion, + collectChannelState, + RELEASE_CHANNELS, +} from "../commands/channels.js"; +import type { CommandRunner } from "../commands/install.js"; + +describe("channelForVersion", () => { + it("maps published versions to their lane", () => { + expect(channelForVersion("2026.811.0")).toBe("stable"); + expect(channelForVersion("2026.811.0-beta.0")).toBe("beta"); + expect(channelForVersion("2026.811.0-nightly.0")).toBe("nightly"); + expect(channelForVersion("2026.811.0-canary.3")).toBe("canary"); + }); + + it("treats non-CalVer versions as unknown instead of guessing", () => { + expect(channelForVersion("0.3.1")).toBe("unknown"); + expect(channelForVersion("2026.811.0-rc.1")).toBe("unknown"); + expect(channelForVersion("garbage")).toBe("unknown"); + }); +}); + +describe("collectChannelState", () => { + const versionsByTag: Record = { + latest: "2026.722.0", + beta: "2026.811.0-beta.0", + nightly: "2026.811.0-nightly.0", + canary: "2026.811.0-canary.3", + }; + + const fakeRunner: CommandRunner = async (_command, args) => { + const spec = (args ?? []).find((arg) => arg.startsWith("paperclipai@")); + const tag = spec?.slice("paperclipai@".length) ?? ""; + const version = versionsByTag[tag]; + if (!version) throw new Error(`unexpected dist-tag: ${tag}`); + return { stdout: JSON.stringify(version), stderr: "" }; + }; + + it("resolves every channel's dist-tag from the registry", async () => { + const state = await collectChannelState(fakeRunner); + + expect(state.map((entry) => entry.channel)).toEqual([ + "stable", + "beta", + "nightly", + "canary", + ]); + expect(state.map((entry) => entry.version)).toEqual([ + "2026.722.0", + "2026.811.0-beta.0", + "2026.811.0-nightly.0", + "2026.811.0-canary.3", + ]); + }); + + it("degrades a single unavailable channel to null without failing the rest", async () => { + const flakyRunner: CommandRunner = async (command, args, options) => { + const spec = (args ?? []).find((arg) => arg.startsWith("paperclipai@")); + if (spec === "paperclipai@nightly") throw new Error("registry timeout"); + return fakeRunner(command, args, options); + }; + + const state = await collectChannelState(flakyRunner); + const byChannel = Object.fromEntries(state.map((entry) => [entry.channel, entry.version])); + + expect(byChannel.nightly).toBeNull(); + expect(byChannel.stable).toBe("2026.722.0"); + expect(byChannel.beta).toBe("2026.811.0-beta.0"); + expect(byChannel.canary).toBe("2026.811.0-canary.3"); + }); + + it("keeps the channel table and dist-tags in sync", () => { + expect(RELEASE_CHANNELS.map((entry) => entry.distTag)).toEqual([ + "latest", + "beta", + "nightly", + "canary", + ]); + }); +}); diff --git a/cli/src/commands/channels.ts b/cli/src/commands/channels.ts new file mode 100644 index 0000000000..3fe211b495 --- /dev/null +++ b/cli/src/commands/channels.ts @@ -0,0 +1,119 @@ +import { execFile } from "node:child_process"; +import { promisify } from "node:util"; +import pc from "picocolors"; +import { resolvePublishedVersion, type CommandRunner } from "./install.js"; +import { packageVersion } from "../version.js"; + +const execFileAsync = promisify(execFile); + +const defaultRunCommand: CommandRunner = (command, args, options) => + execFileAsync(command, args, { ...options, encoding: "utf8" }); + +export type ChannelName = "stable" | "beta" | "nightly" | "canary"; + +export type ChannelDescriptor = { + channel: ChannelName; + distTag: string; + cadence: string; + audience: string; +}; + +// Ordered from most to least stable — the order users should consider them. +export const RELEASE_CHANNELS: readonly ChannelDescriptor[] = [ + { + channel: "stable", + distTag: "latest", + cadence: "manual, soaked in beta for 3+ days", + audience: "the recommended release for almost everyone", + }, + { + channel: "beta", + distTag: "beta", + cadence: "manual promotion behind an approval gate", + audience: "release candidates: what stable becomes a few days later", + }, + { + channel: "nightly", + distTag: "nightly", + cadence: "once a night, smoke-gated", + audience: "yesterday's merges, tested as a unit", + }, + { + channel: "canary", + distTag: "canary", + cadence: "every merge to master", + audience: "the bleeding edge", + }, +]; + +const CALVER_RE = /^\d{4}\.\d{1,4}\.\d+$/; +const PRERELEASE_RE = /^\d{4}\.\d{1,4}\.\d+-(canary|nightly|beta)\.\d+$/; + +// Published versions carry their lane in the version string; the source +// checkout's package.json holds a placeholder that matches neither form. +export function channelForVersion(version: string): ChannelName | "unknown" { + const prerelease = version.match(PRERELEASE_RE); + if (prerelease) return prerelease[1] as ChannelName; + if (CALVER_RE.test(version)) return "stable"; + return "unknown"; +} + +export type ChannelState = ChannelDescriptor & { version: string | null }; + +export async function collectChannelState( + runCommand: CommandRunner = defaultRunCommand, +): Promise { + const resolved = await Promise.allSettled( + RELEASE_CHANNELS.map((entry) => resolvePublishedVersion(entry.distTag, runCommand)), + ); + return RELEASE_CHANNELS.map((entry, index) => { + const outcome = resolved[index]; + return { + ...entry, + version: outcome.status === "fulfilled" ? outcome.value : null, + }; + }); +} + +export type ChannelsOptions = { json?: boolean }; + +export async function channelsCommand( + options: ChannelsOptions = {}, + runCommand: CommandRunner = defaultRunCommand, +): Promise { + const state = await collectChannelState(runCommand); + const currentChannel = channelForVersion(packageVersion); + + if (options.json) { + console.log( + JSON.stringify( + { + current: { version: packageVersion, channel: currentChannel }, + channels: state, + }, + null, + 2, + ), + ); + return; + } + + console.log(pc.bold("Paperclip release channels")); + console.log(""); + for (const entry of state) { + const version = entry.version ?? pc.yellow("unavailable"); + console.log(` ${pc.bold(entry.channel.padEnd(8))} ${version}`); + console.log(` ${" ".repeat(8)} ${pc.dim(`${entry.cadence} — ${entry.audience}`)}`); + console.log(` ${" ".repeat(8)} ${pc.dim(`npx paperclipai@${entry.distTag} onboard`)}`); + console.log(""); + } + + if (currentChannel === "unknown") { + console.log( + `This install reports version ${pc.bold(packageVersion)}, which does not map to a published channel (source checkouts report the repository placeholder).`, + ); + } else { + console.log(`This install is version ${pc.bold(packageVersion)} on the ${pc.bold(currentChannel)} channel.`); + } + console.log(`Docker images use the same names: ghcr.io/paperclipai/paperclip:{latest,beta,nightly,canary}`); +} diff --git a/cli/src/index.ts b/cli/src/index.ts index fd8d1ee4f7..b26b5cbe18 100644 --- a/cli/src/index.ts +++ b/cli/src/index.ts @@ -2,6 +2,7 @@ import { Command } from "commander"; import { onboard } from "./commands/onboard.js"; import { doctor } from "./commands/doctor.js"; import { envCommand } from "./commands/env.js"; +import { channelsCommand } from "./commands/channels.js"; import { configure } from "./commands/configure.js"; import { addAllowedHostname } from "./commands/allowed-hostname.js"; import { heartbeatRun } from "./commands/heartbeat-run.js"; @@ -130,6 +131,14 @@ program .option("-d, --data-dir ", DATA_DIR_OPTION_HELP) .action(envCommand); +program + .command("channels") + .description("Show the release channels and which one this install follows") + .option("--json", "Machine-readable output") + .action(async (opts) => { + await channelsCommand(opts); + }); + program .command("configure") .description("Update configuration sections") diff --git a/doc/CHANNELS.md b/doc/CHANNELS.md index b99ae33a3d..f809a386fc 100644 --- a/doc/CHANNELS.md +++ b/doc/CHANNELS.md @@ -56,6 +56,16 @@ docker pull ghcr.io/paperclipai/paperclip:canary Every image is also published as `:sha-` for exact pinning, and stable images additionally get `:YYYY.MDD.P` version tags. +## Seeing where you are + +```bash +npx paperclipai channels +``` + +prints every channel with the version it currently resolves to, the install +command for each, and which channel your install follows (with `--json` for +scripting). + ## Switching channels Channel choice is per-install: install from a different tag and you're on that