diff --git a/CHANGELOG.md b/CHANGELOG.md index 4f6ef70..577fb2a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,7 +4,7 @@ ### Changed -- Rebuilt the public README around a concise product overview, real Dext frontend captures, direct quick start, plain safety boundaries, and links to focused references instead of duplicating the technical documentation. Follow-up review replaced the overbroad “project-aware memory” shorthand with explicit project-scoped autosave/resume and user-authored recall/Seat semantics, changed paste-ready auth examples to keep credentials out of shell arguments, and made incomplete CLI login guidance point to Dext's `/login` paste path for API keys or manual OAuth callbacks. Added lightweight Linux/macOS and Windows installers that require exact release tags and safe regular-file destinations, select a matching release, verify `SHA256SUMS`, validate the candidate's reported version before replacing an existing binary, install per-user, and use a documented exact-revision locked source fallback until the first tagged release; Windows uses `File.Replace` when supported and a rollback-preserving rename fallback only for explicit unsupported-operation failures, retaining a recoverable backup if rollback fails. Fixed the public `irm | iex` path under Windows PowerShell 5.1 by replacing nullable modern-.NET architecture metadata with native Windows environment detection, including 32-bit PowerShell on 64-bit Windows. Attestation-required mode fails closed instead of using an unattested source build. CI now executes offline Unix and Windows installer harnesses covering success, no-clobber failures, strict tags/destinations, source pinning/fallback disablement, malformed API state, version mismatch, and Windows replacement rollback/recovery; both Windows PowerShell 5.1 and PowerShell 7 parse and execute the complete harness plus an in-memory install matching `irm | iex`. Release tags must be annotated and point to a commit contained in `origin/main`; Pages deployment has a bounded 15-minute action deadline within a 20-minute job. The verified remaining GitHub governance-setting gaps are recorded in R-008. +- Rebuilt the public README around a concise product overview, real Dext frontend captures, direct quick start, plain safety boundaries, and links to focused references instead of duplicating the technical documentation. Follow-up review replaced the overbroad “project-aware memory” shorthand with explicit project-scoped autosave/resume and user-authored recall/Seat semantics, changed paste-ready auth examples to keep credentials out of shell arguments, and made incomplete CLI login guidance point to Dext's `/login` paste path for API keys or manual OAuth callbacks. Added lightweight Linux/macOS and Windows installers that require exact release tags and safe regular-file destinations, select a matching release, verify `SHA256SUMS`, validate the candidate's reported version before replacing an existing binary, install per-user, and use a documented exact-revision locked source fallback when no tagged release is available; Windows uses `File.Replace` when supported and a rollback-preserving rename fallback only for explicit unsupported-operation failures, retaining a recoverable backup if rollback fails. Fixed the public `irm | iex` path under Windows PowerShell 5.1 by replacing nullable modern-.NET architecture metadata with native Windows environment detection, including 32-bit PowerShell on 64-bit Windows. Attestation-required mode fails closed instead of using an unattested source build. CI now executes offline Unix and Windows installer harnesses covering success, no-clobber failures, strict tags/destinations, source pinning/fallback disablement, malformed API state, version mismatch, and Windows replacement rollback/recovery; both Windows PowerShell 5.1 and PowerShell 7 parse and execute the complete harness plus an in-memory install matching `irm | iex`. Release tags must be annotated and point to a commit contained in `origin/main`; Pages deployment has a bounded 15-minute action deadline within a 20-minute job. For the `v0.1.0` publication, Windows joined Ubuntu/macOS as a required `main` check, `v*` tags gained update/deletion protection, immutable releases and private vulnerability reporting were enabled, and vulnerability alerts plus Dependabot security updates were activated; R-008 now tracks only the residual trusted-maintainer boundary for initial tag creation. - Pack Runtime Protocol v1 now fails closed across the full lifecycle: recursive schemas accept only the implemented keyword subset; native-name and host approval-operation collisions use the full occupied catalog during activation and resume; executable bytes are hashed, displayed at approval, and rechecked before every call; prompt-level `Always` approval is scoped to that exact runtime identity; changing approval or sandbox policy revokes the active executable runtime and queued callbacks; current-run approval/sandbox policy remains authoritative during resume and saved grants are discarded before restoration; restoration preflights exact canonical pack-directory/source identity, manifest/hash/state accounting, project trust, and executable approval before mutating the live agent; activation/idle/read events enforce read-only confinement inside the executor; protocol-sized stdout is preserved and content/effects/queued prompts reject unsafe terminal controls; malformed timeout overrides fail closed; stdin delivery and root execution share the configured deadline, and output drain after process-tree cleanup has a separate one-second cap; state/effects/continuation accounting applies atomically; and pending continuations persist, cancel/refund on interrupt, and remain bounded. Runtime calls also persist state/results without read-tool debounce, surfaced lifecycle errors are privacy-redacted, `/allow`/`/allowed` recognize active dynamic tools, and any runtime-bearing session uses format v5 so pre-runtime binaries reject rather than silently discard executable-runtime state. diff --git a/README.md b/README.md index 07a3097..f49e57b 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,7 @@ Windows PowerShell 5.1 or PowerShell 7: irm https://raw.githubusercontent.com/SiliconState/Dext/main/scripts/install.ps1 | iex ``` -The Windows installer uses native Windows environment values for architecture detection so the same in-memory script works under Windows PowerShell 5.1 and PowerShell 7. The installers select the matching release archive, require an exact `vX.Y.Z` tag, verify its SHA-256 checksum, and validate that it starts and reports the selected version before replacement. Dext has not published its first tagged release yet, so the current installers resolve and pin the current `main` commit before running a locked Cargo build; that fallback requires [Rust](https://rustup.rs). Set `DEXT_SOURCE_FALLBACK=0` to require a release instead. Set `DEXT_REQUIRE_ATTESTATION=1` to additionally require [GitHub CLI](https://cli.github.com/) verification of release provenance; because source builds have no release attestation, that setting also disables source fallback. +The Windows installer uses native Windows environment values for architecture detection so the same in-memory script works under Windows PowerShell 5.1 and PowerShell 7. The installers select the matching release archive, require an exact `vX.Y.Z` tag, verify its SHA-256 checksum, and validate that it starts and reports the selected version before replacement. Dext `v0.1.0` is published, so the default installers download prebuilt archives and do not require Rust. If no tagged release is available, the documented fallback resolves and pins the current `main` commit before running a locked Cargo build; that fallback requires [Rust](https://rustup.rs). Set `DEXT_SOURCE_FALLBACK=0` to refuse source fallback. Set `DEXT_REQUIRE_ATTESTATION=1` to additionally require [GitHub CLI](https://cli.github.com/) verification of release provenance; because source builds have no release attestation, that setting also disables source fallback. Prefer to review before running? Download [`install.sh`](scripts/install.sh) or [`install.ps1`](scripts/install.ps1), inspect it, then execute it locally. Release provenance and manual verification are documented in [`docs/RELEASING.md`](docs/RELEASING.md). diff --git a/SECURITY.md b/SECURITY.md index 6246665..1044837 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -68,7 +68,7 @@ cargo test --release --locked cargo test --release --locked --test tui_smoke -- --nocapture ``` -Also scan untracked and ignored files before deciding what to preserve locally vs. delete. Dependency licenses are checked against `deny.toml`; release publication generates `dext.cdx.json` and includes it in checksum and provenance verification. The public installers are reviewable repository scripts: they install per-user, require exact `vX.Y.Z` release tags, verify the selected archive against `SHA256SUMS`, extract only the expected root binary, require the candidate to start and report the selected release version before replacement, and can require `gh attestation verify` with `DEXT_REQUIRE_ATTESTATION=1`. The Windows installer derives native architecture from Windows environment values rather than nullable modern-.NET runtime metadata; CI and release builders execute the complete harness and an in-memory `Invoke-Expression` install under both Windows PowerShell 5.1 and PowerShell 7. Windows uses `File.Replace` when supported and a rollback-preserving same-directory rename fallback only when replacement is unsupported before mutation; a failed rollback retains the previous binary under the recovery path reported in the error. Before the first tagged release, the installers' documented source fallback resolves one current `main` commit and passes that exact revision plus `--locked` to Cargo; attestation-required mode refuses this unattested fallback. Offline Unix and Windows installer tests cover successful replacement, checksum rejection without clobbering an existing binary, exact-revision source fallback, malformed release/ref responses, strict tag parsing, version mismatch, fallback disablement, and the attestation requirement; Windows also forces unsupported replacement, rollback, and backup-retention paths. The release workflow rejects a tag commit not contained in `origin/main`. Owner tag creation, immutable asset handling, manual checksum/SBOM verification, and GitHub build-provenance verification are documented in [`docs/RELEASING.md`](docs/RELEASING.md). Terminal dependency and renderer changes must also satisfy [`docs/TUI.md`](docs/TUI.md), including its PTY gate and live-terminal acceptance. Published release assets should be used only after both `SHA256SUMS` and `gh attestation verify --repo SiliconState/Dext` succeed. +Also scan untracked and ignored files before deciding what to preserve locally vs. delete. Dependency licenses are checked against `deny.toml`; release publication generates `dext.cdx.json` and includes it in checksum and provenance verification. The public installers are reviewable repository scripts: they install per-user, require exact `vX.Y.Z` release tags, verify the selected archive against `SHA256SUMS`, extract only the expected root binary, require the candidate to start and report the selected release version before replacement, and can require `gh attestation verify` with `DEXT_REQUIRE_ATTESTATION=1`. The Windows installer derives native architecture from Windows environment values rather than nullable modern-.NET runtime metadata; CI and release builders execute the complete harness and an in-memory `Invoke-Expression` install under both Windows PowerShell 5.1 and PowerShell 7. Windows uses `File.Replace` when supported and a rollback-preserving same-directory rename fallback only when replacement is unsupported before mutation; a failed rollback retains the previous binary under the recovery path reported in the error. The published `v0.1.0` archives are the default installer path and do not require Rust. If no tagged release is available, the documented source fallback resolves one current `main` commit and passes that exact revision plus `--locked` to Cargo; attestation-required mode refuses this unattested fallback. Offline Unix and Windows installer tests cover successful replacement, checksum rejection without clobbering an existing binary, exact-revision source fallback, malformed release/ref responses, strict tag parsing, version mismatch, fallback disablement, and the attestation requirement; Windows also forces unsupported replacement, rollback, and backup-retention paths. The release workflow rejects a tag commit not contained in `origin/main`. Owner tag creation, immutable asset handling, manual checksum/SBOM verification, and GitHub build-provenance verification are documented in [`docs/RELEASING.md`](docs/RELEASING.md). Terminal dependency and renderer changes must also satisfy [`docs/TUI.md`](docs/TUI.md), including its PTY gate and live-terminal acceptance. Published release assets should be used only after both `SHA256SUMS` and `gh attestation verify --repo SiliconState/Dext` succeed. ## Runtime safety notes diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 7306ef1..1c0a8d6 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -257,7 +257,7 @@ Compaction preserves recent tool evidence and summarizes older conversation when ## Verification surface -Expected release assets also include a CycloneDX JSON SBOM. The release workflow includes the SBOM in `SHA256SUMS`, provenance attestation, verification, and publication alongside the four platform archives. The first successful tag run remains explicitly tracked in [`RELEASING.md`](RELEASING.md) until this path has end-to-end evidence. +Expected release assets also include a CycloneDX JSON SBOM. The release workflow includes the SBOM in `SHA256SUMS`, provenance attestation, verification, and publication alongside the four platform archives. This path completed end to end for `v0.1.0`; [`RELEASING.md`](RELEASING.md) records the workflow and verification evidence. Expected checks before releasing Dext changes: diff --git a/docs/RELEASING.md b/docs/RELEASING.md index 8d8c2d8..7fa3d18 100644 --- a/docs/RELEASING.md +++ b/docs/RELEASING.md @@ -1,6 +1,6 @@ # Releasing Dext -Releases are owner-triggered by an annotated version tag. The workflow does not publish from branches or manual dispatch, rejects tag commits outside `origin/main`, and treats published tags/assets as immutable by policy; repository tag protection and immutable-release settings remain owner controls tracked in [`R-008`](RISK_REGISTER.md). +Releases are owner-triggered by an annotated version tag. The workflow does not publish from branches or manual dispatch and rejects tag commits outside `origin/main`. Active `v*` rules prevent updates and deletion, published releases are immutable, and initial tag creation remains a trusted maintainer action guarded by workflow validation. ## Dry review @@ -32,18 +32,18 @@ Releases are owner-triggered by an annotated version tag. The workflow does not If an agent must orchestrate the gate, start a separate trusted Dext process with `dext --sandbox-profile danger-full-access --approval always` and use it only in a controlled checkout. Changing `DEXT_SANDBOX_PROFILE` inside an already-confined shell does not remove the parent process's kernel sandbox. Do not weaken `workspace-write` or grant shared temp, PTY, or Cargo-home access merely to make self-hosted tests pass. 4. Confirm branch CI is green on Linux, macOS, and Windows; do not rely only on the currently configured required checks. Windows CI includes the native Job Object descendant-lifecycle test and parses/executes the complete installer harness under both inbox Windows PowerShell 5.1 and PowerShell 7. Each engine evaluates `install.ps1` from in-memory text through `Invoke-Expression`, matching the public `irm | iex` path, and checks native architecture detection without nullable modern-.NET metadata. Linux and macOS execute the Unix installer harness. These offline tests cover successful replacement, checksum failure without clobbering the existing binary, exact-revision source fallback, malformed release/ref responses, strict tag parsing, unsafe destination refusal, version mismatch, fallback disablement, and attestation-required refusal of source fallback. Windows additionally forces unsupported `File.Replace`, successful fallback, rollback, and retained-backup recovery paths. Linux compiles Criterion benchmarks. Confirm the scheduled security workflow passes both vulnerability auditing and the dependency-license policy. If terminal dependencies or `src/tui.rs` changed, apply the renderer contract and live-terminal checks in [`TUI.md`](TUI.md). Review `.github/workflows/release.yml`, especially its full action commit pins, quality gate, four-target matrix, annotated-tag/origin-`main` ancestry checks, and publish-job permissions. -5. Before the first public release, resolve the GitHub-setting gaps recorded in [`R-008`](RISK_REGISTER.md): require Windows CI alongside Ubuntu/macOS, protect `v*` tags, enable immutable releases, private vulnerability reporting, vulnerability alerts, and Dependabot security updates. Confirm the tag and release do not already exist. Treat release artifacts as immutable even before the setting is enabled: never move a published tag or replace bytes under an existing tag/checksum. +5. Before every public release, recheck the owner-controlled GitHub settings: require Windows CI alongside Ubuntu/macOS, protect `v*` tags from update and deletion, and keep immutable releases, private vulnerability reporting, vulnerability alerts, and Dependabot security updates enabled. Confirm the tag and release do not already exist. Initial release-tag creation remains a trusted maintainer action because this personal repository does not currently enforce a creation-only rule with an owner bypass; the workflow must still reject lightweight tags, commits outside `origin/main`, and tag/package version mismatches. ## First-release evidence -The publication workflow has not yet completed a version tag. Before treating it as proven, record the first successful tag run here: +The publication path first completed for [`v0.1.0`](https://github.com/SiliconState/Dext/releases/tag/v0.1.0) in [release run `31139795179`](https://github.com/SiliconState/Dext/actions/runs/31139795179) from commit `9a48eb9a8f7065a2dd71041527e0b276a7444876`: -- [ ] Annotated-tag, `origin/main` ancestry, and package-version validation passed. -- [ ] Four platform archives and `dext.cdx.json` were published and listed in `SHA256SUMS`. -- [ ] Provenance verification passed for every checksummed asset. -- [ ] Packaged binaries passed the workflow smoke checks. +- [x] Annotated-tag, `origin/main` ancestry, and package-version validation passed. +- [x] Four platform archives and `dext.cdx.json` were published and listed in `SHA256SUMS`. +- [x] Provenance verification passed for every checksummed asset in the workflow and an independent post-publication download. +- [x] Packaged binaries passed the workflow smoke checks. -After the first successful release, replace these unchecked items with the tag and workflow URL. The README/usage installers will then consume the published archives automatically; until that point their default `latest` path deliberately falls back to a locked source build from one resolved `main` revision. Attestation-required mode refuses that fallback because a local source build has no release attestation. +The README/usage installers now consume the published archives automatically, so normal installation does not require Rust. Their exact-revision locked source fallback remains available only when no tagged release exists. Attestation-required mode refuses that fallback because a local source build has no release attestation. ## Publish diff --git a/docs/RISK_REGISTER.md b/docs/RISK_REGISTER.md index 3f2feaf..ba13e31 100644 --- a/docs/RISK_REGISTER.md +++ b/docs/RISK_REGISTER.md @@ -13,7 +13,7 @@ Priorities: **P1** needs planned mitigation before a stronger security/reliabili | R-005 | Reliability · provider transport · P2 | Medium with broken or hostile endpoints | Medium | High | Connect, first-header, and idle deadlines do not impose an overall turn duration. A peer can keep a response alive indefinitely by sending valid chunks just before each idle deadline. Evidence: per-chunk timeout reset in `read_provider_body_limited` and `Agent::read_stream_next_chunk`. | Connect/first-byte/idle deadlines; response/frame/body caps; output-token requests; user interrupt; bounded retry counts. | Add an optional total request/turn deadline with separate local-provider defaults and diagnostics · provider owner · review after long-running-stream incidents or timeout-policy changes. | | R-006 | Security · packs · same-user concurrency · P2 | Low | High | Medium | Active shelf helpers, optional `runtime.json` executables, and native user-pack mutation destinations are validated before path-based execution or replacement. A hostile process running as the same OS user can replace a helper, runtime binary/manifest, pack marker, or directory after validation; user packs may also receive narrowly declared credentials through ordinary direct helpers. Evidence: `active_pack_helper_invocation` in `src/main.rs`, `src/pack_runtime.rs`, pack-root validation in `src/session.rs`, and atomic application in `src/mutation_preview.rs`. | Shelf-only discovery; project declarations ignored; conversational project-pack activation and all project shelf metadata require repository-scoped first-use confirmation; executable runtimes require separate activation approval, prompt-level `Always` approval is scoped to exact canonical pack-directory/source/manifest/executable identity, policy changes revoke active runtimes and queued callbacks, and runtime executable bytes are rehashed before each call; runtimes receive no inherited credentials; activation/idle/read runtime calls enforce read-only confinement inside the executor; write/danger runtime tools retain per-call approval, side-effect journal, and fail-closed Git checkpoints; recursive runtime schemas accept only implemented keywords; protocol capture/state/effect/continuation sizes and versions are bounded, and runtime-bearing sessions use a distinct v5 format so pre-runtime readers reject them; state/effects/continuation accounting is atomic; runtime results and bounded queued prompts are durably persisted; stdin delivery and root execution share the configured deadline, and output drain after process-tree cleanup has a separate one-second cap; session restore preserves current-run approval/sandbox policy, discards saved grants, and preflights project trust, exact canonical pack-directory/source identity, manifest/hash/state accounting, and current executable approval before applying saved session fields; `Always` persists a bounded owner-private, no-follow, single-link Unix project decision marker and reset refuses unsafe marker shapes; denied project metadata cannot shadow trusted prompt entries; `PACK.md`/`shelf.json` reads are no-follow regular files capped at 1 MiB; provider credential names excluded; canonical parent checks; regular `PACK.md` required for external native mutations; destination/parent revalidation; atomic file replacement; direct-helper grammar; input/output redaction for approved hooks/runtime effects; same-user processes are outside the intended isolation boundary. | Use descriptor-relative no-follow traversal and execute/replace from validated handles where supported, or copy helpers/runtimes/mutations through a private immutable staging location · extensions/security owner · review when executable runtimes, credential-bearing helpers, user-pack mutation scope, project extension trust, or shelf execution changes. | | R-007 | Reliability · TUI · Windows · P2 | Medium | Medium | High | Real-PTY TUI smoke tests run on Unix only; Windows CI compiles/tests the code and process lifecycle but does not exercise an interactive ConPTY/Git-Bash terminal. Evidence: `.github/workflows/ci.yml` and `release.yml` skip `tui_smoke` on Windows. | Cross-platform unit tests; Windows CI build/release tests; stdout-based TUI detection; manual Windows use; Unix PTY regression suite. | Add a deterministic ConPTY or Git-Bash interactive smoke harness and require it in Windows CI · TUI owner · review before Windows terminal changes or a Windows support-level increase. | -| R-008 | Release · governance · P2 | Medium with current repository settings | High | High | Source workflows cannot guarantee repository settings. Verified 2026-08-06: `main` protection is strict and administrator-enforced but requires only Ubuntu and macOS CI, not Windows; no repository rulesets or tag-protection rules are configured; private vulnerability reporting, vulnerability alerts/Dependabot security updates, and immutable releases are disabled. A repository administrator can therefore merge without the Windows gate, create/move release tags outside a protected-tag rule, replace release assets, or miss platform security advisories despite source policy. | Read-only workflow permissions; commit-pinned actions; locked builds; scheduled audit/license workflow; four-target release matrix; checksums; attestations; exact tag/version parsing; release workflow requires an annotated tag whose commit is contained in `origin/main`; checksum-verifying per-user installers with candidate-version and safe-destination validation, rollback-preserving Windows replacement fallback, and exact-revision locked source fallback; Windows PowerShell 5.1 and PowerShell 7 both parse and execute the complete installer harness plus an in-memory `Invoke-Expression` install matching `irm | iex`, including native architecture detection for a 32-bit shell on 64-bit Windows; platform-native functional installer tests; documentation-link validation in CI. | Require Windows alongside Ubuntu/macOS on `main`; enable tag rules that restrict `v*` creation/update/deletion; enable immutable releases, private vulnerability reporting, vulnerability alerts, and Dependabot security updates; periodically verify these settings · repository owner · before the first public release, after settings/admin changes, and quarterly. | +| R-008 | Release · governance · P3 | Low with trusted maintainers | High | High | Initial `v*` tag creation is not restricted by a repository creation rule on this personal repository. A writer could trigger a release when a matching package-version commit is already on `main`; source workflows cannot guarantee owner intent. Verified 2026-08-07: attempts to configure a creation-only rule with a repository-administrator bypass were rejected atomically by GitHub, while the active update/deletion rules remained unchanged. | Strict administrator-enforced `main` protection requires Ubuntu, macOS, and Windows CI; active `v*` rules prevent tag updates and deletion; immutable releases prevent asset replacement; private vulnerability reporting, vulnerability alerts, and Dependabot security updates are enabled; release publication requires an annotated exact-version tag whose commit is contained in `origin/main`; read-only workflow defaults, commit-pinned actions, locked four-target builds, checksums, attestations, SBOM, candidate-version validation, and platform-native installer tests. | Restrict release-tag creation to the owner when GitHub supports a valid creation-only bypass for this repository type; meanwhile keep write access least-privilege and verify owner intent before version bumps reach `main` · repository owner · after settings/admin changes and quarterly. | | R-009 | Security · network egress · P1 | Medium for approved shell/process work | High | High | Filesystem sandbox profiles do not restrict outbound network access. An approved arbitrary subprocess can use its own network client and is not subject to the built-in `http` tool's destination checks. Evidence: `SECURITY.md` runtime safety notes and `src/sandbox.rs`. | Approval gates; actual shell curl/wget/HTTPie/XH requests are Danger; credential-shaped environment scrubbing; built-in `http` always blocks current-network/broadcast, multicast, and unspecified targets, blocks local/private/link-local/metadata targets unless narrowly opted in, connects without proxies, validates each complete DNS answer before bounded retention, rejects dangerous/duplicate transport and method-override headers plus URL credentials, removes URL details from errors, blocks HTTPS redirect downgrades and sensitive cross-origin replay, classifies body-bearing nominal read methods as Danger, and caps decoded response reads exactly. | Add an optional kernel network boundary/allowlist for confined subprocesses, with explicit provider and package-manager exceptions · sandbox/security owner · review before claiming network confinement or handling untrusted repositories with outbound-sensitive data. | | R-010 | Privacy · local recovery · P3 | Low with normal Git push; medium with mirror/backup sharing | Medium | High | Checkpoint refs and owner-private sidecars/blobs may retain sensitive file content and symlink targets. Write-risk arbitrary-command checkpoints can preserve existing untracked entries within bounded limits. Mirroring `refs/dext/*`, copying full repository metadata, or sharing state backups can disclose it. Evidence: checkpoint storage in `src/git_checkpoints.rs` and warnings in `SECURITY.md`. | On Unix, checkpoint storage containers are current-user-owned, `.dext` is not group/world-writable, and managed checkpoint/sidecar/blob directories are owner-private; unsafe restore containers fail closed, prune retains unsafe blob entries and sidecar directory trees with bounded warnings, and orphan top-level sidecar symlinks are unlinked without traversal. Blobs are content-addressed and verified before/while restoring; current manifests record exact direct-sidecar membership, while ambiguous missing artifacts in older manifests fail before mutation; every manifest path is validated by one repo-relative rule that a row cannot opt out of; recognized retired rows require intact headers, complete retired field grammar, and live-ref OID matches; retention publishes the compacted manifest before deleting expired/retired refs or artifacts so cleanup failure leaves orphan state rather than a manifest naming deleted recovery points, while corruption or tampering fails closed; runtime manifest reads are capped at 16 MiB; cache reuse requires stable source/blob metadata fingerprints; `.dext/` is locally excluded; arbitrary-command inventory/capture is capped at 500 paths, 8 MiB/file, and 32 MiB/checkpoint; non-UTF-8/unsupported/capped entries require partial-recovery approval; failed creation cleans new blobs; automatic retention is 20 checkpoints/seven days and prunes valid unreferenced blobs; normal Git pushes do not include hidden refs; docs warn against mirror-pushing Dext refs. | Add an explicit sensitive-checkpoint inventory/prune workflow and optional checkpoint disable/exclude patterns · recovery/privacy owner · review when capture scope, retention, backup, or ref publication behavior changes. | | R-011 | Maintainability · architecture · P2 | High for routine core changes | Medium | High | `src/main.rs`, `src/tui.rs`, and the in-crate test surface remain large; unrelated runtime concerns still share broad compile/review boundaries. Evidence: module line counts and the responsibility map in `docs/ARCHITECTURE.md`. | Provider streaming, tool rounds/journal, checkpoints, mutation previews, sandbox, policy, pack runtime, packs, shelves, seats, sessions, and orchestration already have focused modules; the unused work-map/focus/track vertical slice and its TUI/event/test surface were removed rather than extracted; tool metadata has one registry for required fields and execution flags; release tests cover cross-module behavior. | Extract one stable seam at a time (HTTP tool, diagnostics, doctor, export, eval) with behavior-preserving tests; do not combine extraction with feature work · architecture owner · review when adding another substantial `main.rs` subsystem or when merge/compile cost blocks delivery. | diff --git a/docs/USAGE.md b/docs/USAGE.md index be5e72c..bcbf8e6 100644 --- a/docs/USAGE.md +++ b/docs/USAGE.md @@ -14,7 +14,7 @@ Windows PowerShell 5.1 or PowerShell 7: irm https://raw.githubusercontent.com/SiliconState/Dext/main/scripts/install.ps1 | iex ``` -The Windows installer derives the native architecture from Windows environment values instead of nullable modern-.NET runtime metadata, so the same in-memory script works under Windows PowerShell 5.1 and PowerShell 7. The installers query the latest GitHub release, require an exact `vX.Y.Z` tag, select Linux x86_64 GNU, macOS x86_64/arm64, or Windows x86_64 as appropriate, verify the archive against the release `SHA256SUMS`, validate that the candidate starts and reports the selected version, and replace `dext` for the current user from a same-directory staged file. The Unix rename is atomic within the destination filesystem. Windows uses `File.Replace` when available; if that API is unsupported before mutation, it falls back to same-directory renames, restores the previous binary if installing the staged candidate fails, and retains the backup with a recovery path in the error if rollback itself fails. The default destination is `~/.local/bin` on Linux/macOS and `%LOCALAPPDATA%\Dext\bin` on Windows; the Windows installer adds its directory to the user `PATH`. Override the destination with `DEXT_INSTALL_DIR` and select a tag with `DEXT_VERSION=vX.Y.Z`. Dext has not published its first tagged release yet, so `latest` currently resolves and pins the current `main` commit before running `cargo install --git ... --rev ... --locked`; set `DEXT_SOURCE_FALLBACK=0` to fail instead. The source fallback requires stable Rust with edition 2024 support. Set `DEXT_REQUIRE_ATTESTATION=1` (and install GitHub CLI) to require build-provenance verification in addition to the default checksum verification; this also disables source fallback because source builds have no release attestation. +The Windows installer derives the native architecture from Windows environment values instead of nullable modern-.NET runtime metadata, so the same in-memory script works under Windows PowerShell 5.1 and PowerShell 7. The installers query the latest GitHub release, require an exact `vX.Y.Z` tag, select Linux x86_64 GNU, macOS x86_64/arm64, or Windows x86_64 as appropriate, verify the archive against the release `SHA256SUMS`, validate that the candidate starts and reports the selected version, and replace `dext` for the current user from a same-directory staged file. The Unix rename is atomic within the destination filesystem. Windows uses `File.Replace` when available; if that API is unsupported before mutation, it falls back to same-directory renames, restores the previous binary if installing the staged candidate fails, and retains the backup with a recovery path in the error if rollback itself fails. The default destination is `~/.local/bin` on Linux/macOS and `%LOCALAPPDATA%\Dext\bin` on Windows; the Windows installer adds its directory to the user `PATH`. Override the destination with `DEXT_INSTALL_DIR` and select a tag with `DEXT_VERSION=vX.Y.Z`. Dext `v0.1.0` is published, so `latest` downloads a prebuilt archive and does not require Rust. If no tagged release is available, the installer can resolve and pin the current `main` commit before running `cargo install --git ... --rev ... --locked`; set `DEXT_SOURCE_FALLBACK=0` to refuse that fallback. The source fallback requires stable Rust with edition 2024 support. Set `DEXT_REQUIRE_ATTESTATION=1` (and install GitHub CLI) to require build-provenance verification in addition to the default checksum verification; this also disables source fallback because source builds have no release attestation. A one-line installer executes repository code. For a review-first installation, download [`../scripts/install.sh`](../scripts/install.sh) or [`../scripts/install.ps1`](../scripts/install.ps1), inspect it, and run the local file. The installers verify release checksums; use [`RELEASING.md`](RELEASING.md#verify-published-assets) to additionally verify GitHub build provenance and the release SBOM. Windows shell-backed tools also require a real Bash such as Git for Windows; use `DEXT_BASH_PATH` when automatic discovery is not suitable. diff --git a/docs/index.html b/docs/index.html index 00a7db3..6bd4558 100644 --- a/docs/index.html +++ b/docs/index.html @@ -15,12 +15,9 @@ - - - + -