gentle-pi 3.3.0 → 3.5.0

package/tests/shell-usage.test.ts

@@ -7,15 +7,20 @@ import {
 	parseAnthropicHeaders,
 	parseCodexHeaders,
 	parseNanQuota,
+	parseProviderUsage,
 	parseUsageHeaders,
 	parseCodexUsage,
+	parseUsageSource,
 	providerNote,
 	renderUsageBar,
 	renderUsagePanel,
 	SUPPORTED_USAGE_PROVIDERS,
+	UsageSourceRegistry,
+	USAGE_SOURCE_SCHEMA,
 	UsageStore,
 	windowLabel,
 	type ProviderUsage,
+	type UsageSource,
 	type UsageWindow,
 } from "../lib/shell-usage.ts";
 
@@ -243,6 +248,130 @@ test("nan is a supported usage provider with its own pending note", () => {
 	assert.deepEqual(renderUsagePanel([], plainTheme, 100, NOW, { provider: "nan" }), ["✿ nan · no usage yet · r to fetch"]);
 });
 
+// A generic hook: any extension can register a usage source for its own
+// provider at runtime, without gentle-shell knowing anything about it.
+
+test("parseUsageSource validates the registration payload and ignores anything malformed", () => {
+	const fetchFn = async () => undefined;
+	const valid = parseUsageSource({ schema: USAGE_SOURCE_SCHEMA, provider: "acme-cloud", fetch: fetchFn });
+	assert.equal(valid?.schema, USAGE_SOURCE_SCHEMA);
+	assert.equal(valid?.provider, "acme-cloud");
+	assert.equal(valid?.fetch, fetchFn);
+	assert.equal(valid?.pendingNote, undefined);
+
+	const withNote = parseUsageSource({ schema: USAGE_SOURCE_SCHEMA, provider: "acme-cloud", pendingNote: "warming up", fetch: fetchFn });
+	assert.equal(withNote?.pendingNote, "warming up");
+
+	assert.equal(parseUsageSource({ schema: "gentle-pi.usage-source/v0", provider: "acme-cloud", fetch: fetchFn }), undefined, "wrong schema");
+	assert.equal(parseUsageSource({ schema: USAGE_SOURCE_SCHEMA, provider: "", fetch: fetchFn }), undefined, "empty provider");
+	assert.equal(parseUsageSource({ schema: USAGE_SOURCE_SCHEMA, provider: "acme cloud", fetch: fetchFn }), undefined, "unsafe provider id");
+	assert.equal(parseUsageSource({ schema: USAGE_SOURCE_SCHEMA, provider: "acme-cloud", fetch: "nope" }), undefined, "fetch not a function");
+	assert.equal(parseUsageSource({ schema: USAGE_SOURCE_SCHEMA, provider: "acme-cloud", pendingNote: 7, fetch: fetchFn }), undefined, "pendingNote must be a string when present");
+	assert.equal(parseUsageSource(null), undefined);
+	assert.equal(parseUsageSource(undefined), undefined);
+	assert.equal(parseUsageSource("acme-cloud"), undefined);
+	assert.equal(parseUsageSource({}), undefined);
+});
+
+test("UsageSourceRegistry replaces a provider's source on re-registration", () => {
+	const registry = new UsageSourceRegistry();
+	assert.equal(registry.has("acme-cloud"), false);
+	assert.equal(registry.get("acme-cloud"), undefined);
+	assert.equal(registry.note("acme-cloud"), undefined);
+
+	const first: UsageSource = { schema: USAGE_SOURCE_SCHEMA, provider: "acme-cloud", fetch: async () => undefined };
+	registry.register(first);
+	assert.equal(registry.has("acme-cloud"), true);
+	assert.equal(registry.get("acme-cloud"), first);
+	assert.equal(registry.note("acme-cloud"), "no usage yet · r to fetch", "default note when the source sets none");
+
+	const second: UsageSource = { schema: USAGE_SOURCE_SCHEMA, provider: "acme-cloud", pendingNote: "still warming up", fetch: async () => undefined };
+	registry.register(second);
+	assert.equal(registry.get("acme-cloud"), second, "re-registration replaces, never accumulates");
+	assert.equal(registry.note("acme-cloud"), "still warming up");
+});
+
+test("a registered provider is supported without touching the built-in note map", () => {
+	const registry = new UsageSourceRegistry();
+	assert.equal(providerNote("acme-cloud"), "no subscription usage for this provider");
+	assert.equal(providerNote("acme-cloud", registry), "no subscription usage for this provider", "an empty registry changes nothing");
+	registry.register({ schema: USAGE_SOURCE_SCHEMA, provider: "acme-cloud", fetch: async () => undefined });
+	assert.equal(providerNote("acme-cloud", registry), "no usage yet · r to fetch");
+	assert.equal(providerNote("nan", registry), "no usage yet · r to fetch", "the static built-ins are unaffected");
+	assert.deepEqual(renderUsagePanel([], plainTheme, 100, NOW, { provider: "acme-cloud" }, registry), ["✿ acme-cloud · no usage yet · r to fetch"]);
+});
+
+// A registered source's resolved value crosses the same trust boundary a
+// parsed HTTP payload does. parseProviderUsage validates it exactly like
+// one, and the object gentle-shell records is always freshly built, never
+// the caller's own reference.
+
+const VALID_SOURCE_USAGE = {
+	provider: "acme-cloud",
+	plan: "Acme · 42 credits",
+	fetchedAt: 100,
+	limits: [
+		{
+			name: "acme-cloud",
+			limitReached: false,
+			windows: [
+				{ label: "week", usedPercent: 40, windowSeconds: 604_800, resetAt: null },
+				{ label: "day", usedPercent: 12, windowSeconds: 86_400, resetAt: 200, used: 5, budget: 40 },
+			],
+		},
+	],
+};
+
+test("parseProviderUsage accepts a matching shape and copies it defensively", () => {
+	const source = structuredClone(VALID_SOURCE_USAGE);
+	const parsed = parseProviderUsage(source, "acme-cloud");
+	assert.deepEqual(parsed, source);
+	assert.notEqual(parsed, source, "the recorded object must never be the caller's own reference");
+	assert.notEqual(parsed?.limits, source.limits);
+	assert.notEqual(parsed?.limits[0], source.limits[0]);
+	assert.notEqual(parsed?.limits[0].windows, source.limits[0].windows);
+	assert.notEqual(parsed?.limits[0].windows[0], source.limits[0].windows[0]);
+
+	// Mutating the caller's own object after the fact must never reach the copy.
+	source.limits[0].windows[0].usedPercent = 999;
+	assert.equal(parsed?.limits[0].windows[0].usedPercent, 40);
+});
+
+test("parseProviderUsage rejects a resolution for a different provider", () => {
+	assert.equal(parseProviderUsage(structuredClone(VALID_SOURCE_USAGE), "other-provider"), undefined);
+});
+
+test("parseProviderUsage rejects a missing or malformed limits array", () => {
+	assert.equal(parseProviderUsage({ provider: "acme-cloud", plan: undefined, fetchedAt: 0 }, "acme-cloud"), undefined, "limits missing entirely");
+	assert.equal(parseProviderUsage({ provider: "acme-cloud", plan: undefined, fetchedAt: 0, limits: "nope" }, "acme-cloud"), undefined, "limits not an array");
+	assert.equal(
+		parseProviderUsage({ provider: "acme-cloud", plan: undefined, fetchedAt: 0, limits: [{ name: "x", limitReached: "nope", windows: [] }] }, "acme-cloud"),
+		undefined,
+		"limitReached must be a boolean",
+	);
+});
+
+test("parseProviderUsage rejects a non-numeric usedPercent inside a window", () => {
+	const usage = structuredClone(VALID_SOURCE_USAGE);
+	(usage.limits[0].windows[0] as unknown as { usedPercent: unknown }).usedPercent = "40";
+	assert.equal(parseProviderUsage(usage, "acme-cloud"), undefined);
+});
+
+test("parseProviderUsage rejects a limit whose windows is not an array", () => {
+	const usage = structuredClone(VALID_SOURCE_USAGE);
+	(usage.limits[0] as unknown as { windows: unknown }).windows = "nope";
+	assert.equal(parseProviderUsage(usage, "acme-cloud"), undefined);
+});
+
+test("parseProviderUsage rejects malformed inputs outright", () => {
+	assert.equal(parseProviderUsage(undefined, "acme-cloud"), undefined);
+	assert.equal(parseProviderUsage(null, "acme-cloud"), undefined);
+	assert.equal(parseProviderUsage("acme-cloud", "acme-cloud"), undefined);
+	assert.equal(parseProviderUsage({ provider: "acme-cloud", plan: 7, fetchedAt: 0, limits: [] }, "acme-cloud"), undefined, "plan must be a string when present");
+	assert.equal(parseProviderUsage({ provider: "acme-cloud", plan: undefined, fetchedAt: Number.POSITIVE_INFINITY, limits: [] }, "acme-cloud"), undefined, "fetchedAt must be finite");
+	assert.deepEqual(parseProviderUsage({ provider: "acme-cloud", plan: undefined, fetchedAt: 0, limits: [] }, "acme-cloud"), { provider: "acme-cloud", plan: undefined, fetchedAt: 0, limits: [] });
+});
+
 test("renderUsagePanel lists each NaN model allowance with its reset on the same row", () => {
 	const usage = parseNanQuota(NAN_QUOTA, NOW);
 	const lines = renderUsagePanel([usage], plainTheme, 80, NOW, { provider: "nan" });

package/tests/skill-collision-prefixes.test.ts

@@ -25,7 +25,7 @@ const PREFIXED_NAMES: Record<string, string> = {
 	"work-unit-commits": "gentle-ai-work-unit-commits",
 };
 
-const UNPREFIXED_DIRS = ["gentle-ai", "release"];
+const UNPREFIXED_DIRS = ["gentle-ai"];
 
 for (const [dir, expectedName] of Object.entries(PREFIXED_NAMES)) {
 	test(`skills/${dir}/SKILL.md frontmatter name is prefixed`, () => {

package/tests/startup-banner.test.ts

@@ -2,7 +2,9 @@ import assert from "node:assert/strict";
 import test from "node:test";
 import { syncBuiltinESMExports } from "node:module";
 import fs from "node:fs/promises";
-import { readFileSync } from "node:fs";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import startup, { readGitBranch } from "../extensions/startup-banner.ts";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { visibleWidth } from "@earendil-works/pi-tui";
@@ -74,6 +76,15 @@ test("startup branch lookup uses direct git argv and hides its Windows child", a
 });
 
 test("startup banner keeps animating after invalidate and cleans up on dispose", async (t) => {
+	const home = mkdtempSync(join(tmpdir(), "gp-banner-quality-"));
+	writeFileSync(join(home, "animations.json"), '{"schema":"gentle-pi.animations/v1","policy":"quality"}');
+	const previousHome = process.env.GENTLE_PI_CONFIG_HOME;
+	process.env.GENTLE_PI_CONFIG_HOME = home;
+	t.after(() => {
+		if (previousHome === undefined) delete process.env.GENTLE_PI_CONFIG_HOME;
+		else process.env.GENTLE_PI_CONFIG_HOME = previousHome;
+		rmSync(home, { recursive: true, force: true });
+	});
 	t.mock.timers.enable({ apis: ["setTimeout", "setInterval", "Date"] });
 	t.mock.method(fs, "readFile", async () => JSON.stringify({ showRose: true, showTextLogo: true, color: "pink" }));
 	syncBuiltinESMExports();
@@ -115,6 +126,85 @@ test("startup banner keeps animating after invalidate and cleans up on dispose",
 	assert.equal(renders, afterDispose, "session_shutdown cleanup stays idle");
 });
 
+test("animation modes retain banner lifetime policy, final artwork and approximate duration", async (t) => {
+	const home = mkdtempSync(join(tmpdir(), "gp-banner-animations-"));
+	const previousHome = process.env.GENTLE_PI_CONFIG_HOME;
+	process.env.GENTLE_PI_CONFIG_HOME = home;
+	t.after(() => {
+		if (previousHome === undefined) delete process.env.GENTLE_PI_CONFIG_HOME;
+		else process.env.GENTLE_PI_CONFIG_HOME = previousHome;
+		rmSync(home, { recursive: true, force: true });
+	});
+	t.mock.method(fs, "readFile", async () => JSON.stringify({ showRose: true, showTextLogo: true, color: "pink" }));
+	syncBuiltinESMExports();
+	t.after(() => { t.mock.restoreAll(); syncBuiltinESMExports(); });
+	const argv = process.argv;
+	process.argv = ["node"];
+	t.after(() => { process.argv = argv; });
+	for (const [key, value] of [["rows", 40], ["columns", 200]] as const) {
+		const descriptor = Object.getOwnPropertyDescriptor(process.stdout, key);
+		Object.defineProperty(process.stdout, key, { configurable: true, writable: true, value });
+		t.after(() => descriptor ? Object.defineProperty(process.stdout, key, descriptor) : Reflect.deleteProperty(process.stdout, key));
+	}
+	let boot: () => void;
+	let pulse: () => void;
+	let active = false;
+	let delay = 0;
+	let clock = 0;
+	let paints = 0;
+	t.mock.method(Date, "now", () => clock);
+	t.mock.method(globalThis, "setTimeout", (callback: () => void, ms: number) => {
+		if (ms === 50) boot = callback; // Never run operational stats/home reads.
+		return {};
+	});
+	t.mock.method(globalThis, "setInterval", (callback: () => void, ms: number) => {
+		pulse = callback; delay = ms; active = true; return {};
+	});
+	t.mock.method(globalThis, "clearInterval", () => { active = false; });
+	let start: (event: unknown, ctx: unknown) => Promise<void>;
+	let shutdown: () => void;
+	let header: { render(width: number): string[]; dispose(): void };
+	// Stroke warmup is module-global; keep duration driving isolated from cold-start tests.
+	const { default: isolatedStartup } = await import(new URL("../extensions/startup-banner.ts?animations", import.meta.url).href) as typeof import("../extensions/startup-banner.ts");
+	isolatedStartup({ on: (name: string, fn: typeof start) => {
+		if (name === "session_start") start = fn;
+		if (name === "session_shutdown") shutdown = fn as unknown as () => void;
+	}, registerCommand() {}, getCommands: () => [], getAllTools: () => [] } as unknown as ExtensionAPI);
+	const ctx = { hasUI: true, cwd: "/fixture", ui: { setHeader(factory: (tui: unknown, theme: unknown) => typeof header) {
+		header = factory({ requestRender() { paints++; } }, { fg: (_role: string, text: string) => text });
+	} } };
+	const save = (policy: string) => writeFileSync(join(home, "animations.json"), JSON.stringify({ schema: "gentle-pi.animations/v1", policy }));
+	try {
+		save("potato");
+		await start!({}, ctx); boot!();
+		assert.equal(active, false, "potato starts no animation interval");
+		const staticArt = stripAnsi(header!.render(200).join("\n"));
+		assert.match(staticArt, /[▄▀█]/);
+		assert.match(staticArt, /[\u2800-\u28ff]/);
+		header!.dispose();
+		let qualityDuration = 0;
+		let qualityPaints = 0;
+		for (const policy of ["quality", "performance"]) {
+			save(policy);
+			await start!({}, ctx); boot!();
+			for (let i = 0; i < 15; i++) await new Promise<void>((resolve) => setImmediate(resolve));
+			assert.equal(delay, policy === "quality" ? 25 : 250);
+			save("potato"); // Already-created animation keeps its policy.
+			const began = clock;
+			const before = paints;
+			while (active && clock - began <= 5500) { clock += delay; pulse!(); }
+			assert.equal(active, false, "finishes and clears the interval");
+			assert.equal(stripAnsi(header!.render(200).join("\n")), staticArt);
+			if (policy === "quality") { qualityDuration = clock - began; qualityPaints = paints - before; }
+			else {
+				assert.ok(Math.abs(clock - began - qualityDuration) <= 250);
+				assert.ok(paints - before <= Math.ceil(qualityPaints / 10));
+			}
+			header!.dispose();
+		}
+	} finally { shutdown!(); }
+});
+
 // Drive the real header factory; background git/home reads never run.
 for (const showRose of [false, true]) for (const showTextLogo of [false, true]) {
 	test(`startup art respects rose=${showRose}, logo=${showTextLogo} and cyan palette`, async (t) => {
@@ -134,7 +224,8 @@ for (const showRose of [false, true]) for (const showTextLogo of [false, true])
 		let shutdown: Function;
 		let header: { render(width: number): string[]; dispose(): void };
 		const writes: string[] = [];
-		startup({ on: (name: string, fn: Function) => {
+		const { default: coldStartup } = await import(new URL(`../extensions/startup-banner.ts?art-${showRose}-${showTextLogo}`, import.meta.url).href) as typeof import("../extensions/startup-banner.ts");
+		coldStartup({ on: (name: string, fn: Function) => {
 			if (name === "session_start") start = fn;
 			if (name === "session_shutdown") shutdown = fn;
 		}, registerCommand() {}, getCommands: () => [], getAllTools: () => [] } as unknown as ExtensionAPI);

package/skills/release/SKILL.md

@@ -1,137 +0,0 @@
----
-name: release
-description: "Release gentle-pi through GitHub and npm. Trigger: release, publish, npm publish, GitHub release, version bump."
-license: Apache-2.0
-metadata:
-  author: gentleman-programming
-  version: "1.2"
----
-
-## When to Use
-
-Use this skill when preparing, publishing, or verifying a `gentle-pi` release.
-
-## Hard Rules
-
-- Do not publish `gentle-pi` to npm from a local machine.
-- npm publishing MUST go through the GitHub Actions workflow `.github/workflows/publish.yml` so provenance, environment protection, and registry credentials are controlled by GitHub.
-- Dispatch the trusted workflow definition from protected default `main`, never from a release tag. Its only caller input is the exact annotated version tag.
-- Use a clean worktree for release commits. Do not package unrelated local files or scratch artifacts.
-- Review outcomes are informational. Release delivery follows ordinary repository policy and must not be blocked, authorized, or rewritten by RDD.
-- Never infer the release tag target from local `HEAD`; use the freshly fetched `origin/main` commit and the repository's normal release safeguards.
-- Never skip package verification. The publish workflow runs verification again, but local validation should still pass before tagging.
-
-## Release Procedure
-
-1. **Inspect state**
-
-   ```bash
-   git status --short
-   git fetch origin main --tags
-   git log --oneline --decorate --max-count=5 origin/main
-   ```
-
-2. **Prepare the release commit**
-
-   - Apply only intended changes.
-   - Bump `package.json` to the next semver version.
-   - Keep lockfile changes out unless dependency resolution actually changed.
-
-3. **Verify locally**
-
-   ```bash
-   pnpm test
-   node scripts/verify-package-files.mjs
-   npm pack --dry-run
-   ```
-
-   `npm pack --dry-run` verifies package contents and lifecycle scripts without entering a publish path.
-
-4. **Commit and push**
-
-   ```bash
-   git add <intended-files>
-   git commit -m "<type(scope): release-ready change>"
-   git push origin HEAD:main
-   git fetch origin main --tags
-   ```
-
-5. **Create and verify the exact version tag**
-
-   ```bash
-   version="$(node -p "require('./package.json').version")"
-   tag="v${version}"
-   release_sha="$(git rev-parse 'origin/main^{commit}')"
-
-   test "$(git rev-parse 'HEAD^{commit}')" = "${release_sha}"
-   test -z "$(git ls-remote --tags origin "refs/tags/${tag}")"
-
-   git tag -a "${tag}" "${release_sha}" -m "gentle-pi ${tag}"
-   test "$(git rev-parse "${tag}^{commit}")" = "${release_sha}"
-
-   git fetch origin main
-   test "$(git rev-parse 'origin/main^{commit}')" = "${release_sha}"
-   git push origin "refs/tags/${tag}"
-
-   git fetch --no-tags origin "refs/tags/${tag}"
-   test "$(git rev-parse 'FETCH_HEAD^{commit}')" = "${release_sha}"
-
-   gh release create "${tag}" \
-     --repo Gentleman-Programming/gentle-pi \
-     --verify-tag \
-     --title "gentle-pi ${tag}" \
-     --notes "<release notes>"
-   ```
-
-   Do not retag or overwrite an existing version. The tag target comes from the freshly fetched immutable `origin/main` commit, not an ambient local branch.
-
-6. **Publish npm through GitHub Actions**
-
-   ```bash
-   version="$(node -p "require('./package.json').version")"
-   tag="v${version}"
-   gh workflow run publish.yml \
-     --repo Gentleman-Programming/gentle-pi \
-     --ref main \
-     -f tag="${tag}"
-   ```
-
-   The workflow definition always comes from protected default `main`. It accepts only one exact `vSemVer` tag, fetches the remote annotated tag and current remote `main`, and requires the peeled tag commit, dispatch/main workflow commit, checkout, and `package.json` version to match. It re-queries remote tag and `main` immediately before npm publication, derives the dist-tag internally, and uses trusted OIDC with provenance.
-
-   Watch the run and fail the release if it fails:
-
-   ```bash
-   gh run list --repo Gentleman-Programming/gentle-pi --workflow publish.yml --limit 3
-   gh run watch <run-id> --repo Gentleman-Programming/gentle-pi --exit-status
-   ```
-
-7. **Verify npm**
-
-   ```bash
-   npm view gentle-pi@<version> version --registry=https://registry.npmjs.org/
-   npm dist-tag ls gentle-pi --registry=https://registry.npmjs.org/
-   ```
-
-## Failure Handling
-
-- A publication failure is handled through ordinary repository policy. It does not reopen or alter a review lineage.
-- Never attempt or retry `npm publish` locally. Re-dispatch from trusted `main` only when the same tag still targets the current remote `main` and the failure was publication-only.
-- If remote `main` advances, do not move or recreate the existing tag. Prepare a new release commit/version and create a new annotated version tag.
-- If the workflow fails, inspect logs with:
-
-  ```bash
-  gh run view <run-id> --repo Gentleman-Programming/gentle-pi --log
-  ```
-
-- If npm verification is briefly stale after a successful workflow, check the exact version first (`npm view gentle-pi@<version> version`) before assuming publish failed.
-
-## Output Contract
-
-Report:
-
-- Commit SHA pushed to `main`.
-- Exact version tag and its peeled commit SHA.
-- GitHub release URL.
-- Publish workflow run URL and conclusion.
-- npm exact version and the workflow-derived dist-tag (`latest`, `beta`, or `next`).
-- Any remaining follow-up or warnings.