From 598266f68a5cbc410b8b1482179953e288157ed6 Mon Sep 17 00:00:00 2001 From: hyscodebase <193484132+hyscodebase@users.noreply.github.com> Date: Tue, 3 Nov 2026 15:44:53 +0900 Subject: [PATCH] Make the default demo concise and honor detail output --- CHANGELOG.md | 7 +++++++ README.md | 17 ++++++++++------- docs/README.ko.md | 7 ++++++- docs/npm-publishing.md | 11 ++++++----- package-lock.json | 4 ++-- package.json | 2 +- src/cli.ts | 4 ++-- src/report.ts | 24 ++++++++++++++++++++++++ test/cli.test.ts | 14 ++++++++++++-- 9 files changed, 70 insertions(+), 20 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0dd67ce..cc8b272 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,12 @@ # Changelog +## 0.1.0-alpha.5 — 2026-11-03 + +- Show the built-in demo as a short onboarding example with readable enabled + states, a clear synthetic-data label, and an executable next capture step. +- Honor `demo --detail` instead of always printing the detailed report. Preserve + the JSON comparison and real snapshot comparison reports. + ## 0.1.0-alpha.4 — 2026-11-03 - Recommend the public npm `alpha` installation in the English and Korean diff --git a/README.md b/README.md index d00a8e6..1c3ed50 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ SkillWhy compares the skills that fresh Codex CLI processes discover. Capture tw ![A 42-second synthetic CLI demo: compare, inspect, preview a selected share, then compare the shares](https://raw.githubusercontent.com/hyscodebase/skillwhy/main/assets/demo.gif) -Actual CLI output from synthetic fixtures, shown as excerpts. [Video](https://github.com/hyscodebase/skillwhy/blob/main/assets/demo.mp4) · [Full transcript](https://github.com/hyscodebase/skillwhy/blob/main/assets/demo-transcript.txt). This demonstrates the workflow; external user outcomes are still being evaluated. +Actual alpha.3 CLI output from synthetic fixtures, shown as excerpts. The current default demo is shorter; `demo --detail` retains the diagnostic report. [Video](https://github.com/hyscodebase/skillwhy/blob/main/assets/demo.mp4) · [Full transcript](https://github.com/hyscodebase/skillwhy/blob/main/assets/demo-transcript.txt). This demonstrates the workflow; external user outcomes are still being evaluated. ## Try the offline demo @@ -30,16 +30,19 @@ skillwhy demo Use the explicit `alpha` tag while prereleases are being evaluated. [GitHub release tarballs](https://github.com/hyscodebase/skillwhy/releases) with SHA-256 checksums remain available. From a checkout, use `npm ci`, then `npm run demo`; replace `skillwhy` below with `node dist/src/cli.js`. ```text -SkillWhy · skill discovery comparison -SYNTHETIC EXAMPLE — NOT A LIVE SCAN +SkillWhy · demo complete +Synthetic example; your project was not scanned. -key:demo:release-review · enabled-changed - true → false [observed] +release-review: enabled → disabled -Model selected/read/executed a skill: NOT OBSERVED -Existing Desktop session: NOT ASSESSED +1 difference between two sample snapshots. +Scope: discovery metadata. No model or Desktop session was inspected. ``` +This is the built-in example, not a capture of your environment. The command also +prints the next capture step. Use `demo --detail` for the full evidence notes or +`demo --json` for the structured comparison. + ## Capture and compare ```sh diff --git a/docs/README.ko.md b/docs/README.ko.md index 11a75c9..f12aec0 100644 --- a/docs/README.ko.md +++ b/docs/README.ko.md @@ -5,7 +5,8 @@ Codex CLI를 새로 실행해 발견 목록을 수집하고 두 환경을 비교 ![합성 데이터로 보여주는 42초 CLI 데모](https://raw.githubusercontent.com/hyscodebase/skillwhy/main/assets/demo.gif) -실제 CLI 출력의 일부를 사용한 합성 예시입니다. [영상](https://github.com/hyscodebase/skillwhy/blob/main/assets/demo.mp4)과 [전체 출력 기록](https://github.com/hyscodebase/skillwhy/blob/main/assets/demo-transcript.txt)도 제공합니다. +alpha.3 CLI 출력의 일부를 사용한 합성 예시입니다. 현재 기본 demo는 더 짧고, +`demo --detail`로 상세 보고서를 볼 수 있습니다. [영상](https://github.com/hyscodebase/skillwhy/blob/main/assets/demo.mp4)과 [전체 출력 기록](https://github.com/hyscodebase/skillwhy/blob/main/assets/demo-transcript.txt)도 제공합니다. Node.js 22 이상이 있다면 한 줄로 데모를 실행할 수 있습니다. @@ -26,6 +27,10 @@ skillwhy demo 데모는 합성 데이터이며 API 키와 Codex 설치가 필요하지 않습니다. 실제 수집은 검증된 Codex/OS 조합만 지원합니다. +기본 demo는 예제 Skill의 `enabled → disabled` 차이와 실제 수집을 시작하는 +명령을 보여줍니다. 내 환경을 검사한 결과는 아닙니다. 긴 근거 설명은 +`demo --detail`, 구조화된 결과는 `demo --json`으로 확인할 수 있습니다. + 핵심 명령은 `demo`, `capture`, `inspect`, `diff`, `share`입니다. 사용법은 [영문 README](../README.md), 지원 범위는 [호환성 문서](compatibility.md)를 참고하세요. diff --git a/docs/npm-publishing.md b/docs/npm-publishing.md index e28847a..d4d00f5 100644 --- a/docs/npm-publishing.md +++ b/docs/npm-publishing.md @@ -88,8 +88,9 @@ before the clean-install checks above. ## Distribution tags -Use the explicit `alpha` tag or an exact prerelease version. After the initial -publication npm also assigned `latest` to alpha.3. An authenticated attempt to -remove that tag returned HTTP 400, so it still points to alpha.3; alpha.4 is -available through `@alpha` and `@0.1.0-alpha.4`. The package has no stable release. -This tag state does not change the verified alpha.4 artifact or its provenance. +Use the explicit `alpha` tag or an exact prerelease version. At the alpha.4 +publication, npm's initial `latest` tag still pointed to alpha.3 after an +authenticated removal returned HTTP 400. The `alpha` tag moves with subsequent +prereleases; check `npm view @hyscodebase/skillwhy dist-tags` for its current target. +Exact versions such as `@0.1.0-alpha.4` retain their original artifacts and +provenance. The package has no stable release. diff --git a/package-lock.json b/package-lock.json index 8fe3c39..45ec873 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@hyscodebase/skillwhy", - "version": "0.1.0-alpha.4", + "version": "0.1.0-alpha.5", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@hyscodebase/skillwhy", - "version": "0.1.0-alpha.4", + "version": "0.1.0-alpha.5", "license": "MIT", "bin": { "skillwhy": "dist/src/cli.js" diff --git a/package.json b/package.json index 56cd32b..5e19f80 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@hyscodebase/skillwhy", - "version": "0.1.0-alpha.4", + "version": "0.1.0-alpha.5", "description": "Compare the skills your Codex CLI environments actually discover.", "type": "module", "license": "MIT", diff --git a/src/cli.ts b/src/cli.ts index 9b4a4d8..6aed6a4 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -6,7 +6,7 @@ import { compareSnapshots } from "./compare.js"; import { createShareBundle } from "./share.js"; import { readSnapshot, writeSnapshot } from "./io.js"; import { demoSnapshots } from "./demo.js"; -import { display, renderCapture, renderComparison } from "./report.js"; +import { display, renderCapture, renderComparison, renderDemo } from "./report.js"; import { inspectSnapshot, renderInspection } from "./inspect.js"; import { VERSION } from "./version.js"; @@ -68,7 +68,7 @@ async function main(): Promise { if (command === "demo") { const [left, right] = demoSnapshots(); const comparison = compareSnapshots(left, right); - console.log(values.json ? JSON.stringify(comparison, null, 2) : renderComparison(comparison, true)); + console.log(values.json ? JSON.stringify(comparison, null, 2) : renderDemo(comparison, values.detail ?? false)); return comparison.status === "complete" ? 0 : 2; } if (command === "capture") { diff --git a/src/report.ts b/src/report.ts index 0907c45..a79144a 100644 --- a/src/report.ts +++ b/src/report.ts @@ -6,6 +6,30 @@ export function display(value: unknown): string { return String(value ?? "unknown").replace(/[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/g, " "); } +/** Keep the built-in onboarding example separate from real diagnostic reports. */ +export function renderDemo(result: Comparison, detail = false): string { + const next = [ + "Next: run this from your own project with a supported Codex CLI:", + " npx --yes @hyscodebase/skillwhy@alpha capture --cwd . --out before.snapshot.json", + ]; + if (detail || !result.synthetic) return [renderComparison(result, detail), "", ...next].join("\n"); + const lines = [ + `SkillWhy · demo ${result.status}`, + "Synthetic example; your project was not scanned.", + "", + ]; + for (const difference of result.differences) { + const label = display(difference.key.replace(/^key:demo:/, "")); + const value = (input: unknown): string => difference.kind === "enabled-changed" && typeof input === "boolean" + ? input ? "enabled" : "disabled" : display(input); + lines.push(`${label}: ${value(difference.before)} → ${value(difference.after)}`); + } + lines.push("", `${result.differences.length} difference${result.differences.length === 1 ? "" : "s"} between two sample snapshots.`, + "Scope: discovery metadata. No model or Desktop session was inspected.", + "", ...next, "", "Full explanation: npx --yes @hyscodebase/skillwhy@alpha demo --detail"); + return lines.join("\n"); +} + export function renderComparison(result: Comparison, detail = false): string { const lines = [ "SkillWhy · skill discovery comparison", diff --git a/test/cli.test.ts b/test/cli.test.ts index 5d819e2..58a15f8 100644 --- a/test/cli.test.ts +++ b/test/cli.test.ts @@ -26,8 +26,18 @@ test("offline demo is explicitly synthetic and detects the disabled entry", asyn assert.equal(value.synthetic, true); assert.ok(value.differences.some((d: { kind: string }) => d.kind === "enabled-changed")); const human = await run(["demo"]); - assert.match(human.stdout, /SYNTHETIC EXAMPLE/); - assert.match(human.stdout, /NOT OBSERVED/); + assert.equal(human.code, 0, human.stderr); + assert.match(human.stdout, /Synthetic example; your project was not scanned/); + assert.match(human.stdout, /release-review: enabled → disabled/); + assert.match(human.stdout, /No model or Desktop session was inspected/); + assert.match(human.stdout, /npx --yes @hyscodebase\/skillwhy@alpha capture --cwd \./); + assert.doesNotMatch(human.stdout, /NOT OBSERVED|NOT ASSESSED|Note:/); + const detailed = await run(["demo", "--detail"]); + assert.equal(detailed.code, 0, detailed.stderr); + assert.match(detailed.stdout, /SYNTHETIC EXAMPLE/); + assert.match(detailed.stdout, /NOT OBSERVED/); + assert.match(detailed.stdout, /Note:/); + assert.deepEqual(JSON.parse((await run(["demo", "--json", "--detail"])).stdout), value); }); test("bad arguments consistently fail with exit 2", async () => {