diff --git a/.agents/skills/cryptad-architecture/SKILL.md b/.agents/skills/cryptad-architecture/SKILL.md index 9fd715dd52..e107e16e80 100644 --- a/.agents/skills/cryptad-architecture/SKILL.md +++ b/.agents/skills/cryptad-architecture/SKILL.md @@ -69,6 +69,9 @@ Use this skill when you need to: AppHost core) - `:platform-app-ui` → `network.crypta.platform.appui` (app-owned static UI route and asset resolution helpers) + - `:platform-sdk-js` → browser SDK resource for app-owned static UI bootstrap, Platform API + transport helpers, mutation form handling, error parsing, and conservative fragment + sanitization - `:platform-appdist` → `network.crypta.platform.appdist` (signed local app bundle digest, signature, manifest, verifier, trusted-key, and distribution tooling) - `:platform-appcatalog` → `network.crypta.platform.appcatalog` (signed catalog sources, @@ -128,8 +131,9 @@ Use this skill when you need to: `:kernel-routing` owns the compile-neutral phase-1 routing/helper slice, `:platform-api` owns the transport-neutral Platform API surface, `:platform-apphost` owns the transport-neutral AppHost core, `:platform-app-ui` owns app-owned static UI route helpers, - `:platform-appdist` owns signed local bundle distribution, `:platform-appcatalog` owns signed - catalog sources and verified staging, `:platform-web-shell` owns the browser-facing + `:platform-sdk-js` owns the browser SDK resource, `:platform-appdist` owns signed local bundle + distribution, `:platform-appcatalog` owns signed catalog sources and verified staging, + `:platform-web-shell` owns the browser-facing node-management shell, `:runtime-alerts` owns the extracted alert/feed model subset, `:runtime-node` owns the remaining runtime/node/client/support body, `:adapter-fcp` owns the FCP adapter tree, @@ -163,8 +167,9 @@ Use this skill when you need to: `RuntimeNodeKernelSplitPrepBoundaryTest`, `KernelContentBoundaryTest`, `KernelTransportBoundaryTest`, `KernelRoutingBoundaryTest`, `PlatformApiBoundaryTest`, `AdapterFcpBoundaryTest`, `BridgeFcpRuntimeBoundaryTest`, `AppHostBoundaryTest`, - `WebShellBoundaryTest`, `HttpLegacyAdminBoundaryTest`, `LegacyHttpBrowseBoundaryTest`, and - `BridgeHttpRuntimeBoundaryTest` guard leaf ownership/import rules. The runtime, kernel, + `CryptaPlatformSdkBoundaryTest`, `WebShellBoundaryTest`, `HttpLegacyAdminBoundaryTest`, + `LegacyHttpBrowseBoundaryTest`, and `BridgeHttpRuntimeBoundaryTest` guard leaf + ownership/import rules. The runtime, kernel, platform, FCP, and HTTP boundary suites also require `package-info.java` in the production packages they own. @@ -290,6 +295,9 @@ Use this skill when you need to: - `SecurityLevelsToadlet` uses `SecurityLevelsPort` for detached page state, warning HTML, and master-password mutation flows. - `PageMaker` reads shared shell status through `PageChromePort`. + - `LegacyAdminRetirementRegistry` maps replaced legacy admin surfaces, and + `LegacyAdminUsageRecorder` feeds process-local legacy-page counters into Platform API + diagnostics without storing query strings, form bodies, tokens, or remote addresses. - `network.crypta.clients.http.updater.CoreActionToadlet` reaches updater availability, download triggers, and installer-path validation through `CoreUpdateActionPort`. - `FirstTimeWizardToadlet` and `FirstTimeWizardNewToadlet` use `FirstTimeWizardPort` for @@ -316,15 +324,22 @@ Use this skill when you need to: - `:platform-api` owns the transport-neutral Platform API v1 under `network.crypta.platform.api`. It exposes node/config/peer/connectivity/security, queue, updates, wizard, alerts, diagnostics, apps, and app-catalog control-plane families and is currently mounted at `/api/v1/` by the - legacy HTTP adapter. + legacy HTTP adapter. It also owns the central app-token authorization matrix and bounded + process-local app audit log for AppHost-originated API requests. - `:platform-apphost` owns the transport-neutral out-of-process AppHost v1 under `network.crypta.platform.apphost`. It validates staged local app bundles, owns the immutable installed-bundle layout plus mutable data/cache/run directories, and provides local - install/list/describe/start/stop/update/uninstall operations. + install/list/describe/start/stop/update/uninstall operations, per-launch app tokens, minimal + launch environments, token-redacted process-log snapshots, and in-session restart attempts for + manifests that opt in. - `:platform-app-ui` owns `network.crypta.platform.appui`, the transport-neutral app-owned static UI path layer. It maps installed static UI manifests to `/apps/{appId}/`, preserves nested entry base URLs, resolves bundle assets, rejects traversal/symlink/reparse escapes, and supplies deterministic content-type and security-header helpers for HTTP adapters. +- `:platform-sdk-js` owns the dependency-free browser SDK resource staged into first-party static + app bundles. It wraps route bootstrap, same-origin Platform API reads, form-password mutations, + error parsing, and conservative legacy HTML fragment sanitization; it is not an authority or + isolation boundary. - `:platform-appdist` owns `network.crypta.platform.appdist`, the signed local bundle distribution layer. It parses normalized app manifests, writes deterministic SHA-256 digest sidecars, verifies Ed25519 signatures, rejects reserved sidecars as executable/UI entries, and @@ -346,8 +361,8 @@ Use this skill when you need to: `QueueCompletionPort`, `QueuePagePort`, `QueueDownloadPort`, `QueueInsertPort`, `QueueMutationPort`, `StatisticsPort`, `SecurityLevelsPort`, `PageChromePort`, `CoreUpdateActionPort`, `FirstTimeWizardPort`, `ToadletSymlinkPort`, `WelcomePagePort`, - `WelcomeActionPort`, `AlertFeedPort`, `AlertMutationPort`, `RequestQueuePort`, `NodeInfoPort`, - and `PeerPort` + `WelcomeActionPort`, `AlertFeedPort`, `AlertMutationPort`, `LegacyAdminUsagePort`, + `RequestQueuePort`, `NodeInfoPort`, and `PeerPort` - Detached DTOs include config, connectivity, peer, darknet-friends, node-reference, queue, security-level, shared shell, first-time-wizard, symlinker, welcome-page, alert, and statistics/report snapshot types such as @@ -356,7 +371,8 @@ Use this skill when you need to: `QueuePageSnapshot`, `QueuePersistenceStatusSnapshot`, `QueueInsertOutcome`, `SecurityLevelsSnapshot`, `PageChromeSnapshot`, `FirstTimeWizardSnapshot`, `FirstTimeWizardCurrentBandwidthLimits`, `ToadletSymlinkEntry`, `WelcomePageSnapshot`, - `AlertListSnapshot`, `AlertSnapshot`, and `AlertSeverity` + `AlertListSnapshot`, `AlertSnapshot`, `AlertSeverity`, `LegacyAdminUsageSnapshot`, and + `LegacyAdminSurfaceUsage` - Daemon-backed adapters in `network.crypta.runtime.core` (currently in `:runtime-node`): `LegacyRuntimePorts`, `LegacyConfigPort`, `LegacyConnectivityPort`, `LegacyNodeInfoPort`, `LegacyPeerPort`, `LegacyRequestQueuePort`, @@ -453,6 +469,7 @@ Use this skill when you need to: - `:platform-api`: `network.crypta.platform.api` - `:platform-apphost`: `network.crypta.platform.apphost` - `:platform-app-ui`: `network.crypta.platform.appui` +- `:platform-sdk-js`: browser SDK resource under `network/crypta/platform/sdk/js` - `:platform-appdist`: `network.crypta.platform.appdist` - `:platform-appcatalog`: `network.crypta.platform.appcatalog` - `:platform-web-shell`: `network.crypta.platform.webshell` @@ -486,6 +503,9 @@ Use this skill when you need to: 2. `RequestScheduler` manages queues and priorities 3. `SendableRequest` implementations perform request types 4. Routing uses location-based algorithms for discovery +- `ClientRequestSelector` returns the earliest useful cooldown wakeup, and + `ClientRequestScheduler#scheduleWakeStarterAt` coalesces starter wakeup jobs. Selector code + should not queue duplicate ticker wakeups directly. ### Update system (high level) - `NodeUpdateManager` coordinates updates. diff --git a/.agents/skills/cryptad-build-test/SKILL.md b/.agents/skills/cryptad-build-test/SKILL.md index 8a4204f5e9..d495b0e33c 100644 --- a/.agents/skills/cryptad-build-test/SKILL.md +++ b/.agents/skills/cryptad-build-test/SKILL.md @@ -23,7 +23,7 @@ Use this skill when you need to: `:foundation-config`, `:foundation-fs`, `:foundation-compat`, `:kernel-content`, `:kernel-transport`, `:kernel-routing`, `:runtime-spi`, `:platform-api`, `:platform-apphost`, `:platform-app-ui`, `:platform-appdist`, `:platform-appcatalog`, - `:platform-web-shell`, `:runtime-alerts`, `:runtime-node`, `:adapter-fcp`, + `:platform-sdk-js`, `:platform-web-shell`, `:runtime-alerts`, `:runtime-node`, `:adapter-fcp`, `:bridge-fcp-runtime`, `:bridge-http-runtime`, `:adapter-http-legacy-admin`, `:adapter-http-legacy-browse`, `:thirdparty-onion`, `:thirdparty-legacy`, and `:launcher-desktop`. @@ -81,9 +81,10 @@ Use this skill when you need to: `RuntimeNodeKernelSplitPrepBoundaryTest`, `KernelContentBoundaryTest`, `KernelTransportBoundaryTest`, `KernelRoutingBoundaryTest`, `PlatformApiBoundaryTest`, `AdapterFcpBoundaryTest`, `BridgeFcpRuntimeBoundaryTest`, `AppHostBoundaryTest`, - `WebShellBoundaryTest`, `HttpLegacyAdminBoundaryTest`, `LegacyHttpBrowseBoundaryTest`, and - `BridgeHttpRuntimeBoundaryTest` are the focused regression checks for leaf ownership/import - boundaries. The runtime, kernel, platform, FCP, and HTTP boundary suites also enforce + `CryptaPlatformSdkBoundaryTest`, `WebShellBoundaryTest`, `HttpLegacyAdminBoundaryTest`, + `LegacyHttpBrowseBoundaryTest`, and `BridgeHttpRuntimeBoundaryTest` are the focused regression + checks for leaf ownership/import boundaries. The runtime, kernel, platform, FCP, and HTTP + boundary suites also enforce `package-info.java` coverage for the production packages they own. - `:runtime-spi` is the JDK-only runtime/config API leaf. Its focused unit tests still live in the root test tree and run through the root build. @@ -98,6 +99,8 @@ Use this skill when you need to: - `:platform-appcatalog` owns signed catalog source parsing, verification, artifact download, safe ZIP extraction, and verified staging code plus focused tests under `platform-appcatalog/src/test/java`. +- `:platform-sdk-js` owns the dependency-free browser SDK resource and focused resource/boundary + tests under `platform-sdk-js/src/test/java`. - `:platform-web-shell` owns the browser-facing Web Shell leaf and its focused leaf tests under `platform-web-shell/src/test/java`. - `:runtime-alerts` owns the extracted leaf-safe `network.crypta.runtime.alerts` feed/model @@ -158,6 +161,7 @@ When running ./gradlew test via OpenCode bash, set timeout ≥ 15 minutes (≥ 9 - `./gradlew :platform-app-ui:test` - `./gradlew :platform-appdist:test` - `./gradlew :platform-appcatalog:test` + - `./gradlew :platform-sdk-js:test` - `./gradlew :platform-web-shell:test` - `./gradlew :kernel-content:test` - `./gradlew :kernel-transport:test` @@ -223,6 +227,9 @@ When running ./gradlew test via OpenCode bash, set timeout ≥ 15 minutes (≥ 9 - `./gradlew :platform-appdist:compileJava` - Compile the app catalog leaf when you touched `network.crypta.platform.appcatalog`: - `./gradlew :platform-appcatalog:compileJava` +- Process and test the Platform SDK resource leaf when you touched + `platform-sdk-js/src/main/resources/network/crypta/platform/sdk/js/crypta-platform.js`: + - `./gradlew :platform-sdk-js:processResources :platform-sdk-js:test` - Compile the Web Shell leaf when you touched `network.crypta.platform.webshell`: - `./gradlew :platform-web-shell:compileJava` - Compile the extracted runtime-alerts leaf when you touched `network.crypta.runtime.alerts`: @@ -246,7 +253,8 @@ When running ./gradlew test via OpenCode bash, set timeout ≥ 15 minutes (≥ 9 - `./gradlew compileJava compileTestJava` ## First-party app bundle checks -- Stage first-party app bundles: +- Stage first-party app bundles, especially after changing `:platform-sdk-js` because Queue + Manager and Publisher copy the SDK into staged static assets: - `./gradlew stageFirstPartyApps` - Run app project tests: - `./gradlew :apps:queue-manager:test` diff --git a/.agents/skills/cryptad-core-updater/SKILL.md b/.agents/skills/cryptad-core-updater/SKILL.md index 43d1a80b11..b502e74c67 100644 --- a/.agents/skills/cryptad-core-updater/SKILL.md +++ b/.agents/skills/cryptad-core-updater/SKILL.md @@ -50,6 +50,9 @@ Use this skill when working on: - Actions: `download`, `install`, `openStore` - UI: alerts panel shows progress percent when available. - Failures surface clear retry guidance (non-fatal errors relabel to “Retry”). +- `NodeUpdater` intentionally delays retries for `FetchExceptionMode.RECENTLY_FAILED` instead of + rescheduling immediately while the key is still in the recently-failed table. Preserve that + throttle unless replacing it with an explicit, tested retry policy. - Request parsing, redirects, `AppEnv` checks, and OS-specific installer or store-launching now live in the HTTP adapter layer at `network.crypta.clients.http.updater.CoreActionToadlet`, currently packaged in `:adapter-http-legacy-admin`. diff --git a/.agents/skills/cryptad-interop-performance-gates/SKILL.md b/.agents/skills/cryptad-interop-performance-gates/SKILL.md new file mode 100644 index 0000000000..c375ca1457 --- /dev/null +++ b/.agents/skills/cryptad-interop-performance-gates/SKILL.md @@ -0,0 +1,66 @@ +--- +name: cryptad-interop-performance-gates +description: "Maintain Cryptad's Hyphanet interop and performance regression gates under tools/interop, tools/perf, CI jobs, and release-readiness documentation." +--- + +# Cryptad interop and performance gates + +Use this skill before changing `tools/interop`, `tools/perf`, related CI jobs, or release-gate +documentation. + +## Read first + +- Hyphanet interop gate: `tools/interop/README.md` +- Performance regression gate: `tools/perf/README.md` +- Release readiness gates: `docs/cryptad-release-workflow-and-runbook.md` +- Phase 3 platform closeout context: `docs/phase-3-platform-primacy-closeout.md` + +## Hyphanet interop gate + +- Tier 1 smoke is the release-readiness compatibility gate. It is Linux-only and runs a packaged + Cryptad node against a pinned Hyphanet baseline. +- Tier 2 extended soak runs locally or through scheduled/manual CI when compatibility-sensitive + behavior changed. It adds long-lived `SubscribeUSK`, persistent request replay, optional opennet + plumbing, and longer diagnostics. +- Normal local commands: + +```bash +python3 tools/interop/interop_smoke.py --self-test +tools/interop/run-hyphanet-interop-smoke.sh +INTEROP_SKIP_BUILD=1 tools/interop/run-hyphanet-interop-smoke.sh +INTEROP_MODE=extended INTEROP_SKIP_BUILD=1 tools/interop/run-hyphanet-interop-smoke.sh +``` + +- Do not publish `artifacts/private-insert-uris.json`; it contains temporary insert keys and CI + excludes it from uploads. +- Preserve `build/interop-smoke/` or `build/interop-extended/` when a gate fails or when a release + record needs compatibility evidence. + +## Performance regression gate + +- The performance gate records lightweight packaged-node startup, local FCP/Platform API timing, + distribution size, Web Shell asset size, SDK asset size, and first-party static app asset size + signals. It is not a broad benchmark suite. +- The runner requires Python 3.12 or newer. +- Normal local commands: + +```bash +python3 tools/perf/perf_smoke.py --self-test +tools/perf/run-performance-smoke.sh +PERF_SKIP_BUILD=1 tools/perf/run-performance-smoke.sh +PERF_MODE=collect PERF_SKIP_BUILD=1 tools/perf/run-performance-smoke.sh +``` + +- Deterministic asset-size failures are release blockers unless a maintainer records an accepted + baseline update or waiver. Environment-sensitive timing regressions need comparable hardware or + runner evidence before promotion decisions. +- Do not update `tools/perf/baselines/performance-smoke.json` only to silence a regression. Record + before/after summaries, host or runner details, Java version, commit SHA, and the rationale. + +## CI and release notes + +- `.github/workflows/ci.yml` runs `interop-smoke` on push/PR, `interop-extended` on schedule/manual, + interop self-tests on the multi-OS matrix, performance self-tests on the multi-OS matrix, and + `performance-smoke` on schedule/manual. +- Release notes should mention interop/performance gate changes only when they affect release + readiness, operator confidence, app/platform behavior, or packager workflows. diff --git a/.agents/skills/cryptad-packaging/SKILL.md b/.agents/skills/cryptad-packaging/SKILL.md index eaa4b4b762..da9f89444c 100644 --- a/.agents/skills/cryptad-packaging/SKILL.md +++ b/.agents/skills/cryptad-packaging/SKILL.md @@ -25,7 +25,7 @@ Use this skill when working on: `:foundation-config`, `:foundation-fs`, `:foundation-compat`, `:kernel-content`, `:kernel-transport`, `:kernel-routing`, `:runtime-spi`, `:platform-api`, `:platform-apphost`, `:platform-app-ui`, `:platform-appdist`, `:platform-appcatalog`, - `:platform-web-shell`, `:runtime-alerts`, `:runtime-node`, `:adapter-fcp`, + `:platform-sdk-js`, `:platform-web-shell`, `:runtime-alerts`, `:runtime-node`, `:adapter-fcp`, `:bridge-fcp-runtime`, `:bridge-http-runtime`, `:adapter-http-legacy-admin`, `:adapter-http-legacy-browse`, `:thirdparty-onion`, `:thirdparty-legacy`, and `:launcher-desktop`. @@ -48,6 +48,8 @@ Use this skill when working on: trusted-key, and distribution-tool classes used by first-party app tasks and AppHost validation. - The `:platform-appcatalog` JAR contributes signed catalog source parsing, verification, artifact download, safe ZIP extraction, and verified staging support. +- The `:platform-sdk-js` JAR contributes the browser SDK resource staged into first-party static + app bundles and loaded by app-owned UIs under `/apps/{appId}/`. - The `:platform-web-shell` JAR contributes the browser-facing node-management shell HTML, CSS, JavaScript, and bootstrap resources that the legacy HTTP adapter mounts at `/app/node/`. - The `:runtime-alerts` JAR contributes the detached alert/feed model subset, including the @@ -72,7 +74,8 @@ Use this skill when working on: - First-party app projects such as `:apps:queue-manager` and `:apps:publisher` provide staged app bundles through their `stageApp`, `signApp`, and `verifyApp` tasks. Those bundles are release artifacts and AppHost install inputs; they are not daemon entrypoints inside - `build/cryptad-dist`. + `build/cryptad-dist`. Their static UI staging copies the current `:platform-sdk-js` browser + resource into each bundle's `static/` assets. ## Distributions and Windows wrapper sources - `assembleCryptadDist` creates a portable layout under `build/cryptad-dist` with `bin/`, `lib/`, and `conf/`. diff --git a/.agents/skills/cryptad-platform-apps/SKILL.md b/.agents/skills/cryptad-platform-apps/SKILL.md new file mode 100644 index 0000000000..f50cd398a6 --- /dev/null +++ b/.agents/skills/cryptad-platform-apps/SKILL.md @@ -0,0 +1,78 @@ +--- +name: cryptad-platform-apps +description: "Work on Cryptad's app platform: Platform API v1, AppHost runtime, signed app bundles/catalogs, app-owned static UI, the browser SDK, app permissions/audit, and legacy admin retirement routing." +--- + +# Cryptad platform apps + +Use this skill before touching app-platform code, docs, or tests. + +## Read first + +Load only the docs needed for the change: + +- Platform API and shell surface: `docs/platform-api-surface.md` +- Signed bundles and first-party app tasks: `docs/app-distribution.md` +- Signed catalogs: `docs/app-catalogs.md` +- App-owned static UI routes and bootstrap JSON: `docs/app-owned-ui.md` +- Browser SDK behavior: `docs/platform-sdk-js.md` +- AppHost runtime/log/token boundary: `docs/apphost-runtime-hardening.md` +- App-token permission matrix and audit model: `docs/app-permissions-and-audit.md` +- Legacy admin replacement map and usage counters: `docs/legacy-retirement-plan.md` + +## Ownership map + +- `:platform-api` owns the transport-neutral Platform API v1 router, route families, app-token + authorization decisions, capabilities, and bounded app audit log. +- `:platform-apphost` owns installed app layout, manifest parsing, app process lifecycle, + per-launch `CRYPTAD_APP_TOKEN`, runtime status, process-log capture/redaction, and restart + attempts. +- `:platform-app-ui` owns static route/path/content-type/header helpers for `/apps/{appId}/`. +- `:platform-sdk-js` owns `crypta-platform.js`, the dependency-free browser helper staged into + first-party static app bundles. +- `:platform-appdist` owns local signed bundle digests, signatures, trusted-key verification, and + first-party signing/verification tooling. +- `:platform-appcatalog` owns signed catalog parsing, source/artifact verification, safe ZIP + extraction, and verified staging into AppHost install/update flows. +- `:platform-web-shell` owns `/app/node/` browser shell assets and bootstrap. +- `:adapter-http-legacy-admin` hosts the current `/api/v1/`, `/app/node/`, and `/apps/{appId}/` + HTTP bridges plus legacy admin retirement notices and diagnostics counters. +- `:apps:queue-manager` and `:apps:publisher` stage first-party static UI bundles. + +## Guardrails + +- Never expose `CRYPTAD_APP_TOKEN` through browser bootstrap JSON, Web Shell bootstrap, app + summaries, runtime/log/audit API responses, diagnostics, `toString()`, or error text. +- Browser static UI is same-origin with the local admin UI. It is not a sandbox, an app session, or + app-token authority. Server-side Platform API permission checks remain authoritative. +- App-originated Platform API requests must authenticate with a live launch token and pass the + central capability matrix. Deny app principals by default. +- Audit entries are bounded and process-local. Do not add query strings, request bodies, form + passwords, tokens, absolute filesystem paths, or large payloads. +- Static UI routes must serve only immutable installed-bundle files. Reject traversal, encoded path + separators, symlink/reparse escapes, reserved sidecars, and host-dependent MIME inference. +- Signed catalogs and bundles must verify before install/update. Unsigned live-node installs require + the explicit development-only escape hatch. +- Legacy admin retirement changes must update both the code map + (`LegacyAdminRetirementRegistry`) and `docs/legacy-retirement-plan.md`. + +## Validation + +Use `$cryptad-build-test` for Gradle rules and timeouts. Common focused checks: + +```bash +./gradlew :platform-api:test +./gradlew :platform-apphost:test +./gradlew :platform-app-ui:test +./gradlew :platform-appdist:test +./gradlew :platform-appcatalog:test +./gradlew :platform-sdk-js:test +./gradlew :platform-web-shell:test +./gradlew :adapter-http-legacy-admin:test +./gradlew :apps:queue-manager:test +./gradlew :apps:publisher:test +./gradlew stageFirstPartyApps +``` + +When changing route contracts or bridge wiring, also run the relevant root router/toadlet tests +with `./gradlew :test --tests *PlatformApiRouterTest --tests *PlatformApiToadletTest`. diff --git a/.agents/skills/cryptad-release-workflow/SKILL.md b/.agents/skills/cryptad-release-workflow/SKILL.md index 5622e36bc3..e214745b91 100644 --- a/.agents/skills/cryptad-release-workflow/SKILL.md +++ b/.agents/skills/cryptad-release-workflow/SKILL.md @@ -28,6 +28,10 @@ Build: 2 - Merge `release/*` into `main` and back-merge into `develop` using **no squash** and `--no-ff`. - Stabilization only: allow critical fixes/docs/release tasks; avoid large refactors. - Do not rebase/squash release merges. +- Use `docs/cryptad-release-workflow-and-runbook.md` as the detailed release-readiness source of + truth. Current release gates include first-party app staging/signing/verification, catalog and + app-owned UI smoke when those surfaces ship, Hyphanet interop smoke/soak evidence, and the + packaged-node performance smoke. --- @@ -40,6 +44,9 @@ git checkout -b release/ ``` 2) Set the build number in `build.gradle.kts` (e.g., `version = `), and run CI/tests per repo conventions. + Follow the release gates in `docs/cryptad-release-workflow-and-runbook.md`; load + `$cryptad-build-test`, `$cryptad-platform-apps`, and `$cryptad-interop-performance-gates` when + those areas are involved. 3) Stabilize on `release/` (critical fixes only). Keep diffs minimal. @@ -73,6 +80,11 @@ git push origin v ## Checklist - [ ] `build.gradle.kts` version is the intended integer build number. - [ ] CI green on `release/`. +- [ ] First-party AppHost bundles staged, signed, and verified when shipping app-platform artifacts. +- [ ] Hyphanet interop smoke passed or CI evidence recorded; extended interop captured when + compatibility-sensitive behavior changed. +- [ ] Performance smoke passed or scheduled/manual CI evidence recorded when release readiness or + performance-sensitive changes require it. - [ ] Tag `v` created. - [ ] Merged to `main` with `--no-ff` (no squash), then back-merged to `develop` with `--no-ff`. - [ ] Branches and tag pushed. diff --git a/.agents/skills/cryptad-style-docs/SKILL.md b/.agents/skills/cryptad-style-docs/SKILL.md index a72851836d..0db1faef8a 100644 --- a/.agents/skills/cryptad-style-docs/SKILL.md +++ b/.agents/skills/cryptad-style-docs/SKILL.md @@ -21,6 +21,8 @@ Use this skill when you: `:platform-web-shell`, and the adapter modules, keep `package-info.java` in each production package you add or move. Boundary tests currently enforce this for the runtime, kernel, platform, FCP, and HTTP leaves, and the adapter packages follow the same convention. +- Resource-owned leaves such as `:platform-sdk-js` still keep Java tests under `src/test/java`. + Add `package-info.java` only when a production Java package is added. ## Style guides - Java: follow the Google Java Style Guide. diff --git a/.agents/skills/cryptad-write-release-notes/SKILL.md b/.agents/skills/cryptad-write-release-notes/SKILL.md index 576955b36d..87867ddbc4 100644 --- a/.agents/skills/cryptad-write-release-notes/SKILL.md +++ b/.agents/skills/cryptad-write-release-notes/SKILL.md @@ -15,6 +15,7 @@ This skill covers how to draft or review a Cryptad GitHub release body and match - Repo-root `changelog-short.txt` if it exists - Repo-root `changelog-full.txt` if it exists - Repo-root `docs/standard-git-branching-and-release-workflow.md` +- Repo-root `docs/cryptad-release-workflow-and-runbook.md` - Repo-root `build.gradle.kts` ## Process @@ -71,10 +72,11 @@ Typical Cryptad buckets: - `What's new` - `Upgrade and compatibility` +- App platform, Platform API, Web Shell, app bundles/catalogs, app-owned UI, and browser SDK - Installers and packaging - Launcher and UI - Core updater -- Stability, performance, and security +- Interop, stability, performance, and security - Contributor or packager notes, only if they matter outside the core dev loop ### 5. Draft the release body @@ -109,6 +111,9 @@ Authoring rules: - Tag, build number, and asset names are correct. - Commands and upgrade steps match the shipped artifacts. - Linux, macOS, Windows, Flatpak, and Snap notes are present when relevant. +- App permission/audit changes, AppHost runtime boundary changes, legacy admin retirement changes, + interop gate changes, and performance-gate changes are called out when they affect operators, + packagers, or app developers. - Internal churn, reverted noise, and same-cycle regressions are removed. - The final body does not leave GitHub's autogenerated `## What's Changed` section in place unless the user explicitly wants that format. - `changelog-short.txt` matches `changelog-full.md` in substance. diff --git a/AGENTS.md b/AGENTS.md index 6e6d2a192b..878257e7e7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,7 +1,7 @@ # Project Configuration ## Project Overview -Crypta is a peer-to-peer network providing a distributed, encrypted, and decentralized datastore. It is a fork of Hyphanet (formerly Freenet), building upon its technology for censorship-resistant communication and publishing. This repository contains the reference node implementation (the "Crypta reference daemon"). +Crypta is a peer-to-peer network providing a distributed, encrypted, and decentralized datastore plus a local app platform. It is a fork of Hyphanet (formerly Freenet), building upon its technology for censorship-resistant communication and publishing. This repository contains the reference node implementation (the "Crypta reference daemon"). ## Skills: load on demand @@ -23,6 +23,8 @@ Load only what you need. It’s normal to load multiple skills for one task. - **$cryptad-hotfix-workflow** — Run emergency hotfix flow: cut `hotfix/` from `main`, ship fix, tag `v`, and no-squash `--no-ff` merges to `main` and `develop`. - **$cryptad-launcher-ui** — Work on the Swing launcher: start/stop logic, logging, keyboard shortcuts, FlatLaf/theme handling, and Windows specifics. - **$cryptad-packaging** — Build and troubleshoot distributions and installers (assembleCryptadDist, jpackage, Windows wrapper assets, Flatpak, Linux DEB/RPM behavior). +- **$cryptad-platform-apps** — Work on Platform API v1, AppHost, signed app bundles/catalogs, app-owned static UI, the browser SDK, app permissions/audit, and legacy admin retirement routing. +- **$cryptad-interop-performance-gates** — Maintain the Hyphanet interop and performance regression gates under `tools/interop`, `tools/perf`, and CI/release readiness docs. - **$improve-unit-test-coverage-for-current-changes** — Improve unit test coverage for the current uncommitted Java changes with targeted Gradle runs and one final full-suite pass. - **$cryptad-runtime-debugging** — Debug live or reproducible Cryptad JVM failures on Windows, macOS, and Linux using `jcmd`, `jdb`, thread dumps, and the default JDWP listener on `127.0.0.1:5005`. - **$cryptad-write-release-notes** — Draft or review GitHub release notes and changelog artifacts for Cryptad builds, including `changelog-full.md`, `changelog-short.txt`, and `changelog-full.txt`. @@ -33,7 +35,7 @@ Load only what you need. It’s normal to load multiple skills for one task. ### Skill-first workflow -1. Identify the task domain(s) (build/test, tooling, packaging, updater, platform detection, crypto formats, UI, git branching/release/hotfix workflows, etc.). +1. Identify the task domain(s) (build/test, tooling, packaging, updater, app platform, compatibility/performance gates, platform detection, crypto formats, UI, git branching/release/hotfix workflows, etc.). 2. Load the matching skill(s) via `skill(...)`. 3. If relevant files are not already known, identify them with targeted local searches first, then inspect code (don’t guess). 4. Make the smallest safe change. @@ -51,6 +53,8 @@ Load only what you need. It’s normal to load multiple skills for one task. - For AEAD stream / format changes, load `$cryptad-crypto-aead` first. - **Environment detection:** Treat `AppEnv` as the single source of truth. Load `$cryptad-appenv` before touching OS/arch/sandbox/service detection code. - **Updater:** For any changes touching CoreUpdater descriptors, endpoints, or UI, load `$cryptad-core-updater`. +- **App platform:** For Platform API, AppHost, app catalogs/bundles, app-owned UI routes, the browser SDK, app permission/audit, or legacy admin retirement routing, load `$cryptad-platform-apps`. +- **Interop/performance gates:** For `tools/interop`, `tools/perf`, related CI jobs, or release-gate evidence, load `$cryptad-interop-performance-gates`. - **Packaging/Installers:** For dist builds, installers, or Flatpak, load `$cryptad-packaging`. - **Runtime debugging:** For live deadlocks, hangs, blocked threads, stalled requests, or JDWP debugging with `jcmd` / `jdb`, load `$cryptad-runtime-debugging`. - **Branch workflow questions:** For branch model/merge/tag/version policy questions, load `$cryptad-git-workflow`. diff --git a/README.md b/README.md index 74c5b65022..05780fb016 100644 --- a/README.md +++ b/README.md @@ -398,6 +398,9 @@ Key docs: - [Signed app catalogs](docs/app-catalogs.md) - [App-owned static UI](docs/app-owned-ui.md) - [Platform JavaScript SDK](docs/platform-sdk-js.md) +- [AppHost runtime hardening](docs/apphost-runtime-hardening.md) +- [App permissions and audit](docs/app-permissions-and-audit.md) +- [Legacy admin retirement plan](docs/legacy-retirement-plan.md) ## Hyphanet Interop Gate @@ -461,6 +464,10 @@ leaf ownership and import rules: ```bash ./gradlew :platform-api:test ./gradlew :platform-apphost:test +./gradlew :platform-app-ui:test +./gradlew :platform-appdist:test +./gradlew :platform-appcatalog:test +./gradlew :platform-sdk-js:test ./gradlew :platform-web-shell:test ./gradlew :kernel-content:test ./gradlew :kernel-transport:test @@ -489,8 +496,8 @@ Additional root and mixed verification slices remain available: ./gradlew :test --tests *PlatformApiRouterTest --tests *PlatformApiAppsIntegrationTest ``` -Platform boundary checks now live in `:platform-api`, `:platform-apphost`, and -`:platform-web-shell`. +Platform checks now live in `:platform-api`, `:platform-apphost`, `:platform-app-ui`, +`:platform-appdist`, `:platform-appcatalog`, `:platform-sdk-js`, and `:platform-web-shell`. ## Code Quality @@ -889,7 +896,7 @@ Tip: Keep the Spotless formatter at the intended version (currently `googleJavaF `:foundation-config`, `:foundation-fs`, `:foundation-compat`, `:kernel-content`, `:kernel-transport`, `:kernel-routing`, `:runtime-spi`, `:runtime-alerts`, `:platform-api`, `:platform-apphost`, `:platform-app-ui`, `:platform-appdist`, - `:platform-appcatalog`, `:platform-web-shell`, `:runtime-node`, + `:platform-appcatalog`, `:platform-sdk-js`, `:platform-web-shell`, `:runtime-node`, `:adapter-fcp`, `:bridge-fcp-runtime`, `:bridge-http-runtime`, `:adapter-http-legacy-admin`, `:adapter-http-legacy-browse`, `:thirdparty-onion`, `:thirdparty-legacy`, and `:launcher-desktop`.