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

[yamcodes]

This was generated by AI during triage.

Problem Summary

Marketing copy and documentation currently specify npx arkenv@latest init (e.g., in the hero and outro install panels on the homepage). Omitting @latest (simplifying to npx arkenv init) looks cleaner and is standard across developer tools (e.g., create-next-app, create-turbo).

However, npx caches packages locally in the user's cache directory without automatically fetching the newest version when @latest is omitted. If a user runs npx arkenv init today and executes it again 6 months later, npx may execute the stale, cached CLI version instead of the latest release.

Current Behavior

• Documentation and marketing copy use npx arkenv@latest init.
• The CLI does not perform runtime version freshness checks or detect if it is running from an outdated local npx cache.

Desired Behavior

1. CLI Version Freshness Check / Update Mechanism:
   • Investigate best practices used by leading CLIs (e.g., Next.js, Turbo, Vite, Astro, shadcn).
   • Implement a safe, lightweight check in the CLI (e.g., background registry ping with timeout, warning prompt when running a stale version, or recommending/spawning the latest version).
2. Clean Marketing Copy:
   • Safely drop @latest across homepage components (apps/www/components/page/install-panel.tsx), documentation MDX files, and READMEs to standardize on npx arkenv init.

Acceptance Criteria

• Research competitor/industry standard patterns for npx caching mitigation and document findings.
• Implement a non-blocking / fail-open version check in the arkenv CLI that informs the user if their executed CLI version is outdated when invoked via npx.
• Update website hero/outro install pills (apps/www/components/page/install-panel.tsx) and copy to npx arkenv init.
• Update getting started and reference docs to use npx arkenv init.
• Unit/integration tests covering the version check / updater logic with offline / network-error fallbacks.

Out of Scope

• Blocking offline executions if npm registry is unreachable (checks must fail open / gracefully degrade).
• Modifying how global installations (npm i -g arkenv) are managed beyond standard update notices.

[pullfrog]

This run croaked 😵

The workflow encountered an error before any progress could be reported. Please check the link below for details.

  ^{｜ Rerun failed job ➔ ｜ View workflow run ｜ via Pullfrog ｜ 𝕏}

[yamcodes]

This was generated by AI during triage.

Agent Brief

Category: enhancement
Summary: Implement synchronous pre-flight freshness check with interactive prompt to run latest version on init, and safely omit @latest from marketing copy.

Current behavior:

• Documentation, website install panels, and READMEs specify npx arkenv@latest init.
• Running npx arkenv init relies on local npx cache without checking if a newer release of the CLI exists on npm.
• If a user runs npx arkenv init with an outdated cached version, the CLI scaffolds templates using stale CLI logic without warning.

Desired behavior:

• During init execution in interactive TTY environments (!process.env.CI && process.stdout.isTTY), perform a fast, synchronous registry check against https://registry.npmjs.org/arkenv/latest with an abortable timeout (strict ~1000ms max).
• If the running CLI version is older than the latest published version:
  • Pause before writing any files or mutating the workspace.
  • Interactively prompt the user: Version <latest> is available (running <current>). Run latest instead? (Y/n).
  • If confirmed (default Y), spawn npx arkenv@latest init (passing through any initial arguments and flags with inherited standard I/O) and cleanly exit the current process.
  • If declined, proceed with initialization using the current version.
• In non-interactive/CI environments or when network errors occur (offline, timeout, DNS resolution failure, registry error):
  • Fail open immediately and silently proceed without hanging, throwing unhandled exceptions, or rendering error traces.
• Once the safety mechanism is in place, simplify marketing copy and documentation by omitting @latest (standardizing on npx arkenv init).

Key interfaces:

• Version freshness checker:
  • Input: Current package version, target package name (arkenv), timeout duration (1000ms).
  • Output: Status object indicating if an update is available ({ isOutdated: boolean, latestVersion?: string }) or failure ({ isOutdated: false }).
  • Network: Native fetch with AbortSignal.timeout(1000) with zero third-party dependencies.
• Init workflow orchestration:
  • Hooks into pre-flight validation phase before scaffolding files.
  • Interactively prompts for switch confirmation.
  • Process spawning utility to re-execute with @latest.
• Marketing & Docs install snippets:
  • Install pill and snippet templates updated from npx arkenv@latest init to npx arkenv init.

Acceptance criteria:

• Running init in an interactive TTY with a stale cached version detects the newer version via the npm registry within 1000ms.
• When an update is detected, the user is prompted to run the latest version. Confirming spawns npx arkenv@latest init with inherited stdio and original arguments.
• Declining the prompt allows the current version to complete initialization normally.
• In CI environments (CI=true or equivalent) or non-TTY streams, the version check is skipped or non-interactive without blocking execution.
• Network failures (offline, timeout > 1000ms, registry error) fail open silently without logging errors or interrupting the user.
• Documentation and website hero/outro install copy are updated to npx arkenv init.
• Automated tests cover version comparison, prompt handling, spawn handoff, timeout cancellation, and silent offline degradation.

Out of scope:

• Creating or publishing a separate create-arkenv proxy package.
• Adding third-party update notification packages (must use zero-dependency native fetch).
• Blocking offline executions if npm registry is unreachable.
• Automatic version upgrades or spawning for non-interactive check or preset commands.