trending/OpenSpec
1
0
Fork 0
mirror of https://github.com/Fission-AI/OpenSpec.git synced 2026-10-20 06:19:21 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
main
OpenSpec/openspec/changes/add-version-command/specs/cli-version/spec.md
T
Clay Good 56528ea454 feat(cli): report version and update metadata (#2001) 
* docs(openspec): propose version reporting command

* docs(openspec): clarify update guidance availability

* feat(cli): report version and update metadata

* fix(cli): harden version install detection
2026-09-29 18:26:04 +00:00

5.1 KiB
Raw Permalink Blame History

ADDED Requirements

Requirement: Report the installed version

The system SHALL provide an openspec version command that reports the running OpenSpec version and install context without requiring an OpenSpec project or contacting the network.

Scenario: Human-readable version report

  • WHEN a user runs openspec version
  • THEN the command reports the running OpenSpec version
  • AND identifies the install's package manager and scope when they can be determined
  • AND exits successfully without contacting a registry

Scenario: Machine-readable version report

  • WHEN a user runs openspec version --json
  • THEN stdout contains one valid JSON document
  • AND the document contains schemaVersion: 1, version, and install
  • AND install contains location, packageManager, and scope
  • AND scope is one of global, project, temporary, or source
  • AND values that cannot be determined are represented as null

Scenario: Source checkout

  • WHEN the running CLI is a source checkout
  • THEN the command reports scope as source
  • AND it does not claim that a package manager owns the checkout

Scenario: Existing version flag remains compatible

  • WHEN a user runs openspec --version
  • THEN the command prints the same bare version string as before this capability was added
  • AND no JSON or install metadata is added to that output

Requirement: Check for an available update on request

The system SHALL contact the configured package registry only when openspec version receives --check, and SHALL report the outcome without making command success depend on registry availability.

Scenario: Update is available

  • WHEN a user runs openspec version --check
  • AND the registry reports a safe newer version
  • THEN the command reports the latest version
  • AND reports the appropriate update command only when one exists for this install
  • AND human-readable output omits package-manager guidance when no such command exists
  • AND reports whether the existing self-upgrade path can safely update this copy
  • AND exits successfully

Scenario: Installed version is current

  • WHEN a user runs openspec version --check
  • AND the registry reports no version newer than the running version
  • THEN the command reports the update status as current
  • AND exits successfully

Scenario: Update check is disabled

  • WHEN a user runs openspec version --check
  • AND an existing OpenSpec privacy or update-check opt-out disables registry access
  • THEN the command does not contact the registry
  • AND reports the update status as disabled
  • AND reports no latest version
  • AND exits successfully

Scenario: Registry is unavailable

  • WHEN a user runs openspec version --check
  • AND the registry cannot be reached or returns an unusable response
  • THEN the command reports the update status as offline
  • AND reports no latest version
  • AND exits successfully

Scenario: Machine-readable update result

  • WHEN a user runs openspec version --check --json
  • THEN the base version and install fields remain present
  • AND the document contains an update object with status, latest, command, and canSelfUpgrade
  • AND status is one of available, current, disabled, or offline
  • AND unavailable values are represented as null
  • AND stdout contains no text outside the JSON document

Requirement: Preserve update-check safeguards

The version command SHALL use the same privacy, registry, timeout, response-size, redirect, and version-validation safeguards as OpenSpec's existing update check.

Scenario: Explicit privacy opt-out

  • WHEN telemetry is disabled or DO_NOT_TRACK, OPENSPEC_TELEMETRY, or OPENSPEC_NO_UPDATE_CHECK disables outbound checks
  • AND a user runs openspec version --check
  • THEN the command performs no update-check request
  • AND reports the update status as disabled

Scenario: Unsafe configured registry

  • WHEN the configured registry is rejected by the existing registry safeguards
  • AND a user runs openspec version --check
  • THEN the command does not fall back to the public registry
  • AND reports the update status as disabled

Scenario: Untrusted version response

  • WHEN the registry response does not contain a version accepted by OpenSpec's existing version validator
  • THEN the command does not print the untrusted value
  • AND reports the update status as offline

Requirement: Version reporting is read-only

The version command SHALL NOT install, upgrade, or modify OpenSpec, project files, or user configuration.

Scenario: Update is available

  • WHEN openspec version --check reports an available update
  • THEN it reports guidance only
  • AND does not run a package manager or alter the installed copy

Scenario: Upgrade option is rejected

  • WHEN a user runs openspec version --upgrade
  • THEN the command reports that --upgrade is not supported
  • AND does not attempt an upgrade
Reference in New Issue View Git Blame Copy Permalink