broader-vids 0.1.0 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/docs/REFERENCE.md CHANGED
@@ -749,8 +749,13 @@ Completed assessments normally remove downloaded full videos automatically.
749
749
 
750
750
  ## Run automated checks
751
751
 
752
+ Tests cover complete recommendation workflows, scoring, learning, saved data, essential dashboard actions, and package releases.
753
+ Retain regression tests for distinct failures that change these results or lose user data.
754
+ Use representative input cases. Avoid duplicate helper checks, retired compatibility matrices, and exhaustive visual combinations.
755
+ Keep detailed visual inspection separate from the regression suite.
756
+
752
757
  ```powershell
753
- uv sync --locked --extra evidence --extra asr
758
+ uv sync --locked --extra evidence
754
759
  npm ci --ignore-scripts
755
760
  uv run --no-sync ruff check src tests scripts
756
761
  uv run --no-sync ruff format --check src tests scripts
@@ -813,7 +818,7 @@ CI uses `scripts/test.py --jobs 3 --verbose` and limits that step to ten minutes
813
818
  The runner reports active files every fifteen seconds. Timeout reports include the last running test.
814
819
  CI uses the runner scratch directory for temporary profiles.
815
820
  Path tests compare resolved paths. Reset and Clean tests use the exact directory shown by each preview.
816
- Dashboard tests check drafts, failed writes, duplicate feedback, dialogs, platform navigation, and responsive themes.
821
+ Dashboard tests check rating saves, drafts, duplicate feedback, dialogs, and platform navigation.
817
822
  Keep screenshots and other visual checks under the ignored `.cache/` directory.
818
823
  Browser tests reuse a browser process within each worker and create a fresh context for each test.
819
824
 
@@ -824,9 +829,9 @@ The desktop app accepts the public GitHub repository directly through Add market
824
829
  The repository catalog points to the released npm package.
825
830
  GitHub provides the catalog, not an unbuilt engine checkout.
826
831
 
827
- `npx --yes broader-vids@0.1.0 plugin install` provides a separate npm entry point.
832
+ `npx --yes broader-vids@latest plugin install` provides a separate npm entry point.
828
833
  It registers an npm-only marketplace named `broader-vids-npm` and installs `broader-vids@broader-vids-npm` through Codex.
829
- Its source pins the version of the running npm package.
834
+ Its source pins the version of the running npm package. The `latest` selector retrieves the current public bootstrap.
830
835
  This route does not require the GitHub catalog.
831
836
  The package contains the engine wheel, launcher, skills, and dashboard assets.
832
837
  No npm lifecycle script registers plugins or installs the runtime.
@@ -932,37 +937,119 @@ npm run release:prepare
932
937
  It builds a Python wheel, packs and verifies the npm archive, builds a plugin ZIP and generated `dist/local-marketplace`, and writes `dist/release.json` and `dist/SHA256SUMS`.
933
938
  It does not upload artifacts.
934
939
 
935
- The public npm package is `broader-vids@0.1.0`.
936
- The GitHub marketplace catalog uses the name `broader-vids` and pins its npm source to version `0.1.0`.
940
+ The public npm package is `broader-vids`.
941
+ The GitHub marketplace catalog uses the name `broader-vids` and tracks the npm `latest` distribution tag.
937
942
  Users install the marketplace plugin from the README instructions.
938
943
  The npm `plugin install` command registers the full plugin. A plain global npm install provides only the launcher.
939
944
 
940
- ### Publish a release
945
+ ### Automatic public releases
946
+
947
+ After a push updates `main`, its successful `checks` run starts `.github/workflows/release.yml`.
948
+ Direct commits and merged pull requests both qualify.
949
+ Other branches and unmerged pull requests do not publish packages.
950
+ The workflow checks the source repository, main branch, push event, and exact tested commit before privileged work.
951
+ A newer main commit can supersede an earlier queued release.
952
+ Automatic runs reuse the successful Windows and Ubuntu checks. A manual dispatch runs those checks again.
953
+
954
+ Releases run in sequence. The next patch follows the latest stable npm version.
955
+ An existing Git tag reserves its version, even when npm publication did not finish.
956
+ A different source receives a later version. A retry of the same source can reuse its tag.
957
+ A higher version declared in the source acts as a minimum for the release version.
958
+ The workflow synchronizes Node, Python, plugin, lock-file, and wheel-whitelist versions in a temporary release checkout.
959
+ It records the tested source commit in `package.json` under `broaderVidsRelease.sourceCommit`.
960
+ It writes the version commit to main and creates its `vX.Y.Z` tag in one atomic push.
961
+ The commit contains the tested functional source with synchronized release metadata.
962
+ A guarded push refuses to overwrite a newer main update.
963
+ The frozen starter preset remains unchanged.
964
+
965
+ The workflow prepares the wheel, npm archive, plugin ZIP, manifest, and checksums.
966
+ It checks source inclusion, versions, private-data exclusions, and archive integrity before publication.
967
+ The npm job uses OIDC through the `npm-release` environment.
968
+ Only that job receives `id-token: write` permission.
969
+ Publication jobs accept the intentionally skipped duplicate checks on automatic runs.
970
+ They still require successful preparation and stop after cancellation. GitHub assets also require successful npm publication.
971
+ Tag creation and GitHub release assets use separate jobs with `contents: write` permission.
972
+ The workflow publishes the verified archive under `latest`, then checks public registry integrity.
973
+ It creates a GitHub release with the archives, manifest, and checksums after npm publication succeeds.
974
+ It retains workflow artifacts for seven days.
975
+
976
+ Retries resolve a tagged version commit back to its tested merge source.
977
+ They reuse a release when its recorded source commit matches that source.
978
+ An existing tag must have the expected parent and exact release tree.
979
+ The bot version commit does not allocate a second version.
980
+ GitHub does not start another push workflow for a commit pushed with the workflow's `GITHUB_TOKEN`.
981
+ See [GitHub's trigger rules](https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/trigger-a-workflow).
982
+ An existing npm version must match the archive checksum. The workflow never replaces its contents.
983
+ Existing GitHub assets must match their size and checksum.
984
+ A conflict stops publication with an error.
985
+ For recovery, rerun the failed workflow or manually dispatch Release from main.
986
+ Manual dispatch uses the current main commit and requires passing checks.
987
+ It does not require a manually created tag.
988
+
989
+ ### Configure automatic publication once
990
+
991
+ Complete these account settings before the first automatic release:
992
+
993
+ 1. In GitHub, open this repository's **Settings → Environments**.
994
+ 2. Create an environment named `npm-release`.
995
+ 3. Restrict deployment to the `main` branch.
996
+ 4. Omit required reviewers and wait timers when releases must proceed automatically.
997
+ 5. Allow the release workflow to push version commits to main and create `v*` tags.
998
+ 6. In npm, open **broader-vids → Settings → Trusted Publisher**.
999
+ 7. Select **GitHub Actions** and enter the following values.
1000
+
1001
+ | Field | Value |
1002
+ | --- | --- |
1003
+ | Organization or user | `antidemosthenes` |
1004
+ | Repository | `broader-vids` |
1005
+ | Workflow filename | `release.yml` |
1006
+ | Environment | `npm-release` |
1007
+ | Allowed action | Enable direct `npm publish` |
1008
+
1009
+ Staging alone does not provide automatic publication. Staged packages require a separate maintainer approval.
1010
+ The first successful trusted publication must complete within two days after configuration.
1011
+ Recreate an expired configuration before retrying.
1012
+ The workflow uses no permanent npm token.
1013
+ See the [npm trusted-publisher guide](https://docs.npmjs.com/trusted-publishers/) for account controls and validation requirements.
1014
+
1015
+ After these settings are complete, push the reviewed changes to main directly or merge a development pull request into main.
1016
+ Check both the ordinary CI run and the following Release run.
1017
+ Check the npm `latest` version and matching GitHub release before announcing the update.
1018
+ A Git tag can exist before npm publication finishes.
1019
+ Check the `publish` and `github-release` jobs, not only the tag or overall workflow status.
1020
+ The account settings and the first live OIDC publication require separate acceptance. Local fixtures cannot check them.
941
1021
 
942
- The release workflow does not publish on push.
943
- An authorized maintainer must manually dispatch `.github/workflows/release.yml` with an existing `vX.Y.Z` tag.
944
- The tag must point to the intended release commit, and its version must match the package version.
945
- The `npm-release` protected environment uses GitHub OIDC and Node.js 24 with npm 11.5.1 or later.
946
- This workflow publishes the npm package only. It does not submit the marketplace catalog to a directory.
1022
+ ### Update an installed plugin
947
1023
 
948
- For the first publish, prepare the artifacts and publish the tarball from a local npm session:
1024
+ Finish active recommendations and stop the dashboard before updating.
1025
+ For a GitHub installation:
949
1026
 
950
1027
  ```powershell
951
- npm login
952
- npm run release:prepare
953
- uv run --no-sync scripts/release.py verify --artifacts-dir dist
954
- uv run --no-sync scripts/release.py available --tag v0.1.0
955
- npm publish ./dist/broader-vids-0.1.0.tgz --ignore-scripts --access public --tag latest --registry https://registry.npmjs.org
1028
+ codex plugin marketplace upgrade broader-vids
1029
+ codex plugin add broader-vids@broader-vids
956
1030
  ```
957
1031
 
958
- Complete any required npm two-factor authentication during this manual publish.
959
- Configure npm trusted publishing when the first CI publication is ready.
960
- Set its publisher owner to `antidemosthenes`, repository to `broader-vids`, workflow filename to `release.yml`, and environment to `npm-release`.
961
- The first successful CI publish must complete within two days after you create the trusted publisher configuration.
962
- The npm package must allow direct `npm publish` from the trusted publisher.
963
- Configure `npm-release` as a GitHub environment and set its reviewers according to your release policy.
964
- Reviewers require manual configuration in GitHub.
965
- The workflow uses no permanent npm token.
1032
+ For an npm installation:
1033
+
1034
+ ```powershell
1035
+ npx --yes broader-vids@latest plugin install
1036
+ ```
1037
+
1038
+ Run npm acceptance commands outside this source checkout.
1039
+ Npm can treat a matching source project as an installed package and omit its executable shim.
1040
+ The npm bootstrap updates its existing catalog and asks Codex to install that exact package version.
1041
+ The GitHub catalog follows `latest` after refresh.
1042
+ The host has no separate `codex plugin update` command.
1043
+ A marketplace refresh updates catalog information. The following install action selects the current plugin package.
1044
+ Use the installation method that matches the existing marketplace to avoid duplicate plugin entries.
1045
+
1046
+ In the desktop app, refresh the marketplace and select the current plugin release.
1047
+ If an update action is unavailable, use the terminal commands for that marketplace.
1048
+ Start a new conversation and run the setup skill after updating.
1049
+ Setup refreshes the matching runtime and preserves preferences, ratings, history, exclusions, and sign-in.
1050
+ An update does not run Reset or Clean.
1051
+
1052
+ ### Repair the installed runtime
966
1053
 
967
1054
  From an unpacked package, install its external engine:
968
1055