feat(repo): maintenance mode, with triage that closes out-of-policy requests

MAINTENANCE.md is the policy: dependency updates on a schedule, high and
critical advisories fixed as soon as a fix exists, major platform upgrades,
bug/UI/UX/accessibility/translation fixes, and features only when they are
on docs/15's roadmap or genuinely needed.

- The feature form asks one required question — on the roadmap, needed for
  a fix, or something new — and links the policy and Discussions › Ideas.
- scripts/triage.mjs decides what happens, as a pure, unit-tested function;
  .github/workflows/triage.yml carries it out with `gh` alone. Something new
  is labelled maintenance-mode, commented and closed as not planned; the two
  in-policy answers get needs-triage; an outside `feat…` pull request is
  closed the same way. Owner, members, collaborators, bots and `roadmap` are
  exempt.
- pull_request_target checks out the base branch only, runs nothing from the
  pull request, and never interpolates a title or body into the shell.
- README gains a status badge and a "Project status" section; CONTRIBUTING,
  the PR template and the issue chooser say what is accepted.
- docs: 00 status, 11 inventory, 12 §2.6 and §5 (labels), 13 §6, 15 (a
  pointer to the policy, not a copy, and the decision-log rows); CLAUDE.md
  Phase 10.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
poli0981andClaude Opus 5.5 committed 2026-11-18 21:03:47 +07:00
1 parent 11e7e50fe6
commit eabffbe652
16 files changed
+815 -19

No files matched your search

+7
View File
@@ -6,6 +6,13 @@
blank_issues_enabled: false
contact_links:
- name: An idea, to talk through first
url: https://github.com/poli0981/bookmarkmagic/discussions/categories/ideas
about: >-
BookmarkMagic is in maintenance mode (MAINTENANCE.md). A new idea is
welcome here, where it can be discussed without an issue that has to be
accepted or refused.
- name: Security vulnerability
url: https://github.com/poli0981/bookmarkmagic/security/advisories/new
about: Report privately, never as a public issue. See SECURITY.md.
+41 -11
View File
@@ -1,20 +1,50 @@
name: Suggest a feature
description: An idea for something BookmarkMagic should do.
description: BookmarkMagic is in maintenance mode — read what that means before asking for something new.
title: '[feature] '
labels: [enhancement]
body:
- type: markdown
attributes:
value: |
Before writing: this project has a short, deliberate
[never list](https://github.com/poli0981/bookmarkmagic/blob/main/docs/15_ROADMAP.md).
Cloud sync, accounts, analytics of any kind, and anything that would
require new browser permissions are out of scope permanently — not
because they are hard, but because "offline, two permissions, no
network" is the entire point of the extension.
**BookmarkMagic is in maintenance mode**
([MAINTENANCE.md](https://github.com/poli0981/bookmarkmagic/blob/main/MAINTENANCE.md)).
A feature is added only when it is already on the
[roadmap](https://github.com/poli0981/bookmarkmagic/blob/main/docs/15_ROADMAP.md),
or when it is genuinely needed to fix a defect or remove a barrier.
Everything else is genuinely open. The roadmap in that same file lists
what is already planned.
**The first question below decides what happens to this issue.** A
request for something new is closed automatically and labelled
`maintenance-mode` — not deleted, and read; the
[Ideas discussions](https://github.com/poli0981/bookmarkmagic/discussions/categories/ideas)
are the place to talk one through. The other two answers keep the issue
open for the maintainer.
Out of scope permanently, whatever the mode: cloud sync, accounts,
analytics of any kind, and anything that would need a new browser
permission. "Offline, two permissions, no network" is the point of the
extension.
- type: dropdown
id: kind
attributes:
label: Which kind of change is this?
description: See MAINTENANCE.md. Please answer honestly — a mislabelled request is closed by hand.
options:
- Something already on the roadmap (docs/15)
- Needed to fix a bug, a UI/UX defect or an accessibility barrier
- Something new — not on the roadmap
validations:
required: true
- type: input
id: reference
attributes:
label: Which roadmap item, or which defect?
description: >-
The line in docs/15, or the issue or behaviour it fixes. Leave empty
for something new.
validations:
required: false
- type: textarea
id: problem
@@ -52,5 +82,5 @@ body:
permission, and does not involve a server, an account, or sending
data anywhere.
required: true
- label: I checked the roadmap and the never list.
required: false
- label: I read MAINTENANCE.md and checked the roadmap and the never list.
required: true
+7
View File
@@ -7,6 +7,13 @@ a translation fix does not need the parser section, and vice versa.
<!-- What changes, and what problem it solves. Link the issue if there is one. -->
**Kind of change** ([MAINTENANCE.md](https://github.com/poli0981/bookmarkmagic/blob/main/MAINTENANCE.md) — the project
is in maintenance mode): <!-- bug fix · UI/UX fix · accessibility · translation
· dependency or security update · roadmap item (which?) -->
A pull request titled `feat…` from outside the project is closed automatically
unless its feature is on the roadmap — open a feature request first.
## Checklist
- [ ] `npm run verify` is green. (Release-bearing? `npm run verify:full` —
+88
View File
@@ -0,0 +1,88 @@
# Maintenance-mode triage — MAINTENANCE.md, docs/12 §2.6.
#
# scripts/triage.mjs decides (a pure, unit-tested function of the event); this
# file only carries the decision out with the `gh` CLI the runner ships. No
# third-party action holds the write token.
#
# Security, because `pull_request_target` runs with a write token even for a
# pull request from a fork:
# - the checkout is the DEFAULT BRANCH (what pull_request_target checks out
# unless told otherwise) — never the pull request's head, and nothing from
# the pull request is executed;
# - the payload reaches the script as the runner's event FILE; no title, body
# or label is ever interpolated into a shell line with `${{ }}`;
# - the decision the shell reads back is constants: an action from a fixed
# set, an integer, a label from a fixed list, a comment the script wrote.
name: Triage
on:
issues:
types: [opened, labeled]
pull_request_target:
types: [opened]
permissions: {}
# A new issue from the feature form fires `opened` and `labeled` together; one
# at a time per number, and the second re-reads the live state before acting.
concurrency:
group: triage-${{ github.event.issue.number || github.event.pull_request.number }}
cancel-in-progress: false
jobs:
triage:
name: Maintenance-mode triage
runs-on: ubuntu-latest
timeout-minutes: 5
permissions:
contents: read
issues: write
pull-requests: write
steps:
- uses: actions/checkout@v7
with:
persist-credentials: false
- uses: actions/setup-node@v7
with:
node-version-file: .nvmrc
- name: Decide
run: node scripts/triage.mjs > "$RUNNER_TEMP/decision.json"
- name: Act
env:
GH_TOKEN: ${{ github.token }}
GH_REPO: ${{ github.repository }}
run: |
set -euo pipefail
decision="$RUNNER_TEMP/decision.json"
action=$(jq -r '.action' "$decision")
echo "triage: $action — $(jq -r '.reason' "$decision")"
[ "$action" = none ] && exit 0
kind=$(jq -r '.kind' "$decision")
number=$(jq -r '.number' "$decision")
label=$(jq -r '.label' "$decision")
case "$kind" in issue|pr) ;; *) echo "::error::unexpected kind"; exit 1 ;; esac
[[ "$number" =~ ^[0-9]+$ ]] || { echo "::error::unexpected number"; exit 1; }
# Re-read the live state: the second of two events for one issue
# finds the first one's label and does nothing.
live=$(gh "$kind" view "$number" --json state,labels \
--jq '[.state] + [.labels[].name] | join(" ")')
case " $live " in
*" maintenance-mode "*|*" needs-triage "*|*" roadmap "*)
echo "already triaged: $live"; exit 0 ;;
esac
case "$live" in OPEN*) ;; *) echo "not open: $live"; exit 0 ;; esac
gh "$kind" edit "$number" --add-label "$label"
if [ "$action" = close ]; then
jq -r '.comment' "$decision" > "$RUNNER_TEMP/comment.md"
gh "$kind" comment "$number" --body-file "$RUNNER_TEMP/comment.md"
if [ "$kind" = issue ]; then
gh issue close "$number" --reason "not planned"
else
gh pr close "$number"
fi
fi
+21 -1
View File
@@ -11,9 +11,14 @@ This file is the entry point; the `docs/` suite is the specification.
> 2026-10-28; v1.1.0 live, confirmed on the listing 2026-11-06; v1.2.0 live,
> confirmed on the listing 2026-11-10; v1.2.1 released on GitHub 2026-11-10,
> ⚠️ not yet submitted).
> Phases 0–9 are complete; the project is in **maintenance**.
> Phases 0–9 are complete; since 2026-11-18 the project is in **maintenance
> mode** — `/MAINTENANCE.md` is the policy (Phase 10 below).
> That changes the rules of the game:
>
> - **New work must fit `/MAINTENANCE.md`**: dependency and security updates,
> major platform upgrades, bug/UI/UX/accessibility/translation fixes, and
> features only when they are on `docs/15`'s roadmap or genuinely needed. A
> feature that is not on the roadmap needs a decision-log row before code.
> - Every change now reaches installed users through a store review. It needs a
> semver bump, a `CHANGELOG.md` entry and an update submission — `13 §1b`.
> - Breaking something is no longer a local cost. The 1.0.0 → 1.0.x **upgrade
@@ -203,6 +208,21 @@ checksum-verified zip). Human-only ⚠️: the `11 §5` pass with the
theme and a screen-reader pass over Alt+↑/↓, the zip upload, and the native
review of the two new strings.
### Phase 10 — maintenance mode; Firefox and Edge → v1.3.0
The owner put the project into maintenance mode and asked for the last
roadmap item, the other two stores. In order: Dependabot #39–#41 and the
hand sync they always need → the `picomatch` advisory recorded (no fix
exists) → a licence gate over the lockfile (`check:licenses`) → the policy
(`/MAINTENANCE.md`, a feature form that asks which kind of change it is, and
`triage.yml`, which closes requests for something new) → Qodana (`qodana-js`,
Ultimate) beside SonarCloud → then Firefox (AMO) and Edge: the docs first,
then the port, then CI, review and 1.3.0.
One thing to carry forward: **`triage.yml` runs on `pull_request_target`,
with a write token, for pull requests from forks.** It checks out the base
branch and only compares event text with constants. Never add a checkout of
the pull request's head, a step that runs its code, or a `${{ }}` of a title
or body inside a `run:` line to that file.
## Working style
- Small commits per module; tests land with (or before) implementation.
+10
View File
@@ -7,6 +7,16 @@ stop reading here — the forms ask for what is needed.
Security problems go through [`SECURITY.md`](SECURITY.md), never a public issue.
**The project is in maintenance mode** ([`MAINTENANCE.md`](MAINTENANCE.md)).
What it takes: bug, UI/UX and accessibility fixes; translation fixes (wording
wrong for a language or region, misleading spelling); dependency and security
updates; major platform upgrades; and features that are already on the
roadmap or genuinely needed. A feature request for something new, or a pull
request titled `feat…` from outside the project, is closed automatically and
labelled `maintenance-mode` — read, not deleted, and reopened if it fits.
Ideas belong in
[Discussions › Ideas](https://github.com/poli0981/bookmarkmagic/discussions/categories/ideas).
If something is hard or impossible to use — with a keyboard, a screen reader, a
contrast theme, zoom — that is a defect, and it has its own form.
[`ACCESSIBILITY.md`](ACCESSIBILITY.md) says what is already known and how a
+86
View File
@@ -0,0 +1,86 @@
# Maintenance
**Status: maintenance mode, since 2026-11-18.**
BookmarkMagic does what it set out to do: import, export and edit bookmarks
between browsers — offline, with two permissions and no network access. From
here the project is **maintained, not extended**. That is not abandonment: it
means keeping the extension correct, safe and current matters more than adding
to it, and every change still reaches people through a store review.
This file is the policy. The reasoning behind it is in the decision log of
[`docs/15_ROADMAP.md`](docs/15_ROADMAP.md).
## What is still done
1. **Dependencies, on a schedule.** Dependabot proposes updates weekly, for npm
and for the GitHub Actions the workflows use, and only for releases that
have been public for at least seven days. Each is merged after CI and the
follow-up the docs ask for ([`docs/01 §6`](docs/01_TECH_STACK.md)).
2. **Security, urgently.** An advisory rated **high or critical** against any
dependency — or a serious security problem in the toolchain itself, Node.js
for example — is fixed as soon as a fixed version exists. While none exists,
[`docs/09 §3.1`](docs/09_SECURITY_PRIVACY.md) records the advisory and why it
cannot reach a user, until the fix lands. To report a vulnerability, follow
[`SECURITY.md`](SECURITY.md).
3. **Major upgrades of the platform.** A new major of the language, runtime or
framework — Node.js 24 → 26, TypeScript 6 → 7, a major of WXT or Svelte — is
adopted on purpose, in its own pull request, with the docs updated first.
4. **Defects.** Bugs, UI/UX defects and accessibility barriers
([`ACCESSIBILITY.md`](ACCESSIBILITY.md)). A bookmark file that will not
import is the most useful report there is
([`CONTRIBUTING.md`](CONTRIBUTING.md)).
5. **Language.** Translation fixes: wording that is wrong for a language, or
for a region's culture or usage, and spelling mistakes that could mislead
someone. The translation form is the way in.
6. **Roadmap features, and necessary ones.** A feature that is already on the
roadmap ([`docs/15`](docs/15_ROADMAP.md)) can still land, and so can a change
that is genuinely needed — to fix a defect, to remove a barrier, or to keep
the extension working in a browser it is published for.
## What is not
**New features outside the roadmap.** Requests for them are closed
automatically, by [`.github/workflows/triage.yml`](.github/workflows/triage.yml):
- An issue opened with the **Suggest a feature** form whose first answer is
"Something new — not on the roadmap" is labelled `maintenance-mode`, gets a
comment that links here, and is closed as *not planned*. The form's other two
answers — on the roadmap, or needed for a fix — keep the issue open, labelled
`needs-triage`, for the maintainer to read.
- A pull request from outside the project whose title starts with `feat`
(Conventional Commits) is labelled and closed the same way. Open a feature
request first.
- The maintainer can label any issue `enhancement` to close it the same way.
Nothing is deleted. Every closed request is read, and one that fits this
policy is reopened and labelled `roadmap`, which the automation leaves alone.
**Ideas** are welcome in
[Discussions › Ideas](https://github.com/poli0981/bookmarkmagic/discussions/categories/ideas),
where they can be talked through without an issue that has to be accepted or
refused.
Out of scope permanently, maintenance mode or not: cloud sync, accounts,
analytics of any kind, and anything that would need a new browser permission —
the never list in [`docs/15`](docs/15_ROADMAP.md).
## Releases
A **patch** ships when there is something to fix: a file that will not import,
a data-integrity defect or a dead end, an accessibility barrier, a batch of
translation fixes, or a dependency advisory. A **minor** carries a roadmap
feature, a new UI language or a change to the permissions
([`docs/12 §4`](docs/12_CI_CD.md)). There is no fixed schedule.
Your browser updates the extension by itself once a new version passes store
review; there is nothing to do.
## Supported versions
The latest version published on each store. See [`SECURITY.md`](SECURITY.md).
## Changing this policy
Through a pull request like any other, recorded in `docs/15`'s decision log
and announced in Discussions.
+16 -4
View File
@@ -1,5 +1,6 @@
# BookmarkMagic
[![Status: maintenance mode](https://img.shields.io/badge/status-maintenance%20mode-yellow.svg)](MAINTENANCE.md)
[![License: GPL-3.0-or-later](https://img.shields.io/badge/license-GPL--3.0--or--later-blue.svg)](LICENSE)
[![CI](https://github.com/poli0981/bookmarkmagic/actions/workflows/ci.yml/badge.svg)](https://github.com/poli0981/bookmarkmagic/actions/workflows/ci.yml)
[![CodeQL](https://github.com/poli0981/bookmarkmagic/actions/workflows/codeql.yml/badge.svg)](https://github.com/poli0981/bookmarkmagic/actions/workflows/codeql.yml)
@@ -14,6 +15,14 @@ no cloud sync, 100% offline.
A Chrome (MV3) extension for importing, exporting and editing bookmarks and
folder trees. English · Tiếng Việt · 日本語 · 简体中文 · Română.
## Project status
**Maintenance mode** since 2026-11-18 — see [`MAINTENANCE.md`](MAINTENANCE.md).
Bug, UI/UX, accessibility and translation fixes, dependency and security
updates, and features already on the roadmap still land; requests for new
features beyond that are closed automatically. Ideas are welcome in
[Discussions › Ideas](https://github.com/poli0981/bookmarkmagic/discussions/categories/ideas).
## Screenshots
| Import | Edit |
@@ -134,7 +143,9 @@ code and docs disagree, the docs win. Start with [`CLAUDE.md`](CLAUDE.md), then
Bug reports and translation fixes are welcome —
[the issue forms](https://github.com/poli0981/bookmarkmagic/issues/new/choose)
ask for what is needed, and none of them requires you to write code.
ask for what is needed, and none of them requires you to write code. The
project is in maintenance mode, so a request for a feature that is not on the
roadmap is closed automatically ([`MAINTENANCE.md`](MAINTENANCE.md)).
If a bookmark file will not import, that is the most useful report there is,
because the sample becomes a permanent test. Sanitize it first:
@@ -167,9 +178,10 @@ a public issue.
| Contributing and code of conduct | code@poli0981.dev |
| Sponsorship · collaboration · press | sponsor@ · collab@ · press@poli0981.dev |
Bugs and feature ideas are best as
[issues](https://github.com/poli0981/bookmarkmagic/issues) — they help the next
person too. The extension itself never shows or uses any of these addresses.
Bugs are best as
[issues](https://github.com/poli0981/bookmarkmagic/issues) and ideas as
[Discussions](https://github.com/poli0981/bookmarkmagic/discussions/categories/ideas)
— they help the next person too. The extension itself never shows or uses any of these addresses.
## Support development
+7 -1
View File
@@ -37,7 +37,13 @@
> here reaches installed users through a store review, so it needs a version
> bump, a CHANGELOG entry and an update submission (`13 §1b`). Sequencing lives
> in `/CLAUDE.md`; what is still open is in §10 below.
> **Doc suite version:** 1.11 (2026-11-10 — v1.2.1 released on GitHub)
>
> **Since 2026-11-18 that is a written policy: maintenance mode**
> (`/MAINTENANCE.md`). Dependency and security updates, major platform
> upgrades, bug/UI/UX/accessibility/translation fixes, and features only when
> they are on `15`'s roadmap or genuinely needed; requests for anything else
> are closed by `triage.yml` (`12 §2.6`).
> **Doc suite version:** 1.12 (2026-11-18 — maintenance mode)
---
+3 -1
View File
@@ -263,7 +263,9 @@ them is tested where it lives:
`sanitize-bookmarks.test.ts` — `09 §6`). New in Phase 10:
`check-licenses.test.ts` (SPDX expressions, the shipped list held stricter
than the toolchain's, a missing or custom licence refused, the repository's
own lockfile passing — `09 §3.2`).
own lockfile passing — `09 §3.2`) and `triage.test.ts` (every branch of the
maintenance-mode decision, the feature form's dropdown wording, and no event
text interpolated into the workflow's shell — `12 §2.6`).
## 5. Manual QA checklist (run before every store submission)
+32
View File
@@ -220,6 +220,34 @@ Added 2026-10-28, replacing SonarCloud's Automatic Analysis so the project gets
Snyk is connected only as a GitHub App (the `security/snyk (poli0981)` PR
check); there is no `SNYK_TOKEN` and no Snyk step in any workflow.
### 2.6 `triage.yml` — maintenance-mode triage
Added 2026-11-18 with `/MAINTENANCE.md`. On `issues: [opened, labeled]` and
`pull_request_target: [opened]` it runs `scripts/triage.mjs`, which reads the
runner's event file and prints a decision, then carries it out with the `gh`
CLI the runner ships — no third-party action ever holds its write token
(`issues: write`, `pull-requests: write`, `contents: read`).
- **The decision is code with tests**, not shell: `decide()` is a pure
function (`tests/unit/scripts/triage.test.ts`) — a feature-form issue
answering "Something new" is labelled `maintenance-mode`, commented and
closed *not planned*; the two in-policy answers get `needs-triage`; an
`enhancement` label added by hand closes the issue the same way; an outside
pull request titled `feat…` is closed. The owner's own issues, members,
collaborators, bots and anything labelled `roadmap` are exempt. The test also
pins the dropdown's wording against `feature_request.yml`, which is the only
thing the decision parses.
- ⚠️ **`pull_request_target` holds a write token for fork pull requests.** The
checkout is the base branch — the event's default — and nothing from the
pull request runs. Titles and bodies reach the script as the event file and
are only compared with constants; the shell reads back an action from a fixed
set, an integer, a label from a fixed list and a comment the script wrote, and
validates the first two before using them.
- **Idempotent.** The feature form fires `opened` and `labeled` for one new
issue. `concurrency` runs them one at a time per number and the second
re-reads the live labels and state before acting.
- The labels must exist (`§5`); `gh … --add-label` fails on a missing one.
## 3. Chrome Web Store publishing automation
WXT ships publishing built-in: **`wxt submit`** (wrapping
@@ -308,6 +336,10 @@ means "unknown", not "not done".
(matching `.npmrc` `min-release-age=7`, `09 §3.1`); WXT is excluded from
the group so every WXT bump arrives alone and gets its built-manifest
diff; majors of the TypeScript pair and `@types/node` are ignored.
- [x] Labels the forms and `triage.yml` apply — `maintenance-mode`,
`needs-triage`, `roadmap` (new with `MAINTENANCE.md`) and `parser`, `i18n`
(named by the parser and translation forms since 2026-08-03, and missing
until 2026-11-18: a form silently drops a label that does not exist).
- [x] Issue templates: `.github/ISSUE_TEMPLATE/` — bug, parser report (requires
a sanitized sample), translation, feature, plus a `config.yml` chooser.
Landed 2026-08-03; `13 §6` had asserted they existed since before launch.
+5 -1
View File
@@ -189,7 +189,11 @@ actually shows and correct the files, not the dashboard.
that is not fixed at once goes into its Known limitations.
- Discord servers (`#support` in the OSS server) — pin an FAQ post.
⚠️ The invite URL is not recorded anywhere in the repo.
- Review flow for feature requests: label → roadmap doc PR → milestone.
- Feature requests, in maintenance mode (`/MAINTENANCE.md`): `triage.yml`
closes a request for something new and labels the two in-policy answers
`needs-triage` (`12 §2.6`). Read every `needs-triage` issue and every closed
one; one that fits goes into `15` by pull request and gets the `roadmap`
label, which the automation leaves alone. Ideas live in Discussions › Ideas.
The three recurring questions are already answered in prose and make the FAQ
seed: favicons cannot be imported; imported bookmarks carry today's date (the
+10
View File
@@ -1,5 +1,10 @@
# 15 — Roadmap
> **Maintenance mode since 2026-11-18.** What the project still takes, and how
> requests outside that are handled, is [`/MAINTENANCE.md`](../MAINTENANCE.md) —
> the policy, not restated here. Every feature that can still land is on this
> page; anything not on it needs a decision-log row first.
## v1.0 — MVP (store launch) — ✔ SHIPPED
Everything in `00_PROJECT_OVERVIEW.md §6`. Definition of done was
@@ -395,3 +400,8 @@ attempted.
| 2026-11-10 | **Alt+↑ / Alt+↓ reorders, and it is a patch.** It reuses `planDrop` and `moveTo`, so a keyboard move and a drag cannot disagree about what is legal, and there is no second write path to test. One place at a time, among the siblings on screen, like a drag. It ships in a patch because it closes a barrier to something the product already did rather than adding a capability; `12 §4` now says so. Rejected: "Move up / Move down" row buttons (two more on a row that already hides up to five), and a position field in "Move to…" (a new dialog flow for the same result) — though a click-only route is still owed (WCAG 2.5.7, backlog) | 05 §10, 12 §4 |
| 2026-11-10 | **Focus after a route change goes to `<main>`, not to the tree.** "Open in Edit" removes the button that was clicked. Focusing the tree when `#edit` mounts would also have fired on every first load, highlighting a row nobody chose and changing every screenshot; a route change with focus lost is the narrower condition and covers every tab | 06 §5 |
| 2026-11-10 | **Dependabot's bumps are not the whole bump.** #31 and #36 moved Biome twice and left `biome.json`'s `$schema` behind both times, and left `vitest`'s declared range a minor behind the coverage plugin's, which must match it (the lockfile had both at 5.1.0); `01 §2` drifted with them. The sync is a human step after each Dependabot merge, and WXT still gets the built-manifest diff — 0.21.5 produced a manifest byte-identical to the 1.2.0 release asset | 01 §2, §6 |
| 2026-11-18 | **Maintenance mode, as a written policy.** The project had been "in maintenance" since launch in the loose sense; the owner made it explicit: dependency updates on a schedule, high/critical advisories fixed as soon as a fix exists, major platform upgrades, bug/UI/UX/accessibility/translation fixes, and features only when on this roadmap or genuinely needed. **`/MAINTENANCE.md` is the policy and this file does not restate it** — the lesson of `12 §2`: a copy in two places drifts. The roadmap below stays valid; it is now the whole list of features that can still land | `MAINTENANCE.md` |
| 2026-11-18 | **Out-of-policy requests are closed by a workflow, not by hand.** The feature form asks one required question (on the roadmap / needed for a fix / something new); `scripts/triage.mjs` decides, as a pure and unit-tested function, and `triage.yml` acts with `gh` only — labelled `maintenance-mode` and closed *not planned*, or labelled `needs-triage`. `pull_request_target` checks out the base branch only and never interpolates a title or body into a shell line. Outside `feat…` pull requests are closed the same way; the owner, members, collaborators, bots and anything labelled `roadmap` are exempt. Rejected: removing the feature form (requests would arrive through the bug form, where nothing can detect them) and closing every request unread (the two in-policy answers deserve a human) | `12 §2.6`, `MAINTENANCE.md` |
| 2026-11-18 | **A high advisory with no fix is recorded, not worked around.** `npm audit` reports 14 high findings, all `picomatch` GHSA-fc5q-39xc-vjpf, every version affected, nothing to upgrade to. It is the toolchain's glob engine, matching patterns this repository writes, and never ships. The `deepmerge` row left: GitHub withdrew that advisory on 2026-11-16 | `09 §3.1` |
| 2026-11-18 | **A licence gate over the whole lockfile** (`scripts/check-licenses.mjs`): shipped packages must be permissive and GPL-3.0-compatible, tooling may also be MPL-2.0 and a few other non-copyleft licences; anything else fails until a person adds it on purpose. One shared `CREDITED_PACKAGES` list (`scripts/credited-packages.mjs`) now feeds the build gate, the notices test and this gate. `dependency-review-action` was considered and not used: PR-only, ClearlyDefined rather than the lockfile, runtime scope by default, not runnable locally. `legal/THIRD_PARTY_NOTICES.md` had called the tooling all MIT/Apache-2.0/ISC; corrected, **not a `LEGAL_VERSION` bump** — it describes tooling that never ships | `09 §3.2`, `14 §3.1` |
| 2026-11-18 | **Dependabot #39–#41 merged and synced by hand**, as the 2026-11-10 row requires: `biome.json`'s `$schema` to 2.6.6, `01 §2`, the scan action's pin in `12 §2.5`, and for the jsdom 31 major a new column in `11 §6` (2 484 ms median) beside the jsdom 29 figure | `01 §2`, `11 §6` |
+22
View File
@@ -0,0 +1,22 @@
/**
* Types for scripts/triage.mjs, so its tests can call it directly.
* The script itself is plain JavaScript checked with `// @ts-check`.
*/
export interface Decision {
action: 'close' | 'label' | 'none';
reason: string;
kind?: 'issue' | 'pr';
number?: number;
label?: string;
comment?: string;
}
export const POLICY_URL: string;
export const IDEAS_URL: string;
export const KIND_QUESTION: string;
export const KIND: Readonly<{ roadmap: string; needed: string; fresh: string }>;
export const LABEL: Readonly<{ feature: string; closed: string; triage: string; exempt: string }>;
export const ISSUE_COMMENT: string;
export const PR_COMMENT: string;
export function kindOf(body: unknown): string | undefined;
export function decide(eventName: string | undefined, payload: unknown): Decision;
+243
View File
@@ -0,0 +1,243 @@
// @ts-check
/**
* Maintenance-mode triage — MAINTENANCE.md, docs/12 §2.6.
*
* Decides what `.github/workflows/triage.yml` does with a new issue or pull
* request; the workflow then carries the decision out with `gh`. The decision
* is a pure function of the event payload, so every branch is unit-tested
* (tests/unit/scripts/triage.test.ts) instead of living in shell `if`s.
*
* - An issue labelled `enhancement` (the feature form applies it) whose
* "kind of change" answer is "something new" — or that has no answer at
* all, i.e. the maintainer labelled it by hand — is labelled
* `maintenance-mode`, gets a comment and is closed as not planned.
* - The other two answers (on the roadmap; needed for a fix) keep it open,
* labelled `needs-triage`, for the maintainer to read.
* - A pull request from outside the project titled `feat…` (Conventional
* Commits) is labelled and closed the same way.
* - Exempt: the owner's own issues, project members and collaborators, bots
* (Dependabot), anything labelled `roadmap`, anything already triaged.
*
* Nothing here runs code from the event: titles and bodies are only compared
* with constants, and the workflow passes the payload by file, never through
* shell interpolation.
*
* Usage (in CI): node scripts/triage.mjs — reads GITHUB_EVENT_NAME and
* GITHUB_EVENT_PATH from the environment the runner sets, prints a JSON
* decision on stdout. It takes no arguments.
*/
import { readFileSync } from 'node:fs';
import { resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
const REPO = 'https://github.com/poli0981/bookmarkmagic';
export const POLICY_URL = `${REPO}/blob/main/MAINTENANCE.md`;
export const IDEAS_URL = `${REPO}/discussions/categories/ideas`;
/** The feature form's dropdown, word for word (`.github/ISSUE_TEMPLATE/feature_request.yml`). */
export const KIND_QUESTION = 'Which kind of change is this?';
export const KIND = Object.freeze({
roadmap: 'Something already on the roadmap (docs/15)',
needed: 'Needed to fix a bug, a UI/UX defect or an accessibility barrier',
fresh: 'Something new — not on the roadmap',
});
export const LABEL = Object.freeze({
feature: 'enhancement',
closed: 'maintenance-mode',
triage: 'needs-triage',
exempt: 'roadmap',
});
/** Associations that mean "part of the project", per GitHub's author_association. */
const INSIDERS = new Set(['OWNER', 'MEMBER', 'COLLABORATOR']);
const BOT_NOTE = '<sub>Posted automatically by the triage workflow.</sub>';
export const ISSUE_COMMENT = [
'Thank you for the suggestion.',
'',
`BookmarkMagic is in **maintenance mode** ([MAINTENANCE.md](${POLICY_URL})): it takes bug, UI/UX and accessibility fixes, translation fixes, dependency and security updates, and features that are already on the roadmap. This request is for something new, so it has been labelled \`${LABEL.closed}\` and closed.`,
'',
'It has not been deleted, and it will be read. If it is on the roadmap, or it is needed to fix a defect or remove a barrier, it will be reopened. Ideas are welcome in [Discussions › Ideas](' +
`${IDEAS_URL}).`,
'',
BOT_NOTE,
].join('\n');
export const PR_COMMENT = [
'Thank you for the pull request.',
'',
`BookmarkMagic is in **maintenance mode** ([MAINTENANCE.md](${POLICY_URL})). A pull request that adds a feature — its title starts with \`feat\` — is closed automatically unless the feature is already on the roadmap, so this one has been labelled \`${LABEL.closed}\` and closed.`,
'',
'Please open a feature request first; if it is accepted (label `roadmap`), this pull request will be reopened. If it is a fix rather than a feature, say so in a comment — a `fix:` title is what the maintainer expects.',
'',
BOT_NOTE,
].join('\n');
/**
* @typedef {{
* action: 'close' | 'label' | 'none',
* reason: string,
* kind?: 'issue' | 'pr',
* number?: number,
* label?: string,
* comment?: string,
* }} Decision
*/
/**
* The answer to the feature form's dropdown, or undefined when the body has
* none (an issue from another form, labelled by hand). Issue forms render each
* field as `### <label>` followed by the answer.
* @param {unknown} body
* @returns {string | undefined}
*/
export function kindOf(body) {
if (typeof body !== 'string') return undefined;
const lines = body.split(/\r?\n/);
const at = lines.findIndex((line) => line.trim() === `### ${KIND_QUESTION}`);
if (at === -1) return undefined;
for (const line of lines.slice(at + 1)) {
const text = line.trim();
if (text.startsWith('### ')) return undefined;
if (text !== '') return text;
}
return undefined;
}
/** @param {unknown} value @returns {Record<string, unknown>} */
function record(value) {
return typeof value === 'object' && value !== null
? /** @type {Record<string, unknown>} */ (value)
: {};
}
/** @param {unknown} labels @returns {string[]} */
function labelNames(labels) {
if (!Array.isArray(labels)) return [];
return labels.map((label) => record(label).name).filter((name) => typeof name === 'string');
}
/** @param {unknown} value @returns {number | undefined} */
function positiveInt(value) {
return typeof value === 'number' && Number.isInteger(value) && value > 0 ? value : undefined;
}
/**
* @param {Record<string, unknown>} payload
* @returns {Decision}
*/
function decideIssue(payload) {
const issue = record(payload.issue);
const number = positiveInt(issue.number);
if (number === undefined) return { action: 'none', reason: 'no issue number' };
if (payload.action !== 'opened' && payload.action !== 'labeled') {
return { action: 'none', reason: `issue action ${String(payload.action)}` };
}
if (payload.action === 'labeled' && record(payload.label).name !== LABEL.feature) {
return { action: 'none', reason: 'a different label was added' };
}
if (issue.state !== 'open') return { action: 'none', reason: 'issue is not open' };
const labels = labelNames(issue.labels);
if (!labels.includes(LABEL.feature)) return { action: 'none', reason: 'not a feature request' };
for (const done of [LABEL.exempt, LABEL.closed, LABEL.triage]) {
if (labels.includes(done)) return { action: 'none', reason: `already labelled ${done}` };
}
if (issue.author_association === 'OWNER')
return { action: 'none', reason: "the owner's own issue" };
const kind = kindOf(issue.body);
if (kind === KIND.roadmap || kind === KIND.needed) {
return {
action: 'label',
reason: 'in policy — for the maintainer',
kind: 'issue',
number,
label: LABEL.triage,
};
}
return {
action: 'close',
reason:
kind === KIND.fresh ? 'a new feature outside the roadmap' : 'labelled enhancement by hand',
kind: 'issue',
number,
label: LABEL.closed,
comment: ISSUE_COMMENT,
};
}
/** Conventional Commits `feat`, with an optional scope and breaking-change mark. */
const FEAT_TITLE = /^feat(\([^)]*\))?!?:/i;
/**
* @param {Record<string, unknown>} payload
* @returns {Decision}
*/
function decidePullRequest(payload) {
const pr = record(payload.pull_request);
const number = positiveInt(pr.number);
if (number === undefined) return { action: 'none', reason: 'no pull request number' };
if (payload.action !== 'opened')
return { action: 'none', reason: `pull request action ${String(payload.action)}` };
if (pr.state !== 'open') return { action: 'none', reason: 'pull request is not open' };
if (record(pr.user).type === 'Bot') return { action: 'none', reason: 'opened by a bot' };
if (INSIDERS.has(String(pr.author_association)))
return { action: 'none', reason: 'opened from inside the project' };
if (labelNames(pr.labels).includes(LABEL.exempt))
return { action: 'none', reason: 'labelled roadmap' };
if (typeof pr.title !== 'string' || !FEAT_TITLE.test(pr.title.trim())) {
return { action: 'none', reason: 'not a feature pull request' };
}
return {
action: 'close',
reason: 'a feature pull request from outside the project',
kind: 'pr',
number,
label: LABEL.closed,
comment: PR_COMMENT,
};
}
/**
* What to do with one event.
* @param {string | undefined} eventName — GITHUB_EVENT_NAME
* @param {unknown} payload — the parsed GITHUB_EVENT_PATH file
* @returns {Decision}
*/
export function decide(eventName, payload) {
const event = record(payload);
if (eventName === 'issues') return decideIssue(event);
if (eventName === 'pull_request_target') return decidePullRequest(event);
return { action: 'none', reason: `event ${String(eventName)} is not triaged` };
}
/** @returns {number} exit code */
function main() {
const eventPath = process.env.GITHUB_EVENT_PATH;
if (eventPath === undefined || eventPath === '') {
console.error('triage: GITHUB_EVENT_PATH is not set — this runs inside GitHub Actions only');
return 1;
}
/** @type {unknown} */
let payload;
try {
payload = JSON.parse(readFileSync(eventPath, 'utf8'));
} catch (cause) {
console.error(`triage: cannot read the event payload (${String(cause)})`);
return 1;
}
process.stdout.write(`${JSON.stringify(decide(process.env.GITHUB_EVENT_NAME, payload))}\n`);
return 0;
}
// Run only as the entry point (same guard as check-manifest.mjs).
const isEntry =
import.meta.url.startsWith('file:') &&
process.argv[1] !== undefined &&
resolve(process.argv[1]) === fileURLToPath(import.meta.url);
if (isEntry) {
// exitCode, not exit(): exit() can cut off piped output before CI reads it.
process.exitCode = main();
}
+217
View File
@@ -0,0 +1,217 @@
import { readFileSync } from 'node:fs';
import { join } from 'node:path';
import { describe, expect, it } from 'vitest';
import {
decide,
IDEAS_URL,
ISSUE_COMMENT,
KIND,
KIND_QUESTION,
kindOf,
LABEL,
POLICY_URL,
PR_COMMENT,
} from '../../../scripts/triage.mjs';
/**
* scripts/triage.mjs — what the maintenance-mode triage workflow does with an
* issue or a pull request (MAINTENANCE.md, docs/12 §2.6).
*/
const read = (path: string): string => readFileSync(join(process.cwd(), path), 'utf8');
/** An issue body as GitHub renders the feature form. */
function formBody(kind: string): string {
return [
`### ${KIND_QUESTION}`,
'',
kind,
'',
'### What are you trying to do?',
'',
'Something.',
].join('\n');
}
function issueEvent(
overrides: {
action?: string;
label?: string;
labels?: string[];
body?: unknown;
association?: string;
state?: string;
} = {},
): unknown {
return {
action: overrides.action ?? 'opened',
...(overrides.label !== undefined && { label: { name: overrides.label } }),
issue: {
number: 7,
state: overrides.state ?? 'open',
author_association: overrides.association ?? 'NONE',
labels: (overrides.labels ?? [LABEL.feature]).map((name) => ({ name })),
body: overrides.body ?? formBody(KIND.fresh),
},
};
}
function prEvent(
overrides: {
action?: string;
title?: string;
association?: string;
userType?: string;
labels?: string[];
} = {},
): unknown {
return {
action: overrides.action ?? 'opened',
pull_request: {
number: 12,
state: 'open',
title: overrides.title ?? 'feat(export): add a PDF format',
author_association: overrides.association ?? 'FIRST_TIME_CONTRIBUTOR',
user: { type: overrides.userType ?? 'User' },
labels: (overrides.labels ?? []).map((name) => ({ name })),
},
};
}
describe('kindOf — the feature form dropdown', () => {
it.each(Object.values(KIND))('reads %j', (kind) => {
expect(kindOf(formBody(kind))).toBe(kind);
});
it('reads a CRLF body', () => {
expect(kindOf(formBody(KIND.needed).replaceAll('\n', '\r\n'))).toBe(KIND.needed);
});
it('is undefined without the question, with an empty answer, or for a non-string', () => {
expect(kindOf('### What happened?\n\nIt broke.')).toBeUndefined();
expect(kindOf(`### ${KIND_QUESTION}\n\n### Next\n\nx`)).toBeUndefined();
expect(kindOf(null)).toBeUndefined();
});
});
describe('decide — issues', () => {
it('closes a request for something new, with the policy comment', () => {
expect(decide('issues', issueEvent())).toEqual({
action: 'close',
reason: 'a new feature outside the roadmap',
kind: 'issue',
number: 7,
label: LABEL.closed,
comment: ISSUE_COMMENT,
});
});
it.each([KIND.roadmap, KIND.needed])('keeps %j open for the maintainer', (kind) => {
expect(decide('issues', issueEvent({ body: formBody(kind) }))).toMatchObject({
action: 'label',
label: LABEL.triage,
number: 7,
});
});
it('closes an issue the maintainer labelled enhancement by hand', () => {
const event = issueEvent({
action: 'labeled',
label: LABEL.feature,
body: '### What happened?\n\nx',
});
expect(decide('issues', event)).toMatchObject({
action: 'close',
reason: 'labelled enhancement by hand',
});
});
it.each([
['another label was added', issueEvent({ action: 'labeled', label: 'bug' })],
['not a feature request', issueEvent({ labels: ['bug'] })],
['the roadmap exemption', issueEvent({ labels: [LABEL.feature, LABEL.exempt] })],
['already closed by the bot', issueEvent({ labels: [LABEL.feature, LABEL.closed] })],
['already sent to triage', issueEvent({ labels: [LABEL.feature, LABEL.triage] })],
["the owner's own issue", issueEvent({ association: 'OWNER' })],
['a closed issue', issueEvent({ state: 'closed' })],
['an edit', issueEvent({ action: 'edited' })],
])('does nothing for %s', (_case, event) => {
expect(decide('issues', event).action).toBe('none');
});
it('does nothing without a usable issue number', () => {
expect(decide('issues', { action: 'opened', issue: { number: '7; rm -rf /' } }).action).toBe(
'none',
);
expect(decide('issues', null).action).toBe('none');
});
});
describe('decide — pull requests', () => {
it.each([
'feat: add a PDF export',
'feat(export): add a PDF export',
'feat!: drop CSV',
'FEAT(edit)!: new panel',
])('closes %j from outside the project', (title) => {
expect(decide('pull_request_target', prEvent({ title }))).toEqual({
action: 'close',
reason: 'a feature pull request from outside the project',
kind: 'pr',
number: 12,
label: LABEL.closed,
comment: PR_COMMENT,
});
});
it.each([
'fix(import): read a BOM',
'feature: something',
'docs: feat is not a prefix here',
'chore(deps): bump vite',
])('leaves %j alone', (title) => {
expect(decide('pull_request_target', prEvent({ title })).action).toBe('none');
});
it.each([
['the owner', prEvent({ association: 'OWNER' })],
['a collaborator', prEvent({ association: 'COLLABORATOR' })],
['a member', prEvent({ association: 'MEMBER' })],
['Dependabot', prEvent({ userType: 'Bot' })],
['a roadmap pull request', prEvent({ labels: [LABEL.exempt] })],
['a reopened pull request', prEvent({ action: 'reopened' })],
])('exempts %s', (_case, event) => {
expect(decide('pull_request_target', event).action).toBe('none');
});
});
describe('decide — other events', () => {
it('ignores events it does not triage', () => {
expect(decide('push', {}).action).toBe('none');
expect(decide(undefined, {}).action).toBe('none');
});
});
describe('the pieces the script shares with other files', () => {
it('matches the feature form word for word', () => {
const form = read('.github/ISSUE_TEMPLATE/feature_request.yml');
expect(form).toContain(`label: ${KIND_QUESTION}`);
for (const kind of Object.values(KIND)) expect(form).toContain(`- ${kind}`);
expect(form).toContain(`labels: [${LABEL.feature}]`);
});
it('links the policy and the ideas board, which exist', () => {
for (const comment of [ISSUE_COMMENT, PR_COMMENT]) expect(comment).toContain(POLICY_URL);
expect(ISSUE_COMMENT).toContain(IDEAS_URL);
expect(read('MAINTENANCE.md')).toContain(`\`${LABEL.closed}\``);
});
it('is what the workflow runs, with the labels the workflow re-checks', () => {
const workflow = read('.github/workflows/triage.yml');
expect(workflow).toContain('node scripts/triage.mjs');
for (const label of [LABEL.closed, LABEL.triage, LABEL.exempt])
expect(workflow).toContain(` ${label} `);
// Nothing from the event payload is interpolated into a shell line.
expect(workflow).not.toMatch(/\$\{\{\s*github\.event\.(issue|pull_request)\.(title|body)/);
});
});