@manhquy/flow-skill 0.1.0-rc.1 → 0.1.0-rc.2

package/CHANGELOG.md

@@ -2,9 +2,91 @@
 
 All notable changes to `@manhquy/flow-skill`. Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning: [SemVer](https://semver.org/).
 
+## [0.1.0-rc.2] — 2026-07-17 (not yet published — see release command below)
+
+Ships `skills/flow` v0.22.0 (concierge front-door + standalone native rituals — see the root
+repo's CHANGELOG.md `## 0.22.0` entry for the full skill-content changelog). This wrapper
+release fixes the actual reported installer bug, adds a 5th install target (Cursor), and fixes
+two hardening items found while verifying it all.
+
+### Fixed — the reported symptom (A0)
+- **Antigravity users installing via `npx` got no guidance and saw a silent `/flow`-not-found.**
+  A freshly-installed skill isn't discovered by an agent until it reloads; the post-install
+  summary line only ever told Claude + Codex users what to do. Every installed target now gets
+  its own restart/reload hint (`bin/cli.mjs`'s `doneLine()`, `install.sh`, `install.ps1` — all
+  three entry points, built from the actual installed-targets list, not a static string).
+
+### Fixed — hardening found during verification
+- `scripts/sync.mjs` baked an **absolute local filesystem path** (e.g. `D:\project\flow\...`)
+  into `skills-manifest.json`'s `source` field, and that file ships inside the published
+  tarball (`package.json` `files:`) — leaking local machine layout and being non-reproducible
+  across dev machines/CI. Now emits a repo-relative `"../skills/flow"` (or a literal
+  `"$FLOW_SKILL_SRC (override)"` marker when the env override is used).
+- `pretest: node scripts/sync.mjs` — the bundled `skills/flow/` tree is gitignored
+  (regenerated by `npm run sync`/`prepack`); a fresh checkout now gets it automatically before
+  `npm test` instead of failing with a missing/stale bundle.
+- `--test-concurrency=1` pinned on the `test` script — the two new real (non-dry-run) CLI
+  install tests below, run in parallel with `lock-atomicity.test.mjs`'s own child-process
+  spawns, intermittently starved on Windows (spurious non-zero exit unrelated to any of the
+  three files' own logic, confirmed by serialized re-runs going 38/38 green repeatedly vs an
+  occasional false-red in parallel). Total suite time impact: negligible (~1-2s).
+
+### Added — 5th install target: Cursor
+- New `cursor` target → `~/.cursor/skills/flow`. **Marker is `.cursor/skills`, never bare
+  `.cursor`** — the bare dir holds unrelated editor config (settings, caches, `argv.json`) that
+  exists for every Cursor user, and a bare marker would have silently auto-installed flow under
+  `--yes` for anyone with Cursor installed at all (the exact false-positive class the existing
+  Antigravity `~/.gemini` guard already dodges).
+- **Path confirmed by a live probe on the dev machine, not documentation/web research**: found a
+  real pre-existing symlink `~/.cursor/skills/find-skills -> ~/.agents/skills/find-skills`,
+  empirically proving Cursor's actual skill-read location and that it already consumes content
+  from the universal Agent-Skills home (see below).
+- `agents` target relabeled "Agents home — universal Agent-Skills home" — it's the shared
+  directory the open Agent Skills standard ([agentskills.io](https://agentskills.io), Anthropic,
+  now stewarded by the Agentic AI Foundation) defines, which spec-compliant tools beyond this
+  installer's named targets (Cursor confirmed; ~30 others per the standard's adoption) can read.
+- **Honesty limit, not overclaim**: Cursor has no discoverable headless CLI (`cursor agent --help`
+  falls through to generic IDE flags, no `-p`/`exec` print-mode). Unlike Antigravity (`agy -p`)
+  and Codex (`codex exec`), the installed skill's *runner execution* inside Cursor is not
+  independently live-verified here — install correctness is (real scratch-`$HOME` test, content
+  lands at the confirmed path). README/CHANGELOG say "install verified, runner not yet
+  independently confirmed" rather than claiming parity with the other two targets.
+- `--all` now installs 5 targets; every "4 target(s)" mention across `--help`, both root READMEs,
+  and both npm-wrapper READMEs updated to 5 (the count in `--help` is now derived from
+  `TARGETS.length` so it cannot drift again).
+
+### Added — tests
+- `test/detect.test.mjs`: 2 new cases — bare `.cursor` does NOT trigger detection (the
+  false-positive regression guard), `.cursor/skills` present → detected at the confirmed dest.
+- `test/cli.test.mjs`: three REAL (non-dry-run, scratch-`$HOME`) installs asserting the Done-line
+  restart hint — `antigravity` alone, `cursor` alone (this one caught a real bug: the Done-line
+  printed empty for a cursor-only install because Cursor wasn't yet in `RESTART_HINTS` when it
+  was written — fixed same-session), and `claude,codex` (proving the old Codex hint survives and
+  no unrelated agent line leaks in).
+- `test/sync-manifest.test.mjs`: asserts `skills-manifest.json.source` is never an absolute path.
+- `tests/test_flow_antigravity_integration.sh` (root repo bash suite): 4 new assertions —
+  both `install.sh` and `install.ps1` carry the Antigravity restart/reload hint, and the old
+  hardcoded Claude+Codex-only Done line is gone from both.
+
+### Release command (operator-gated — not run by this change)
+```
+cd npm-wrapper && npm test   # confirm green first
+git tag npm@0.1.0-rc.2 && git push --tags   # triggers .github/workflows/publish-npm-wrapper.yml
+```
+
 ## [0.1.0-rc.1] — 2026-07-12
 
-Initial release candidate. Ships to the `rc` npm dist-tag.
+**LIVE on npm**: https://www.npmjs.com/package/@manhquy/flow-skill
+
+Initial release candidate. Published manually to bootstrap npm Trusted Publisher (which requires the package to exist first). rc.2+ will be published from CI with OIDC + SLSA L2 provenance.
+
+Publish details (for the record):
+- Method: Granular Access Token with `Bypass 2FA` (created + used + revoked within 60s from the maintainer's local machine).
+- No provenance on this bootstrap version (`npm publish --provenance` requires a supported CI environment; laptop publish is not).
+- Dist-tags at publish: `{rc: 0.1.0-rc.1, latest: 0.1.0-rc.1}` — npm auto-populated `latest` on first publish. Docs advise pinning `@rc` or `@0.1.0-rc.1` explicitly.
+- Tarball: 76 files, 203 KB gzipped, 566 KB unpacked.
+
+Ships to the `rc` npm dist-tag.
 
 ### Post-implementation audit fixes (before first publish)
 - **installer:** `acquireLock` was TOCTOU-racy — switched to atomic `writeFileSync(..., { flag: 'wx' })` so two `npx` runs cannot both acquire.

package/README.md

@@ -5,41 +5,18 @@ One-command installer that copies the [flow](https://github.com/manhquydev/flow-
 - Pure Node — works on macOS, Linux, and Windows (cmd, PowerShell 5.1/7, Git Bash) with the same code path.
 - Interactive multi-select or non-interactive CI mode.
 - Preserves any user-added files in the destination outside the 6 subdirs the skill owns.
-- Ships with [npm provenance](https://docs.npmjs.com/generating-provenance-statements) via GitHub Actions trusted publishing (from rc.2+).
-
-## Status — 2026-07-12
-
-- ✅ Code complete, 35/35 tests green, CI matrix green (ubuntu/macos/windows × Node 22/24).
-- ⏳ Not yet on npm registry. Repo public + renamed; transfer to `manhquy` account pending accept; first publish (`v0.1.0-rc.1`, manual, no provenance) queued.
-- ➡️ Once published, this section will disappear and `npx @manhquy/flow-skill@rc` becomes the canonical install path.
+- Ships with [npm provenance](https://docs.npmjs.com/generating-provenance-statements) via GitHub Actions trusted publishing **starting with rc.2** — rc.1 was a manual bootstrap because npm Trusted Publisher cannot bind to a package that does not yet exist.
 
 ## Install
 
-**A. From the git repo (works today, no npm registry needed)**
-
-```bash
-git clone https://github.com/manhquydev/flow-skill.git
-cd flow-skill/npm-wrapper
-npm install
-npm run sync          # materializes skills/flow from ../skills/flow
-npm link              # exposes `flow-skill` as a global command
-
-flow-skill --yes --all --dry-run --json   # smoke check
-flow-skill                                # interactive install
 ```
-
-To remove: `npm unlink -g @manhquy/flow-skill`.
-
-**B. Via npx (once published)**
-
-```
-# Pre-release channel (RC candidate — will exist after first publish)
+# Pre-release channel (current — v0.1.0-rc.2)
 npx @manhquy/flow-skill@rc
 ```
 
 An interactive prompt asks which agents to install to. Pick one or more, confirm, done.
 
-> **RC phase**: pin `@rc` (dist-tag) or a specific version like `@0.1.0-rc.1`. `npx @manhquy/flow-skill@0.1.x` will start working after stable `0.1.0` is published — semver ranges do **not** match pre-release tuples by default. See [SECURITY.md](./SECURITY.md).
+> **RC phase**: pin `@rc` (dist-tag) or a specific version like `@0.1.0-rc.2`. `npx @manhquy/flow-skill@0.1.x` will start working after stable `0.1.0` is published — semver ranges do **not** match pre-release tuples by default. See [SECURITY.md](./SECURITY.md).
 
 ## Non-interactive
 
@@ -51,7 +28,7 @@ npx @manhquy/flow-skill@rc --yes
 npx @manhquy/flow-skill@rc --yes -t claude -t codex
 npx @manhquy/flow-skill@rc --yes -t claude,codex           # comma form OK
 
-# Force all four targets even if not detected
+# Force all five targets even if not detected
 npx @manhquy/flow-skill@rc --yes --all
 
 # Project scope (Claude only — see below)
@@ -67,16 +44,25 @@ npx @manhquy/flow-skill@rc --yes --all --dry-run --json
 |---|---|---|---|
 | `claude` | Claude Code | `~/.claude/skills/flow` | any presence of `~/.claude` (Claude is always pre-checked) |
 | `codex` | Codex CLI | `~/.codex/skills/flow` | `~/.codex/skills` |
-| `agents` | Agents home | `~/.agents/skills/flow` | `~/.agents/skills` |
+| `agents` | Agents home — also the universal [Agent-Skills](https://agentskills.io) home other spec-compliant tools read | `~/.agents/skills/flow` | `~/.agents/skills` |
 | `antigravity` | Antigravity (CLI + IDE) | `~/.gemini/antigravity-cli/skills/flow` **and** `~/.gemini/config/skills/flow` | `~/.gemini/antigravity-cli` **or** `~/.gemini/config/skills` |
+| `cursor` | Cursor | `~/.cursor/skills/flow` | `~/.cursor/skills` (never the bare `~/.cursor` config dir every Cursor user has) |
 
 `--project` scope writes to `<dir>/.claude/skills/flow` and supports only the `claude` target. Combining `--project` with a non-Claude target exits with code `2`.
 
 ## After install
 
+A freshly-installed skill isn't discovered by an agent until it reloads — the installer's final
+line tells you exactly what to do for whichever targets you installed:
+
 - Claude Code: type `/flow`.
-- Codex CLI: type `$flow` (restart Codex once to load).
-- Antigravity: `/flow` in the IDE.
+- Codex CLI: type `$flow` (restart Codex once to load a new skill).
+- Antigravity: restart/reload the IDE (or restart `agy`) to load the new skill, then type `/flow`.
+- Agents home: restart/reload your tool if it does not auto-detect new skills.
+- Cursor: **install verified, live runner execution not yet independently confirmed** — Cursor
+  has no headless CLI probe available for automated verification (unlike Antigravity's `agy -p`
+  or Codex's `codex exec`); restart/reload Cursor after install and check the Agent panel for
+  the `flow` skill.
 - Diagnostics: run `/flow doctor` from your agent.
 
 ## Uninstall
@@ -100,7 +86,7 @@ rm -rf <project>/.claude/skills/flow
 - **Windows `EBUSY` / `EPERM` mid-install**: an agent (Claude Code, Codex, Antigravity IDE) is holding a file inside the destination. Close the agent and re-run. The installer already retries with 100/300/900 ms backoff before surfacing the error.
 - **Stale advisory lock**: a prior run crashed. The next run detects the dead PID and reclaims the lock automatically. If it does not (very rare — the recorded PID was recycled by another live process), delete `<parent-of-dest>/.flow-skill.installing.lock`.
 - **`No matching version found` on `@0.1.x`**: you are trying to install a pre-release version through a stable range. Use `@rc` (dist-tag) or an explicit `@0.1.0-rc.N` until stable `0.1.0` ships.
-- **Node too old** (`requires Node.js >=20.11.0`): upgrade with your preferred version manager (`nvm install 20`, `fnm install 20`, or Node's official installer).
+- **Node too old** (`requires Node.js >=22.14.0`): upgrade with your preferred version manager (`nvm install 22`, `fnm install 22`, or Node's official installer). Node 20 reached end-of-life April 2026; npm OIDC Trusted Publishing needs npm >=11.5.1 which bundles with Node 22.14+.
 
 ## JSONL contract
 

package/README_VN.md

@@ -7,39 +7,16 @@ Trình cài đặt một-lệnh sao chép skill [flow](https://github.com/manhqu
 - Bảo toàn file người dùng đã thêm ngoài 6 subdir mà skill sở hữu.
 - Ship kèm [npm provenance](https://docs.npmjs.com/generating-provenance-statements) qua GitHub Actions trusted publishing (từ rc.2+).
 
-## Tình trạng — 2026-07-12
-
-- ✅ Code hoàn thiện, 35/35 test xanh, CI matrix xanh (ubuntu/macos/windows × Node 22/24).
-- ⏳ Chưa lên npm registry. Repo đã public + đã rename; transfer sang `manhquy` account đang chờ accept; first publish (`v0.1.0-rc.1`, thủ công, không có provenance) đang queued.
-- ➡️ Sau khi publish, section này sẽ biến mất và `npx @manhquy/flow-skill@rc` thành lệnh cài chính thức.
-
 ## Cài đặt
 
-**A. Từ git repo (chạy được ngay, không cần npm registry)**
-
-```bash
-git clone https://github.com/manhquydev/flow-skill.git
-cd flow-skill/npm-wrapper
-npm install
-npm run sync          # materialize skills/flow từ ../skills/flow
-npm link              # expose `flow-skill` như global command
-
-flow-skill --yes --all --dry-run --json   # smoke check
-flow-skill                                # cài tương tác
 ```
-
-Gỡ: `npm unlink -g @manhquy/flow-skill`.
-
-**B. Qua npx (sau khi publish)**
-
-```
-# Kênh pre-release (RC candidate — sẽ tồn tại sau first publish)
+# Kênh pre-release (hiện tại — v0.1.0-rc.2)
 npx @manhquy/flow-skill@rc
 ```
 
 Prompt tương tác hỏi cài vào agent nào. Chọn một hoặc nhiều, xác nhận, xong.
 
-> **Giai đoạn RC**: pin `@rc` (dist-tag) hoặc phiên bản cụ thể `@0.1.0-rc.1`. `npx @manhquy/flow-skill@0.1.x` chỉ dùng được sau khi stable `0.1.0` publish — semver range **không** match pre-release theo mặc định. Xem [SECURITY.md](./SECURITY.md).
+> **Giai đoạn RC**: pin `@rc` (dist-tag) hoặc phiên bản cụ thể `@0.1.0-rc.2`. `npx @manhquy/flow-skill@0.1.x` chỉ dùng được sau khi stable `0.1.0` publish — semver range **không** match pre-release theo mặc định. Xem [SECURITY.md](./SECURITY.md).
 
 ## Non-interactive
 
@@ -51,7 +28,7 @@ npx @manhquy/flow-skill@rc --yes
 npx @manhquy/flow-skill@rc --yes -t claude -t codex
 npx @manhquy/flow-skill@rc --yes -t claude,codex           # Dạng comma OK
 
-# Ép cài cả 4 target dù không detect
+# Ép cài cả 5 target dù không detect
 npx @manhquy/flow-skill@rc --yes --all
 
 # Project scope (chỉ Claude — xem bên dưới)
@@ -67,16 +44,24 @@ npx @manhquy/flow-skill@rc --yes --all --dry-run --json
 |---|---|---|---|
 | `claude` | Claude Code | `~/.claude/skills/flow` | bất kỳ presence của `~/.claude` (Claude luôn pre-check) |
 | `codex` | Codex CLI | `~/.codex/skills/flow` | `~/.codex/skills` |
-| `agents` | Agents home | `~/.agents/skills/flow` | `~/.agents/skills` |
+| `agents` | Agents home — cũng là thư mục [Agent-Skills](https://agentskills.io) chung mà các tool tuân chuẩn khác đọc | `~/.agents/skills/flow` | `~/.agents/skills` |
 | `antigravity` | Antigravity (CLI + IDE) | `~/.gemini/antigravity-cli/skills/flow` **và** `~/.gemini/config/skills/flow` | `~/.gemini/antigravity-cli` **hoặc** `~/.gemini/config/skills` |
+| `cursor` | Cursor | `~/.cursor/skills/flow` | `~/.cursor/skills` (không bao giờ dùng thư mục config `~/.cursor` trần — ai dùng Cursor cũng có) |
 
 Scope `--project` ghi vào `<dir>/.claude/skills/flow` và chỉ hỗ trợ target `claude`. Kết hợp `--project` với target khác → exit code `2`.
 
 ## Sau khi cài
 
+Skill vừa cài xong sẽ không được agent nhận ra cho tới khi agent reload — dòng cuối cùng của
+installer nói rõ việc cần làm cho đúng target đã cài:
+
 - Claude Code: gõ `/flow`.
-- Codex CLI: gõ `$flow` (restart Codex 1 lần để load).
-- Antigravity: `/flow` trong IDE.
+- Codex CLI: gõ `$flow` (restart Codex 1 lần để load skill mới).
+- Antigravity: restart/reload IDE (hoặc restart `agy`) để load skill mới, rồi gõ `/flow`.
+- Agents home: restart/reload tool nếu nó không tự nhận skill mới.
+- Cursor: **đã xác nhận cài đúng chỗ, chưa xác nhận runner chạy độc lập** — Cursor không có
+  CLI headless để tự động kiểm (khác `agy -p` của Antigravity hay `codex exec` của Codex);
+  restart/reload Cursor sau khi cài rồi kiểm tra panel Agent xem có skill `flow` không.
 - Chẩn đoán: chạy `/flow doctor` từ agent.
 
 ## Gỡ cài đặt
@@ -111,7 +96,7 @@ Hợp đồng additive trong `0.1.x` — field mới có thể thêm, field cũ
 - **`EBUSY`/`EPERM` giữa install trên Windows**: một agent đang giữ handle vào file trong destination. Đóng agent + re-run. Installer đã retry 100/300/900 ms trước khi báo error.
 - **Advisory lock cũ**: run trước crash. Run mới tự phát hiện PID dead → reclaim. Trường hợp hiếm (PID được recycle bởi process khác đang chạy): xóa `<parent-of-dest>/.flow-skill.installing.lock`.
 - **`No matching version found` với `@0.1.x`**: cài pre-release qua stable range. Dùng `@rc` hoặc `@0.1.0-rc.N` cho tới khi stable `0.1.0` ship.
-- **Node quá cũ** (`requires Node.js >=20.11.0`): update bằng `nvm install 20`, `fnm install 20`, hoặc installer chính thức của Node.
+- **Node quá cũ** (`requires Node.js >=22.14.0`): update bằng `nvm install 22`, `fnm install 22`, hoặc installer chính thức của Node. Node 20 hết vòng đời từ 4/2026; npm OIDC Trusted Publishing cần npm >=11.5.1 (bundle theo Node 22.14+).
 
 ## Yêu cầu
 

package/bin/cli.mjs

@@ -147,6 +147,29 @@ function humanResult(target, result) {
   return `${status} ${target} -> ${dests}${err}`;
 }
 
+// v0.23 A0 fix — the reported symptom: a user installs to a non-Claude agent, opens it, types
+// /flow, and sees nothing, because a freshly-installed skill isn't discovered until the agent
+// reloads. The old static message only told Claude+Codex users what to do; every installed
+// target now gets its own line so nobody is left guessing why /flow doesn't show up.
+const RESTART_HINTS = {
+  claude: 'Claude Code: type /flow',
+  codex: 'Codex CLI: type $flow (restart Codex once to load a new skill)',
+  antigravity:
+    'Antigravity: restart/reload the IDE (or restart `agy`) to load the new skill, then type /flow',
+  agents:
+    'Agents home (~/.agents/skills/): restart/reload your tool if it does not auto-detect new skills',
+  // Cursor has no headless CLI probe (unlike Antigravity's `agy -p` or Codex's `codex exec`) to
+  // independently verify the runner loads post-install — restart/reload guidance is still the
+  // correct advice (same discovery-on-reload mechanism), just without our own live confirmation
+  // that the Agent panel picks it up. See README's "After install" section for the caveat.
+  cursor: 'Cursor: restart/reload Cursor to load the new skill, then check the Agent panel for flow',
+};
+
+function doneLine(targets) {
+  const hints = targets.map((t) => RESTART_HINTS[t]).filter(Boolean);
+  return `Done. ${hints.join('  |  ')}`;
+}
+
 async function main() {
   const rawArgs = process.argv.slice(2);
   let opts;
@@ -346,10 +369,7 @@ async function main() {
   );
 
   if (!opts.json && success) {
-    log(
-      '\nDone. Claude Code: type /flow  |  Codex CLI: type $flow (restart Codex once).',
-      false
-    );
+    log(`\n${doneLine(plan.map((p) => p.target))}`, false);
   }
 
   // If aborted mid-loop, exit 130 (matches shell convention) instead of the generic failure.
@@ -360,6 +380,9 @@ async function main() {
 main().catch((err) => {
   // F2 — a crash inside main() must not truncate JSONL: emit a machine-parseable summary
   // before exit so CI consumers can distinguish "crashed" from "hung".
+  // Argv fallback: `--json` is a boolean flag with no alias in parseArgs config, so a raw
+  // string match on process.argv is safe today; if the flag ever gets an alias or
+  // `--json=true` form, hoist `jsonMode` to module scope from parseCliArgs instead.
   const isJson = process.argv.includes('--json');
   const message = err?.message ?? String(err);
   if (isJson) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@manhquy/flow-skill",
-  "version": "0.1.0-rc.1",
+  "version": "0.1.0-rc.2",
   "description": "Install the flow skill (buildflow gated build process) into your coding agent(s) via one npx command",
   "type": "module",
   "bin": {
@@ -23,7 +23,8 @@
   "scripts": {
     "sync": "node scripts/sync.mjs",
     "prepack": "node scripts/sync.mjs",
-    "test": "node --test test/installer.test.mjs test/detect.test.mjs test/cli.test.mjs test/lock-atomicity.test.mjs",
+    "pretest": "node scripts/sync.mjs",
+    "test": "node --test --test-concurrency=1 test/installer.test.mjs test/detect.test.mjs test/cli.test.mjs test/lock-atomicity.test.mjs test/sync-manifest.test.mjs",
     "smoke": "node scripts/smoke.mjs"
   },
   "dependencies": {