feat(cli): ensure safe execution without @latest and omit @latest from marketing

[yamcodes]

Fixes #1720

Summary of Changes

• CLI Version Freshness Pre-Flight Check: Added zero-dependency SemVer 2.0 comparator and registry checker with strict 1000ms timeout that fails open silently.
• Dist-Tag Awareness: Supports dynamic dist-tag querying (e.g. alpha for alpha pre-releases, latest for stable releases).
• Interactive Upgrade Prompt & DLX Runner: Interactively prompts user on outdated CLI versions during interactive TTY init executions to run latest release via package-manager-aware runner (pnpm dlx, bunx, yarn dlx, or npx) with full stdio: 'inherit' and signal forwarding.
• Process Signal Exit Codes: Correctly handles signal terminations (SIGINT -> 130, SIGTERM -> 143, other signals -> 1).
• Marketing & Documentation Cleanup: Omitted @latest across website install pills, documentation MDX guides, package READMEs, and missing-schema error hints.
• Targeted Base: v1 branch.

[changeset-bot]

⚠️ No Changeset found

Latest commit: c07667e

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[pkg-pr-new]

Open in StackBlitz

@arkenv/agent-plugin

npm i https://pkg.pr.new/@arkenv/agent-plugin@1725

arkenv

npm i https://pkg.pr.new/arkenv@1725

@arkenv/build

npm i https://pkg.pr.new/@arkenv/build@1725

@arkenv/bun-plugin

npm i https://pkg.pr.new/@arkenv/bun-plugin@1725

@arkenv/core

npm i https://pkg.pr.new/@arkenv/core@1725

@arkenv/fumadocs-ui

npm i https://pkg.pr.new/@arkenv/fumadocs-ui@1725

@arkenv/nextjs

npm i https://pkg.pr.new/@arkenv/nextjs@1725

@arkenv/nuxt

npm i https://pkg.pr.new/@arkenv/nuxt@1725

@arkenv/standard

npm i https://pkg.pr.new/@arkenv/standard@1725

@arkenv/vite-plugin

npm i https://pkg.pr.new/@arkenv/vite-plugin@1725

commit: c07667e

[pullfrog]

ℹ️ Minor suggestions only — the dist-tag plumbing is correctly realized and the check tests genuinely pin the new behavior. Two small suggestions inline plus an assumption worth naming in the body.

Reviewed changes

• Dist-tag-aware freshness — VersionCheckerClient.checkFreshness now derives the queried tag from the running version: the first prerelease identifier when it's a string (alpha for 1.0.0-alpha.x, beta for -beta.x), else latest, and reports the tag in the result. resolveDlxCommand / spawnLatest gain a tag option (default latest), and init.ts forwards freshness.distTag into the spawned upgrade so an alpha user re-runs as arkenv@alpha, not arkenv@latest.
• Dist-tag test coverage — version-checker tests now pin the result distTag and the queried URL for the prerelease, stable, and pre-release-numeric cases.
• Local-installation docs — getting-started/installation.mdx adds a "Local installation (recommended workflow)" section (install command with the runtime engine, rationale, package.json script wiring), the arkenv README quickstart splits "Scaffolding (Day 1)" from "Local installation (Daily driver & CI)", and docs/LAUNCH_RUNBOOK.md gains a matching launch checkbox.

ℹ️ Prerelease tag assumption is implicit

defaultTag = typeof parsed?.prerelease[0] === "string" ? parsed.prerelease[0] : "latest" assumes the first prerelease identifier is a published npm dist-tag. That holds for alpha/beta today, but any real version whose first identifier is not an actual tag (e.g. 1.0.0-rc.1 published under next, or a numeric 1.0.0-0) makes the registry query 404 and silently fail open — the user never sees an upgrade prompt. Harmless today, but the assumption should be named in the code (or a fallback to latest considered later), since the check burning out silently inverts the whole feature.

ℹ️ Nitpicks

• The new "Recommended" framing still opens with npx arkenv init as the Day-1 scaffold, which resolves the mutable latest tag — slightly at odds with the "deterministic versioning" rationale the section just made for local installs. Fine as-is (scaffolding is inherently one-off), but the tension is worth a sentence noting Day-1 can also be npm i -D arkenv + ./node_modules/.bin/arkenv init.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using DeepSeek Flash (free via Pullfrog for OSS) ｜ 𝕏}

[pullfrog]

✅ No new issues found. The new commit cleanly resolves both prior review threads and names the prerelease-tag assumption in code — all 43 tests across the three affected suites pass locally.

Reviewed changes

• Runtime/CLI dependency split — getting-started/installation.mdx and the arkenv README now install the runtime engine (@arkenv/core / @arkenv/standard) as a regular dependency and arkenv as a devDependency, so non-bundled Node/Nub production installs with --omit=dev boot safely.
• End-to-end dist-tag pinning — init.test.ts mocks distTag: "alpha" and asserts the spawner is called with tag: "alpha"; spawner.test.ts pins arkenv@alpha for both resolveDlxCommand (pnpm + npx) and spawnLatest, closing the previously untested tag: freshness.distTag wiring.
• Dist-tag assumption named — version-checker.client.ts documents the prerelease-identifier→dist-tag inference and its latest fallback.

The prior nitpick about the Day-1 npx arkenv init scaffold standing slightly at odds with the deterministic-versioning rationale remains open, but it is cosmetic and unchanged — leaving it as is.

  ^{｜ View workflow run ｜ Using DeepSeek Flash (free via Pullfrog for OSS) ｜ 𝕏}

[yamcodes]

@pullfrog I added a few more changes. Do you approve?

[pullfrog]

✅ No new issues found. Both commits since the prior approval are docs-only, accurate, and consistent with the local-installation workflow the PR establishes.

Reviewed changes

• Clarified local binary execution — installation.mdx now notes that once installed locally, npx arkenv, pnpm arkenv, or bun arkenv run the locked node_modules/.bin binary.
• Aligned SKILL.md preset commands with the local-runner workflow — the Day-2 preset apply / preset remove examples now use pnpm arkenv preset ..., while Day-1 init keeps pnpm dlx arkenv init.

  ^{｜ View workflow run ｜ Using DeepSeek Flash (free via Pullfrog for OSS) ｜ 𝕏}