desktop-foundation v2.0.0

All on-screen UI is gone. There is no terminal UI, no native notice or
prompt dialog, and no dialog capability probe. Products present everything
in the terminal they already own (status --json for scripts, prePrompt
and renderRecovery for people), and hraness-helper exists only to
assemble, sign and launch the macOS local app. The headless control kit —
registry, owner sockets, human gate, audience, permissions, login items and
retirement — is unchanged. Every product pins an exact release, so nothing
changes until a product bumps.

Changes

• Removed the ./tui SDK subpath and the hraness-control-kit tui
  feature, with their ratatui, crossterm and ratatui-textarea
  dependencies. runTui and renderSnapshot are gone; <product> status --json is the view for scripts and the basis for any product's
  own terminal listing.
• Removed the native dialog helper modes. --notice, --prompt and
  --prompt-probe now answer invalid-arguments (exit 1) like any unknown
  argv, and contract/helper-argv.v0.8.1.json pins exactly that. This drops
  the GTK 3 dependency on Linux, the AppKit dialogs on macOS and the Win32
  dialog on Windows, and with them the objc2, windows and zeroize
  dependency trees.
• Removed the SDK dialog surface: sdk/src/notice.ts,
  sdk/src/prompt.ts and sdk/src/tui.ts are deleted, including
  promptNative, promptTui, promptCapability, promptSecret,
  permissionNoticeRequest, NoticeRequest, NoticeResult,
  PermissionNoticeRequest and the injectable notice hook on the
  permission renderer.
• Surface / Surface::Dialog is gone. renderPrePrompt and
  renderRecovery are terminal-only: renderPrePrompt(need, env) and
  renderRecovery(need, state, env) in TypeScript, and the same signatures
  without a surface argument in Rust.
• Removed scripts/prompt-smoke.mjs and the dialog-capability check in
  CI, plus the orphaned tui-status goldens under sdk/test/golden/ and
  crates/hraness-control-kit/tests/golden/.
• Unchanged: hraness-helper keeps --version, --assemble-app,
  --signing-identity and --launch, so the macOS local app and Ghostget's
  Safe Storage cookie reader keep working. hraness-companion remains an
  alias that prints byte-identical output for the retained modes and still
  refuses the 0.x menu bar argv with exit 2 and tray-removed; the stderr
  line now points to <product> status --json. packagedManifest,
  resolveHelper and every other SDK subpath (./audience, ./cli-style,
  ./control, ./helper, ./human-gate, ./login, ./permissions,
  ./registry, ./retire) keep their APIs. Terminal permission copy,
  settings links, permission probes, JSON error envelopes and the shared
  golden files are unchanged; the golden files now cover terminal output
  only.

Install

npm install https://github.com/hraness/desktop-foundation/releases/download/v2.0.0/hraness-desktop-foundation-2.0.0.tgz

Rust products pin the tag: desktop-foundation = { git = "https://github.com/hraness/desktop-foundation", tag = "v2.0.0" }.

Verify

Checksums for every asset are in SHA256SUMS. The source commit is 798be31fca87bbe9195e351cdf358c4d14eb42d4. Each asset has a GitHub build attestation: gh attestation verify <file> --repo hraness/desktop-foundation. See the installation guide.

desktop-foundation v1.1.2

The Rust CLI kit can now be published separately to crates.io. Its runtime API
and behavior are unchanged from 1.1.1.

Changes

• Made hraness-cli-kit publishable with its source, README, and MIT license.
• Added crates.io trusted publishing after the existing release checks. It
  stays disabled until the first publication and registry setup are complete;
  later releases use GitHub OIDC without a stored token or human approval.

Install

npm install https://github.com/hraness/desktop-foundation/releases/download/v1.1.2/hraness-desktop-foundation-1.1.2.tgz

Rust products pin the tag: desktop-foundation = { git = "https://github.com/hraness/desktop-foundation", tag = "v1.1.2" }.

Verify

Checksums for every asset are in SHA256SUMS. The source commit is c6003c05a86ab9a188b8bc20dd4de5fe459affab. Each asset has a GitHub build attestation: gh attestation verify <file> --repo hraness/desktop-foundation. See the installation guide.

desktop-foundation v1.1.1

Fixes from the review of 1.1.0. Exit codes, schema ids, error codes and the envelope shape are unchanged. Some behaviour, message text and helper signatures did change, and every change is listed below.

Changes

• help is a command only as the first word (after --json at most). In 1.1.0 runCli removed the first help anywhere in the command line, so approvals decide a1 --digest help deny lost its --digest value, and -- help printed help. Now a flag's value and every word after -- are left alone.
• --debug works like HRANESS_DEBUG=1, as CLI_MENU_STYLE.md D5 says: a text error adds the code and detail. runCli takes --debug (before any --) out of the command line, unless one of the product's verbs declares its own debug flag, in which case it stays that verb's flag and the other verbs reject it as before. 1.1.0 answered --debug with an unknown-option error.
• An undeclared code no longer shows its code to a person. The internal error reads The command failed with an error it did not declare., and the code moved to detail as Undeclared code <code>., which text mode shows only with --debug or HRANESS_DEBUG=1. In 1.1.0 the message was The command answered an undeclared code <code>. This changes --json error.message and adds error.detail.
• A wrong or expired code points at the same command. gate-failed and gate-expired from runCli now have one next step for a person, the same command again, so the → line re-runs it. In 1.1.0 they had no next, and the → line pointed at --help. This adds error.next to those --json envelopes. T3 unsupported-platform still points at --help, since running it again cannot succeed in this release.
• help commands --json lists one descriptor for commands in data.verbs instead of an empty list.
• error.permission is built the same way by both kits. In 1.1.0 TypeScript kept only the known System Settings panes, while Rust kept any x-apple.systempreferences: link.
  • Both now keep only the twelve panes in contract/names.json settingsUrls. Rust exports them as SETTINGS_URLS.
  • Both leave permission out for a kind outside ^[a-z][a-z0-9-]*$ (validPermissionKind, valid_permission_kind).
  • contract/golden/error-permission-cases.json checks that both kits print the same bytes.
  • errorPermission now returns ErrorPermission | undefined. TypeScript code that assigns its result to an ErrorPermission must handle undefined.
  • Rust ErrorPermission::with_settings_url drops a link that is not one of the twelve panes, and ErrorBody::with_permission drops a permission with an invalid kind.
  • The Rust reader now rejects a permission whose kind or link the schema rejects. 1.1.0 accepted it.
  • permissionErrorJson keeps its 1.0 shape. Its error.permission is now tested to hold the same kind and link as errorPermission and to pass the schema.
• Documented from 1.1.0: an agent that runs a decide verb without --json gets human-required (exit 3) and no prompt. In 1.0 only --json did that, and an agent without it was prompted at /dev/tty. The 1.1.0 notes left this out. A person who wants to decide runs the command at their own terminal, as the next step says.

Install

npm install https://github.com/hraness/desktop-foundation/releases/download/v1.1.1/hraness-desktop-foundation-1.1.1.tgz

Rust products pin the tag: desktop-foundation = { git = "https://github.com/hraness/desktop-foundation", tag = "v1.1.1" }.

Verify

Checksums for every asset are in SHA256SUMS. The source commit is 5a76ba99a90c5754be50244c7d0ef8a9b4120f9b. Each asset has a GitHub build attestation: gh attestation verify <file> --repo hraness/desktop-foundation. See the installation guide.

desktop-foundation v1.1.0

Command-line errors and help from ./registry now follow CLI_MENU_STYLE.md, agents get JSON without asking for it, and an error can name the macOS permission behind it. Exit codes, schema ids, error codes, the envelope shape and the order of next are unchanged. Some message text did change, and every change is listed below.

Changes

• A person at a terminal sees a text error as two lines on stderr: ✗ and one sentence, then → and the one command to run next (FAIL and -> without UTF-8). A mistyped command adds Did you mean "status"?, and HRANESS_DEBUG=1 adds the error code.
• Help starts with Usage:. It says in plain words when a person has to decide, instead of the [decide T1T2] tags. <product> help <command> works like <command> --help, and help help prints the root help. User-facing text no longer says "gate".
• When detectAudience reports an agent, runCli prints the JSON envelope even without --json. Raw verbs still see only the --json the caller passed.
• A single-dash option such as -x, before or after the command, is a usage error (exit 2), and the command does not run. In 1.0 it reached the verb as a word. After --, and for a bare - or -5, it is still a word.
• error.permission is new and optional: { kind, settingsUrl }, the macOS permission behind the failure and the System Settings pane that fixes it.
  • It is in contract/envelope.schema.json, the TypeScript ErrorBody and HranessError, and the Rust ErrorBody.
  • New helpers: errorPermission(kind, settingsUrl) in TypeScript, and ErrorPermission::new(kind).with_settings_url(url) with ErrorBody::with_permission in Rust. Both drop a link outside System Settings; TypeScript also keeps only the known panes, and Rust checks the x-apple.systempreferences: prefix.
  • permissionErrorJson keeps its 1.0 shape.
• Scripts (the quiet audience: no terminal, no agent) get what 1.0 gave them. A failure still prints the error envelope on stdout. The stderr line carries code: message after a plain FAIL , in ASCII whatever the locale: FAIL usage: Unknown command "x". then -> example --help. A grep anchored at the line start (^human-required:) must allow for the FAIL prefix. The 1.0 next: lines are gone.
• --json output has the same shape, with these message changes:
  • An unknown command reads Unknown command "x". instead of Unknown command: x., adds Did you mean …? when there is a close match, and has two next steps (agent first, as before, then <product> --help for a person).
  • Name a command after "approvals". is new for a group name typed with no command after it.
  • Unknown options read Unknown option "--x" for "example status", so nothing ran., and a malformed one reads Unknown option "--Bad", so nothing ran.
  • Put options after "example status". uses quotes instead of backticks.
  • Messages that ended with "… . Nothing changed." now end with ", so nothing changed." This covers human-required, gate-failed, gate-expired and T3 unsupported-platform, in TypeScript and Rust. The T3 message now reads Deciding with your macOS login is not supported yet, so nothing changed.
  • An undeclared code reads The command answered an undeclared code … instead of The verb answered ….
  • Match on error.code, never on message text.
• commands text output is a Usage: line and a Commands list without class tags. It is no longer one bare line per verb. Scripts should read commands --json.
• 1.0 readers reject error.permission. The 1.0 schema's error has additionalProperties: false, and the 1.0 Rust ErrorBody denies unknown fields. An envelope without it is byte-identical to 1.0. Set it only when every reader is on 1.1.
• Rust ErrorBody has a new public field, permission. Code that builds ErrorBody with a struct literal, or destructures it without .., must add the field or use ErrorBody::new. No Hraness repository does either.

Install

npm install https://github.com/hraness/desktop-foundation/releases/download/v1.1.0/hraness-desktop-foundation-1.1.0.tgz

Rust products pin the tag: desktop-foundation = { git = "https://github.com/hraness/desktop-foundation", tag = "v1.1.0" }.

Verify

Checksums for every asset are in SHA256SUMS. The source commit is 5e9202c664a79f618da6a39314ff63ac1272724c. Each asset has a GitHub build attestation: gh attestation verify <file> --repo hraness/desktop-foundation. See the installation guide.

desktop-foundation v1.0.0

The menu bar is gone. Products run through the owner process, status --json, tui and the verbs that 0.9 added; hraness-helper handles the few things a terminal cannot. Every product already moved off the tray, and each pins an exact release, so nothing changes until a product bumps. See docs/migration-1.0.md.

Changes

• Removed the tray runner. hraness-companion is now an alias of hraness-helper: for --version, --prompt-probe, --assemble-app, --signing-identity, --launch, --notice and --prompt it prints the same bytes and exits with the same status (only --version names the binary), checked against contract/helper-argv.v0.8.1.json and the new contract/companion-alias.v1.json. Local apps assembled from the companion, including Ghostget's Safe Storage cookie reader, keep working.
• Given the old menu bar argv (--state-dir, --check-protocol or --foreground) or no arguments, the alias draws nothing and exits 2 with a tray-removed error that points to <product> tui and <product> status --json.
• Removed ./menu-kit, the companion CLI, the companion lifecycle calls (runCompanion, startCompanion, stopCompanion, companionStatus, handleCompanionCommand), the menu snapshot protocol and its validators, openBrowser and permissionMenuItems. The Rust crate drops MenuModel, Host, run, outputs and the Tauri, WebKitGTK and AppIndicator dependencies, and re-exports hraness-local-app and hraness-cli-kit.
• diagnosePlatform on Linux reports only what the helper needs: GTK 3, and a display for dialogs (graphical_session_missing is now a warning, since prompts fall back to the terminal). The session_bus_missing and tray_host_unverified codes are gone.
• The login-item notice now says the product starts in the background and shows no window or icon, instead of describing a menu bar icon.
• resolveHelper and the prompt calls look for hraness-helper first. The release manifest keeps both assets (the alias) and helperAssets, so an SDK 0.9 can still read it.

Install

npm install https://github.com/hraness/desktop-foundation/releases/download/v1.0.0/hraness-desktop-foundation-1.0.0.tgz

Rust products pin the tag: desktop-foundation = { git = "https://github.com/hraness/desktop-foundation", tag = "v1.0.0" }.

Verify

Checksums for every asset are in SHA256SUMS. The source commit is 878bfae8af59cbc0693ebb3156ad006b97fb4938. Each asset has a GitHub build attestation: gh attestation verify <file> --repo hraness/desktop-foundation. See the installation guide.

desktop-foundation v0.9.0

Products can now run without a menu bar: one owner process per product, short-lived commands that print JSON, a human gate for decisions a person owns, and terminal views in place of the menu. Everything is additive; the tray, ./menu-kit and the companion lifecycle calls work as before.

Changes

• New SDK subpaths ./registry, ./control, ./human-gate, ./tui, ./login, ./retire and ./helper, with a new Rust crate, hraness-control-kit, that matches them. Both read the shared contract in contract/, which now ships in the package.
• Every --json command prints one envelope with a stable error code and exit code: 2 usage, 3 needs a person, 4 owner not running, 5 conflict. commands --json lists every verb with its operation class.
• A decide verb needs a person at a foreground terminal who types back a one-time code shown on /dev/tty. Run from an agent with --json, it exits 3 with the command a person should run, and never prompts. This stops accidental approvals, not a determined process running as the same user; see docs/human-gate.md.
• The owner listens on an agent socket and an admin socket in a 0700 directory. ensureOwner starts it on demand, and controlStatus reports it without sending signals.
• tui views render interactively on a terminal, as a plain-text snapshot when piped, or as the same JSON status --json prints.
• retireLegacyLoginItem moves a product's old menu bar login item aside after checking it is the product's own, and installLoginItem adds an opt-in login item for the owner.
• A new hraness-helper-<target> executable runs the one-shot modes (--notice, --prompt, --launch, --assemble-app and the others) with the same arguments and output as hraness-companion, without the tray. macOS builds are ad-hoc signed. The release manifest lists it under helperAssets, and resolveHelper falls back to the companion for older manifests. SDK 0.8.x refuses the new field, so use a 0.9.0 or later manifest only with SDK 0.9.0 or later; the manifest that ships in the package always matches.
• The macOS local app, login items and one-shot dialogs moved into the hraness-local-app crate, which has no Tauri dependency. The desktop-foundation crate's public API is unchanged.

Install

npm install https://github.com/hraness/desktop-foundation/releases/download/v0.9.0/hraness-desktop-foundation-0.9.0.tgz

Rust products pin the tag: desktop-foundation = { git = "https://github.com/hraness/desktop-foundation", tag = "v0.9.0" }.

Verify

Checksums for every asset are in SHA256SUMS. The source commit is 6174033a51cd0fa4f5259c8c2492b9a28b942602. Each asset has a GitHub build attestation: gh attestation verify <file> --repo hraness/desktop-foundation. See the installation guide.

v0.8.1

Unsigned, unbundled CLI companions for macOS, Windows and Linux. Includes a pinned SDK manifest and GitHub build attestations. See docs/installation.md for human OS approval guidance. Native event-loop tests do not establish clean-machine visual acceptance.

v0.8.0

Unsigned, unbundled CLI companions for macOS, Windows and Linux. Includes a pinned SDK manifest and GitHub build attestations. See docs/installation.md for human OS approval guidance. Native event-loop tests do not establish clean-machine visual acceptance.

v0.7.0

Unsigned, unbundled CLI companions for macOS, Windows and Linux. Includes a pinned SDK manifest and GitHub build attestations. See docs/installation.md for human OS approval guidance. Native event-loop tests do not establish clean-machine visual acceptance.

v0.6.1

Unsigned, unbundled CLI companions for macOS, Windows and Linux. Includes a pinned SDK manifest and GitHub build attestations. See docs/installation.md for human OS approval guidance. Native event-loop tests do not establish clean-machine visual acceptance.