From ec7a3b5b4dcfee843bc5f4c6068dd5253697147f Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 24 Sep 2026 19:49:30 +0000 Subject: [PATCH 1/7] docs: move design records into docs/design with an index Twenty-six audits, designs, decision records and plans sat at the repository root, so GitHub listed them ahead of the README. They move, unchanged, to docs/design/ (git mv keeps their history), and docs/design/README.md indexes them by area: templates, country flags, panel compatibility, installer, documentation platform. The index says plainly that these are historical records: their own "Status" lines describe the project when they were written, and several marked "proposal only" have since been implemented. Nothing reads these files. The six code and test files that mention them do so in comments, by bare file name, so the names are kept as they were and no code changes. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011QC3E9ChkFK7sDFBTfwNJ3 --- .../ADR-0001-DOCUMENTATION-FRAMEWORK.md | 0 .../design/ARCHITECTURE-MULTIPANEL-PLAN.md | 0 .../design/CUSTOM-TEMPLATE-GUIDELINES.md | 0 .../design/CUSTOM-TEMPLATES-PROPOSAL.md | 0 .../DOCUMENTATION-DESIGN-SYSTEM-PROPOSAL.md | 0 .../DOCUMENTATION-IMPLEMENTATION-PLAN.md | 0 .../design/DOCUMENTATION-PLATFORM-PROPOSAL.md | 0 .../design/FLAG-RENDERER-AUDIT.md | 0 .../design/FLAG-RENDERER-PHASE-0.5.md | 0 .../design/INSTALLER-ACTIVATION-AUDIT.md | 0 .../design/INSTALLER-BACKUP-DESIGN.md | 0 .../design/INSTALLER-BACKUP-REVIEW.md | 0 .../design/INSTALLER-MULTIPANEL-AUDIT.md | 0 .../design/INSTALLER-MULTIPANEL-DESIGN.md | 0 .../design/INSTALLER-PANEL-3XUI.md | 0 .../design/INSTALLER-PANEL-INTERFACE.md | 0 .../design/INSTALLER-TRANSACTION-DESIGN.md | 0 .../design/LIVE-POLLING-AUDIT.md | 0 .../design/MULTIPANEL-CHECKPOINT-PLAN.md | 0 .../design/PANEL-COMPATIBILITY-AUDIT.md | 0 .../design/PASARGUARD-ADAPTER-AUDIT.md | 0 .../design/PASARGUARD-RUNTIME-FIXTURE-PLAN.md | 0 .../design/PHASE-1-BOOTSTRAP-PLAN.md | 0 .../design/PHASE-1-FOUNDATION-PLAN.md | 0 docs/design/README.md | 72 +++++++++++++++++++ .../design/REBECCA-ADAPTER-AUDIT.md | 0 .../design/REBECCA-ADAPTER-DECISIONS.md | 0 27 files changed, 72 insertions(+) rename ADR-0001-DOCUMENTATION-FRAMEWORK.md => docs/design/ADR-0001-DOCUMENTATION-FRAMEWORK.md (100%) rename ARCHITECTURE-MULTIPANEL-PLAN.md => docs/design/ARCHITECTURE-MULTIPANEL-PLAN.md (100%) rename CUSTOM-TEMPLATE-GUIDELINES.md => docs/design/CUSTOM-TEMPLATE-GUIDELINES.md (100%) rename CUSTOM-TEMPLATES-PROPOSAL.md => docs/design/CUSTOM-TEMPLATES-PROPOSAL.md (100%) rename DOCUMENTATION-DESIGN-SYSTEM-PROPOSAL.md => docs/design/DOCUMENTATION-DESIGN-SYSTEM-PROPOSAL.md (100%) rename DOCUMENTATION-IMPLEMENTATION-PLAN.md => docs/design/DOCUMENTATION-IMPLEMENTATION-PLAN.md (100%) rename DOCUMENTATION-PLATFORM-PROPOSAL.md => docs/design/DOCUMENTATION-PLATFORM-PROPOSAL.md (100%) rename FLAG-RENDERER-AUDIT.md => docs/design/FLAG-RENDERER-AUDIT.md (100%) rename FLAG-RENDERER-PHASE-0.5.md => docs/design/FLAG-RENDERER-PHASE-0.5.md (100%) rename INSTALLER-ACTIVATION-AUDIT.md => docs/design/INSTALLER-ACTIVATION-AUDIT.md (100%) rename INSTALLER-BACKUP-DESIGN.md => docs/design/INSTALLER-BACKUP-DESIGN.md (100%) rename INSTALLER-BACKUP-REVIEW.md => docs/design/INSTALLER-BACKUP-REVIEW.md (100%) rename INSTALLER-MULTIPANEL-AUDIT.md => docs/design/INSTALLER-MULTIPANEL-AUDIT.md (100%) rename INSTALLER-MULTIPANEL-DESIGN.md => docs/design/INSTALLER-MULTIPANEL-DESIGN.md (100%) rename INSTALLER-PANEL-3XUI.md => docs/design/INSTALLER-PANEL-3XUI.md (100%) rename INSTALLER-PANEL-INTERFACE.md => docs/design/INSTALLER-PANEL-INTERFACE.md (100%) rename INSTALLER-TRANSACTION-DESIGN.md => docs/design/INSTALLER-TRANSACTION-DESIGN.md (100%) rename LIVE-POLLING-AUDIT.md => docs/design/LIVE-POLLING-AUDIT.md (100%) rename MULTIPANEL-CHECKPOINT-PLAN.md => docs/design/MULTIPANEL-CHECKPOINT-PLAN.md (100%) rename PANEL-COMPATIBILITY-AUDIT.md => docs/design/PANEL-COMPATIBILITY-AUDIT.md (100%) rename PASARGUARD-ADAPTER-AUDIT.md => docs/design/PASARGUARD-ADAPTER-AUDIT.md (100%) rename PASARGUARD-RUNTIME-FIXTURE-PLAN.md => docs/design/PASARGUARD-RUNTIME-FIXTURE-PLAN.md (100%) rename PHASE-1-BOOTSTRAP-PLAN.md => docs/design/PHASE-1-BOOTSTRAP-PLAN.md (100%) rename PHASE-1-FOUNDATION-PLAN.md => docs/design/PHASE-1-FOUNDATION-PLAN.md (100%) create mode 100644 docs/design/README.md rename REBECCA-ADAPTER-AUDIT.md => docs/design/REBECCA-ADAPTER-AUDIT.md (100%) rename REBECCA-ADAPTER-DECISIONS.md => docs/design/REBECCA-ADAPTER-DECISIONS.md (100%) diff --git a/ADR-0001-DOCUMENTATION-FRAMEWORK.md b/docs/design/ADR-0001-DOCUMENTATION-FRAMEWORK.md similarity index 100% rename from ADR-0001-DOCUMENTATION-FRAMEWORK.md rename to docs/design/ADR-0001-DOCUMENTATION-FRAMEWORK.md diff --git a/ARCHITECTURE-MULTIPANEL-PLAN.md b/docs/design/ARCHITECTURE-MULTIPANEL-PLAN.md similarity index 100% rename from ARCHITECTURE-MULTIPANEL-PLAN.md rename to docs/design/ARCHITECTURE-MULTIPANEL-PLAN.md diff --git a/CUSTOM-TEMPLATE-GUIDELINES.md b/docs/design/CUSTOM-TEMPLATE-GUIDELINES.md similarity index 100% rename from CUSTOM-TEMPLATE-GUIDELINES.md rename to docs/design/CUSTOM-TEMPLATE-GUIDELINES.md diff --git a/CUSTOM-TEMPLATES-PROPOSAL.md b/docs/design/CUSTOM-TEMPLATES-PROPOSAL.md similarity index 100% rename from CUSTOM-TEMPLATES-PROPOSAL.md rename to docs/design/CUSTOM-TEMPLATES-PROPOSAL.md diff --git a/DOCUMENTATION-DESIGN-SYSTEM-PROPOSAL.md b/docs/design/DOCUMENTATION-DESIGN-SYSTEM-PROPOSAL.md similarity index 100% rename from DOCUMENTATION-DESIGN-SYSTEM-PROPOSAL.md rename to docs/design/DOCUMENTATION-DESIGN-SYSTEM-PROPOSAL.md diff --git a/DOCUMENTATION-IMPLEMENTATION-PLAN.md b/docs/design/DOCUMENTATION-IMPLEMENTATION-PLAN.md similarity index 100% rename from DOCUMENTATION-IMPLEMENTATION-PLAN.md rename to docs/design/DOCUMENTATION-IMPLEMENTATION-PLAN.md diff --git a/DOCUMENTATION-PLATFORM-PROPOSAL.md b/docs/design/DOCUMENTATION-PLATFORM-PROPOSAL.md similarity index 100% rename from DOCUMENTATION-PLATFORM-PROPOSAL.md rename to docs/design/DOCUMENTATION-PLATFORM-PROPOSAL.md diff --git a/FLAG-RENDERER-AUDIT.md b/docs/design/FLAG-RENDERER-AUDIT.md similarity index 100% rename from FLAG-RENDERER-AUDIT.md rename to docs/design/FLAG-RENDERER-AUDIT.md diff --git a/FLAG-RENDERER-PHASE-0.5.md b/docs/design/FLAG-RENDERER-PHASE-0.5.md similarity index 100% rename from FLAG-RENDERER-PHASE-0.5.md rename to docs/design/FLAG-RENDERER-PHASE-0.5.md diff --git a/INSTALLER-ACTIVATION-AUDIT.md b/docs/design/INSTALLER-ACTIVATION-AUDIT.md similarity index 100% rename from INSTALLER-ACTIVATION-AUDIT.md rename to docs/design/INSTALLER-ACTIVATION-AUDIT.md diff --git a/INSTALLER-BACKUP-DESIGN.md b/docs/design/INSTALLER-BACKUP-DESIGN.md similarity index 100% rename from INSTALLER-BACKUP-DESIGN.md rename to docs/design/INSTALLER-BACKUP-DESIGN.md diff --git a/INSTALLER-BACKUP-REVIEW.md b/docs/design/INSTALLER-BACKUP-REVIEW.md similarity index 100% rename from INSTALLER-BACKUP-REVIEW.md rename to docs/design/INSTALLER-BACKUP-REVIEW.md diff --git a/INSTALLER-MULTIPANEL-AUDIT.md b/docs/design/INSTALLER-MULTIPANEL-AUDIT.md similarity index 100% rename from INSTALLER-MULTIPANEL-AUDIT.md rename to docs/design/INSTALLER-MULTIPANEL-AUDIT.md diff --git a/INSTALLER-MULTIPANEL-DESIGN.md b/docs/design/INSTALLER-MULTIPANEL-DESIGN.md similarity index 100% rename from INSTALLER-MULTIPANEL-DESIGN.md rename to docs/design/INSTALLER-MULTIPANEL-DESIGN.md diff --git a/INSTALLER-PANEL-3XUI.md b/docs/design/INSTALLER-PANEL-3XUI.md similarity index 100% rename from INSTALLER-PANEL-3XUI.md rename to docs/design/INSTALLER-PANEL-3XUI.md diff --git a/INSTALLER-PANEL-INTERFACE.md b/docs/design/INSTALLER-PANEL-INTERFACE.md similarity index 100% rename from INSTALLER-PANEL-INTERFACE.md rename to docs/design/INSTALLER-PANEL-INTERFACE.md diff --git a/INSTALLER-TRANSACTION-DESIGN.md b/docs/design/INSTALLER-TRANSACTION-DESIGN.md similarity index 100% rename from INSTALLER-TRANSACTION-DESIGN.md rename to docs/design/INSTALLER-TRANSACTION-DESIGN.md diff --git a/LIVE-POLLING-AUDIT.md b/docs/design/LIVE-POLLING-AUDIT.md similarity index 100% rename from LIVE-POLLING-AUDIT.md rename to docs/design/LIVE-POLLING-AUDIT.md diff --git a/MULTIPANEL-CHECKPOINT-PLAN.md b/docs/design/MULTIPANEL-CHECKPOINT-PLAN.md similarity index 100% rename from MULTIPANEL-CHECKPOINT-PLAN.md rename to docs/design/MULTIPANEL-CHECKPOINT-PLAN.md diff --git a/PANEL-COMPATIBILITY-AUDIT.md b/docs/design/PANEL-COMPATIBILITY-AUDIT.md similarity index 100% rename from PANEL-COMPATIBILITY-AUDIT.md rename to docs/design/PANEL-COMPATIBILITY-AUDIT.md diff --git a/PASARGUARD-ADAPTER-AUDIT.md b/docs/design/PASARGUARD-ADAPTER-AUDIT.md similarity index 100% rename from PASARGUARD-ADAPTER-AUDIT.md rename to docs/design/PASARGUARD-ADAPTER-AUDIT.md diff --git a/PASARGUARD-RUNTIME-FIXTURE-PLAN.md b/docs/design/PASARGUARD-RUNTIME-FIXTURE-PLAN.md similarity index 100% rename from PASARGUARD-RUNTIME-FIXTURE-PLAN.md rename to docs/design/PASARGUARD-RUNTIME-FIXTURE-PLAN.md diff --git a/PHASE-1-BOOTSTRAP-PLAN.md b/docs/design/PHASE-1-BOOTSTRAP-PLAN.md similarity index 100% rename from PHASE-1-BOOTSTRAP-PLAN.md rename to docs/design/PHASE-1-BOOTSTRAP-PLAN.md diff --git a/PHASE-1-FOUNDATION-PLAN.md b/docs/design/PHASE-1-FOUNDATION-PLAN.md similarity index 100% rename from PHASE-1-FOUNDATION-PLAN.md rename to docs/design/PHASE-1-FOUNDATION-PLAN.md diff --git a/docs/design/README.md b/docs/design/README.md new file mode 100644 index 0000000..c4d4e54 --- /dev/null +++ b/docs/design/README.md @@ -0,0 +1,72 @@ +# Design records + +The audits, designs, decision records and plans behind Row-Template's larger +changes. They are kept for maintainers and contributors who want to know **why** +the code is shaped the way it is. + +> **These are historical records.** Each one describes the state of the project +> when it was written, including its own "Status" line. A document marked +> "proposal only" or "nothing implemented" may since have been implemented, in +> full or in part. For how the product behaves today, read the code, the +> [README](../../README.md) and the [documentation site](../README.md). + +Code and tests cite these documents by file name (for example +`REBECCA-ADAPTER-DECISIONS.md §2`), so the names are stable. + +## Templates and designs + +| Document | What it is | +| --- | --- | +| [CUSTOM-TEMPLATE-GUIDELINES.md](CUSTOM-TEMPLATE-GUIDELINES.md) | The binding contract every template added to the repository must meet. | +| [CUSTOM-TEMPLATES-PROPOSAL.md](CUSTOM-TEMPLATES-PROPOSAL.md) | Architecture proposal for adding third-party and custom templates. | + +## Country flags + +| Document | What it is | +| --- | --- | +| [FLAG-RENDERER-AUDIT.md](FLAG-RENDERER-AUDIT.md) | Audit and cost study of the country flag system. | +| [FLAG-RENDERER-PHASE-0.5.md](FLAG-RENDERER-PHASE-0.5.md) | Addendum to the audit: the Phase 0.5 cost study. | + +## Panel compatibility + +How the subscription page is made to render on panels other than 3X-UI. 3X-UI +is the only supported panel; PasarGuard and Rebecca are research targets. + +| Document | What it is | +| --- | --- | +| [PANEL-COMPATIBILITY-AUDIT.md](PANEL-COMPATIBILITY-AUDIT.md) | Source audit of PasarGuard and Rebecca against 3X-UI. Start here. | +| [ARCHITECTURE-MULTIPANEL-PLAN.md](ARCHITECTURE-MULTIPANEL-PLAN.md) | The multi-panel architecture plan built on that audit. | +| [PHASE-1-FOUNDATION-PLAN.md](PHASE-1-FOUNDATION-PLAN.md) | Implementation plan for the multi-panel foundation: canonical shell, adapter interface, panel registry, panel build target. | +| [PASARGUARD-ADAPTER-AUDIT.md](PASARGUARD-ADAPTER-AUDIT.md) | Mapping PasarGuard to the page's data contract, from source. | +| [PASARGUARD-RUNTIME-FIXTURE-PLAN.md](PASARGUARD-RUNTIME-FIXTURE-PLAN.md) | How to validate that mapping against an observed PasarGuard response. | +| [REBECCA-ADAPTER-AUDIT.md](REBECCA-ADAPTER-AUDIT.md) | Mapping Rebecca to the page's data contract, from source. | +| [REBECCA-ADAPTER-DECISIONS.md](REBECCA-ADAPTER-DECISIONS.md) | Decision record for Rebecca's time and status values. | +| [LIVE-POLLING-AUDIT.md](LIVE-POLLING-AUDIT.md) | Audit of the live status refresh contract across panels. | +| [MULTIPANEL-CHECKPOINT-PLAN.md](MULTIPANEL-CHECKPOINT-PLAN.md) | Repository-state audit and commit plan for the multi-panel work. | + +## Installer + +The management layer under `installer/`, in the order the work was done. + +| Document | What it is | +| --- | --- | +| [INSTALLER-MULTIPANEL-AUDIT.md](INSTALLER-MULTIPANEL-AUDIT.md) | Phase 7A: what the installer would need to support more than one panel. | +| [INSTALLER-ACTIVATION-AUDIT.md](INSTALLER-ACTIVATION-AUDIT.md) | Phase 8A: how activation works today, per panel. | +| [INSTALLER-MULTIPANEL-DESIGN.md](INSTALLER-MULTIPANEL-DESIGN.md) | Phase 8B: the multi-panel installer design. | +| [INSTALLER-BACKUP-DESIGN.md](INSTALLER-BACKUP-DESIGN.md) | Phase 8C: the format-2 backup snapshot design. | +| [INSTALLER-BACKUP-REVIEW.md](INSTALLER-BACKUP-REVIEW.md) | Phase 8D: review of the backup design. | +| [INSTALLER-PANEL-INTERFACE.md](INSTALLER-PANEL-INTERFACE.md) | P3: the frozen panel adapter interface. | +| [INSTALLER-TRANSACTION-DESIGN.md](INSTALLER-TRANSACTION-DESIGN.md) | P4: the transaction engine that drives a panel adapter. | +| [INSTALLER-PANEL-3XUI.md](INSTALLER-PANEL-3XUI.md) | P5A: the 3X-UI panel adapter and its validation boundary. | + +## Documentation platform + +How the documentation site under `docs/` was chosen and built. + +| Document | What it is | +| --- | --- | +| [ADR-0001-DOCUMENTATION-FRAMEWORK.md](ADR-0001-DOCUMENTATION-FRAMEWORK.md) | Decision record: why Astro Starlight. | +| [DOCUMENTATION-PLATFORM-PROPOSAL.md](DOCUMENTATION-PLATFORM-PROPOSAL.md) | Architecture proposal for the documentation platform. | +| [DOCUMENTATION-DESIGN-SYSTEM-PROPOSAL.md](DOCUMENTATION-DESIGN-SYSTEM-PROPOSAL.md) | The site's design system: tokens and components. | +| [DOCUMENTATION-IMPLEMENTATION-PLAN.md](DOCUMENTATION-IMPLEMENTATION-PLAN.md) | The roadmap that turned the proposals into phases. | +| [PHASE-1-BOOTSTRAP-PLAN.md](PHASE-1-BOOTSTRAP-PLAN.md) | Phase 1 of the documentation programme: bootstrapping the site. | diff --git a/REBECCA-ADAPTER-AUDIT.md b/docs/design/REBECCA-ADAPTER-AUDIT.md similarity index 100% rename from REBECCA-ADAPTER-AUDIT.md rename to docs/design/REBECCA-ADAPTER-AUDIT.md diff --git a/REBECCA-ADAPTER-DECISIONS.md b/docs/design/REBECCA-ADAPTER-DECISIONS.md similarity index 100% rename from REBECCA-ADAPTER-DECISIONS.md rename to docs/design/REBECCA-ADAPTER-DECISIONS.md From 3d095f16220c06f61e3234ae8110e068b74a010a Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 24 Sep 2026 19:49:41 +0000 Subject: [PATCH 2/7] docs(site): publish the documentation site to GitHub Pages The Starlight site under docs/ built but was published nowhere: no site URL, no deployment, and nothing linked to it. - .github/workflows/docs.yml builds the site on pull requests that touch docs/ and deploys it from main (push or manual run) with actions/deploy-pages. Least privilege: contents: read, and pages / id-token write only on the deploy job, which runs only on main. One-time setup: Settings -> Pages -> Source: GitHub Actions. - A project site is served under /Row-Template/, so astro.config.mjs sets site and base. Content keeps its root-relative links (/installation/, /fa/branding/): plugins/base-links.mjs, a dependency-free Satteri mdast plugin, adds the base at build time, and the two preview components prefix import.meta.env.BASE_URL. Moving the site later only means changing `base`. - @astrojs/markdown-satteri is declared at 0.4.1, the exact version astro 7.3.3 already pins and installs; the lockfile gains one line. - public/favicon.svg: every page linked /favicon.svg, which never existed (a 404 on each page load, also on main). It redraws the banner's mark in the site's accent colour. - Starlight gets the repository's GitHub link and "Edit page" links. - docs/README.md: documents publishing and the base-link rule, points at design/ for the ADR it cited at the old root path, and replaces a `brand/` directory that never existed with the real layout. Checked: npm ci and npm run build pass (37 pages, as before; the 36 Vite MODULE_LEVEL_DIRECTIVE warnings are identical on main). Every one of the 1,072 internal href/src/srcset URLs in the build resolves under /Row-Template/ to a built file. actionlint passes. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011QC3E9ChkFK7sDFBTfwNJ3 --- .github/workflows/docs.yml | 72 +++++++++++++++++++++++ docs/README.md | 23 ++++++-- docs/astro.config.mjs | 23 +++++++- docs/package-lock.json | 1 + docs/package.json | 1 + docs/plugins/base-links.mjs | 33 +++++++++++ docs/public/favicon.svg | 1 + docs/src/components/HomePreviews.astro | 4 +- docs/src/components/TemplateGallery.astro | 6 +- 9 files changed, 154 insertions(+), 10 deletions(-) create mode 100644 .github/workflows/docs.yml create mode 100644 docs/plugins/base-links.mjs create mode 100644 docs/public/favicon.svg diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..3c7d276 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,72 @@ +# Build the documentation site in docs/ and publish it to GitHub Pages. +# +# Pull requests that touch docs/ are built but never deployed. A push to main +# that touches docs/, or a manual run on main, builds and deploys. +# +# One-time repository setup: Settings -> Pages -> Build and deployment -> +# Source: "GitHub Actions". + +name: Docs + +on: + push: + branches: [main] + paths: + - "docs/**" + - ".github/workflows/docs.yml" + pull_request: + paths: + - "docs/**" + - ".github/workflows/docs.yml" + workflow_dispatch: + +permissions: + contents: read + +# One deployment at a time; a newer push supersedes a queued one, but a +# deployment already running is allowed to finish. +concurrency: + group: pages-${{ github.ref }} + cancel-in-progress: false + +jobs: + build: + runs-on: ubuntu-latest + defaults: + run: + working-directory: docs + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-node@v4 + with: + node-version-file: docs/.nvmrc + cache: npm + cache-dependency-path: docs/package-lock.json + + - name: Install (lockfile only) + run: npm ci + + - name: Build + run: npm run build + + - name: Upload the site + if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request' + uses: actions/upload-pages-artifact@v3 + with: + path: docs/dist + + deploy: + if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request' + needs: build + runs-on: ubuntu-latest + permissions: + pages: write + id-token: write + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/docs/README.md b/docs/README.md index 320708a..8cfeccc 100644 --- a/docs/README.md +++ b/docs/README.md @@ -6,7 +6,7 @@ This directory is the documentation site. It is **separate from the product**. ```sh cd docs -npm ci # reproducible install — see PHASE-1-BOOTSTRAP-PLAN.md 2.7 +npm ci # reproducible install — see design/PHASE-1-BOOTSTRAP-PLAN.md 2.7 npm run build # writes docs/dist/ npm run dev # local preview ``` @@ -24,7 +24,7 @@ npm run dev # local preview ## Why Starlight -See `../ADR-0001-DOCUMENTATION-FRAMEWORK.md`. The short version: Pagefind gives a +See [`design/ADR-0001-DOCUMENTATION-FRAMEWORK.md`](design/ADR-0001-DOCUMENTATION-FRAMEWORK.md). The short version: Pagefind gives a build-time search index served from this site's own origin, which is the only option consistent with the product's promise that the artifact fetches nothing from anywhere. @@ -38,6 +38,21 @@ consistent with the product's promise that the artifact fetches nothing from any | `src/styles/` | design tokens from the design system proposal | | `src/components/` | the design-system components | | `src/data/` | generated data (gallery, error center) — never hand-edited | -| `public/` | static passthrough — favicons | -| `brand/` | logo assets | +| `public/` | static passthrough — template previews | +| `plugins/` | build-time helpers (the site-base link rewriter) | +| `assets/` | the banner and screenshots, shared by the repository README and the site | +| `design/` | design records: audits, designs and decisions — [index](design/README.md) | | `dist/` | build output, gitignored | + +## Publishing + +`.github/workflows/docs.yml` builds this site on every pull request that touches +`docs/`, and publishes it to GitHub Pages on every push to `main` that does: + + + +The site is served under `/Row-Template/`, which `astro.config.mjs` sets as its +`base`. Write links in content as root-relative paths (`/installation/`, +`/fa/branding/`) and reference files in `public/` the same way; +`plugins/base-links.mjs` and the components add the base at build time, +so content never hard-codes it. diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index d4feda5..e96487f 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -6,18 +6,35 @@ // Locales: English is the root locale (and the documentation source of truth), // Persian and Arabic are declared with dir: "rtl" rather than mirrored after the fact. // -// No "site" is configured: hosting is a Phase 5 decision, and setting a URL now would -// mean inventing one. The sitemap integration therefore stays skipped — that warning is -// expected, not suppressed. +// Hosting: GitHub Pages, published by .github/workflows/docs.yml. A project site is +// served under //, so `base` is set to it. Content keeps writing links +// root-relative (/installation/); plugins/base-links.mjs adds the base at build +// time, and the components prefix import.meta.env.BASE_URL to files in public/. import { defineConfig } from "astro/config"; import starlight from "@astrojs/starlight"; +import { satteri } from "@astrojs/markdown-satteri"; +import baseLinks from "./plugins/base-links.mjs"; + +const SITE = "https://iitzseridev.github.io"; +const BASE = "/Row-Template"; export default defineConfig({ + site: SITE, + base: BASE, + markdown: { + processor: satteri({ mdastPlugins: [baseLinks(BASE)] }), + }, integrations: [ starlight({ title: "Row-Template", description: "Documentation for the Row-Template subscription page.", + social: [ + { icon: "github", label: "GitHub", href: "https://github.com/iitzSeriZdev/Row-Template" }, + ], + editLink: { + baseUrl: "https://github.com/iitzSeriZdev/Row-Template/edit/main/docs/", + }, // The design system's tokens, applied over Starlight's own variables. customCss: ["./src/styles/tokens.css"], defaultLocale: "root", diff --git a/docs/package-lock.json b/docs/package-lock.json index e678aa6..7bc2f59 100644 --- a/docs/package-lock.json +++ b/docs/package-lock.json @@ -6,6 +6,7 @@ "": { "name": "row-template-docs", "dependencies": { + "@astrojs/markdown-satteri": "0.4.1", "@astrojs/starlight": "0.42.1", "astro": "7.3.3" } diff --git a/docs/package.json b/docs/package.json index d41a10a..0d33774 100644 --- a/docs/package.json +++ b/docs/package.json @@ -9,6 +9,7 @@ "previews": "node scripts/capture-previews.mjs" }, "dependencies": { + "@astrojs/markdown-satteri": "0.4.1", "astro": "7.3.3", "@astrojs/starlight": "0.42.1" } diff --git a/docs/plugins/base-links.mjs b/docs/plugins/base-links.mjs new file mode 100644 index 0000000..e3317b0 --- /dev/null +++ b/docs/plugins/base-links.mjs @@ -0,0 +1,33 @@ +// Prefix the site's base path to root-relative links in Markdown and MDX content. +// +// The site is served from a sub-path (GitHub Pages serves a project site under +// //), but content links are written root-relative — `/installation/`, +// `/fa/branding/` — and Starlight does not rewrite links inside content. Writing +// the base into every page would tie the content to one host; this plugin adds it +// at build time instead, so moving the site only means changing `base` in +// astro.config.mjs. +// +// Only links that start with a single "/" are touched. Protocol-relative ("//"), +// absolute ("https:"), fragment ("#") and relative links are left as written, and +// a link that already carries the base is not prefixed twice. +// +// A Sätteri mdast plugin (Astro's default Markdown processor): one visitor per +// node type that carries a URL, rewriting it through the context. + +export default function baseLinks(base = "/") { + const prefix = base.replace(/\/+$/, ""); + const rewrite = (node, ctx) => { + const url = node.url; + if ( + prefix && + typeof url === "string" && + url.startsWith("/") && + !url.startsWith("//") && + url !== prefix && + !url.startsWith(prefix + "/") + ) { + ctx.setProperty(node, "url", prefix + url); + } + }; + return { name: "row-template-base-links", link: rewrite, image: rewrite, definition: rewrite }; +} diff --git a/docs/public/favicon.svg b/docs/public/favicon.svg new file mode 100644 index 0000000..fbe4d88 --- /dev/null +++ b/docs/public/favicon.svg @@ -0,0 +1 @@ + diff --git a/docs/src/components/HomePreviews.astro b/docs/src/components/HomePreviews.astro index acb38b2..63b1b06 100644 --- a/docs/src/components/HomePreviews.astro +++ b/docs/src/components/HomePreviews.astro @@ -21,6 +21,8 @@ import { join } from "node:path"; // See TemplateGallery: the compiled component's import.meta.url is not the source // path, so the preview directory is resolved from the build's working directory. const PREVIEW_DIR = join(process.cwd(), "public", "previews"); +// URL of the same folder once built: files in public/ are served under the site base. +const PREVIEW_URL = `${import.meta.env.BASE_URL.replace(/\/$/, "")}/previews`; const locale = Astro.currentLocale === "fa" ? "fa" : Astro.currentLocale === "ar" ? "ar" : "en"; const PICKS = ["row", "editorial", "brutal", "pulsenova"]; @@ -42,7 +44,7 @@ const available = PICKS.filter((id) => existsSync(join(PREVIEW_DIR, `${id}-deskt {available.map((id) => (
{CAPTION.alt(CAPTION[id])}
{t.altDesktop(tpl.name)}
{t.altMobile(tpl.name)} Date: Thu, 24 Sep 2026 19:49:51 +0000 Subject: [PATCH 3/7] docs: add the 1.2.0 changelog entry and current release contents CHANGELOG.md gains a [1.2.0] - Unreleased entry covering the 48 commits since v1.1.0, each item checked against the code: - Added: the fifteen designs and how to choose one (install chooser, RT_TEMPLATE, Reconfigure -> Template; kept across updates); per-design checksums that `row-template verify` checks; CSS-drawn flags for DE, FR, NL, JP, SE and US (Windows + Chromium shows the letters instead); the documentation site; panel shells packaged for research, which the installer does not place. - Changed: panel database detection now fails closed on a file that is not SQLite (1.1.0 took the first file found); live refresh ignores a response without the page's own fields; the country-code table is a bitmap. - Internal: the multi-panel groundwork, which no row-template command calls yet; backups and rollback keep the 1.1.0 format. Deliberately left out until they can be verified: an upgrade-from-1.1.0 statement and a "validated against" 3X-UI version. PROVENANCE.md described the tarball as template, VERSION, install.sh, lib/ and bin/. It now lists what tools/make-release.sh actually packs, checked against an extracted build: template.html, templates// and shells/// with their checksum sidecars, and the inner SHA256SUMS. Rebuilding a release now needs Node.js to build the designs. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011QC3E9ChkFK7sDFBTfwNJ3 --- CHANGELOG.md | 72 +++++++++++++++++++++++++++++++++++++++++++++++++++ PROVENANCE.md | 16 +++++++++--- 2 files changed, 84 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e003eff..461634e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,77 @@ All notable changes to this project are documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [1.2.0] - Unreleased + +Turns Row-Template from one page into a collection of designs. A minor release: +Row stays the default design, and 3X-UI (>= 3.6.0) stays the only supported +panel. + +### Added + +- **Fifteen designs.** Row plus Editorial, Canvas, Prism, Terminal, Pulse, + Brutal, Arcade, Sketch, Signature, Saffron, Pulse Nova, Prism Nova, Terminal + Nova, and Arcade Nova. Every design is built from the same runtime and + translations, so status, Connect, QR codes, the Configuration Explorer, and + the five languages behave the same in each. +- **Choosing a design.** A fresh interactive install shows a design chooser + (Enter keeps Row). `RT_TEMPLATE=` picks one for a scripted install, and + the manager's **Reconfigure → Template** changes it later. Updates keep the + selected design. +- **Checksummed designs.** Each design ships in the release with its own + SHA-256 checksum. `row-template verify` checks every installed design against + its checksum and confirms the live page is the selected design. +- **Painted country flags.** The flags of Germany, France, the Netherlands, + Japan, Sweden, and the United States are drawn with CSS, so they appear on + Windows in Chromium-based browsers, which otherwise show the two letters + (`DE`) instead of a flag. Other countries keep the platform's flag emoji. +- **Documentation site** in English, Persian, and Arabic: installation, + configuration, a template gallery with real previews, branding, security, + compatibility, a developer reference, and troubleshooting. +- **Panel shells for research.** The release carries each design's page shell + for every panel in the registry under `shells/`: 3X-UI, PasarGuard (Jinja2) + and Rebecca (pongo2). The installer does not place these files. PasarGuard + and Rebecca are research targets, not supported panels, and there are no + installation instructions for them. + +### Changed + +- **Panel database detection fails closed.** Row-Template previously used the + first `x-ui.db` it found. It now uses the first database file that exists — + the one `XUI_DB_FOLDER` names, then the default locations in order — and + only if it is a real SQLite database. If that file is not, it is refused with + a warning instead of silently moving on to another, possibly stale, database; + activation then falls back to the manual instructions. +- **Live refresh accepts only its own data.** The status refresh now checks + that a response carries the page's own fields before using it. An + unexpected response stops the refresh and leaves the server-rendered figures + in place, instead of repainting the page with wrong values. +- The country-code table is stored as a bitmap, saving about 800 bytes in + every page. + +### Internal + +- Groundwork for installing on more than one panel: a normalized data + contract, build-time adapters for 3X-UI, PasarGuard and Rebecca, a frozen + panel interface, a transaction engine, a 3X-UI panel adapter, and a + format-2 backup snapshot. No `row-template` command calls any of it yet; + backups and rollback still use the 1.1.0 format. + +### Development + +- `npm test` first renders every design's fixture pages (`npm run + fixtures:all`), so a fresh clone can run the suite; it needs Go 1.22 or + newer. +- `npm run lint:sh` runs ShellCheck over every shell script. +- The test harness runs on Linux and on Windows with Git Bash. +- `tools/make-release.sh` is executable, as its usage line documents. +- Design records moved from the repository root to + [`docs/design/`](docs/design/README.md), with an index. + +### Compatibility + +- Requires 3X-UI (MHSanaei) **>= 3.6.0**. + ## [1.1.0] - 2026-08-30 Evolves the subscriber page into a connection and configuration hub. A minor, @@ -81,5 +152,6 @@ First stable release. - Requires 3X-UI (MHSanaei) **>= 3.6.0**; validated against stock 3.7.0. - Recommended operating system: Ubuntu 24.04 LTS (x86_64). +[1.2.0]: https://github.com/iitzSeriZdev/Row-Template/compare/v1.1.0...main [1.1.0]: https://github.com/iitzSeriZdev/Row-Template/releases/tag/v1.1.0 [1.0.0]: https://github.com/iitzSeriZdev/Row-Template/releases/tag/v1.0.0 diff --git a/PROVENANCE.md b/PROVENANCE.md index b25f75d..f8a9817 100644 --- a/PROVENANCE.md +++ b/PROVENANCE.md @@ -11,17 +11,25 @@ Every release published on GitHub carries these assets: | Asset | Purpose | | ----- | ------- | -| `row-template-.tar.gz` | The runtime payload (template, `VERSION`, `install.sh`, `lib/`, `bin/`). | +| `row-template-.tar.gz` | The runtime payload — see below. | | `SHA256SUMS` | The SHA-256 checksum of the tarball above. | | `manifest.txt` | Plain-text metadata (`name`, `version`, `artifact`, `min_xui`, `created`), parsed as data — never executed. | | `install.sh` | The bootstrap used by the one-command installer. | -Inside the tarball there is a second `SHA256SUMS` listing the checksum of every -payload file, so the contents can be checked after extraction as well. +The tarball expands to a single `row-template-/` directory: + +| Path | Contents | +| ---- | -------- | +| `template.html` | The Row design, the page an older installed version updates against. | +| `templates//template.html` (+ `.sha256`) | Every selectable design, each with its own checksum. | +| `shells///shell.html` (+ `.sha256`) | Each design's page shell per panel, packaged for research; the installer does not place them. | +| `VERSION`, `install.sh`, `lib/`, `bin/` | The version, the installer and the `row-template` manager. | +| `SHA256SUMS` | The checksum of every payload file, so the contents can be checked after extraction as well. | The build is deterministic: the same sources always produce a byte-identical `row-template-.tar.gz`. Anyone can rebuild it from a checkout with -`tools/make-release.sh` and compare the checksum. +`tools/make-release.sh` (which needs Node.js to build the designs) and compare +the checksum. ## Integrity: mandatory SHA-256 From 7960a7d2b6cb29865018b40163b08f0b81c559e8 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 24 Sep 2026 19:49:52 +0000 Subject: [PATCH 4/7] docs: add community health files and extend the contributing guide - CODE_OF_CONDUCT.md: Contributor Covenant 2.1. Reports go through GitHub's "Report content" to the maintainers, matching SECURITY.md's use of GitHub's private channels; no email address is published. - .github/pull_request_template.md: a checklist built from the repository's real commands (npm test, verify, build, lint:sh, the docs build), the no-secrets rule, the changelog, and README translation parity. - .github/FUNDING.yml: the NOWPayments link the README already lists, so GitHub shows a Sponsor button. - CONTRIBUTING.md: links the code of conduct and the PR checklist, and adds how translations work (the build rejects a locale catalogue whose keys differ from English), where designs live and the contract a new one must meet, how to work on and publish the docs site, and where the design records are. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011QC3E9ChkFK7sDFBTfwNJ3 --- .github/FUNDING.yml | 4 + .github/pull_request_template.md | 19 +++++ CODE_OF_CONDUCT.md | 133 +++++++++++++++++++++++++++++++ CONTRIBUTING.md | 53 +++++++++++- 4 files changed, 206 insertions(+), 3 deletions(-) create mode 100644 .github/FUNDING.yml create mode 100644 .github/pull_request_template.md create mode 100644 CODE_OF_CONDUCT.md diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml new file mode 100644 index 0000000..59b2d62 --- /dev/null +++ b/.github/FUNDING.yml @@ -0,0 +1,4 @@ +# Shows a "Sponsor" button on the repository. The crypto wallet addresses are +# listed in the README's "Support the project" section. +custom: + - https://nowpayments.io/donation/iitzSeriZ diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..294d518 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,19 @@ +## What this changes + + + +## How it was checked + + + +- [ ] `npm test` passes (needs Go 1.22+; it renders the fixture pages first) +- [ ] `npm run verify` passes +- [ ] `npm run build` was run and `template/index.html` is committed, if anything under `src/` changed +- [ ] `npm run lint:sh` passes, if a shell script changed +- [ ] `cd docs && npm ci && npm run build` passes, if anything under `docs/` changed + +## Before you submit + +- [ ] No secrets anywhere: no subscription URLs, `subId` values, UUIDs, panel credentials, cookies, tokens, keys or real server addresses, in code, fixtures, tests, screenshots or commit messages +- [ ] User-facing changes are noted under the unreleased version in `CHANGELOG.md` +- [ ] If the README changed, the translated READMEs keep the same commands, paths, URLs and wallet addresses diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..20d25cc --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,133 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, caste, color, religion, or sexual +identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the overall + community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or advances of + any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email address, + without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement. On GitHub, use +**Report content** from the "..." menu of the issue, pull request, or comment +concerned, and choose to report it to the repository's maintainers. All +complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of +actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or permanent +ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the +community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.1, available at +[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. + +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder][Mozilla CoC]. + +For answers to common questions about this code of conduct, see the FAQ at +[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at +[https://www.contributor-covenant.org/translations][translations]. + +[homepage]: https://www.contributor-covenant.org +[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html +[Mozilla CoC]: https://github.com/mozilla/diversity +[FAQ]: https://www.contributor-covenant.org/faq +[translations]: https://www.contributor-covenant.org/translations diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ffa42c7..4c55d09 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,7 +1,8 @@ # Contributing to Row-Template Thanks for your interest in improving Row-Template. This is a small project, so -the process is intentionally lightweight. +the process is intentionally lightweight. Everyone taking part is expected to +follow the [Code of Conduct](CODE_OF_CONDUCT.md). ## Ways to help @@ -9,7 +10,9 @@ the process is intentionally lightweight. 3X-UI version, operating system, and clear reproduction steps. - **Improve translations.** The interface ships in English, Persian, Arabic, Russian, and Chinese. Corrections and refinements from native speakers are - very welcome. + very welcome — see [Translations](#translations). +- **Improve the documentation** — the README, or the documentation site under + [`docs/`](docs/README.md). - **Suggest features** by opening an issue to discuss the idea before writing code. @@ -22,6 +25,8 @@ the process is intentionally lightweight. 3. **Never commit secrets.** No subscription URLs, `subId` values, UUIDs, panel credentials, cookies, tokens, private keys, or real server addresses — in code, fixtures, tests, commit messages, or history. +4. **Fill in the pull request checklist.** It lists the checks that apply to + what you changed. ## Development @@ -62,6 +67,46 @@ The gate is severity `error`. For the full report, including warnings, run ShellCheck checks each file on its own, so a global defined in one installer file and read in another is reported as unused. +## Translations + +- **The subscription page:** one catalogue per language in `src/locales/` + (`en.json`, `fa.json`, `ar.json`, `ru.json`, `zh.json`). English is the + reference: every other catalogue must have exactly its keys, none blank, or + `npm run build` fails. Rebuild after editing and commit `template/index.html`. +- **The README:** `README.md` and its translations (`README.fa.md`, + `README.ar.md`, `README.ru.md`, `README.zh-CN.md`) share one structure. + Commands, paths, URLs, version numbers, and wallet addresses must stay + byte-for-byte identical across all five. +- **The documentation site:** pages live in `docs/src/content/docs/` — English + at the top level, Persian under `fa/`, Arabic under `ar/`. + +## Designs + +Each design lives in `src/templates//`, and the catalogue in +`tools/templates.mjs` lists them. A new design must meet the binding contract in +[`docs/design/CUSTOM-TEMPLATE-GUIDELINES.md`](docs/design/CUSTOM-TEMPLATE-GUIDELINES.md); +open an issue before starting one. + +## Documentation site + +The site in `docs/` is its own workspace with its own `package.json`; see +[`docs/README.md`](docs/README.md). Pull requests that touch `docs/` are built +by the Docs workflow, and merges to `main` publish the site to GitHub Pages. + +```bash +cd docs +npm ci # reproducible install from the committed lockfile +npm run dev # local preview +npm run build # the same build the workflow runs +``` + +## Design records + +The audits, designs and decision records behind larger changes live in +[`docs/design/`](docs/design/README.md). Code and tests cite them by file name. +A change that alters one of those decisions should update or supersede the +record rather than contradict it silently. + ## Commit messages Write clear, descriptive commit messages in the imperative mood @@ -70,4 +115,6 @@ obvious from the diff. ## Code of conduct -Be respectful and constructive. Assume good faith. +Be respectful and constructive, and assume good faith. The full +[Code of Conduct](CODE_OF_CONDUCT.md) applies to every issue, pull request and +discussion. From e12c722c8035bb435f1b42f959f675e96ba2f71c Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 24 Sep 2026 20:02:09 +0000 Subject: [PATCH 5/7] docs: redesign the README for 1.2.0 and update all four translations The README described 1.1.0 and made claims the code contradicts. It is rebuilt around what Row-Template 1.2.0 does, every claim checked against the code: - Hero with a Documentation badge and quick links; a "What it is" section; Features grouped for subscribers, for operators, and privacy and safety. - Designs: a gallery of the fifteen designs from the existing preview captures in docs/public/previews/, and the three ways to choose one (install chooser, RT_TEMPLATE, Reconfigure branding -> Template). - Supported panels: 3X-UI supported; PasarGuard and Rebecca marked research with no installation path, as the docs site already says. Marzban and Marzneshin, which nothing in the repository mentions, are removed. - Architecture: a Mermaid diagram of build -> release -> install -> subThemeDir -> render, and a repository layout table. - Installation, Usage, Development, Testing, Roadmap (documented direction only), Contributing, Security, Support, License. Corrected claims: - "never touches your panel's own files": activation writes the panel's subThemeDir setting. It now says that is the only panel setting it changes (the only settings key any shell code writes), and that automatic activation briefly stops and restarts the panel. - Uninstall "does not touch ... its database": it clears subThemeDir when it points at Row-Template. Now stated as such. - `version` shows the installed, minimum-supported and detected 3X-UI versions, as `row-template help` says. - The license section now also names the embedded Vazirmatn font subset (SIL OFL, src/fonts/OFL.txt). README.fa.md, README.ar.md, README.ru.md and README.zh-CN.md follow the same structure. Code blocks, the diagram, commands, paths, URLs and wallet addresses are byte-identical to English; unchanged passages (the OS note, the secrets warning, security, support) reuse the existing translations verbatim; documentation links go to the Persian and Arabic site locales where they exist. No invisible characters, as before. Native-speaker review of the new passages is recommended. Checked: for all five, code blocks, inline code, URLs, images, heading structure and table rows match English, relative links resolve, the Mermaid diagram parses and renders, and every in-page anchor resolves. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011QC3E9ChkFK7sDFBTfwNJ3 --- README.ar.md | 274 +++++++++++++++++++++++++++-------------------- README.fa.md | 268 +++++++++++++++++++++++++++------------------- README.md | 270 +++++++++++++++++++++++++++------------------- README.ru.md | 274 +++++++++++++++++++++++++++-------------------- README.zh-CN.md | 276 ++++++++++++++++++++++++++++-------------------- 5 files changed, 801 insertions(+), 561 deletions(-) diff --git a/README.ar.md b/README.ar.md index c652773..6726f26 100644 --- a/README.ar.md +++ b/README.ar.md @@ -6,7 +6,7 @@

- صفحة اشتراك مخصّصة وأنيقة ومكتفية ذاتيًا للوحات 3X-UI — ملف HTML واحد، قابل للعلامة البيضاء بالكامل، بلا أي شبكات توزيع محتوى (CDN) خارجية وبلا أي طلبات خارجية من الصفحة التي يفتحها المشتركون لديك. + صفحة اشتراك مصقولة ومكتفية ذاتيًا للوحات 3X-UI — خمسة عشر تصميمًا، كلٌّ منها ملف HTML واحد، قابلة لإعادة التسمية بالكامل (white-label)، ودون أي طلبات إلى أطراف ثالثة من الصفحة التي يفتحها مشتركوك.

@@ -18,121 +18,161 @@ Latest release Panel Platform + Documentation +

+ +

+ التثبيت · + التصاميم · + التوثيق · + سجل التغييرات · + الإصدارات

--- +## ما هو Row-Template؟ + +يستطيع 3X-UI أن يعرض على المشتركين صفحة مخصّصة بدلًا من صفحته المدمجة. وRow-Template هو تلك الصفحة: يفتح المشترك رابط اشتراكه فيرى باقته واستهلاكه وتاريخ انتهاء اشتراكه، مع طرق لإضافة الاشتراك بلمسة واحدة إلى التطبيق الذي يستخدمه. + +يُقدَّم كل تصميم في ملف HTML واحد مكتفٍ ذاتيًا، تُضمَّن فيه جميع الأنماط والسكربتات والخطوط ومولّد رمز QR. يثبّته أمر واحد بجوار لوحتك، ويوجّه اللوحة إليه، ويمنحك المدير `row-template` لإدارة العلامة التجارية والتحديثات والتراجع. + ## لماذا Row-Template؟ -- **خاصة بحكم التصميم.** الصفحة التي يفتحها المشتركون لديك لا تُجري أي طلبات لطرف خارجي. وتُولَّد رموز QR محليًا، وتُحقَن بيانات علامتك التجارية كنص — لا تُنفَّذ أبدًا ولا تُرسَل إلى أي جهة. -- **علامة بيضاء حقًّا.** اسم خدمتك ورابط الدعم والشعار الخاص بك. ولا يوجد ما يشير إلى Row-Template على الصفحة المقدَّمة. -- **ملف واحد، بلا اعتماديات وقت تشغيل.** أكواد CSS وJavaScript والخطوط ومولّد رمز QR مضمّنة داخل ملف HTML واحد يُثبَّت بأدوات Linux القياسية فقط — بلا حاجة إلى Node.js أو Python أو قاعدة بيانات. -- **مصمّمة لمشتركيك.** عرض مباشر للاستهلاك وتاريخ الانتهاء، واستيراد بلمسة واحدة إلى التطبيقات الشائعة، وقائمة قابلة للبحث بالإعدادات المفردة لإضافة خادم واحد يدويًا. -- **آمنة في التشغيل.** تثبيت ذرّي مع تحقّق وتراجع بأمر واحد. لا يعدّل 3X-UI إطلاقًا ولا يمسّ ملفات لوحتك. +- **الخصوصية في صميم التصميم.** الصفحة التي يفتحها مشتركوك لا ترسل أي طلبات إلى أطراف ثالثة. تُولَّد رموز QR داخل الصفحة نفسها، وتُحقن علامتك التجارية كنص — لا تُنفَّذ أبدًا ولا تُرسل إلى أي مكان. +- **إعادة تسمية حقيقية بالكامل.** اسم خدمتك، ورابط الدعم الخاص بك، وشعارك. لا شيء في الصفحة المعروضة يشير إلى Row-Template. +- **خمسة عشر تصميمًا، كلٌّ في ملف واحد.** اختر المظهر الذي يناسب خدمتك. جميع التصاميم تتشارك المزايا واللغات وفحوص الأمان نفسها. +- **مصمَّم لمشتركيك.** عرض حيّ للاستهلاك وتاريخ الانتهاء، واستيراد بلمسة واحدة إلى التطبيقات الشائعة، وقائمة قابلة للبحث بالإعدادات الفردية لإضافة خادم واحد يدويًا. +- **آمن في التشغيل.** إصدارات يُتحقَّق من مجموعها الاختباري، وتفعيل ذرّي، وتراجع بأمر واحد. لا يعدّل 3X-UI أبدًا: الإعداد الوحيد الذي يغيّره في اللوحة هو مجلد صفحة الاشتراك (`subThemeDir`). + +## التصاميم -## لقطات الشاشة +يأتي Row-Template 1.2.0 بخمسة عشر تصميمًا، والتصميم الافتراضي هو Row. - - + + + + + - - + + + + + + + + + + + +
Row-TemplateRow-TemplateRow
Row		Editorial
Editorial		Canvas
Canvas		Prism
Prism		Terminal
Terminal
الوضع الداكنالوضع الفاتحPulse
Pulse		Brutal
Brutal		Arcade
Arcade		Sketch
Sketch		Signature
Signature
Saffron
Saffron		Pulse Nova
Pulse Nova		Prism Nova
Prism Nova		Terminal Nova
Terminal Nova		Arcade Nova
Arcade Nova
-تستخدم اللقطات بيانات نموذجية؛ وقائمة الإعدادات وشارات الدول المعروضة هي أمثلة فقط. - -## التثبيت السريع +المعاينات مولَّدة من بيانات المشروع النموذجية. معاينات سطح المكتب والهاتف لكل تصميم موجودة في معرض القوالب. -> **نظام التشغيل المُوصى به: Ubuntu 24.04 LTS (x86_64).** قد تعمل توزيعات Linux الحديثة الأخرى لكنها لم تحظَ بالمستوى نفسه من تغطية التحقق. - -شغّل الأمر التالي بصلاحية **root** على الخادم الذي يستضيف لوحة 3X-UI لديك: +اختر التصميم أثناء تثبيت تفاعلي جديد، أو اضبط `RT_TEMPLATE` للتثبيت عبر سكربت، أو غيّره لاحقًا من المدير (**Reconfigure branding → Template**). تحتفظ التحديثات باختيارك. -```bash -bash <(curl -fsSL https://github.com/iitzSeriZdev/Row-Template/releases/latest/download/install.sh) -``` +## المزايا -يقوم المُثبِّت بتنزيل أحدث إصدار مستقر، ويتحقق من مجموع التحقق SHA-256 الخاص به (لا يوجد خيار لتخطّي ذلك)، ويستخرجه بأمان، ويرشدك خلال إعداد العلامة التجارية. وهو لا يعدّل 3X-UI إطلاقًا ولا يمسّ ملفات لوحتك الخاصة. +**لمشتركيك** -## اللوحات المدعومة +- **حالة حيّة.** حالة الباقة، والبيانات المستهلكة والمتبقية، وتاريخ الانتهاء، تُحدَّث من لوحتك طالما كانت الصفحة ظاهرة. +- **استيراد بلمسة واحدة** إلى التطبيقات الشائعة، مرتّبة حسب المنصة: v2rayNG وHapp وsing-box على Android؛ وStreisand وV2Box وShadowrocket على iOS؛ وClash Verge Rev وMihomo Party وv2rayN على Windows؛ وClash Verge Rev وStreisand وV2Box على macOS. +- **النسخ ورمز QR.** انسخ رابط الاشتراك أو امسحه كرمز QR يُولَّد داخل الصفحة. +- **مستكشف الإعدادات.** كل خادم في صف خاص به، مع علم الدولة أو شارة بالأحرف الأولى (monogram) ووسم البروتوكول (VLESS وVMess وTrojan وShadowsocks وHysteria/Hysteria2 وWireGuard وAmneziaWG وTelegram MTProto)، مع رمز QR ونسخ لكل إعداد، وبحث في القوائم الطويلة. +- **خمس لغات** — الإنجليزية والفارسية والعربية والروسية والصينية — مع تخطيط من اليمين إلى اليسار، واختيار المظهر System / Light / Dark. -| اللوحة | الحالة | ملاحظات | -| ----- | ------ | ----- | -| [3X-UI](https://github.com/MHSanaei/3x-ui) (MHSanaei) | ✅ مدعومة | يتطلّب الإصدار **>= 3.6.0** | -| [Marzban](https://github.com/Gozargah/Marzban) | ⬜ مُخطط له | غير مدعومة بعد | -| [Marzneshin](https://github.com/marzneshin/marzneshin) | ⬜ مُخطط له | غير مدعومة بعد | -| [Rebecca](https://github.com/rebeccapanel/Rebecca) | ⬜ مُخطط له | غير مدعومة بعد | -| [PasarGuard](https://github.com/PasarGuard/panel) | ⬜ مُخطط له | غير مدعومة بعد | +**لك** -3X-UI هي اللوحة الوحيدة المدعومة حاليًا. أما اللوحات الأخرى فهي ضمن خارطة الطريق ومدرجة هنا لأغراض الشفافية — ولا يوجد لها أي دعم جزئي أو تجريبي في هذا الإصدار. +- **علامة تجارية قابلة لإعادة التسمية.** اسم الخدمة ورابط الدعم والشعار، وكلها اختيارية، تُخزَّن كبيانات وتُحقن كنص. +- **مدير لكل شيء.** قائمة تفاعلية وأوامر مباشرة للعلامة التجارية والتحديثات والتحقق والتراجع وإلغاء التثبيت. +- **تحديثات من القناة المستقرة.** لا يثبّت `row-template update` إصدارًا مستقرًا أحدث إلا إذا وُجد. -## المزايا +**الخصوصية والأمان** -- **صفحة واحدة مكتفية ذاتيًا.** جميع أكواد CSS وJavaScript والخطوط ومولّد رمز QR مضمّنة داخل ملف HTML واحد. والصفحة التي يفتحها المشتركون لديك لا تُجري أي طلبات لطرف خارجي. -- **علامة بيضاء.** حدّد اسم خدمتك ورابط الدعم والشعار الخاص بك. ولا يوجد ما يشير إلى Row-Template على الصفحة المقدَّمة. -- **خمس لغات.** الإنجليزية والفارسية والعربية والروسية والصينية، مع دعم التخطيط من اليمين إلى اليسار. -- **آمنة بحكم التصميم.** تُعامَل بيانات علامتك التجارية كبيانات وتُحقَن كنص، ولا تُنفَّذ أبدًا. والصفحة لا ترسل بيانات المشتركين إلى أي جهة إطلاقًا. -- **عرض مباشر للاستهلاك.** يعرض حالة الباقة، وحجم البيانات المستهلكة والمتبقية، وتاريخ الانتهاء، وروابط كل عميل مع أزرار نسخ ورموز QR. -- **تثبيت واستعادة ذرّيّان.** يُجهَّز كل تغيير ويُتحقَّق منه ثم يُستبدل. فلا تترك خطوة فاشلة صفحة معطوبة قيد التشغيل، ويمكنك التراجع إلى إصدار سابق. -- **لا اعتماديات وقت تشغيل.** أدوات Linux القياسية فقط (bash، coreutils، curl، tar، sha256sum). ولا يلزم Node.js أو Python أو قاعدة بيانات لتثبيته أو تشغيله. +- **لا طلبات إلى أطراف ثالثة** من الصفحة المعروضة: لا شبكات CDN، ولا خدمات خارجية لرموز QR أو تحديد الموقع، ولا قياس عن بُعد (telemetry). تأتي الحالة الحيّة من لوحتك أنت. +- **تحقق SHA-256 إلزامي** لكل تنزيل لإصدار، دون أي خيار لتجاوزه. +- **تفعيل ذرّي.** تُولَّد الصفحة الجديدة ويُتحقَّق منها قبل أن تحل محل الصفحة الحالية، فلا تترك خطوة فاشلة صفحة معطوبة قيد العمل. +- **كشف حذر للوحة.** إذا لم تكن قاعدة بيانات اللوحة التي يعثر عليها Row-Template قاعدة بيانات SQLite صالحة، فإنه يرفض استخدامها بدلًا من تخمين قاعدة بيانات أخرى. -## المتطلبات +## اللوحات المدعومة -- خادم يشغّل لوحة 3X-UI (الإصدار **>= 3.6.0**). -- وصول بصلاحية root إلى ذلك الخادم. -- `curl` و`tar` و`sha256sum` (متوفرة على جميع أنظمة Linux تقريبًا). +| اللوحة | الحالة | ملاحظات | +| ----- | ------ | ----- | +| [3X-UI](https://github.com/MHSanaei/3x-ui) (MHSanaei) | ✅ مدعومة | تتطلب الإصدار **>= 3.6.0** | +| [PasarGuard](https://github.com/PasarGuard/panel) | 🔬 قيد البحث | غير مدعومة؛ لا يوجد مسار تثبيت | +| [Rebecca](https://github.com/rebeccapanel/Rebecca) | 🔬 قيد البحث | غير مدعومة؛ لا يوجد مسار تثبيت | + +3X-UI هي اللوحة الوحيدة المدعومة. تستخدم PasarGuard وRebecca محرّكَي قوالب مختلفين (Jinja2 وpongo2)؛ يُبنى هيكل صفحة كل تصميم لهما ويُحزَم في الإصدار لأغراض الدراسة، لكن المثبّت لا يضعه في مكانه ولا توجد تعليمات تثبيت لهما. راجع [التوافق](https://iitzseridev.github.io/Row-Template/ar/compatibility/) للاطلاع على نتائج البحث. + +## البنية + +```mermaid +flowchart TB + subgraph build ["Build and release"] + direction LR + SRC["src/
runtime, styles, locales,
15 design layouts"] --> BUILD["tools/build.mjs"] + BUILD --> ART["One self-contained
HTML file per design"] + ART --> REL["tools/make-release.sh
tarball + SHA256SUMS"] + end + subgraph host ["Your 3X-UI server"] + direction LR + INST["install.sh / row-template
verify checksum, stage, validate,
back up, activate"] --> DIR["/etc/3x-ui/
sub_templates/row-template"] + DIR -- "subThemeDir" --> XUI["3X-UI renders the page
with the subscriber's data"] + end + build -- "GitHub Releases" --> host + host -- "serves the page" --> BROWSER["Subscriber's browser"] + BROWSER -. "live status: ?format=info" .-> host +``` -## التوافق +- **ملف واحد لكل تصميم.** يضمّن `tools/build.mjs` الشيفرة المشتركة والترجمات والخطوط ومولّد QR داخل تخطيط كل تصميم، ويرفض أي تخطيط ينقصه أيٌّ من نقاط الربط (hooks) التي تحتاجها الشيفرة. ثم يرفض `tools/verify.mjs` أي ملف يحمّل شيئًا من مصدر بعيد أو يحتوي على بنية محظورة. +- **اللوحة هي من تعرض الصفحة.** الصفحة قالب: يملأ 3X-UI بيانات المشترك فيها عند تقديمها، ثم تحدّث الصفحة حالتها من اللوحة نفسها. +- **لا يعدّل المثبّت 3X-UI أبدًا.** يكتب في مجلده الخاص ويغيّر إعدادًا واحدًا في اللوحة، هو `subThemeDir`، ليشير إليه. -- **اللوحة:** 3X-UI (MHSanaei) **>= 3.6.0**. جرى التحقق منها مقابل الإصدار الأصلي 3.7.0. -- **نظام التشغيل:** المُوصى به Ubuntu 24.04 LTS. جرى التحقق على Ubuntu 24.04 LTS (x86_64). قد تعمل التوزيعات الأخرى لكنها لم تحظَ بالمستوى نفسه من تغطية التحقق. +| المسار | المحتوى | +| ---- | ---------------- | +| `src/` | شيفرة الصفحة وأنماطها وترجماتها؛ كل تصميم في `src/templates//` | +| `template/index.html` | صفحة Row المبنية، وهي مُضمَّنة في المستودع | +| `tools/` | البناء والتحقق والإصدار وعارض الـ fixtures المكتوب بـ Go | +| `installer/` | `install.sh` والأمر `row-template` ومكتبته الإدارية | +| `tests/` | مجموعات الاختبارات | +| `docs/` | موقع التوثيق؛ سجلات التصميم في [`docs/design/`](docs/design/README.md) | ## التثبيت -شغّل أمر التثبيت المذكور أعلاه بصلاحية root. سيقوم المُثبِّت بما يلي: - -1. تنزيل أحدث إصدار مستقر من GitHub. -2. التحقق من مجموع تحقق الإصدار (SHA-256، إلزامي — بلا تجاوز). -3. استخراجه بأمان وتثبيته في `/etc/3x-ui/sub_templates/row-template`. -4. طلب بيانات علامتك التجارية (اسم الخدمة، رابط الدعم، الشعار — جميعها اختيارية). -5. توليد الصفحة المقدَّمة وتفعيلها في اللوحة حيثما أمكن. - -إن كنت تفضّل عدم التمرير المباشر من الشبكة، يمكنك تنزيل ملفات الإصدار من [صفحة الإصدارات](https://github.com/iitzSeriZdev/Row-Template/releases/latest)، والتحقق من مجموع التحقق بنفسك، وتشغيل `install.sh` المرفق من داخل المجلد المُستخرَج. +> **نظام التشغيل المُوصى به: Ubuntu 24.04 LTS (x86_64).** قد تعمل توزيعات Linux الحديثة الأخرى لكنها لم تحظَ بالمستوى نفسه من تغطية التحقق. -## المدير +**المتطلبات:** خادم يشغّل 3X-UI **>= 3.6.0**، وصلاحية root عليه، و`curl` و`tar` و`sha256sum` (متوفرة على جميع أنظمة Linux تقريبًا). ويحتاج التفعيل التلقائي أيضًا إلى `sqlite3`. -بعد التثبيت، يمكنك إدارة كل شيء عبر الأمر `row-template`. شغّله بلا أي وسائط في الطرفية لفتح المدير التفاعلي: +شغّل الأمر بصلاحية **root** على الخادم الذي يستضيف لوحة 3X-UI: ```bash -row-template +bash <(curl -fsSL https://github.com/iitzSeriZdev/Row-Template/releases/latest/download/install.sh) ``` -أو استخدم الأوامر المباشرة: - -| الأمر | وظيفته | -| ------- | ------------ | -| `row-template config` | إعادة ضبط العلامة التجارية (اسم الخدمة، رابط الدعم، الشعار) | -| `row-template update` | التحقق من القناة المستقرة والتحديث إذا وُجد إصدار أحدث | -| `row-template rollback` | التراجع إلى الإصدار السابق (`--auto` أو `--to `) | -| `row-template verify` | التحقق من سلامة التثبيت | -| `row-template version` | طباعة الإصدار المثبَّت | -| `row-template uninstall` | إزالة Row-Template (دون المساس بـ 3X-UI) | -| `row-template help` | عرض طريقة الاستخدام | +يقوم المثبّت بما يلي: -## العلامة التجارية والإعداد +1. ينزّل أحدث إصدار مستقر من GitHub. +2. يتحقق من مجموعه الاختباري SHA-256 (إلزامي — دون إمكانية التجاوز). +3. يستخرجه بأمان ويثبّته في `/etc/3x-ui/sub_templates/row-template`. +4. في التثبيت الجديد، يعرض أداة اختيار التصميم (يُبقي Enter على Row). +5. يطلب بيانات علامتك التجارية (اسم الخدمة، رابط الدعم، الشعار — وكلها اختيارية). +6. يولّد الصفحة ويتحقق منها، ثم يفعّلها في اللوحة حيثما أمكن. -حدّد اسم خدمتك ورابط الدعم والشعار أثناء التثبيت، أو غيّرها في أي وقت: +لاختيار تصميم دون أداة الاختيار، في سكربت مثلًا: ```bash -row-template config +RT_TEMPLATE=editorial bash <(curl -fsSL https://github.com/iitzSeriZdev/Row-Template/releases/latest/download/install.sh) ``` -تُخزَّن مدخلاتك كبيانات (ولا تُنفَّذ أبدًا) وتُحقَن في الصفحة كنص. اترك أي حقل فارغًا للحصول على صفحة بلا علامة تجارية (علامة بيضاء). ولا يقبل رابط الدعم سوى المخططات التي يُفترض أن يفتحها المتصفح (على سبيل المثال `https://…` أو `tg://…` أو `mailto:…`). +إن كنت تفضّل عدم تمرير السكربت مباشرة من الشبكة، فنزّل ملفات الإصدار من [صفحة الإصدارات](https://github.com/iitzSeriZdev/Row-Template/releases/latest)، وتحقق من المجموع الاختباري بنفسك كما يشرح [PROVENANCE.md](PROVENANCE.md)، ثم شغّل `install.sh` المرفق من المجلد المستخرج. -## التفعيل +### التفعيل يُثبَّت Row-Template في مجلد تقدّمه اللوحة كصفحة اشتراك: @@ -140,76 +180,84 @@ row-template config /etc/3x-ui/sub_templates/row-template ``` -- **تلقائيًا:** عند توفّر `sqlite3`، يمكن للمُثبِّت/المدير توجيه اللوحة إلى Row-Template نيابةً عنك. -- **يدويًا:** خلاف ذلك، اضبطه في اللوحة بنفسك — افتح **Panel Settings → Subscription → Profile → Sub Theme Directory** وأدخِل بالضبط: +- **تلقائيًا:** عند توفر `sqlite3`، يضبطه Row-Template نيابةً عنك. يوقف خدمة اللوحة لفترة وجيزة، ويكتب الإعداد، ثم يشغّل الخدمة من جديد ويتحقق من القيمة. في التثبيت التفاعلي يعرض الإعداد الحالي ويسألك أولًا. +- **يدويًا:** خلاف ذلك، افتح **Panel Settings → Subscription → Profile → Sub Theme Directory** وأدخل القيمة التالية حرفيًا: ``` /etc/3x-ui/sub_templates/row-template ``` -## التحديث +## الاستخدام + +شغّل المدير دون أي وسائط في الطرفية لفتح القائمة التفاعلية: ```bash -row-template update +row-template ``` -يتحقق هذا من قناة الإصدارات المستقرة العامة، ويعرض الإصدار المثبَّت والإصدار المتاح، ولا يُحدِّث إلا عند وجود إصدار مستقر أحدث. وإذا تعذّر الوصول إلى الشبكة أو إلى مصدر الإصدار، فإنه يبلّغ بأنه لم يتمكن من التحقق — ولا يُعامَل تثبيتك أبدًا على أنه معطوب. ولا يحتاج الاستخدام العادي إلى أي روابط أو تنزيلات يدوية. - -## التراجع +أو استخدم أمرًا مباشرة: -```bash -row-template rollback -``` +| الأمر | وظيفته | +| ------- | ------------ | +| `row-template config` | تغيير اسم الخدمة أو رابط الدعم أو الشعار، ثم إعادة توليد الصفحة | +| `row-template update` | تنزيل إصدار مستقر أحدث والتحقق منه وتفعيله (التحقق من المجموع الاختباري إلزامي) | +| `row-template rollback` | استعادة إصدار سابق (`--auto` أو `--to `) | +| `row-template verify` | فحص التثبيت وربط اللوحة والصفحة الحالية (للقراءة فقط) | +| `row-template version` | عرض الإصدار المثبّت والحد الأدنى المدعوم وإصدار 3X-UI المكتشف | +| `row-template uninstall` | إزالة Row-Template وإعادة اللوحة إلى صفحتها المدمجة | +| `row-template help` | عرض طريقة الاستخدام | -يستعيد الإصدار السابق من نسخة احتياطية جرى التحقق منها. ويُؤخذ أولًا لقطة للإصدار الحالي، بحيث يمكن استرداد الوضع إذا فشل التراجع. ويُحتفَظ بإعدادات علامتك التجارية. +يجب تشغيل الأوامر التي تغيّر النظام (`config` و`update` و`rollback` و`uninstall`) بصلاحية root. -## التحقق +- **العلامة التجارية** تُخزَّن كبيانات، ولا تُنفَّذ أبدًا، وتُحقن في الصفحة كنص. اترك أي حقل فارغًا للحصول على صفحة بلا علامة تجارية. لا يقبل رابط الدعم إلا البروتوكولات التي ينبغي للمتصفح فتحها، مثل `https://…` أو `tg://…` أو `mailto:…`. +- **التحديثات** تتحقق من قناة الإصدارات المستقرة العامة ولا تغيّر شيئًا ما لم يوجد إصدار مستقر أحدث. إذا تعذّر الوصول إلى مصدر الإصدارات، يُبلغ `update` بأنه لم يتمكن من التحقق؛ ولا يُعامَل تثبيتك أبدًا على أنه تالف. +- **التراجع** يستعيد إصدارًا سابقًا من نسخة احتياطية جرى التحقق منها. تُلتقط لقطة (snapshot) للإصدار الحالي أولًا، بحيث يمكن التعافي من تراجع فاشل، وتُحفَظ علامتك التجارية. +- **إلغاء التثبيت** يزيل ملفات Row-Template. ولا يمسح `subThemeDir` في اللوحة إلا إذا كان يشير إلى Row-Template، فتعود اللوحة إلى صفحتها المدمجة؛ ولا يمسّ الواردات (inbounds) أو العملاء أو الشهادات. -```bash -row-template verify -``` +يغطي [التوثيق](https://iitzseridev.github.io/Row-Template/ar/) الإعداد والعلامة التجارية واستكشاف الأخطاء بمزيد من التفصيل. -يبلّغ عمّا إذا كان المُنتَج المثبَّت وربط اللوحة والخدمة في حالة سليمة. +## التطوير -## إلغاء التثبيت +تُبنى الصفحات من مصادر مقروءة في `src/`. تحتاج إلى Node.js 22 أو أحدث، وإلى Go 1.22 أو أحدث لتشغيل الاختبارات. ```bash -row-template uninstall +npm run build # regenerate template/index.html from src/ +npm run verify # check the built page against the safety gates +npm test # render the fixture pages, then run every test suite +npm run fixtures:all # render every design's fixture pages on their own +npm run lint:sh # ShellCheck every shell script +npm run preview # preview the fixture pages at http://127.0.0.1:8787 ``` -يزيل Row-Template وملفاته. وهو **لا** يمسّ 3X-UI أو قاعدة بياناتها أو الـ inbounds أو العملاء أو الشهادات لديك. +عملية البناء حتمية (deterministic) — المصادر نفسها تُنتج دائمًا ملف `template/index.html` مطابقًا بايتًا ببايت. موقع التوثيق مساحة عمل منفصلة في `docs/`؛ راجع [docs/README.md](docs/README.md). + +## الاختبار -## اللغات +- **`npm test`** يولّد أولًا صفحات الـ fixtures لكل التصاميم باستخدام العارض المكتوب بـ Go، ثم يشغّل مجموعات الاختبارات: سكربتات الصفحة، والبناء، والملف النهائي لكل تصميم، وحمولة الإصدار، والمثبّت — الذي تُشغَّل مكتبته الـ shell المنشورة في `bash` حقيقي على fixtures مؤقتة. +- **`npm run verify`** يفحص صفحة مبنية وفق بوابات الأمان الخاصة بها، ومنها: مستند كامل، واستبدال كل علامات البناء، وتضمين كل شيء، وعدم وجود مراجع بعيدة، وعدم وجود بُنى محظورة، وسلامة الترجمات، وخلوّ المصادر من المحارف غير المرئية. +- **`npm run lint:sh`** يفشل عند أي خطأ من ShellCheck؛ ويعرض `npm run lint:sh -- -S warning` التقرير الكامل. +- **سير عمل Docs** يبني موقع التوثيق في كل طلب دمج (pull request) يغيّره. -تأتي صفحة الاشتراك بخمس لغات للواجهة وتتبع لغة لوحة/متصفح المشترك: +## خارطة الطريق -**English · فارسی · العربية · Русский · 简体中文** +توجّه، لا وعود: -تُعرَض العربية والفارسية من اليمين إلى اليسار. +- **Row-Template 1.2.0** — التصاميم الخمسة عشر وأداة اختيار التصميم الموصوفة أعلاه. +- **PasarGuard وRebecca** — قيد البحث. هيكل الصفحة مبنيّ لكليهما؛ وتحتاج الحالة الحيّة إلى تغيير صغير في الشيفرة أو إلى وكيل عكسي (reverse proxy)، وقد أُرجئ هذا القرار. راجع [التوافق](https://iitzseridev.github.io/Row-Template/ar/compatibility/). +- **التثبيت على أكثر من لوحة** — البنية التحتية للمثبّت (واجهة للوحات، ومحرّك معاملات، ومحوّل لـ 3X-UI، وصيغة نسخ احتياطي جديدة) موجودة، لكن لا يستخدمها أي أمر بعد. +- **القوالب المخصّصة** — مقترح لإضافة تصميمك الخاص: [`docs/design/CUSTOM-TEMPLATES-PROPOSAL.md`](docs/design/CUSTOM-TEMPLATES-PROPOSAL.md). -## الإبلاغ عن الأخطاء +## المساهمة -يُرجى فتح تذكرة (issue): +نرحّب كثيرًا بتقارير الأخطاء والترجمات وتصحيحات التوثيق. اقرأ [CONTRIBUTING.md](CONTRIBUTING.md) قبل فتح طلب دمج، والتزم بـ[مدونة السلوك](CODE_OF_CONDUCT.md). -أدرِج إصدار Row-Template لديك (`row-template version`)، وإصدار 3X-UI، ونظام التشغيل وإصداره، ومعمارية المعالج، ومخرجات `row-template verify`، وخطوات واضحة لإعادة إنتاج المشكلة. +**الإبلاغ عن الأخطاء:** افتح تذكرة (issue) على . أدرِج إصدار Row-Template لديك (`row-template version`)، وإصدار 3X-UI، ونظام التشغيل وإصداره، ومعمارية المعالج، ومخرجات `row-template verify`، وخطوات واضحة لإعادة إنتاج المشكلة. > **لا تُدرِج أي أسرار.** لا تلصق إطلاقًا روابط الاشتراك، أو قيم `subId`، أو معرّفات UUID الخاصة بالعملاء، أو أسماء مستخدمي اللوحة أو كلمات مرورها، أو ملفات تعريف الارتباط (cookies)، أو الرموز (tokens)، أو `webBasePath` الخاص باللوحة، أو مفاتيح TLS، أو عناوين الخوادم الحقيقية. ونقِّح السجلات قبل مشاركتها. ## الأمان -هل اكتشفت ثغرة؟ يُرجى الإبلاغ عنها بشكل خاص — راجع [SECURITY.md](SECURITY.md). لا تفتح تذكرة عامة للمشكلات الأمنية. - -## التطوير - -يُبنى المُنتَج ذو الملف الواحد من مصادر قابلة للقراءة في `src/`: - -```bash -npm run build # regenerate template/index.html from src/ -npm run verify # check the artifact against the safety gates -npm test # run the unit and installer test suites -``` - -البناء حتمي — تنتج المصادر نفسها دائمًا ملف `template/index.html` مطابقًا بايتًا ببايت. راجع [CONTRIBUTING.md](CONTRIBUTING.md). +هل اكتشفت ثغرة؟ يُرجى الإبلاغ عنها بشكل خاص — راجع [SECURITY.md](SECURITY.md). لا تفتح تذكرة عامة للمشكلات الأمنية. ويشرح [PROVENANCE.md](PROVENANCE.md) كيف تُبنى الإصدارات وكيف يمكن التحقق منها. ## ادعم المشروع @@ -233,7 +281,7 @@ Row-Template مجاني ومفتوح المصدر. إن وفّر عليك وقت ## الترخيص -مُرخَّص بموجب [رخصة MIT](LICENSE). ومولّد رمز QR المرفق (`src/vendor/uqr`) مُضمَّن بموجب رخصة MIT الخاصة به. +مُرخَّص بموجب [رخصة MIT](LICENSE). ومولّد رمز QR المرفق (`src/vendor/uqr`) مُضمَّن بموجب رخصة MIT الخاصة به، والجزء المضمَّن من خط Vazirmatn بموجب رخصة SIL Open Font License (`src/fonts/OFL.txt`). ## المطوّر diff --git a/README.fa.md b/README.fa.md index ced5634..3728d92 100644 --- a/README.fa.md +++ b/README.fa.md @@ -7,7 +7,7 @@

- یک صفحهٔ اشتراک سفارشی، شکیل و خودبسنده برای پنل های 3X-UI — یک فایل HTML، کاملاً وایت لیبل، بدون هیچ CDN شخص ثالثی و بدون هیچ درخواست بیرونی از صفحه ای که مشترکان شما باز می کنند. + یک صفحهٔ اشتراک شکیل و خودبسنده برای پنل های 3X-UI — پانزده طرح که هر کدام یک فایل HTML است، کاملاً وایت لیبل، و بدون هیچ درخواستی به شخص ثالث از صفحه ای که مشترکان شما باز می کنند.

@@ -19,121 +19,161 @@ Latest release Panel Platform + Documentation +

+ +

+ نصب · + طرح ها · + مستندات · + تغییرات · + نسخه ها

--- +## Row-Template چیست؟ + +3X-UI می تواند به جای صفحهٔ داخلی خود، یک صفحهٔ سفارشی به مشترکان نشان دهد. Row-Template همان صفحه است: مشترک پیوند اشتراک خود را باز می کند و پلن، میزان مصرف و تاریخ انقضای خود را می بیند، به همراه راه هایی برای افزودن اشتراک با یک لمس به برنامه ای که استفاده می کند. + +برای هر طرح یک فایل HTML خودبسنده عرضه می شود که همهٔ استایل ها، اسکریپت ها، فونت ها و مولد کد QR درون آن گنجانده شده اند. یک دستور آن را کنار پنل شما نصب می کند، پنل را به آن اشاره می دهد و ابزار مدیریتی `row-template` را برای برندسازی، به روزرسانی و بازگردانی در اختیار شما می گذارد. + ## چرا Row-Template؟ -- **محرمانه از پایه.** صفحه ای که مشترکان شما باز می کنند هیچ درخواستی به شخص ثالث نمی فرستد. کدهای QR به صورت محلی تولید می شوند و اطلاعات برندسازی شما به صورت متن تزریق می شود — هرگز اجرا نمی شود و هرگز به هیچ جایی فرستاده نمی شود. +- **محرمانه از پایه.** صفحه ای که مشترکان شما باز می کنند هیچ درخواستی به شخص ثالث نمی فرستد. کدهای QR روی خود صفحه تولید می شوند و اطلاعات برندسازی شما به صورت متن تزریق می شود — هرگز اجرا نمی شود و هرگز به هیچ جایی فرستاده نمی شود. - **واقعاً وایت لیبل.** نام سرویس، پیوند پشتیبانی و لوگوی خودتان. هیچ چیزی روی صفحهٔ ارائه شده معرف Row-Template نیست. -- **یک فایل، بدون وابستگی زمان اجرا.** CSS، JavaScript، فونت ها و مولد کد QR درون یک فایل HTML یکپارچه گنجانده شده اند که تنها با ابزارهای استاندارد فضای کاربری لینوکس نصب می شود — بدون نیاز به Node.js، Python یا پایگاه داده. +- **پانزده طرح، هر کدام یک فایل.** ظاهری را انتخاب کنید که به سرویس شما می آید. همهٔ طرح ها ویژگی ها، زبان ها و بررسی های ایمنی یکسانی دارند. - **ساخته شده برای مشترکان شما.** نمای زندهٔ مصرف و انقضا، ورود (import) با یک لمس به برنامه های پرکاربرد، و فهرستی قابل جستجو از پیکربندی های جداگانه برای افزودن دستی یک سرور. -- **ایمن برای بهره برداری.** نصب اتمی همراه با اعتبارسنجی و بازگردانی تک دستوری. هرگز 3X-UI را وصله نمی کند و هرگز به فایل های پنل شما دست نمی زند. +- **ایمن برای بهره برداری.** نسخه هایی که مجموع کنترلی آن ها بررسی می شود، فعال سازی اتمی و بازگردانی تک دستوری. هرگز 3X-UI را وصله نمی کند: تنها تنظیمی از پنل که تغییر می دهد، دایرکتوری صفحهٔ اشتراک (`subThemeDir`) است. -## تصاویر +## طرح ها + +Row-Template 1.2.0 با پانزده طرح عرضه می شود. طرح پیش فرض Row است. - - + + + + + - - + + + + + + + + + + + +
Row-TemplateRow-TemplateRow
Row		Editorial
Editorial		Canvas
Canvas		Prism
Prism		Terminal
Terminal
پوستهٔ تیرهپوستهٔ روشنPulse
Pulse		Brutal
Brutal		Arcade
Arcade		Sketch
Sketch		Signature
Signature
Saffron
Saffron		Pulse Nova
Pulse Nova		Prism Nova
Prism Nova		Terminal Nova
Terminal Nova		Arcade Nova
Arcade Nova
-تصاویر از داده های نمونه استفاده می کنند؛ فهرست پیکربندی ها و نشان های کشور نمایش داده شده صرفاً نمونه هستند. +پیش نمایش ها با داده های نمونهٔ خود پروژه ساخته شده اند. پیش نمایش دسکتاپ و موبایل همهٔ طرح ها در گالری طرح ها موجود است. -## نصب سریع +طرح را هنگام یک نصب تعاملی تازه انتخاب کنید، برای نصب اسکریپتی `RT_TEMPLATE` را تنظیم کنید، یا بعداً آن را از مدیر تغییر دهید (**Reconfigure branding → Template**). به روزرسانی ها انتخاب شما را حفظ می کنند. -> **سیستم عامل پیشنهادی: Ubuntu 24.04 LTS (x86_64).** دیگر توزیع های امروزی لینوکس نیز ممکن است کار کنند، اما پوشش اعتبارسنجی یکسانی نداشته اند. +## ویژگی ها -با کاربر **root** روی سروری که پنل 3X-UI شما را میزبانی می کند اجرا کنید: +**برای مشترکان شما** -```bash -bash <(curl -fsSL https://github.com/iitzSeriZdev/Row-Template/releases/latest/download/install.sh) -``` +- **وضعیت زنده.** وضعیت پلن، ترافیک مصرف شده و باقی مانده و تاریخ انقضا، که تا وقتی صفحه دیده می شود از پنل شما به روز می شود. +- **ورود با یک لمس** به برنامه های پرکاربرد، بر اساس پلتفرم: v2rayNG، Happ و sing-box در Android؛ Streisand، V2Box و Shadowrocket در iOS؛ Clash Verge Rev، Mihomo Party و v2rayN در Windows؛ Clash Verge Rev، Streisand و V2Box در macOS. +- **کپی و QR.** پیوند اشتراک را کپی کنید یا آن را به صورت کد QR که روی خود صفحه ساخته می شود اسکن کنید. +- **کاوشگر پیکربندی ها.** هر سرور در یک ردیف جداگانه، با پرچم کشور یا نشان حروف (monogram) و برچسب پروتکل (VLESS، VMess، Trojan، Shadowsocks، Hysteria/Hysteria2، WireGuard، AmneziaWG، Telegram MTProto)، به همراه QR و کپی برای هر پیکربندی و جستجو برای فهرست های طولانی. +- **پنج زبان** — انگلیسی، فارسی، عربی، روسی و چینی — با چیدمان راست به چپ، و انتخاب پوستهٔ System / Light / Dark. -نصب کننده آخرین نسخهٔ پایدار را دانلود می کند، مجموع کنترلی SHA-256 آن را بررسی می کند (امکان رد کردن این مرحله وجود ندارد)، آن را به شکل ایمن استخراج می کند و شما را گام به گام در برندسازی همراهی می کند. این ابزار هرگز 3X-UI را وصله (patch) نمی کند و هرگز به فایل های خودِ پنل شما دست نمی زند. +**برای شما** + +- **برندسازی وایت لیبل.** نام سرویس، پیوند پشتیبانی و لوگو، همگی اختیاری، که به عنوان داده ذخیره و به صورت متن تزریق می شوند. +- **یک مدیر برای همه چیز.** منوی تعاملی و دستورهای مستقیم برای برندسازی، به روزرسانی، بررسی سلامت، بازگردانی و حذف نصب. +- **به روزرسانی از کانال پایدار.** `row-template update` تنها زمانی نسخهٔ پایدار جدیدتری را نصب می کند که وجود داشته باشد. + +**حریم خصوصی و ایمنی** + +- **بدون درخواست به شخص ثالث** از صفحهٔ ارائه شده: بدون CDN، بدون جستجوی بیرونی QR یا موقعیت جغرافیایی، بدون تله متری. وضعیت زنده از پنل خود شما می آید. +- **SHA-256 الزامی** برای هر دانلود نسخه، بدون هیچ گزینه ای برای رد کردن آن. +- **فعال سازی اتمی.** صفحهٔ جدید پیش از جایگزینی صفحهٔ فعال ساخته و اعتبارسنجی می شود، بنابراین یک گام ناموفق هرگز صفحه ای خراب را فعال باقی نمی گذارد. +- **شناسایی محتاطانهٔ پنل.** اگر پایگاه دادهٔ پنلی که Row-Template پیدا می کند یک پایگاه دادهٔ SQLite معتبر نباشد، به جای حدس زدن پایگاه دادهٔ دیگری، از به کار بردن آن خودداری می کند. ## پنل های پشتیبانی شده | پنل | وضعیت | یادداشت ها | | ----- | ------ | ----- | | [3X-UI](https://github.com/MHSanaei/3x-ui) (MHSanaei) | ✅ پشتیبانی شده | نیازمند نسخهٔ **>= 3.6.0** | -| [Marzban](https://github.com/Gozargah/Marzban) | ⬜ برنامه ریزی شده | هنوز پشتیبانی نمی شود | -| [Marzneshin](https://github.com/marzneshin/marzneshin) | ⬜ برنامه ریزی شده | هنوز پشتیبانی نمی شود | -| [Rebecca](https://github.com/rebeccapanel/Rebecca) | ⬜ برنامه ریزی شده | هنوز پشتیبانی نمی شود | -| [PasarGuard](https://github.com/PasarGuard/panel) | ⬜ برنامه ریزی شده | هنوز پشتیبانی نمی شود | - -امروز تنها 3X-UI پشتیبانی می شود. پنل های دیگر در نقشهٔ راه قرار دارند و برای شفافیت اینجا فهرست شده اند — در این نسخه هیچ گونه پشتیبانی جزئی یا آزمایشی برای آن ها وجود ندارد. - -## ویژگی ها - -- **یک صفحهٔ خودبسنده.** تمام CSS، JavaScript، فونت ها و مولد کد QR درون یک فایل HTML یکپارچه گنجانده شده اند. صفحه ای که مشترکان شما باز می کنند هیچ درخواستی به شخص ثالث نمی فرستد. -- **وایت لیبل.** نام سرویس، پیوند پشتیبانی و لوگوی خودتان را تنظیم کنید. هیچ چیزی روی صفحهٔ ارائه شده معرف Row-Template نیست. -- **پنج زبان.** انگلیسی، فارسی، عربی، روسی و چینی، به همراه پشتیبانی از چیدمان راست به چپ. -- **ایمن از پایه.** اطلاعات برندسازی شما به عنوان داده در نظر گرفته و به صورت متن تزریق می شود و هرگز اجرا نمی شود. صفحه هرگز داده های مشترک را به هیچ جایی نمی فرستد. -- **نمای مصرف زنده.** وضعیت پلن، ترافیک مصرف شده و باقی مانده، تاریخ انقضا و پیوندهای هر کلاینت را به همراه دکمه های کپی و کدهای QR نمایش می دهد. -- **نصب و بازگردانی اتمی.** هر تغییر ابتدا آماده سازی، سپس اعتبارسنجی و آنگاه جایگزین می شود. یک گام ناموفق هرگز صفحه ای خراب را روی سرویس باقی نمی گذارد و می توانید به نسخهٔ پیشین بازگردید. -- **بدون وابستگی زمان اجرا.** تنها ابزارهای استاندارد فضای کاربری لینوکس (bash، coreutils، curl، tar، sha256sum). برای نصب یا اجرای آن به Node.js، Python یا هیچ پایگاه داده ای نیاز نیست. - -## پیش نیازها - -- سروری که یک پنل 3X-UI را اجرا می کند (نسخهٔ **>= 3.6.0**). -- دسترسی root به آن سرور. -- `curl`، `tar` و `sha256sum` (که تقریباً روی همهٔ سیستم های لینوکس موجود است). +| [PasarGuard](https://github.com/PasarGuard/panel) | 🔬 در حال پژوهش | پشتیبانی نمی شود؛ مسیر نصبی ندارد | +| [Rebecca](https://github.com/rebeccapanel/Rebecca) | 🔬 در حال پژوهش | پشتیبانی نمی شود؛ مسیر نصبی ندارد | + +تنها پنل پشتیبانی شده 3X-UI است. PasarGuard و Rebecca از موتورهای قالب متفاوتی (Jinja2 و pongo2) استفاده می کنند؛ پوستهٔ صفحهٔ هر طرح برای آن ها ساخته و برای بررسی در نسخه بسته بندی می شود، اما نصب کننده آن را جایگذاری نمی کند و هیچ دستورالعمل نصبی برای آن ها وجود ندارد. برای یافته های پژوهشی، [سازگاری](https://iitzseridev.github.io/Row-Template/fa/compatibility/) را ببینید. + +## معماری + +```mermaid +flowchart TB + subgraph build ["Build and release"] + direction LR + SRC["src/
runtime, styles, locales,
15 design layouts"] --> BUILD["tools/build.mjs"] + BUILD --> ART["One self-contained
HTML file per design"] + ART --> REL["tools/make-release.sh
tarball + SHA256SUMS"] + end + subgraph host ["Your 3X-UI server"] + direction LR + INST["install.sh / row-template
verify checksum, stage, validate,
back up, activate"] --> DIR["/etc/3x-ui/
sub_templates/row-template"] + DIR -- "subThemeDir" --> XUI["3X-UI renders the page
with the subscriber's data"] + end + build -- "GitHub Releases" --> host + host -- "serves the page" --> BROWSER["Subscriber's browser"] + BROWSER -. "live status: ?format=info" .-> host +``` -## سازگاری +- **یک فایل برای هر طرح.** `tools/build.mjs` کد اجرایی مشترک، ترجمه ها، فونت ها و مولد QR را درون چیدمان هر طرح می گنجاند و چیدمانی را که هر یک از قلاب های (hook) مورد نیاز کد اجرایی را نداشته باشد رد می کند. سپس `tools/verify.mjs` هر فایلی را که چیزی را از راه دور بارگذاری کند یا ساختاری ممنوع داشته باشد رد می کند. +- **رندر را پنل انجام می دهد.** صفحه یک قالب است: 3X-UI هنگام ارائهٔ آن داده های مشترک را در آن قرار می دهد و سپس صفحه وضعیت خود را از همان پنل به روز می کند. +- **نصب کننده هرگز 3X-UI را ویرایش نمی کند.** دایرکتوری خودش را می نویسد و تنها یک تنظیم پنل، `subThemeDir`، را تغییر می دهد تا به آن اشاره کند. -- **پنل:** 3X-UI (MHSanaei) **>= 3.6.0**. با نسخهٔ اصلی (stock) 3.7.0 اعتبارسنجی شده است. -- **سیستم عامل:** پیشنهادی Ubuntu 24.04 LTS. روی Ubuntu 24.04 LTS (x86_64) اعتبارسنجی شده است. توزیع های دیگر ممکن است کار کنند اما پوشش اعتبارسنجی یکسانی دریافت نکرده اند. +| مسیر | محتوا | +| ---- | ---------------- | +| `src/` | کد اجرایی، استایل ها و ترجمه های صفحه؛ هر طرح در `src/templates//` | +| `template/index.html` | صفحهٔ ساخته شدهٔ Row، که commit شده است | +| `tools/` | ساخت، اعتبارسنجی، انتشار و رندرکنندهٔ Go برای fixtureها | +| `installer/` | `install.sh`، دستور `row-template` و کتابخانهٔ مدیریتی آن | +| `tests/` | مجموعه های آزمون | +| `docs/` | سایت مستندات؛ سوابق طراحی در [`docs/design/`](docs/design/README.md) | ## نصب -دستور نصبی را که در بالا نشان داده شد با کاربر root اجرا کنید. نصب کننده: - -1. آخرین نسخهٔ پایدار را از GitHub دانلود می کند. -2. مجموع کنترلی نسخه را بررسی می کند (SHA-256، الزامی — بدون امکان دور زدن). -3. آن را به شکل ایمن استخراج می کند و در `/etc/3x-ui/sub_templates/row-template` نصب می کند. -4. برای برندسازی شما درخواست ورودی می دهد (نام سرویس، پیوند پشتیبانی، لوگو — همگی اختیاری). -5. صفحهٔ ارائه شده را تولید می کند و در صورت امکان، آن را در پنل فعال می کند. - -اگر ترجیح می دهید از طریق شبکه به صورت pipe عمل نکنید، می توانید فایل های نسخه را از [صفحهٔ Releases](https://github.com/iitzSeriZdev/Row-Template/releases/latest) دانلود کنید، مجموع کنترلی را خودتان بررسی کنید و `install.sh` همراه بسته را از دایرکتوری استخراج شده اجرا کنید. +> **سیستم عامل پیشنهادی: Ubuntu 24.04 LTS (x86_64).** دیگر توزیع های امروزی لینوکس نیز ممکن است کار کنند، اما پوشش اعتبارسنجی یکسانی نداشته اند. -## مدیریت +**پیش نیازها:** سروری با 3X-UI **>= 3.6.0**، دسترسی root به آن، و `curl`، `tar` و `sha256sum` (که تقریباً روی همهٔ سیستم های لینوکس موجود است). فعال سازی خودکار به `sqlite3` هم نیاز دارد. -پس از نصب، همه چیز را با دستور `row-template` مدیریت کنید. آن را بدون هیچ آرگومانی در ترمینال اجرا کنید تا مدیر تعاملی باز شود: +با کاربر **root** روی سروری که پنل 3X-UI شما را میزبانی می کند اجرا کنید: ```bash -row-template +bash <(curl -fsSL https://github.com/iitzSeriZdev/Row-Template/releases/latest/download/install.sh) ``` -یا از دستورهای مستقیم استفاده کنید: - -| دستور | کارکرد | -| ------- | ------------ | -| `row-template config` | پیکربندی مجدد برندسازی (نام سرویس، پیوند پشتیبانی، لوگو) | -| `row-template update` | بررسی کانال پایدار و به روزرسانی در صورت وجود نسخهٔ جدیدتر | -| `row-template rollback` | بازگردانی به نسخهٔ پیشین (`--auto` یا `--to `) | -| `row-template verify` | بررسی سلامت نصب | -| `row-template version` | چاپ نسخهٔ نصب شده | -| `row-template uninstall` | حذف Row-Template (بدون دست زدن به 3X-UI) | -| `row-template help` | نمایش راهنمای استفاده | +نصب کننده: -## برندسازی و پیکربندی +1. آخرین نسخهٔ پایدار را از GitHub دانلود می کند. +2. مجموع کنترلی SHA-256 آن را بررسی می کند (الزامی — بدون امکان دور زدن). +3. آن را به شکل ایمن استخراج می کند و در `/etc/3x-ui/sub_templates/row-template` نصب می کند. +4. در نصب تازه، انتخابگر طرح را نشان می دهد (Enter طرح Row را نگه می دارد). +5. برای برندسازی شما درخواست ورودی می دهد (نام سرویس، پیوند پشتیبانی، لوگو — همگی اختیاری). +6. صفحه را تولید و اعتبارسنجی می کند و سپس در صورت امکان آن را در پنل فعال می کند. -نام سرویس، پیوند پشتیبانی و لوگوی خود را هنگام نصب تنظیم کنید، یا هر زمان که خواستید آن ها را تغییر دهید: +برای انتخاب طرح بدون انتخابگر، برای نمونه در یک اسکریپت: ```bash -row-template config +RT_TEMPLATE=editorial bash <(curl -fsSL https://github.com/iitzSeriZdev/Row-Template/releases/latest/download/install.sh) ``` -ورودی های شما به عنوان داده ذخیره می شوند (هرگز اجرا نمی شوند) و به صورت متن در صفحه تزریق می گردند. برای داشتن یک صفحهٔ بدون برند و وایت لیبل، یک فیلد را خالی بگذارید. پیوند پشتیبانی تنها طرح واره هایی (schemes) را می پذیرد که یک مرورگر باید باز کند (برای مثال `https://…`، `tg://…` یا `mailto:…`). +اگر ترجیح می دهید از طریق شبکه به صورت pipe عمل نکنید، فایل های نسخه را از [صفحهٔ Releases](https://github.com/iitzSeriZdev/Row-Template/releases/latest) دانلود کنید، مجموع کنترلی را خودتان همان گونه که در [PROVENANCE.md](PROVENANCE.md) توضیح داده شده بررسی کنید و `install.sh` همراه بسته را از دایرکتوری استخراج شده اجرا کنید. -## فعال سازی +### فعال سازی Row-Template در دایرکتوری ای نصب می شود که پنل آن را به عنوان صفحهٔ اشتراک ارائه می دهد: @@ -141,76 +181,84 @@ Row-Template در دایرکتوری ای نصب می شود که پنل آن ر /etc/3x-ui/sub_templates/row-template ``` -- **خودکار:** هنگامی که `sqlite3` در دسترس باشد، نصب کننده/مدیر می تواند پنل را به جای شما به Row-Template اشاره دهد. -- **دستی:** در غیر این صورت، خودتان آن را در پنل تنظیم کنید — **Panel Settings → Subscription → Profile → Sub Theme Directory** را باز کنید و دقیقاً این را وارد کنید: +- **خودکار:** هنگامی که `sqlite3` در دسترس باشد، Row-Template آن را برای شما تنظیم می کند. سرویس پنل را برای مدت کوتاهی متوقف می کند، تنظیم را می نویسد، سرویس را دوباره راه اندازی می کند و مقدار را بررسی می کند. نصب تعاملی ابتدا تنظیم فعلی را نشان می دهد و پیش از تغییر از شما می پرسد. +- **دستی:** در غیر این صورت، **Panel Settings → Subscription → Profile → Sub Theme Directory** را باز کنید و دقیقاً این را وارد کنید: ``` /etc/3x-ui/sub_templates/row-template ``` -## به روزرسانی +## استفاده + +مدیر را بدون هیچ آرگومانی در ترمینال اجرا کنید تا منوی تعاملی باز شود: ```bash -row-template update +row-template ``` -این دستور کانال عمومی نسخه های پایدار را بررسی می کند، نسخهٔ نصب شده و نسخهٔ در دسترس را نشان می دهد و تنها زمانی به روزرسانی می کند که نسخهٔ پایدار جدیدتری وجود داشته باشد. اگر شبکه یا منبع نسخه در دسترس نباشد، گزارش می دهد که نتوانسته بررسی کند — نصب شما هرگز آسیب دیده تلقی نمی شود. استفادهٔ عادی به هیچ URL یا دانلود دستی نیازی ندارد. +یا یک دستور را مستقیماً اجرا کنید: -## بازگردانی - -```bash -row-template rollback -``` +| دستور | کارکرد | +| ------- | ------------ | +| `row-template config` | تغییر نام سرویس، پیوند پشتیبانی یا لوگو و سپس بازسازی صفحه | +| `row-template update` | دانلود، بررسی و فعال سازی یک نسخهٔ پایدار جدیدتر (بررسی مجموع کنترلی الزامی) | +| `row-template rollback` | بازگردانی یک نسخهٔ پیشین (`--auto` یا `--to `) | +| `row-template verify` | بررسی نصب، اتصال به پنل و صفحهٔ فعال (فقط خواندنی) | +| `row-template version` | نمایش نسخهٔ نصب شده، حداقل نسخهٔ پشتیبانی شده و نسخهٔ شناسایی شدهٔ 3X-UI | +| `row-template uninstall` | حذف Row-Template و بازگرداندن پنل به صفحهٔ داخلی خودش | +| `row-template help` | نمایش راهنمای استفاده | -نسخهٔ پیشین را از یک پشتیبان اعتبارسنجی شده بازیابی می کند. ابتدا از نسخهٔ فعلی یک عکس فوری (snapshot) گرفته می شود، بنابراین یک بازگردانی ناموفق قابل بازیابی است. پیکربندی برندسازی شما حفظ می شود. +دستورهایی که سیستم را تغییر می دهند (`config`، `update`، `rollback`، `uninstall`) باید با root اجرا شوند. -## بررسی سلامت +- **برندسازی** به عنوان داده ذخیره می شود، هرگز اجرا نمی شود و به صورت متن در صفحه تزریق می گردد. برای یک صفحهٔ بدون برند، فیلدی را خالی بگذارید. پیوند پشتیبانی تنها پروتکل هایی را می پذیرد که مرورگر باید باز کند، مانند `https://…`، `tg://…` یا `mailto:…`. +- **به روزرسانی ها** کانال عمومی نسخه های پایدار را بررسی می کنند و تا وقتی نسخهٔ پایدار جدیدتری وجود نداشته باشد چیزی را تغییر نمی دهند. اگر منبع انتشار در دسترس نباشد، `update` گزارش می دهد که نتوانسته بررسی کند؛ نصب شما هرگز آسیب دیده تلقی نمی شود. +- **بازگردانی** یک نسخهٔ پیشین را از یک پشتیبان اعتبارسنجی شده بازیابی می کند. ابتدا از نسخهٔ فعلی یک عکس فوری (snapshot) گرفته می شود تا یک بازگردانی ناموفق قابل جبران باشد، و برندسازی شما حفظ می شود. +- **حذف نصب** فایل های Row-Template را حذف می کند. `subThemeDir` پنل را تنها در صورتی پاک می کند که به Row-Template اشاره کند، تا پنل به صفحهٔ داخلی خود بازگردد؛ به inboundها، کلاینت ها و گواهی های شما دست زده نمی شود. -```bash -row-template verify -``` +[مستندات](https://iitzseridev.github.io/Row-Template/fa/) پیکربندی، برندسازی و رفع اشکال را با جزئیات بیشتری پوشش می دهد. -گزارش می دهد که آیا فایل نصب شده، اتصال به پنل و سرویس سالم هستند یا خیر. +## توسعه -## حذف نصب +صفحه ها از منابع خوانای موجود در `src/` ساخته می شوند. به Node.js نسخهٔ 22 یا بالاتر، و برای اجرای آزمون ها به Go نسخهٔ 1.22 یا بالاتر نیاز دارید. ```bash -row-template uninstall +npm run build # regenerate template/index.html from src/ +npm run verify # check the built page against the safety gates +npm test # render the fixture pages, then run every test suite +npm run fixtures:all # render every design's fixture pages on their own +npm run lint:sh # ShellCheck every shell script +npm run preview # preview the fixture pages at http://127.0.0.1:8787 ``` -Row-Template و فایل های آن را حذف می کند. این کار **به هیچ وجه** به 3X-UI، پایگاه دادهٔ آن، inboundها، کلاینت ها یا گواهی های شما دست نمی زند. +فرآیند ساخت قطعی (deterministic) است — منابع یکسان همیشه یک `template/index.html` با بایت های یکسان تولید می کنند. سایت مستندات یک فضای کاری جداگانه در `docs/` است؛ [docs/README.md](docs/README.md) را ببینید. + +## آزمون -## زبان ها +- **`npm test`** ابتدا صفحه های fixture همهٔ طرح ها را با رندرکنندهٔ Go می سازد و سپس مجموعه های آزمون را اجرا می کند: اسکریپت های صفحه، فرآیند ساخت، فایل نهایی هر طرح، محتوای بستهٔ انتشار و نصب کننده — که کتابخانهٔ shell منتشرشده را در یک `bash` واقعی روی fixtureهای موقت اجرا می کند. +- **`npm run verify`** یک صفحهٔ ساخته شده را با دروازه های ایمنی آن می سنجد، از جمله: سند کامل، جایگزینی همهٔ نشانگرهای ساخت، گنجاندن همه چیز در فایل، نبود ارجاع راه دور، نبود ساختارهای ممنوع، سالم بودن ترجمه ها و نبود نویسه های نامرئی در منابع. +- **`npm run lint:sh`** با هر خطای ShellCheck شکست می خورد؛ `npm run lint:sh -- -S warning` گزارش کامل را نشان می دهد. +- **گردش کار Docs** سایت مستندات را در هر pull request که آن را تغییر دهد می سازد. -صفحهٔ اشتراک با پنج زبان رابط کاربری عرضه می شود و از زبان پنل/مرورگر مشترک پیروی می کند: +## نقشهٔ راه -**English · فارسی · العربية · Русский · 简体中文** +جهت گیری، نه وعده: -عربی و فارسی به صورت راست به چپ نمایش داده می شوند. +- **Row-Template 1.2.0** — پانزده طرح و انتخابگر طرح که در بالا توضیح داده شد. +- **PasarGuard و Rebecca** — در حال پژوهش. پوستهٔ صفحه برای هر دو ساخته شده است؛ وضعیت زنده به یک تغییر کوچک در کد اجرایی یا یک reverse proxy نیاز دارد و این تصمیم به تعویق افتاده است. [سازگاری](https://iitzseridev.github.io/Row-Template/fa/compatibility/) را ببینید. +- **نصب روی بیش از یک پنل** — زیرساخت نصب کننده (یک رابط پنل، یک موتور تراکنش، یک آداپتور 3X-UI و یک قالب پشتیبان گیری جدید) آماده است، اما هنوز هیچ دستوری از آن استفاده نمی کند. +- **قالب های سفارشی** — پیشنهادی برای افزودن طرح خودتان: [`docs/design/CUSTOM-TEMPLATES-PROPOSAL.md`](docs/design/CUSTOM-TEMPLATES-PROPOSAL.md). -## گزارش اشکال +## مشارکت -لطفاً یک issue باز کنید: +گزارش اشکال، ترجمه و اصلاح مستندات بسیار استقبال می شود. پیش از باز کردن pull request، [CONTRIBUTING.md](CONTRIBUTING.md) را بخوانید و از [آیین نامهٔ رفتاری](CODE_OF_CONDUCT.md) پیروی کنید. -نسخهٔ Row-Template خود (`row-template version`)، نسخهٔ 3X-UI، سیستم عامل و نسخهٔ آن، معماری پردازنده، خروجی `row-template verify` و گام های روشن برای بازتولید مشکل را ذکر کنید. +**گزارش اشکال:** یک issue در باز کنید. نسخهٔ Row-Template خود (`row-template version`)، نسخهٔ 3X-UI، سیستم عامل و نسخهٔ آن، معماری پردازنده، خروجی `row-template verify` و گام های روشن برای بازتولید مشکل را ذکر کنید. > **هیچ گونه اطلاعات محرمانه درج نکنید.** هرگز URLهای اشتراک، مقادیر `subId`، UUIDهای کلاینت، نام کاربری یا گذرواژهٔ پنل، کوکی ها، توکن ها، `webBasePath` پنل، کلیدهای TLS یا نشانی های واقعی سرور را وارد نکنید. پیش از اشتراک گذاری لاگ ها، آن ها را ویرایش و پاک سازی کنید. ## امنیت -آیا آسیب پذیری یافته اید؟ لطفاً آن را به صورت خصوصی گزارش دهید — [SECURITY.md](SECURITY.md) را ببینید. برای مشکلات امنیتی یک issue عمومی باز نکنید. - -## توسعه - -فایل یکپارچهٔ نهایی از منابع خوانای موجود در `src/` ساخته می شود: - -```bash -npm run build # regenerate template/index.html from src/ -npm run verify # check the artifact against the safety gates -npm test # run the unit and installer test suites -``` - -فرآیند ساخت قطعی (deterministic) است — منابع یکسان همیشه یک `template/index.html` با بایت های یکسان تولید می کنند. [CONTRIBUTING.md](CONTRIBUTING.md) را ببینید. +آیا آسیب پذیری یافته اید؟ لطفاً آن را به صورت خصوصی گزارش دهید — [SECURITY.md](SECURITY.md) را ببینید. برای مشکلات امنیتی یک issue عمومی باز نکنید. [PROVENANCE.md](PROVENANCE.md) توضیح می دهد که نسخه ها چگونه ساخته می شوند و چگونه می توان آن ها را بررسی کرد. ## حمایت از پروژه @@ -234,7 +282,7 @@ Row-Template رایگان و متن باز است. اگر در وقت شما ص ## مجوز -تحت [مجوز MIT](LICENSE) منتشر شده است. مولد کد QR همراه بسته (`src/vendor/uqr`) تحت مجوز MIT خودش گنجانده شده است. +تحت [مجوز MIT](LICENSE) منتشر شده است. مولد کد QR همراه بسته (`src/vendor/uqr`) تحت مجوز MIT خودش، و زیرمجموعهٔ فونت Vazirmatn که درون صفحه گنجانده شده تحت مجوز SIL Open Font License (`src/fonts/OFL.txt`) عرضه می شوند. ## توسعه دهنده diff --git a/README.md b/README.md index c03e7ff..a115b4a 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@

- A polished, self-contained custom subscription page for 3X-UI panels — one HTML file, fully white-label, with no third-party CDNs and no external requests from the page your subscribers open. + A polished, self-contained subscription page for 3X-UI panels — fifteen designs, each a single HTML file, fully white-label, with no third-party requests from the page your subscribers open.

@@ -19,198 +19,246 @@ Latest release Panel Platform + Documentation +

+ +

+ Install · + Designs · + Documentation · + Changelog · + Releases

--- +## What it is + +3X-UI can serve a custom page to subscribers instead of its built-in one. Row-Template is that page: a subscriber opens their subscription link and sees their plan, their usage, their expiry date, and one-tap ways to add the subscription to the app they use. + +It ships as one self-contained HTML file per design, with every style, script, font, and the QR code generator inlined. A single command installs it next to your panel, points the panel at it, and gives you a `row-template` manager for branding, updates, and rollback. + ## Why Row-Template? -- **Private by design.** The page your subscribers open makes no third-party requests. QR codes are generated locally, and your branding is injected as text — never executed, never sent anywhere. +- **Private by design.** The page your subscribers open makes no third-party requests. QR codes are generated on the page, and your branding is injected as text — never executed, never sent anywhere. - **Genuinely white-label.** Your service name, your support link, your logo. Nothing on the served page identifies Row-Template. -- **One file, no runtime dependencies.** CSS, JavaScript, fonts, and the QR generator are inlined into a single HTML file that installs with standard Linux userland — no Node.js, Python, or database. +- **Fifteen designs, one file each.** Pick the look that fits your service. Every design shares the same features, languages, and safety checks. - **Made for your subscribers.** Live usage and expiry, one-tap import into popular apps, and a searchable list of individual configurations for adding a single server by hand. -- **Safe to operate.** Atomic install with validation and one-command rollback. It never patches 3X-UI and never touches your panel's files. +- **Safe to operate.** Checksum-verified releases, atomic activation, and one-command rollback. It never patches 3X-UI: the only panel setting it changes is the subscription page directory (`subThemeDir`). + +## Designs -## Screenshots +Row-Template 1.2.0 ships fifteen designs. Row is the default. - - + + + + + - - + + + + + + + + + + + +
Row-Template — dark themeRow-Template — light themeRow
Row		Editorial
Editorial		Canvas
Canvas		Prism
Prism		Terminal
Terminal
Dark themeLight themePulse
Pulse		Brutal
Brutal		Arcade
Arcade		Sketch
Sketch		Signature
Signature
Saffron
Saffron		Pulse Nova
Pulse Nova		Prism Nova
Prism Nova		Terminal Nova
Terminal Nova		Arcade Nova
Arcade Nova
-Screens use placeholder data; the configuration list and country badges shown are examples. +Previews are rendered from the project's own placeholder data. Desktop and mobile previews of every design are in the template gallery. -## Quick install +Choose a design during a fresh interactive install, set `RT_TEMPLATE` for a scripted one, or change it later from the manager (**Reconfigure branding → Template**). Updates keep your choice. -> **Recommended OS: Ubuntu 24.04 LTS (x86_64).** Other modern Linux distributions may work but have not had the same validation coverage. +## Features -Run as **root** on the server that hosts your 3X-UI panel: +**For your subscribers** -```bash -bash <(curl -fsSL https://github.com/iitzSeriZdev/Row-Template/releases/latest/download/install.sh) -``` +- **Live status.** Plan state, traffic used and remaining, and expiry, refreshed from your panel while the page is visible. +- **One-tap import** into popular apps, grouped by platform: v2rayNG, Happ and sing-box on Android; Streisand, V2Box and Shadowrocket on iOS; Clash Verge Rev, Mihomo Party and v2rayN on Windows; Clash Verge Rev, Streisand and V2Box on macOS. +- **Copy and QR.** Copy the subscription link or scan it as a QR code generated on the page. +- **Configuration Explorer.** Every server on its own row, with a country flag or monogram and a protocol label (VLESS, VMess, Trojan, Shadowsocks, Hysteria/Hysteria2, WireGuard, AmneziaWG, Telegram MTProto), plus per-configuration QR and copy, and search for long lists. +- **Five languages** — English, Persian, Arabic, Russian, and Chinese — with right-to-left layout, and a System / Light / Dark theme choice. + +**For you** + +- **White-label branding.** Service name, support link, and logo, all optional, stored as data and injected as text. +- **A manager for everything.** An interactive menu and direct commands for branding, updates, verification, rollback, and uninstall. +- **Stable-channel updates.** `row-template update` installs a newer stable release only when one exists. + +**Privacy and safety** -The installer downloads the latest stable release, verifies its SHA-256 checksum (there is no skip option), extracts it safely, and walks you through branding. It never patches 3X-UI and never touches your panel's own files. +- **No third-party requests** from the served page: no CDNs, no external QR or geolocation lookups, no telemetry. Live status comes from your own panel. +- **Mandatory SHA-256** verification of every release download, with no option to skip it. +- **Atomic activation.** A new page is generated and validated before it replaces the live one, so a failed step never leaves a broken page live. +- **Fail-closed panel detection.** If the panel database Row-Template finds is not a valid SQLite database, it refuses to use it rather than guessing another one. ## Supported panels | Panel | Status | Notes | | ----- | ------ | ----- | | [3X-UI](https://github.com/MHSanaei/3x-ui) (MHSanaei) | ✅ Supported | Requires version **>= 3.6.0** | -| [Marzban](https://github.com/Gozargah/Marzban) | ⬜ Planned | Not yet supported | -| [Marzneshin](https://github.com/marzneshin/marzneshin) | ⬜ Planned | Not yet supported | -| [Rebecca](https://github.com/rebeccapanel/Rebecca) | ⬜ Planned | Not yet supported | -| [PasarGuard](https://github.com/PasarGuard/panel) | ⬜ Planned | Not yet supported | - -Only 3X-UI is supported today. The other panels are on the roadmap and are listed here for transparency — there is no partial or experimental support for them in this release. - -## Features - -- **One self-contained page.** All CSS, JavaScript, fonts, and the QR code generator are inlined into a single HTML file. The page your subscribers open makes no third-party requests. -- **White-label.** Set your own service name, support link, and logo. Nothing identifies Row-Template on the served page. -- **Five languages.** English, Persian, Arabic, Russian, and Chinese, with right-to-left layout support. -- **Safe by construction.** Your branding is treated as data and injected as text, never executed. The page never sends subscriber data anywhere. -- **Live usage view.** Shows plan status, traffic used and remaining, expiry, and per-client links with copy buttons and QR codes. -- **Atomic install and rollback.** Each change is staged, validated, then swapped in. A failed step never leaves a broken page live, and you can roll back to a previous version. -- **No runtime dependencies.** Standard Linux userland only (bash, coreutils, curl, tar, sha256sum). No Node.js, Python, or database is required to install or run it. - -## Requirements - -- A server running a 3X-UI panel (version **>= 3.6.0**). -- Root access to that server. -- `curl`, `tar`, and `sha256sum` (present on virtually all Linux systems). +| [PasarGuard](https://github.com/PasarGuard/panel) | 🔬 Research | Not supported; no installation path | +| [Rebecca](https://github.com/rebeccapanel/Rebecca) | 🔬 Research | Not supported; no installation path | + +3X-UI is the only supported panel. PasarGuard and Rebecca use different template engines (Jinja2 and pongo2); each design's page shell is built for them and packaged in the release for study, but the installer does not place it and there are no installation instructions for them. See [Compatibility](https://iitzseridev.github.io/Row-Template/compatibility/) for the research findings. + +## Architecture + +```mermaid +flowchart TB + subgraph build ["Build and release"] + direction LR + SRC["src/
runtime, styles, locales,
15 design layouts"] --> BUILD["tools/build.mjs"] + BUILD --> ART["One self-contained
HTML file per design"] + ART --> REL["tools/make-release.sh
tarball + SHA256SUMS"] + end + subgraph host ["Your 3X-UI server"] + direction LR + INST["install.sh / row-template
verify checksum, stage, validate,
back up, activate"] --> DIR["/etc/3x-ui/
sub_templates/row-template"] + DIR -- "subThemeDir" --> XUI["3X-UI renders the page
with the subscriber's data"] + end + build -- "GitHub Releases" --> host + host -- "serves the page" --> BROWSER["Subscriber's browser"] + BROWSER -. "live status: ?format=info" .-> host +``` -## Compatibility +- **One file per design.** `tools/build.mjs` inlines the shared runtime, the translations, the fonts, and the QR generator into a design's layout, and refuses a layout that is missing any hook the runtime needs. `tools/verify.mjs` then rejects an artifact that loads anything remote or carries a forbidden construct. +- **The panel does the rendering.** The page is a template: 3X-UI fills in the subscriber's data when it serves it, and the page then refreshes its status from the same panel. +- **The installer never edits 3X-UI.** It writes its own directory and changes one panel setting, `subThemeDir`, to point at it. -- **Panel:** 3X-UI (MHSanaei) **>= 3.6.0**. Validated against stock 3.7.0. -- **Operating system:** recommended Ubuntu 24.04 LTS. Validated on Ubuntu 24.04 LTS (x86_64). Other distributions may work but have not received the same validation coverage. +| Path | What lives there | +| ---- | ---------------- | +| `src/` | The page's runtime, styles, and translations; each design in `src/templates//` | +| `template/index.html` | The built Row page, committed | +| `tools/` | Build, verification, release, and the Go fixture renderer | +| `installer/` | `install.sh`, the `row-template` command, and its management library | +| `tests/` | The test suites | +| `docs/` | The documentation site; design records in [`docs/design/`](docs/design/README.md) | ## Installation -Run the [Quick install](#quick-install) command as root. The installer will: - -1. Download the latest stable release from GitHub. -2. Verify the release checksum (SHA-256, mandatory — no bypass). -3. Extract it safely and install to `/etc/3x-ui/sub_templates/row-template`. -4. Prompt for your branding (service name, support link, logo — all optional). -5. Generate the served page and, where possible, activate it in the panel. - -If you prefer not to pipe from the network, you can download the release assets from the [Releases page](https://github.com/iitzSeriZdev/Row-Template/releases/latest), verify the checksum yourself, and run the bundled `install.sh` from the extracted directory. +> **Recommended OS: Ubuntu 24.04 LTS (x86_64).** Other modern Linux distributions may work but have not had the same validation coverage. -## Manager +**Requirements:** a server running 3X-UI **>= 3.6.0**, root access to it, and `curl`, `tar`, and `sha256sum` (present on virtually all Linux systems). Automatic activation also needs `sqlite3`. -After installation, manage everything with the `row-template` command. Run it with no arguments in a terminal to open the interactive manager: +Run as **root** on the server that hosts your 3X-UI panel: ```bash -row-template +bash <(curl -fsSL https://github.com/iitzSeriZdev/Row-Template/releases/latest/download/install.sh) ``` -Or use the direct commands: - -| Command | What it does | -| ------- | ------------ | -| `row-template config` | Reconfigure branding (service name, support link, logo) | -| `row-template update` | Check the stable channel and update if a newer version exists | -| `row-template rollback` | Roll back to the previous version (`--auto` or `--to `) | -| `row-template verify` | Check that the installation is healthy | -| `row-template version` | Print the installed version | -| `row-template uninstall` | Remove Row-Template (leaves 3X-UI untouched) | -| `row-template help` | Show usage | +The installer: -## Branding and configuration +1. Downloads the latest stable release from GitHub. +2. Verifies its SHA-256 checksum (mandatory — no bypass). +3. Extracts it safely and installs to `/etc/3x-ui/sub_templates/row-template`. +4. On a fresh install, offers the design chooser (Enter keeps Row). +5. Prompts for your branding (service name, support link, logo — all optional). +6. Generates and validates the page, then activates it in the panel where possible. -Set your service name, support link, and logo during installation, or change them any time: +To choose a design without the chooser, for example in a script: ```bash -row-template config +RT_TEMPLATE=editorial bash <(curl -fsSL https://github.com/iitzSeriZdev/Row-Template/releases/latest/download/install.sh) ``` -Your inputs are stored as data (never executed) and injected into the page as text. Leave a field blank for an unbranded, white-label page. The support link accepts only schemes a browser should open (for example `https://…`, `tg://…`, or `mailto:…`). +If you prefer not to pipe from the network, download the release assets from the [Releases page](https://github.com/iitzSeriZdev/Row-Template/releases/latest), verify the checksum yourself as described in [PROVENANCE.md](PROVENANCE.md), and run the bundled `install.sh` from the extracted directory. -## Activation +### Activation -Row-Template installs to a directory that the panel serves as the subscription page: +Row-Template installs to a directory that the panel serves as its subscription page: ``` /etc/3x-ui/sub_templates/row-template ``` -- **Automatic:** when `sqlite3` is available, the installer/manager can point the panel at Row-Template for you. -- **Manual:** otherwise, set it in the panel yourself — open **Panel Settings → Subscription → Profile → Sub Theme Directory** and enter exactly: +- **Automatic:** when `sqlite3` is available, Row-Template sets it for you. It briefly stops the panel service, writes the setting, starts the service again, and checks the value. An interactive install shows the current setting and asks first. +- **Manual:** otherwise, open **Panel Settings → Subscription → Profile → Sub Theme Directory** and enter exactly: ``` /etc/3x-ui/sub_templates/row-template ``` -## Update +## Usage + +Run the manager with no arguments in a terminal to open the interactive menu: ```bash -row-template update +row-template ``` -This checks the public stable release channel, shows the installed and available versions, and updates only when a newer stable version exists. If the network or release source is unreachable, it reports that it could not check — your installation is never treated as damaged. Normal use needs no URLs or manual downloads. - -## Rollback +Or use a command directly: -```bash -row-template rollback -``` +| Command | What it does | +| ------- | ------------ | +| `row-template config` | Change the service name, support link, or logo, then regenerate the page | +| `row-template update` | Download, verify, and activate a newer stable release (checksum enforced) | +| `row-template rollback` | Restore a previous version (`--auto` or `--to `) | +| `row-template verify` | Check the install, the panel wiring, and the live page (read-only) | +| `row-template version` | Show the installed, minimum-supported, and detected 3X-UI versions | +| `row-template uninstall` | Remove Row-Template and revert the panel to its built-in page | +| `row-template help` | Show usage | -Restores the previous version from a validated backup. The current version is snapshotted first, so a failed rollback can be recovered. Your branding configuration is preserved. +Commands that change the system (`config`, `update`, `rollback`, `uninstall`) must run as root. -## Verify +- **Branding** is stored as data, never executed, and injected into the page as text. Leave a field blank for an unbranded page. The support link accepts only schemes a browser should open, such as `https://…`, `tg://…`, or `mailto:…`. +- **Updates** check the public stable channel and change nothing unless a newer stable version exists. If the release source is unreachable, `update` reports that it could not check; your installation is never treated as damaged. +- **Rollback** restores a previous version from a validated backup. The current version is snapshotted first, so a failed rollback can be recovered, and your branding is preserved. +- **Uninstall** removes Row-Template's files. It clears the panel's `subThemeDir` only if it points at Row-Template, so the panel falls back to its built-in page; your inbounds, clients, and certificates are not touched. -```bash -row-template verify -``` +The [documentation](https://iitzseridev.github.io/Row-Template/) covers configuration, branding, and troubleshooting in more depth. -Reports whether the installed artifact, panel wiring, and service are healthy. +## Development -## Uninstall +The pages are built from readable sources in `src/`. You need Node.js 22 or newer, and Go 1.22 or newer to run the tests. ```bash -row-template uninstall +npm run build # regenerate template/index.html from src/ +npm run verify # check the built page against the safety gates +npm test # render the fixture pages, then run every test suite +npm run fixtures:all # render every design's fixture pages on their own +npm run lint:sh # ShellCheck every shell script +npm run preview # preview the fixture pages at http://127.0.0.1:8787 ``` -Removes Row-Template and its files. It **does not** touch 3X-UI, its database, your inbounds, clients, or certificates. +The build is deterministic — the same sources always produce a byte-identical `template/index.html`. The documentation site is a separate workspace in `docs/`; see [docs/README.md](docs/README.md). + +## Testing -## Languages +- **`npm test`** renders every design's fixture pages with the Go renderer, then runs the suites: the page's scripts, the build, every design's artifact, the release payload, and the installer — which runs the shipped shell library in real `bash` against throwaway fixtures. +- **`npm run verify`** checks a built page against its safety gates, including: a whole document, every build marker substituted, everything inlined, no remote references, no forbidden constructs, intact translations, and no invisible characters in the sources. +- **`npm run lint:sh`** fails on any ShellCheck error; `npm run lint:sh -- -S warning` shows the full report. +- **The Docs workflow** builds the documentation site on every pull request that changes it. -The subscription page ships in five interface languages and follows the subscriber's panel/browser locale: +## Roadmap -**English · فارسی · العربية · Русский · 简体中文** +Direction, not promises: -Arabic and Persian are rendered right-to-left. +- **Row-Template 1.2.0** — the fifteen designs and the design chooser described above. +- **PasarGuard and Rebecca** — research. Page shells are built for both; live status needs a small runtime change or a reverse proxy, and that decision is deferred. See [Compatibility](https://iitzseridev.github.io/Row-Template/compatibility/). +- **Installing on more than one panel** — the installer groundwork (a panel interface, a transaction engine, a 3X-UI adapter, and a new backup format) is in place but not yet used by any command. +- **Custom templates** — a proposal for adding your own design: [`docs/design/CUSTOM-TEMPLATES-PROPOSAL.md`](docs/design/CUSTOM-TEMPLATES-PROPOSAL.md). -## Bug reports +## Contributing -Please open an issue: +Bug reports, translations, and documentation fixes are very welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request, and follow the [Code of Conduct](CODE_OF_CONDUCT.md). -Include your Row-Template version (`row-template version`), 3X-UI version, operating system and version, CPU architecture, the output of `row-template verify`, and clear steps to reproduce. +**Bug reports:** open an issue at . Include your Row-Template version (`row-template version`), 3X-UI version, operating system and version, CPU architecture, the output of `row-template verify`, and clear steps to reproduce. > **Do not include secrets.** Never paste subscription URLs, `subId` values, client UUIDs, panel usernames or passwords, cookies, tokens, the panel `webBasePath`, TLS keys, or real server addresses. Redact logs before sharing them. ## Security -Found a vulnerability? Please report it privately — see [SECURITY.md](SECURITY.md). Do not open a public issue for security problems. - -## Development - -The single-file artifact is built from readable sources in `src/`: - -```bash -npm run build # regenerate template/index.html from src/ -npm run verify # check the artifact against the safety gates -npm test # run the unit and installer test suites -``` - -The build is deterministic — the same sources always produce a byte-identical `template/index.html`. See [CONTRIBUTING.md](CONTRIBUTING.md). +Found a vulnerability? Please report it privately — see [SECURITY.md](SECURITY.md). Do not open a public issue for security problems. [PROVENANCE.md](PROVENANCE.md) explains how releases are built and how to verify them. ## Support the project @@ -234,7 +282,7 @@ Thank you. ## License -Released under the [MIT License](LICENSE). The bundled QR code generator (`src/vendor/uqr`) is included under its own MIT license. +Released under the [MIT License](LICENSE). The bundled QR code generator (`src/vendor/uqr`) is included under its own MIT license, and the embedded Vazirmatn font subset under the SIL Open Font License (`src/fonts/OFL.txt`). ## Developer diff --git a/README.ru.md b/README.ru.md index bebf86b..f2a1e6e 100644 --- a/README.ru.md +++ b/README.ru.md @@ -7,7 +7,7 @@

- Отточенная, полностью автономная страница подписки для панелей 3X-UI — один HTML-файл, полностью в формате white-label, без сторонних CDN и без внешних запросов со страницы, которую открывают ваши подписчики. + Аккуратная автономная страница подписки для панелей 3X-UI — пятнадцать дизайнов, каждый в одном HTML-файле, полностью white-label и без сторонних запросов со страницы, которую открывают ваши подписчики.

@@ -19,121 +19,161 @@ Latest release Panel Platform + Documentation +

+ +

+ Установка · + Дизайны · + Документация · + Изменения · + Релизы

--- +## Что это такое + +3X-UI умеет показывать подписчикам собственную страницу вместо встроенной. Row-Template — такая страница: подписчик открывает ссылку на подписку и видит свой тариф, расход трафика, дату окончания и способы добавить подписку в своё приложение в одно касание. + +Каждый дизайн поставляется одним автономным HTML-файлом, в который встроены все стили, скрипты, шрифты и генератор QR-кодов. Одна команда устанавливает его рядом с панелью, направляет на него панель и даёт вам менеджер `row-template` для оформления, обновлений и отката. + ## Почему Row-Template? -- **Приватность по конструкции.** Страница, которую открывают ваши подписчики, не делает сторонних запросов. QR-коды генерируются локально, а ваше оформление вставляется как текст — никогда не исполняется и никуда не отправляется. -- **По-настоящему white-label.** Ваше название сервиса, ваша ссылка на поддержку, ваш логотип. На отдаваемой странице ничто не указывает на Row-Template. -- **Один файл, без зависимостей времени выполнения.** CSS, JavaScript, шрифты и генератор QR-кодов встроены в единственный HTML-файл, который ставится средствами стандартного окружения Linux — без Node.js, Python или базы данных. -- **Сделано для ваших подписчиков.** Актуальные использование и срок действия, импорт в популярные приложения в одно касание и список отдельных конфигураций с поиском для добавления одного сервера вручную. -- **Безопасно в эксплуатации.** Атомарная установка с проверкой и откат одной командой. Никогда не патчит 3X-UI и не затрагивает файлы вашей панели. +- **Приватность по умолчанию.** Страница, которую открывают подписчики, не делает сторонних запросов. QR-коды генерируются прямо на странице, а ваше оформление вставляется как текст — никогда не выполняется и никуда не отправляется. +- **Настоящий white-label.** Ваше название сервиса, ваша ссылка на поддержку, ваш логотип. Ничто на странице не указывает на Row-Template. +- **Пятнадцать дизайнов, каждый в одном файле.** Выберите вид, который подходит вашему сервису. У всех дизайнов одинаковые возможности, языки и проверки безопасности. +- **Сделано для ваших подписчиков.** Расход и срок действия в реальном времени, импорт в популярные приложения в одно касание и список отдельных конфигураций с поиском, чтобы добавить один сервер вручную. +- **Безопасен в эксплуатации.** Релизы с проверкой контрольной суммы, атомарная активация и откат одной командой. Row-Template никогда не патчит 3X-UI: единственная настройка панели, которую он меняет, — каталог страницы подписки (`subThemeDir`). -## Скриншоты +## Дизайны + +Row-Template 1.2.0 поставляется с пятнадцатью дизайнами. Дизайн по умолчанию — Row. - - + + + + + + + + + + + + - - + + + + +
Row-TemplateRow-TemplateRow
Row		Editorial
Editorial		Canvas
Canvas		Prism
Prism		Terminal
Terminal
Pulse
Pulse		Brutal
Brutal		Arcade
Arcade		Sketch
Sketch		Signature
Signature
Тёмная темаСветлая темаSaffron
Saffron		Pulse Nova
Pulse Nova		Prism Nova
Prism Nova		Terminal Nova
Terminal Nova		Arcade Nova
Arcade Nova
-На скриншотах — демонстрационные данные; показанные список конфигураций и значки стран приведены для примера. +Превью построены на демонстрационных данных самого проекта. Превью каждого дизайна для компьютера и телефона — в галерее шаблонов. -## Быстрая установка +Выберите дизайн при новой интерактивной установке, задайте `RT_TEMPLATE` для установки скриптом или смените его позже в менеджере (**Reconfigure branding → Template**). Обновления сохраняют ваш выбор. -> **Рекомендуемая ОС: Ubuntu 24.04 LTS (x86_64).** Другие современные дистрибутивы Linux могут работать, но не проходили такого же объёма проверок. +## Возможности -Запустите от имени **root** на сервере, где размещена ваша панель 3X-UI: +**Для ваших подписчиков** -```bash -bash <(curl -fsSL https://github.com/iitzSeriZdev/Row-Template/releases/latest/download/install.sh) -``` +- **Статус в реальном времени.** Состояние тарифа, израсходованный и оставшийся трафик и срок действия, которые обновляются из вашей панели, пока страница открыта на экране. +- **Импорт в одно касание** в популярные приложения, сгруппированные по платформам: v2rayNG, Happ и sing-box на Android; Streisand, V2Box и Shadowrocket на iOS; Clash Verge Rev, Mihomo Party и v2rayN на Windows; Clash Verge Rev, Streisand и V2Box на macOS. +- **Копирование и QR.** Скопируйте ссылку на подписку или отсканируйте её как QR-код, созданный на самой странице. +- **Обозреватель конфигураций.** Каждый сервер в отдельной строке — с флагом страны или монограммой и меткой протокола (VLESS, VMess, Trojan, Shadowsocks, Hysteria/Hysteria2, WireGuard, AmneziaWG, Telegram MTProto), с QR-кодом и копированием для каждой конфигурации и поиском по длинным спискам. +- **Пять языков** — английский, персидский, арабский, русский и китайский — с раскладкой справа налево и выбором темы System / Light / Dark. + +**Для вас** -Установщик загружает последний стабильный релиз, проверяет его контрольную сумму SHA-256 (пропустить проверку нельзя), безопасно распаковывает его и проводит вас через настройку оформления. Он никогда не патчит 3X-UI и не затрагивает собственные файлы вашей панели. +- **White-label оформление.** Название сервиса, ссылка на поддержку и логотип — всё необязательно, хранится как данные и вставляется как текст. +- **Менеджер для всего.** Интерактивное меню и прямые команды для оформления, обновлений, проверки, отката и удаления. +- **Обновления из стабильного канала.** `row-template update` устанавливает новый стабильный релиз, только если он существует. + +**Приватность и безопасность** + +- **Никаких сторонних запросов** со страницы: без CDN, без внешних сервисов QR и геолокации, без телеметрии. Статус в реальном времени приходит из вашей же панели. +- **Обязательная проверка SHA-256** для каждой загрузки релиза, без возможности её пропустить. +- **Атомарная активация.** Новая страница создаётся и проверяется до того, как заменит работающую, поэтому неудачный шаг никогда не оставляет сломанную страницу. +- **Осторожное обнаружение панели.** Если найденная база данных панели не является корректной базой SQLite, Row-Template отказывается её использовать, а не пытается угадать другую. ## Поддерживаемые панели | Панель | Статус | Примечания | | ----- | ------ | ----- | | [3X-UI](https://github.com/MHSanaei/3x-ui) (MHSanaei) | ✅ Поддерживается | Требуется версия **>= 3.6.0** | -| [Marzban](https://github.com/Gozargah/Marzban) | ⬜ Запланировано | Пока не поддерживается | -| [Marzneshin](https://github.com/marzneshin/marzneshin) | ⬜ Запланировано | Пока не поддерживается | -| [Rebecca](https://github.com/rebeccapanel/Rebecca) | ⬜ Запланировано | Пока не поддерживается | -| [PasarGuard](https://github.com/PasarGuard/panel) | ⬜ Запланировано | Пока не поддерживается | - -На сегодняшний день поддерживается только 3X-UI. Остальные панели находятся в планах и перечислены здесь для прозрачности — частичной или экспериментальной поддержки для них в этом релизе нет. - -## Возможности - -- **Одна автономная страница.** Все CSS, JavaScript, шрифты и генератор QR-кодов встроены в единственный HTML-файл. Страница, которую открывают ваши подписчики, не делает сторонних запросов. -- **White-label.** Задайте собственное название сервиса, ссылку на поддержку и логотип. На отдаваемой странице ничто не указывает на Row-Template. -- **Пять языков.** Английский, персидский, арабский, русский и китайский, с поддержкой раскладки справа налево. -- **Безопасность по конструкции.** Ваше оформление обрабатывается как данные и вставляется как текст, а не исполняется. Страница никогда никуда не отправляет данные подписчиков. -- **Актуальная статистика использования.** Показывает статус тарифа, использованный и оставшийся трафик, срок действия и ссылки по каждому клиенту с кнопками копирования и QR-кодами. -- **Атомарная установка и откат.** Каждое изменение сначала подготавливается, проверяется, а затем подменяется. Сбойный шаг никогда не оставит в работе неисправную страницу, и вы можете откатиться к предыдущей версии. -- **Никаких зависимостей времени выполнения.** Только стандартное окружение Linux (bash, coreutils, curl, tar, sha256sum). Для установки и работы не требуются ни Node.js, ни Python, ни база данных. - -## Требования - -- Сервер с работающей панелью 3X-UI (версия **>= 3.6.0**). -- Root-доступ к этому серверу. -- `curl`, `tar` и `sha256sum` (есть практически во всех системах Linux). +| [PasarGuard](https://github.com/PasarGuard/panel) | 🔬 Исследование | Не поддерживается; установка не предусмотрена | +| [Rebecca](https://github.com/rebeccapanel/Rebecca) | 🔬 Исследование | Не поддерживается; установка не предусмотрена | + +3X-UI — единственная поддерживаемая панель. PasarGuard и Rebecca используют другие шаблонизаторы (Jinja2 и pongo2); оболочка страницы каждого дизайна собирается для них и упаковывается в релиз для изучения, но установщик её не размещает, и инструкций по установке для них нет. Результаты исследования — в разделе [Совместимость](https://iitzseridev.github.io/Row-Template/compatibility/). + +## Архитектура + +```mermaid +flowchart TB + subgraph build ["Build and release"] + direction LR + SRC["src/
runtime, styles, locales,
15 design layouts"] --> BUILD["tools/build.mjs"] + BUILD --> ART["One self-contained
HTML file per design"] + ART --> REL["tools/make-release.sh
tarball + SHA256SUMS"] + end + subgraph host ["Your 3X-UI server"] + direction LR + INST["install.sh / row-template
verify checksum, stage, validate,
back up, activate"] --> DIR["/etc/3x-ui/
sub_templates/row-template"] + DIR -- "subThemeDir" --> XUI["3X-UI renders the page
with the subscriber's data"] + end + build -- "GitHub Releases" --> host + host -- "serves the page" --> BROWSER["Subscriber's browser"] + BROWSER -. "live status: ?format=info" .-> host +``` -## Совместимость +- **Один файл на дизайн.** `tools/build.mjs` встраивает общий код, переводы, шрифты и генератор QR в макет дизайна и отклоняет макет, в котором нет хотя бы одной нужной коду точки привязки (hook). Затем `tools/verify.mjs` отклоняет файл, который загружает что-либо извне или содержит запрещённую конструкцию. +- **Страницу отрисовывает панель.** Страница — это шаблон: 3X-UI подставляет данные подписчика при выдаче, а затем страница обновляет свой статус из той же панели. +- **Установщик никогда не редактирует 3X-UI.** Он пишет в собственный каталог и меняет одну настройку панели, `subThemeDir`, чтобы она указывала на него. -- **Панель:** 3X-UI (MHSanaei) **>= 3.6.0**. Проверено на стоковой версии 3.7.0. -- **Операционная система:** рекомендуется Ubuntu 24.04 LTS. Проверено на Ubuntu 24.04 LTS (x86_64). Другие дистрибутивы могут работать, но не проходили такого же объёма проверок. +| Путь | Содержимое | +| ---- | ---------------- | +| `src/` | Код, стили и переводы страницы; каждый дизайн — в `src/templates//` | +| `template/index.html` | Собранная страница Row, хранится в репозитории | +| `tools/` | Сборка, проверка, релизы и рендерер фикстур на Go | +| `installer/` | `install.sh`, команда `row-template` и её библиотека управления | +| `tests/` | Наборы тестов | +| `docs/` | Сайт документации; проектные записи — в [`docs/design/`](docs/design/README.md) | ## Установка -Запустите показанную выше команду установки от имени root. Установщик выполнит следующее: - -1. Загрузит последний стабильный релиз с GitHub. -2. Проверит контрольную сумму релиза (SHA-256, обязательно — обойти нельзя). -3. Безопасно распакует его и установит в `/etc/3x-ui/sub_templates/row-template`. -4. Запросит ваше оформление (название сервиса, ссылку на поддержку, логотип — всё опционально). -5. Сгенерирует отдаваемую страницу и, где это возможно, активирует её в панели. - -Если вы предпочитаете не запускать команду напрямую из сети, вы можете скачать файлы релиза со [страницы релизов](https://github.com/iitzSeriZdev/Row-Template/releases/latest), самостоятельно проверить контрольную сумму и запустить входящий в комплект `install.sh` из распакованного каталога. +> **Рекомендуемая ОС: Ubuntu 24.04 LTS (x86_64).** Другие современные дистрибутивы Linux могут работать, но не проходили такого же объёма проверок. -## Менеджер +**Требования:** сервер с 3X-UI **>= 3.6.0**, root-доступ к нему и `curl`, `tar` и `sha256sum` (есть практически в любой системе Linux). Для автоматической активации также нужен `sqlite3`. -После установки всем управляет команда `row-template`. Запустите её без аргументов в терминале, чтобы открыть интерактивный менеджер: +Запустите от имени **root** на сервере, где работает ваша панель 3X-UI: ```bash -row-template +bash <(curl -fsSL https://github.com/iitzSeriZdev/Row-Template/releases/latest/download/install.sh) ``` -Либо используйте прямые команды: - -| Команда | Назначение | -| ------- | ------------ | -| `row-template config` | Изменить оформление (название сервиса, ссылку на поддержку, логотип) | -| `row-template update` | Проверить стабильный канал и обновиться, если доступна более новая версия | -| `row-template rollback` | Откатиться к предыдущей версии (`--auto` или `--to `) | -| `row-template verify` | Проверить работоспособность установки | -| `row-template version` | Вывести установленную версию | -| `row-template uninstall` | Удалить Row-Template (не затрагивая 3X-UI) | -| `row-template help` | Показать справку по использованию | +Установщик: -## Оформление и настройка +1. Скачивает последний стабильный релиз с GitHub. +2. Проверяет его контрольную сумму SHA-256 (обязательно — без возможности обойти). +3. Безопасно распаковывает его и устанавливает в `/etc/3x-ui/sub_templates/row-template`. +4. При новой установке предлагает выбрать дизайн (Enter оставляет Row). +5. Запрашивает ваше оформление (название сервиса, ссылка на поддержку, логотип — всё необязательно). +6. Создаёт и проверяет страницу, а затем, если возможно, активирует её в панели. -Задайте название сервиса, ссылку на поддержку и логотип во время установки или измените их в любой момент: +Чтобы выбрать дизайн без меню выбора, например в скрипте: ```bash -row-template config +RT_TEMPLATE=editorial bash <(curl -fsSL https://github.com/iitzSeriZdev/Row-Template/releases/latest/download/install.sh) ``` -Введённые вами значения хранятся как данные (никогда не исполняются) и вставляются на страницу как текст. Оставьте поле пустым, чтобы получить страницу без брендинга, в формате white-label. Ссылка на поддержку принимает только схемы, которые должен открывать браузер (например, `https://…`, `tg://…` или `mailto:…`). +Если вы не хотите запускать скрипт прямо из сети, скачайте файлы релиза со [страницы релизов](https://github.com/iitzSeriZdev/Row-Template/releases/latest), проверьте контрольную сумму самостоятельно, как описано в [PROVENANCE.md](PROVENANCE.md), и запустите входящий в комплект `install.sh` из распакованного каталога. -## Активация +### Активация Row-Template устанавливается в каталог, который панель отдаёт как страницу подписки: @@ -141,76 +181,84 @@ Row-Template устанавливается в каталог, который п /etc/3x-ui/sub_templates/row-template ``` -- **Автоматически:** когда доступен `sqlite3`, установщик/менеджер может сам указать панели на Row-Template. -- **Вручную:** иначе задайте это в панели самостоятельно — откройте **Panel Settings → Subscription → Profile → Sub Theme Directory** и введите в точности: +- **Автоматически:** если доступен `sqlite3`, Row-Template настраивает это за вас. Он ненадолго останавливает службу панели, записывает настройку, снова запускает службу и проверяет значение. Интерактивная установка сначала показывает текущее значение и спрашивает разрешения. +- **Вручную:** иначе откройте **Panel Settings → Subscription → Profile → Sub Theme Directory** и введите в точности: ``` /etc/3x-ui/sub_templates/row-template ``` -## Обновление +## Использование + +Запустите менеджер без аргументов в терминале, чтобы открыть интерактивное меню: ```bash -row-template update +row-template ``` -Эта команда проверяет публичный стабильный канал релизов, показывает установленную и доступную версии и обновляется только при наличии более новой стабильной версии. Если сеть или источник релизов недоступны, она сообщает, что не смогла выполнить проверку — ваша установка при этом никогда не считается повреждённой. Для обычного использования не нужны ни URL, ни ручные загрузки. +Или используйте команду напрямую: -## Откат - -```bash -row-template rollback -``` +| Команда | Что делает | +| ------- | ------------ | +| `row-template config` | Меняет название сервиса, ссылку на поддержку или логотип и заново создаёт страницу | +| `row-template update` | Скачивает, проверяет и активирует новый стабильный релиз (проверка контрольной суммы обязательна) | +| `row-template rollback` | Восстанавливает предыдущую версию (`--auto` или `--to `) | +| `row-template verify` | Проверяет установку, связь с панелью и работающую страницу (только чтение) | +| `row-template version` | Показывает установленную, минимально поддерживаемую и обнаруженную версии 3X-UI | +| `row-template uninstall` | Удаляет Row-Template и возвращает панели встроенную страницу | +| `row-template help` | Показывает справку | -Восстанавливает предыдущую версию из проверенной резервной копии. Сначала создаётся снимок текущей версии, поэтому неудачный откат можно восстановить. Ваши настройки оформления сохраняются. +Команды, изменяющие систему (`config`, `update`, `rollback`, `uninstall`), нужно запускать от имени root. -## Проверка +- **Оформление** хранится как данные, никогда не выполняется и вставляется в страницу как текст. Оставьте поле пустым, чтобы получить страницу без брендинга. Ссылка на поддержку принимает только схемы, которые браузер должен открывать, например `https://…`, `tg://…` или `mailto:…`. +- **Обновления** проверяют публичный стабильный канал и ничего не меняют, если более новой стабильной версии нет. Если источник релизов недоступен, `update` сообщает, что не смог проверить; установка при этом никогда не считается повреждённой. +- **Откат** восстанавливает предыдущую версию из проверенной резервной копии. Сначала делается снимок (snapshot) текущей версии, поэтому неудачный откат можно исправить, а ваше оформление сохраняется. +- **Удаление** стирает файлы Row-Template. Настройку `subThemeDir` панели оно очищает, только если та указывает на Row-Template, и панель возвращается к встроенной странице; ваши inbound'ы, клиенты и сертификаты не затрагиваются. -```bash -row-template verify -``` +[Документация](https://iitzseridev.github.io/Row-Template/) подробнее описывает настройку, оформление и устранение неполадок. -Сообщает, исправны ли установленный артефакт, связка с панелью и служба. +## Разработка -## Удаление +Страницы собираются из читаемых исходников в `src/`. Нужен Node.js 22 или новее, а для запуска тестов — Go 1.22 или новее. ```bash -row-template uninstall +npm run build # regenerate template/index.html from src/ +npm run verify # check the built page against the safety gates +npm test # render the fixture pages, then run every test suite +npm run fixtures:all # render every design's fixture pages on their own +npm run lint:sh # ShellCheck every shell script +npm run preview # preview the fixture pages at http://127.0.0.1:8787 ``` -Удаляет Row-Template и его файлы. Он **не** затрагивает 3X-UI, его базу данных, ваши входящие подключения (inbounds), клиентов и сертификаты. +Сборка детерминирована — одни и те же исходники всегда дают побайтно идентичный `template/index.html`. Сайт документации — отдельное рабочее пространство в `docs/`; см. [docs/README.md](docs/README.md). + +## Тестирование -## Языки +- **`npm test`** сначала создаёт страницы фикстур всех дизайнов рендерером на Go, а затем запускает наборы тестов: скрипты страницы, сборку, итоговый файл каждого дизайна, содержимое релиза и установщик — его опубликованная shell-библиотека выполняется в настоящем `bash` на временных фикстурах. +- **`npm run verify`** проверяет собранную страницу по её правилам безопасности, в том числе: цельный документ, замена всех маркеров сборки, всё встроено, нет внешних ссылок, нет запрещённых конструкций, целые переводы и отсутствие невидимых символов в исходниках. +- **`npm run lint:sh`** завершается ошибкой при любой ошибке ShellCheck; `npm run lint:sh -- -S warning` показывает полный отчёт. +- **Workflow Docs** собирает сайт документации в каждом pull request, который его меняет. -Страница подписки поставляется с пятью языками интерфейса и подстраивается под локаль панели/браузера подписчика: +## Дорожная карта -**English · فارسی · العربية · Русский · 简体中文** +Направление, а не обещания: -Арабский и персидский отображаются справа налево. +- **Row-Template 1.2.0** — пятнадцать дизайнов и выбор дизайна, описанные выше. +- **PasarGuard и Rebecca** — исследование. Оболочки страниц для обеих собраны; для статуса в реальном времени нужно небольшое изменение в коде или обратный прокси (reverse proxy), и это решение отложено. См. [Совместимость](https://iitzseridev.github.io/Row-Template/compatibility/). +- **Установка на несколько панелей** — основа установщика (интерфейс панели, движок транзакций, адаптер 3X-UI и новый формат резервных копий) готова, но пока не используется ни одной командой. +- **Собственные шаблоны** — предложение о добавлении своего дизайна: [`docs/design/CUSTOM-TEMPLATES-PROPOSAL.md`](docs/design/CUSTOM-TEMPLATES-PROPOSAL.md). -## Сообщения об ошибках +## Участие в проекте -Пожалуйста, создайте issue: +Сообщения об ошибках, переводы и исправления документации очень приветствуются. Прочитайте [CONTRIBUTING.md](CONTRIBUTING.md), прежде чем открывать pull request, и соблюдайте [Кодекс поведения](CODE_OF_CONDUCT.md). -Укажите версию Row-Template (`row-template version`), версию 3X-UI, операционную систему и её версию, архитектуру процессора, вывод `row-template verify` и чёткие шаги для воспроизведения. +**Сообщения об ошибках:** создайте issue на . Укажите версию Row-Template (`row-template version`), версию 3X-UI, операционную систему и её версию, архитектуру процессора, вывод `row-template verify` и чёткие шаги для воспроизведения. > **Не указывайте секретные данные.** Никогда не вставляйте URL подписок, значения `subId`, UUID клиентов, имена пользователей и пароли панели, cookie, токены, панельный `webBasePath`, ключи TLS или реальные адреса серверов. Скрывайте конфиденциальные данные в логах перед тем, как ими делиться. ## Безопасность -Нашли уязвимость? Пожалуйста, сообщите о ней приватно — см. [SECURITY.md](SECURITY.md). Не создавайте публичный issue по проблемам безопасности. - -## Разработка - -Артефакт из одного файла собирается из читаемых исходников в `src/`: - -```bash -npm run build # regenerate template/index.html from src/ -npm run verify # check the artifact against the safety gates -npm test # run the unit and installer test suites -``` - -Сборка детерминирована — одни и те же исходники всегда дают байт-в-байт идентичный `template/index.html`. См. [CONTRIBUTING.md](CONTRIBUTING.md). +Нашли уязвимость? Пожалуйста, сообщите о ней приватно — см. [SECURITY.md](SECURITY.md). Не создавайте публичный issue по проблемам безопасности. [PROVENANCE.md](PROVENANCE.md) объясняет, как собираются релизы и как их проверить. ## Поддержать проект @@ -234,8 +282,8 @@ Row-Template — бесплатный проект с открытым исхо ## Лицензия -Распространяется под [лицензией MIT](LICENSE). Входящий в комплект генератор QR-кодов (`src/vendor/uqr`) включён под собственной лицензией MIT. +Распространяется под [лицензией MIT](LICENSE). Входящий в комплект генератор QR-кодов (`src/vendor/uqr`) включён под собственной лицензией MIT, а встроенное подмножество шрифта Vazirmatn — под лицензией SIL Open Font License (`src/fonts/OFL.txt`). ## Разработчик -Создано и поддерживается **iitzSeriZdev** — \ No newline at end of file +Создано и поддерживается **iitzSeriZdev** — diff --git a/README.zh-CN.md b/README.zh-CN.md index b352f75..4c532c2 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -6,7 +6,7 @@

- 为 3X-UI 面板打造的精致、自包含的自定义订阅页面——单个 HTML 文件，完全支持白标，不依赖任何第三方 CDN，订阅用户打开的页面也不会发起任何外部请求。 + 为 3X-UI 面板打造的精致、自包含的订阅页面 —— 十五种设计，每种都是一个 HTML 文件，完全白标（white-label），订阅者打开的页面不会向任何第三方发出请求。

@@ -18,198 +18,246 @@ Latest release Panel Platform + Documentation +

+ +

+ 安装 · + 设计 · + 文档 · + 更新日志 · + 发布

--- +## 这是什么 + +3X-UI 可以向订阅者展示自定义页面来代替内置页面。Row-Template 就是这样一个页面：订阅者打开订阅链接，就能看到自己的套餐、用量和到期日期，以及一键把订阅添加到所用应用的方式。 + +每种设计都以一个自包含的 HTML 文件提供，所有样式、脚本、字体和二维码生成器都已内联其中。一条命令即可把它安装到面板旁边、让面板指向它，并为你提供 `row-template` 管理器，用于品牌设置、更新和回滚。 + ## 为什么选择 Row-Template？ -- **设计即隐私。** 订阅用户打开的页面不会发起任何第三方请求。二维码在本地生成，你的品牌信息以文本形式注入——绝不会被执行，也绝不会被发送到任何地方。 -- **真正的白标。** 你自己的服务名称、支持链接和 Logo。对外服务的页面上不会有任何标识 Row-Template 的内容。 -- **单个文件，无运行时依赖。** CSS、JavaScript、字体和二维码生成器都内联到单个 HTML 文件中，仅凭标准的 Linux 用户空间工具即可安装——无需 Node.js、Python 或数据库。 -- **为你的订阅用户而设计。** 实时用量与到期时间、一键导入到常用应用，以及可搜索的单条配置列表，便于手动添加单个服务器。 -- **运行安全。** 原子化安装，带校验与一条命令回滚。绝不修补 3X-UI，也绝不触及面板文件。 +- **隐私优先。** 订阅者打开的页面不会向任何第三方发出请求。二维码在页面内生成，你的品牌信息以文本形式注入 —— 从不执行，也从不发送到任何地方。 +- **真正的白标。** 你的服务名称、你的支持链接、你的徽标。所呈现的页面上没有任何内容标明 Row-Template。 +- **十五种设计，每种一个文件。** 选择适合你服务的外观。所有设计共享相同的功能、语言和安全检查。 +- **为你的订阅者而设计。** 实时显示用量和到期时间，一键导入常用应用，以及可搜索的单独配置列表，便于手动添加单个服务器。 +- **运维安全。** 经校验和验证的发布、原子化激活以及一条命令即可回滚。它从不修补 3X-UI：它唯一会修改的面板设置是订阅页面目录（`subThemeDir`）。 + +## 设计 -## 界面截图 +Row-Template 1.2.0 提供十五种设计，默认设计为 Row。 - - + + + + + - - + + + + + + + + + + + +
Row-TemplateRow-TemplateRow
Row		Editorial
Editorial		Canvas
Canvas		Prism
Prism		Terminal
Terminal
深色主题浅色主题Pulse
Pulse		Brutal
Brutal		Arcade
Arcade		Sketch
Sketch		Signature
Signature
Saffron
Saffron		Pulse Nova
Pulse Nova		Prism Nova
Prism Nova		Terminal Nova
Terminal Nova		Arcade Nova
Arcade Nova
-截图使用示例数据；所示的配置列表与国家/地区标识仅为示例。 +预览图使用项目自带的示例数据渲染。每种设计的桌面端和移动端预览见模板画廊。 -## 快速安装 - -> **推荐操作系统：Ubuntu 24.04 LTS (x86_64)。** 其他较新的 Linux 发行版或许也能运行，但未经过同等程度的验证覆盖。 +可以在全新的交互式安装时选择设计，在脚本安装时设置 `RT_TEMPLATE`，或之后在管理器中更改（**Reconfigure branding → Template**）。更新会保留你的选择。 -在托管 3X-UI 面板的服务器上以 **root** 身份运行： - -```bash -bash <(curl -fsSL https://github.com/iitzSeriZdev/Row-Template/releases/latest/download/install.sh) -``` +## 功能特性 -安装程序会下载最新的稳定版本，校验其 SHA-256 校验和（没有跳过选项），安全地解压，并引导你完成品牌定制。它绝不会修补 3X-UI，也绝不会改动面板自身的任何文件。 +**面向你的订阅者** -## 支持的面板 +- **实时状态。** 套餐状态、已用和剩余流量以及到期时间，在页面可见期间从你的面板刷新。 +- **一键导入**常用应用，按平台分组：Android 上的 v2rayNG、Happ 和 sing-box；iOS 上的 Streisand、V2Box 和 Shadowrocket；Windows 上的 Clash Verge Rev、Mihomo Party 和 v2rayN；macOS 上的 Clash Verge Rev、Streisand 和 V2Box。 +- **复制与二维码。** 复制订阅链接，或扫描在页面内生成的二维码。 +- **配置浏览器。** 每个服务器单独一行，带有国家旗帜或首字母徽章（monogram）以及协议标签（VLESS、VMess、Trojan、Shadowsocks、Hysteria/Hysteria2、WireGuard、AmneziaWG、Telegram MTProto），每个配置都可查看二维码和复制，长列表支持搜索。 +- **五种语言** —— 英语、波斯语、阿拉伯语、俄语和中文 —— 支持从右到左的布局，并可选择 System / Light / Dark 主题。 -| 面板 | 状态 | 说明 | -| ----- | ------ | ----- | -| [3X-UI](https://github.com/MHSanaei/3x-ui) (MHSanaei) | ✅ 已支持 | 需要版本 **>= 3.6.0** | -| [Marzban](https://github.com/Gozargah/Marzban) | ⬜ 计划中 | 暂不支持 | -| [Marzneshin](https://github.com/marzneshin/marzneshin) | ⬜ 计划中 | 暂不支持 | -| [Rebecca](https://github.com/rebeccapanel/Rebecca) | ⬜ 计划中 | 暂不支持 | -| [PasarGuard](https://github.com/PasarGuard/panel) | ⬜ 计划中 | 暂不支持 | +**面向你** -目前仅支持 3X-UI。其他面板已列入路线图，在此列出是为了保持透明——本版本中不存在对它们的任何部分支持或实验性支持。 +- **白标品牌。** 服务名称、支持链接和徽标，均为可选，以数据形式存储并以文本形式注入。 +- **一个管理器搞定一切。** 交互式菜单和直接命令，用于品牌设置、更新、验证、回滚和卸载。 +- **稳定通道更新。** `row-template update` 仅在存在更新的稳定版本时才会安装。 -## 功能特性 +**隐私与安全** -- **单一自包含页面。** 所有 CSS、JavaScript、字体以及二维码生成器都内联到了单个 HTML 文件中。订阅用户打开的页面不会发起任何第三方请求。 -- **白标定制。** 设置你自己的服务名称、支持链接和 Logo。对外服务的页面上不会有任何标识 Row-Template 的内容。 -- **五种语言。** 英语、波斯语、阿拉伯语、俄语和中文，并支持从右到左的布局。 -- **设计即安全。** 你的品牌信息被当作数据处理并以文本形式注入，绝不会被执行。页面绝不会将订阅用户的数据发送到任何地方。 -- **实时用量视图。** 显示套餐状态、已用与剩余流量、到期时间，以及带有复制按钮和二维码的各客户端链接。 -- **原子化的安装与回滚。** 每次变更都会先暂存、校验，再切换生效。失败的步骤绝不会让损坏的页面上线，你也可以回滚到先前的版本。 -- **无运行时依赖。** 仅需标准的 Linux 用户空间工具（bash、coreutils、curl、tar、sha256sum）。安装或运行它无需 Node.js、Python 或任何数据库。 +- 所呈现的页面**不向第三方发出任何请求**：没有 CDN，没有外部二维码或地理定位服务，没有遥测。实时状态来自你自己的面板。 +- 每次下载发布版本都**强制进行 SHA-256 校验**，且没有跳过的选项。 +- **原子化激活。** 新页面在替换当前页面之前先生成并通过验证，因此失败的步骤绝不会让损坏的页面上线。 +- **谨慎的面板检测。** 如果 Row-Template 找到的面板数据库不是有效的 SQLite 数据库，它会拒绝使用，而不是去猜测另一个数据库。 -## 环境要求 +## 支持的面板 -- 一台运行 3X-UI 面板的服务器（版本 **>= 3.6.0**）。 -- 对该服务器的 root 访问权限。 -- `curl`、`tar` 和 `sha256sum`（几乎所有 Linux 系统都自带）。 +| 面板 | 状态 | 说明 | +| ----- | ------ | ----- | +| [3X-UI](https://github.com/MHSanaei/3x-ui) (MHSanaei) | ✅ 已支持 | 需要 **>= 3.6.0** 版本 | +| [PasarGuard](https://github.com/PasarGuard/panel) | 🔬 研究中 | 不受支持；没有安装途径 | +| [Rebecca](https://github.com/rebeccapanel/Rebecca) | 🔬 研究中 | 不受支持；没有安装途径 | + +3X-UI 是唯一受支持的面板。PasarGuard 和 Rebecca 使用不同的模板引擎（Jinja2 和 pongo2）；每种设计都会为它们构建页面外壳并打包进发布版本以供研究，但安装程序不会部署它，也没有针对它们的安装说明。研究结果见[兼容性](https://iitzseridev.github.io/Row-Template/compatibility/)。 + +## 架构 + +```mermaid +flowchart TB + subgraph build ["Build and release"] + direction LR + SRC["src/
runtime, styles, locales,
15 design layouts"] --> BUILD["tools/build.mjs"] + BUILD --> ART["One self-contained
HTML file per design"] + ART --> REL["tools/make-release.sh
tarball + SHA256SUMS"] + end + subgraph host ["Your 3X-UI server"] + direction LR + INST["install.sh / row-template
verify checksum, stage, validate,
back up, activate"] --> DIR["/etc/3x-ui/
sub_templates/row-template"] + DIR -- "subThemeDir" --> XUI["3X-UI renders the page
with the subscriber's data"] + end + build -- "GitHub Releases" --> host + host -- "serves the page" --> BROWSER["Subscriber's browser"] + BROWSER -. "live status: ?format=info" .-> host +``` -## 兼容性 +- **每种设计一个文件。** `tools/build.mjs` 将共享的运行时代码、翻译、字体和二维码生成器内联到设计的布局中，并拒绝缺少任何运行时所需钩子（hook）的布局。随后 `tools/verify.mjs` 会拒绝任何加载远程资源或包含禁用结构的文件。 +- **由面板负责渲染。** 页面是一个模板：3X-UI 在提供页面时填入订阅者的数据，之后页面再从同一面板刷新状态。 +- **安装程序从不修改 3X-UI。** 它只写入自己的目录，并修改一项面板设置 `subThemeDir`，使其指向该目录。 -- **面板：** 3X-UI (MHSanaei) **>= 3.6.0**。已针对原版 3.7.0 完成验证。 -- **操作系统：** 推荐 Ubuntu 24.04 LTS。已在 Ubuntu 24.04 LTS (x86_64) 上验证。其他发行版或许也能运行，但未获得同等程度的验证覆盖。 +| 路径 | 内容 | +| ---- | ---------------- | +| `src/` | 页面的运行时代码、样式和翻译；每种设计位于 `src/templates//` | +| `template/index.html` | 构建好的 Row 页面，已提交到仓库 | +| `tools/` | 构建、验证、发布以及 Go 编写的 fixture 渲染器 | +| `installer/` | `install.sh`、`row-template` 命令及其管理库 | +| `tests/` | 测试套件 | +| `docs/` | 文档站点；设计记录位于 [`docs/design/`](docs/design/README.md) | ## 安装 -以 root 身份运行上方展示的安装命令。安装程序将会： - -1. 从 GitHub 下载最新的稳定版本。 -2. 校验版本的校验和（SHA-256，强制执行——无法绕过）。 -3. 安全地解压，并安装到 `/etc/3x-ui/sub_templates/row-template`。 -4. 提示你输入品牌信息（服务名称、支持链接、Logo——均为可选）。 -5. 生成对外服务的页面，并在可能的情况下于面板中激活它。 - -如果你不希望直接从网络管道执行，可以从 [Releases page](https://github.com/iitzSeriZdev/Row-Template/releases/latest) 下载版本资源文件，自行校验校验和，然后在解压后的目录中运行随附的 `install.sh`。 +> **推荐操作系统：Ubuntu 24.04 LTS (x86_64)。** 其他较新的 Linux 发行版或许也能运行，但未经过同等程度的验证覆盖。 -## 管理器 +**环境要求：** 运行 3X-UI **>= 3.6.0** 的服务器、该服务器的 root 权限，以及 `curl`、`tar` 和 `sha256sum`（几乎所有 Linux 系统都自带）。自动激活还需要 `sqlite3`。 -安装完成后，可使用 `row-template` 命令管理一切。在终端中不带参数运行它即可打开交互式管理器： +在托管 3X-UI 面板的服务器上以 **root** 身份运行： ```bash -row-template +bash <(curl -fsSL https://github.com/iitzSeriZdev/Row-Template/releases/latest/download/install.sh) ``` -或者使用以下直接命令： - -| 命令 | 作用 | -| ------- | ------------ | -| `row-template config` | 重新配置品牌信息（服务名称、支持链接、Logo） | -| `row-template update` | 检查稳定版通道，若存在更新的版本则进行更新 | -| `row-template rollback` | 回滚到先前的版本（`--auto` 或 `--to `） | -| `row-template verify` | 检查安装是否健康 | -| `row-template version` | 打印已安装的版本 | -| `row-template uninstall` | 移除 Row-Template（不影响 3X-UI） | -| `row-template help` | 显示用法 | +安装程序会： -## 品牌与配置 +1. 从 GitHub 下载最新的稳定版本。 +2. 校验其 SHA-256 校验和（强制 —— 无法绕过）。 +3. 安全地解压并安装到 `/etc/3x-ui/sub_templates/row-template`。 +4. 全新安装时显示设计选择器（按 Enter 保留 Row）。 +5. 提示你设置品牌信息（服务名称、支持链接、徽标 —— 均为可选）。 +6. 生成并验证页面，然后在可能的情况下在面板中激活它。 -在安装期间设置你的服务名称、支持链接和 Logo，也可以随时更改它们： +如需不经选择器直接选定设计（例如在脚本中）： ```bash -row-template config +RT_TEMPLATE=editorial bash <(curl -fsSL https://github.com/iitzSeriZdev/Row-Template/releases/latest/download/install.sh) ``` -你输入的内容会作为数据存储（绝不会被执行），并以文本形式注入到页面中。将某个字段留空即可得到一个无品牌的白标页面。支持链接仅接受浏览器应当打开的协议方案（例如 `https://…`、`tg://…` 或 `mailto:…`）。 +如果你不希望直接从网络通过管道执行，可以从 [Releases 页面](https://github.com/iitzSeriZdev/Row-Template/releases/latest)下载发布文件，按照 [PROVENANCE.md](PROVENANCE.md) 中的说明自行校验校验和，然后从解压后的目录运行随附的 `install.sh`。 -## 激活 +### 激活 -Row-Template 会安装到面板用作订阅页面的目录： +Row-Template 安装在一个由面板作为订阅页面提供的目录中： ``` /etc/3x-ui/sub_templates/row-template ``` -- **自动：** 当 `sqlite3` 可用时，安装程序/管理器可以为你将面板指向 Row-Template。 -- **手动：** 否则，请自行在面板中设置——打开 **面板设置 → 订阅 → 配置文件 → 订阅主题目录**，并准确输入： +- **自动：** 当 `sqlite3` 可用时，Row-Template 会替你完成设置。它会短暂停止面板服务、写入设置、重新启动服务并核对该值。交互式安装会先显示当前设置并征求你的同意。 +- **手动：** 否则，请打开 **Panel Settings → Subscription → Profile → Sub Theme Directory** 并准确输入： ``` /etc/3x-ui/sub_templates/row-template ``` -## 更新 +## 使用 + +在终端中不带参数运行管理器以打开交互式菜单： ```bash -row-template update +row-template ``` -此命令会检查公共稳定版发布通道，显示已安装版本与可用版本，并且仅在存在更新的稳定版本时才进行更新。如果网络或发布源无法访问，它会报告无法完成检查——你的安装绝不会被视为已损坏。日常使用无需任何 URL 或手动下载。 +或直接使用命令： -## 回滚 - -```bash -row-template rollback -``` +| 命令 | 作用 | +| ------- | ------------ | +| `row-template config` | 更改服务名称、支持链接或徽标，然后重新生成页面 | +| `row-template update` | 下载、校验并激活更新的稳定版本（强制校验校验和） | +| `row-template rollback` | 恢复到之前的版本（`--auto` 或 `--to `） | +| `row-template verify` | 检查安装、面板连接和当前页面（只读） | +| `row-template version` | 显示已安装版本、最低支持版本以及检测到的 3X-UI 版本 | +| `row-template uninstall` | 移除 Row-Template 并让面板恢复其内置页面 | +| `row-template help` | 显示用法 | -从经过校验的备份中恢复先前的版本。当前版本会先被快照保存，因此即便回滚失败也可恢复。你的品牌配置会被保留。 +会修改系统的命令（`config`、`update`、`rollback`、`uninstall`）必须以 root 身份运行。 -## 验证 +- **品牌信息**以数据形式存储，从不执行，并以文本形式注入页面。将某个字段留空即可得到无品牌的页面。支持链接只接受浏览器应当打开的协议，例如 `https://…`、`tg://…` 或 `mailto:…`。 +- **更新**会检查公共稳定通道，只有存在更新的稳定版本时才会做出更改。如果无法访问发布源，`update` 会报告无法检查；你的安装绝不会因此被视为已损坏。 +- **回滚**会从经过验证的备份中恢复之前的版本。系统会先为当前版本创建快照（snapshot），因此失败的回滚也可以恢复，且你的品牌配置会被保留。 +- **卸载**会移除 Row-Template 的文件。只有当面板的 `subThemeDir` 指向 Row-Template 时才会将其清除，使面板恢复内置页面；你的入站（inbound）、客户端和证书都不会受到影响。 -```bash -row-template verify -``` +[文档](https://iitzseridev.github.io/Row-Template/)更详细地介绍了配置、品牌设置和故障排查。 -报告已安装的产物、面板接线以及服务是否健康。 +## 开发 -## 卸载 +页面由 `src/` 中可读的源代码构建而成。你需要 Node.js 22 或更高版本，运行测试还需要 Go 1.22 或更高版本。 ```bash -row-template uninstall +npm run build # regenerate template/index.html from src/ +npm run verify # check the built page against the safety gates +npm test # render the fixture pages, then run every test suite +npm run fixtures:all # render every design's fixture pages on their own +npm run lint:sh # ShellCheck every shell script +npm run preview # preview the fixture pages at http://127.0.0.1:8787 ``` -移除 Row-Template 及其文件。它 **不会** 触及 3X-UI、其数据库、你的入站、客户端或证书。 +构建是确定性的 —— 相同的源代码总会生成逐字节一致的 `template/index.html`。文档站点是 `docs/` 中的独立工作区；参见 [docs/README.md](docs/README.md)。 + +## 测试 -## 语言 +- **`npm test`** 先用 Go 渲染器生成所有设计的 fixture 页面，然后运行各测试套件：页面脚本、构建、每种设计的最终文件、发布包内容以及安装程序 —— 其发布的 shell 库会在真实的 `bash` 中针对临时 fixture 运行。 +- **`npm run verify`** 按照安全关卡检查构建好的页面，包括：完整的文档、所有构建标记均已替换、所有内容均已内联、没有远程引用、没有禁用结构、翻译完整，以及源代码中没有不可见字符。 +- **`npm run lint:sh`** 遇到任何 ShellCheck 错误即失败；`npm run lint:sh -- -S warning` 会显示完整报告。 +- **Docs 工作流**会在每个修改文档站点的 pull request 中构建该站点。 -订阅页面提供五种界面语言，并会遵循订阅用户的面板/浏览器区域设置： +## 路线图 -**English · فارسی · العربية · Русский · 简体中文** +这是方向，而非承诺： -阿拉伯语和波斯语以从右到左的方式呈现。 +- **Row-Template 1.2.0** —— 上文介绍的十五种设计和设计选择器。 +- **PasarGuard 和 Rebecca** —— 研究中。两者的页面外壳均已构建；实时状态需要对运行时代码做一处小改动或使用反向代理（reverse proxy），这一决定已推迟。参见[兼容性](https://iitzseridev.github.io/Row-Template/compatibility/)。 +- **在多个面板上安装** —— 安装程序的基础设施（面板接口、事务引擎、3X-UI 适配器和新的备份格式）已经就绪，但尚未被任何命令使用。 +- **自定义模板** —— 关于添加你自己设计的提案：[`docs/design/CUSTOM-TEMPLATES-PROPOSAL.md`](docs/design/CUSTOM-TEMPLATES-PROPOSAL.md)。 -## 问题反馈 +## 参与贡献 -请提交一个 issue： +非常欢迎问题反馈、翻译和文档修正。在提交 pull request 之前请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)，并遵守[行为准则](CODE_OF_CONDUCT.md)。 -请附上你的 Row-Template 版本（`row-template version`）、3X-UI 版本、操作系统及其版本、CPU 架构、`row-template verify` 的输出，以及清晰的复现步骤。 +**问题反馈：** 请在 提交 issue。请附上你的 Row-Template 版本（`row-template version`）、3X-UI 版本、操作系统及其版本、CPU 架构、`row-template verify` 的输出，以及清晰的复现步骤。 > **请勿包含机密信息。** 切勿粘贴订阅 URL、`subId` 值、客户端 UUID、面板用户名或密码、Cookie、令牌、面板的 `webBasePath`、TLS 密钥或真实的服务器地址。分享日志前请先对其做脱敏处理。 ## 安全 -发现了漏洞？请私下报告——参见 [SECURITY.md](SECURITY.md)。请勿为安全问题创建公开的 issue。 - -## 开发 - -这个单文件产物由 `src/` 中可读的源码构建而成： - -```bash -npm run build # regenerate template/index.html from src/ -npm run verify # check the artifact against the safety gates -npm test # run the unit and installer test suites -``` - -该构建是确定性的——相同的源码总是生成逐字节相同的 `template/index.html`。参见 [CONTRIBUTING.md](CONTRIBUTING.md)。 +发现了漏洞？请私下报告——参见 [SECURITY.md](SECURITY.md)。请勿为安全问题创建公开的 issue。[PROVENANCE.md](PROVENANCE.md) 说明了发布版本是如何构建的以及如何验证它们。 ## 支持本项目 @@ -233,7 +281,7 @@ Row-Template 是免费且开源的。如果它为你节省了时间，欢迎支 ## 许可证 -基于 [MIT License](LICENSE) 发布。随附的二维码生成器（`src/vendor/uqr`）依据其自身的 MIT 许可证包含在内。 +基于 [MIT License](LICENSE) 发布。随附的二维码生成器（`src/vendor/uqr`）依据其自身的 MIT 许可证包含在内，内嵌的 Vazirmatn 字体子集则依据 SIL Open Font License（`src/fonts/OFL.txt`）提供。 ## 开发者 From a90dfa66e83ba49e1c46276bdd467736821792e3 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 24 Sep 2026 20:02:16 +0000 Subject: [PATCH 6/7] docs(changelog): name the manager menu path exactly The manager's main menu item is "Reconfigure branding", and Template is entry 4 of its submenu; the 1.2.0 entry said "Reconfigure -> Template". Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011QC3E9ChkFK7sDFBTfwNJ3 --- CHANGELOG.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 461634e..d259692 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,8 +20,8 @@ panel. the five languages behave the same in each. - **Choosing a design.** A fresh interactive install shows a design chooser (Enter keeps Row). `RT_TEMPLATE=` picks one for a scripted install, and - the manager's **Reconfigure → Template** changes it later. Updates keep the - selected design. + the manager's **Reconfigure branding → Template** changes it later. Updates + keep the selected design. - **Checksummed designs.** Each design ships in the release with its own SHA-256 checksum. `row-template verify` checks every installed design against its checksum and confirms the live page is the selected design. From ddd81ffbfce7096ac4c160633b450db5d3776331 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 24 Sep 2026 20:27:28 +0000 Subject: [PATCH 7/7] docs: record the 1.1.0 upgrade path and the installer's companion files Follows iitzSeriZdev/Row-Template#3, which ships lib/transaction.sh and panels/ in the release and lets an install that 1.1.0's updater left incomplete be completed: - CHANGELOG 1.2.0, Compatibility: updating from 1.1.0 takes two runs of `row-template update`. The first is 1.1.0's own updater, which copies only the library and the command; the second, by 1.2.0, installs every design and the remaining installer files. `verify` reports whether the second run is needed. (This statement was held back until it could be verified; #3's upgrade test drives exactly this path with the real v1.1.0 updater.) - CHANGELOG 1.2.0, Internal: the release ships the companions, and an incomplete payload is refused. - PROVENANCE.md: the payload table gains panels/. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011QC3E9ChkFK7sDFBTfwNJ3 --- CHANGELOG.md | 10 ++++++++++ PROVENANCE.md | 1 + 2 files changed, 11 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index d259692..603bb4c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -60,6 +60,10 @@ panel. panel interface, a transaction engine, a 3X-UI panel adapter, and a format-2 backup snapshot. No `row-template` command calls any of it yet; backups and rollback still use the 1.1.0 format. +- The release ships the management library's companion files + (`lib/transaction.sh` and `panels/`), and install and update put them next + to the library. A payload whose library is present without them is refused + before anything changes. ### Development @@ -75,6 +79,12 @@ panel. ### Compatibility - Requires 3X-UI (MHSanaei) **>= 3.6.0**. +- **Updating from 1.1.0 takes two runs of `row-template update`.** The first + is carried out by 1.1.0's own updater: it installs the new version — the + page updates and your branding is kept — but copies only the library and + the command, so only Row is available. The second, carried out by 1.2.0, + installs every design and the remaining installer files. `row-template + verify` reports whether the second run is still needed. ## [1.1.0] - 2026-08-30 diff --git a/PROVENANCE.md b/PROVENANCE.md index f8a9817..58d6a7a 100644 --- a/PROVENANCE.md +++ b/PROVENANCE.md @@ -24,6 +24,7 @@ The tarball expands to a single `row-template-/` directory: | `templates//template.html` (+ `.sha256`) | Every selectable design, each with its own checksum. | | `shells///shell.html` (+ `.sha256`) | Each design's page shell per panel, packaged for research; the installer does not place them. | | `VERSION`, `install.sh`, `lib/`, `bin/` | The version, the installer and the `row-template` manager. | +| `panels/` | The panel interface layer the manager loads; installed next to `lib/`. | | `SHA256SUMS` | The checksum of every payload file, so the contents can be checked after extraction as well. | The build is deterministic: the same sources always produce a byte-identical