hd-garden 0.14.8 → 0.14.11

package/app/components/ArticleTitle.tsx

@@ -1,20 +1,40 @@
+"use client";
+
+import { useLayoutEffect, useRef } from "react";
 import { splitTitle, titleLineScale } from "../../ui/garden/title.mjs";
+import { mountArticleTitle } from "../../ui/garden/article-title-fit.mjs";
+import fitRuntime from "../../ui/garden/feature-title-fit.mjs?raw";
+import articleRuntime from "../../ui/garden/article-title-fit.mjs?raw";
+
+// Preserve one authored runtime across SSR/browser builds; function.toString()
+// would be changed independently by server and client optimizers.
+const ARTICLE_TITLE_BOOT = `(()=>{${fitRuntime.replace(/^export /gm, "")}
+${articleRuntime.replace(/^import\s+[^;]+;\s*/u, "").replace(/^export /gm, "")}
+mountArticleTitle(document.currentScript.parentElement);})();`;
 
 export function ArticleTitle({ title, className = "" }: { title: string; className?: string }) {
+  const heading = useRef<HTMLHeadingElement>(null);
   const split = splitTitle(title);
+  useLayoutEffect(() => mountArticleTitle(heading.current?.parentElement), [title]);
   if (!split.split) {
     return <h1 className={`p-name${className ? ` ${className}` : ""}`}>{title}</h1>;
   }
   const scale = titleLineScale(split.lines);
   return (
-    <h1 className={`p-name h1-br${className ? ` ${className}` : ""}`} style={{ ["--l" as string]: scale }}>
-      <span className="h1-line">{split.lines[0]}</span>
-      <span className="vh">{split.separator}</span>
-      <span className="h1-line">{split.lines[1]}</span>
-    </h1>
+    <>
+      <h1
+        id="at"
+        ref={heading}
+        data-article-title=""
+        className={`p-name h1-br${className ? ` ${className}` : ""}`}
+        style={{ ["--l" as string]: scale }}
+      >
+        <span className="h1-line">{split.lines[0]}</span>
+        <span className="vh">{split.separator}</span>
+        <span className="h1-line">{split.lines[1]}</span>
+      </h1>
+      <style data-article-title-rules="">{""}</style>
+      <script data-article-title-boot="" dangerouslySetInnerHTML={{ __html: ARTICLE_TITLE_BOOT }} />
+    </>
   );
 }
-
-export function originalUrl(entry: { original?: unknown }) {
-  return typeof entry.original === "string" && /^https?:\/\//iu.test(entry.original) ? entry.original : "";
-}

package/app/components/PostReadingView.tsx

@@ -2,7 +2,8 @@ import Link from "next/link";
 import { CoverImage } from "./CoverImage";
 import { ArticleMeasure } from "./ArticleMeasure";
 import { ArticleReferences } from "./ArticleReferences";
-import { ArticleTitle, originalUrl } from "./ArticleTitle";
+import { ArticleTitle } from "./ArticleTitle";
+import { originalUrl } from "../../ui/garden/title.mjs";
 import { MarkdownArticle } from "./MarkdownArticle";
 import { TableOfContents } from "./TableOfContents";
 import { Comments } from "./Comments";

package/app/components/TableOfContents.tsx

@@ -15,7 +15,7 @@ import { usePathname } from "next/navigation";
 import { nestHeadings, expandedTocSections, toggleTocSection, type TocHeading, type TocNode, type TocExpansion } from "../lib/toc-expansion";
 import { createPortal } from "react-dom";
 import { TOC_PANEL_ID, TOC_CONTROL_ID, TOC_CLOSED_ID } from "../lib/reading-navigation";
-import { X } from "@phosphor-icons/react";
+import { CaretUp, CaretDown, X } from "@phosphor-icons/react";
 import { ui, type UiLang } from "../lib/i18n";
 
 type TocProps = { headings: TocHeading[]; label?: string; lang?: UiLang };
@@ -457,6 +457,18 @@ function ContentsSession({
       >
         <div className="toc-header">
           <p>{label}</p>
+          {tree.some((node) => node.children.length > 0) ? <div className="toc-mode-controls">
+            <button
+              type="button"
+              data-toc-mode-toggle=""
+              aria-controls={listId}
+              aria-label={expansion.mode === "follow" ? t.tocExpandAll : t.tocResumeFollow}
+              title={expansion.mode === "follow" ? t.tocExpandAll : t.tocResumeFollow}
+              onClick={() => setExpansion({ mode: expansion.mode === "follow" ? "all" : "follow" })}
+            >
+              {expansion.mode === "follow" ? <CaretDown size={14} aria-hidden="true" /> : <CaretUp size={14} aria-hidden="true" />}
+            </button>
+          </div> : null}
           <button
             ref={mobileCloseRef}
             className="toc-mobile-close"
@@ -470,11 +482,6 @@ function ContentsSession({
             <X size={18} aria-hidden="true" />
           </a>
         </div>
-        {tree.some((node) => node.children.length > 0) ? <div className="toc-mode-controls" role="group" aria-label={t.tocDisplay}>
-          <button type="button" data-toc-follow="" aria-controls={listId} aria-pressed={expansion.mode === "follow"} onClick={() => setExpansion({ mode: "follow" })}>{t.tocFollow}</button>
-          <button type="button" data-toc-expand-all="" aria-controls={listId} aria-pressed={expansion.mode === "all"} onClick={() => setExpansion({ mode: "all" })}>{t.tocExpandAll}</button>
-          <span className="toc-mode-status" role="status">{expansion.mode === "manual" ? t.tocManual : ""}</span>
-        </div> : null}
         <ol id={listId} ref={listRef} className="toc-list" role="list">
           {tree.map((node, index) => renderNode(node, [index]))}
         </ol>

package/app/globals.css

@@ -1735,6 +1735,8 @@ button {
 }
 
 .toc-header > p {
+  flex: 1 1 auto;
+  min-width: 0;
   margin: 0;
   color: var(--accent);
   font-size: 12px;
@@ -1810,12 +1812,9 @@ button {
 
 .toc-list > .toc-section > .toc-item-row > a { font-weight: 600; }
 .toc-sublist > .toc-section > .toc-item-row > a { font-weight: 400; }
-.toc-mode-controls { display: flex; flex-wrap: wrap; align-items: center; gap: 4px 10px; flex: 0 0 auto; margin-bottom: 10px; }
-.toc-mode-controls button { min-height: 32px; padding: 4px 0; border: 0; background: transparent; color: var(--muted); font: inherit; cursor: pointer; }
-.toc-mode-controls button[aria-pressed="true"] { color: var(--ink); font-weight: 600; text-decoration: underline; text-underline-offset: 4px; }
+.toc-mode-controls { display: flex; align-items: center; flex: 0 0 auto; margin-left: auto; }
+.toc-mode-controls button { display: grid; place-items: center; width: 24px; height: 24px; padding: 0; border: 0; background: transparent; color: var(--muted); cursor: pointer; touch-action: manipulation; }
 .toc-mode-controls button:focus-visible { outline: 2px solid var(--ink); outline-offset: 3px; }
-.toc-mode-status { color: var(--muted); }
-.toc-mode-status:empty { display: none; }
 
 .toc a:hover {
   color: var(--ink);
@@ -3872,7 +3871,6 @@ html[data-theme="dark"] .search-footer {
      panel, because the post layout's desktop rule overrides the panel's
      padding on post pages but not on column pages. */
   .toc .toc-header,
-  .toc .toc-mode-controls,
   .toc .toc-list {
     padding-left: max(20px, env(safe-area-inset-left));
     padding-right: max(20px, env(safe-area-inset-right));
@@ -3880,7 +3878,7 @@ html[data-theme="dark"] .search-footer {
 
   .toc .toc-item-row > a { display: flex; align-items: center; min-height: 40px; padding-block: 4px; }
   .toc .toc-section-toggle { min-width: 40px; min-height: 40px; }
-  .toc .toc-mode-controls button { min-height: 44px; }
+  .toc .toc-mode-controls button { width: 44px; height: 44px; }
 
   .toc .toc-list .toc-section {
     margin: 2px 0;

package/app/lib/i18n.ts

@@ -38,10 +38,8 @@ const zh = {
   columnNewestFirst: (title: string | undefined) => `${title}，从新到旧`,
   toc: "本篇目录",
   tocShort: "目录",
-  tocDisplay: "目录展开方式",
-  tocFollow: "跟随阅读",
+  tocResumeFollow: "恢复跟读",
   tocExpandAll: "全部展开",
-  tocManual: "手动调整",
   tocPage: "本页目录",
   open: "打开",
   close: "关闭",
@@ -300,10 +298,8 @@ const en: typeof zh = {
   columnNewestFirst: (title: string | undefined) => `${title}, newest first`,
   toc: "Contents",
   tocShort: "TOC",
-  tocDisplay: "Contents display",
-  tocFollow: "Follow reading",
+  tocResumeFollow: "Resume following",
   tocExpandAll: "Expand all",
-  tocManual: "Manual selection",
   tocPage: "On this page",
   open: "Open ",
   close: "Close ",

package/editors/dist/typora/manifest.json

@@ -5,7 +5,7 @@
   "author": "hedon",
   "authorUrl": "https://github.com/hedon954",
   "repo": "hedon954/garden",
-  "version": "0.14.8",
+  "version": "0.14.11",
   "minAppVersion": "1.5.0",
   "minCoreVersion": "2.10.52",
   "platforms": [

package/editors/dist/typora/style.css

@@ -2532,6 +2532,15 @@
     min-width: 0;
   }
 
+  /* Columnized centered rows stretch labels to 100% width, so align-items
+     can center arrows but not text. Center direct labels only; explicit
+     start/end and nested cards or prose stay as authored. */
+  .g-compose-row:not([data-wrap="nowrap"])[data-align="center"] > .g-compose-h:not([data-align="start"]):not([data-align="end"]),
+  .g-compose-row:not([data-wrap="nowrap"])[data-align="center"] > .g-compose-text:not([data-align="start"]):not([data-align="end"]),
+  .g-compose-row:not([data-wrap="nowrap"])[data-align="center"] > .g-compose-caption-inline:not([data-align="start"]):not([data-align="end"]) {
+    text-align: center;
+  }
+
   .g-compose-arrow[data-dir="right"] {
     transform: none;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hd-garden",
-  "version": "0.14.8",
+  "version": "0.14.11",
   "private": false,
   "description": "用 Markdown 写作、用 GitHub Pages 发布的个人博客引擎。",
   "license": "MIT",

package/scripts/release.py

@@ -0,0 +1,367 @@
+#!/usr/bin/env python3
+"""Safe checks by default; explicit execute mode requires current release authorization."""
+import argparse
+import base64
+import fcntl
+import hashlib
+import io
+import json
+import os
+from pathlib import Path
+import subprocess
+import sys
+import tarfile
+import urllib.error
+import urllib.request
+import zipfile
+
+PHASES = ('test', 'pack', 'linux', 'tag-plan', 'published', 'blog-check', 'deployed')
+ENGINE = 'hedon954/garden'
+BLOG = 'hedon954/garden-blog'
+PAGES = 'hedon954/hedon954.github.io'
+
+
+def require(ok, message):
+    if not ok:
+        raise RuntimeError(message)
+
+
+def digest(data):
+    return hashlib.sha256(data).hexdigest()
+
+
+def command(args, cwd):
+    return subprocess.check_output(args, cwd=cwd, stderr=subprocess.PIPE).decode().rstrip('\n')
+
+
+def git(root, *args):
+    return command(['git', *args], root)
+
+
+def atomic_json(path, data):
+    temporary = path.with_suffix('.tmp')
+    temporary.write_text(json.dumps(data, ensure_ascii=False, indent=2) + '\n')
+    temporary.replace(path)
+
+
+def snapshot(root):
+    names = git(root, 'ls-files', '--cached', '--others', '--exclude-standard', '-z').split('\0')
+    result = {}
+    for name in sorted(set(filter(None, names))):
+        p = root / name
+        result[name] = ('link:' + os.readlink(p) if p.is_symlink() else
+                        digest(p.read_bytes()) if p.is_file() else 'MISSING')
+    return result
+
+
+def protect(before, after, allowed=()):
+    changed = [p for p in before.keys() | after.keys()
+               if p not in allowed and before.get(p) != after.get(p)]
+    require(not changed, 'Protected files changed; preserve and review manually: ' + ', '.join(sorted(changed)))
+
+
+def canonical_remote(url):
+    return url.removesuffix('.git').replace('git@github.com:', 'https://github.com/')
+
+
+def validate_layout(root, blog):
+    require(canonical_remote(git(root, 'remote', 'get-url', 'origin')) == 'https://github.com/' + BLOG,
+            'origin must be garden-blog; never infer the push remote')
+    require(canonical_remote(git(root, 'remote', 'get-url', 'upstream')) == 'https://github.com/' + ENGINE,
+            'upstream must be garden engine')
+    require(git(root, 'rev-parse', '--path-format=absolute', '--git-common-dir') ==
+            git(blog, 'rev-parse', '--path-format=absolute', '--git-common-dir'), 'Expected existing shared worktrees')
+
+
+def preflight(root, blog):
+    validate_layout(root, blog)
+    version = json.loads((root / 'package.json').read_text())['version']
+    require(len(version.split('.')) == 3 and all(p.isdigit() for p in version.split('.')), 'Stable version required')
+    command(['node', 'scripts/sync-editor-version.mjs', '--check'], root)
+    lock = json.loads((root / 'package-lock.json').read_text())
+    require(lock['version'] == version == lock['packages']['']['version'], 'Root lock version mismatch')
+    return version, git(root, 'rev-parse', 'HEAD')
+
+
+def http(url):
+    request = urllib.request.Request(url, headers={'Cache-Control': 'no-cache', 'User-Agent': 'Garden-release-check'})
+    try:
+        with urllib.request.urlopen(request, timeout=45) as response:
+            require(response.status == 200, 'HTTP not 200: ' + url)
+            return response.read()
+    except urllib.error.HTTPError:
+        raise
+    except (urllib.error.URLError, TimeoutError):
+        result = subprocess.run(['curl', '--location', '--silent', '--show-error', '--connect-timeout', '10',
+                                 '--max-time', '45', '--write-out', '\n%{http_code}', url], capture_output=True)
+        body, separator, status = result.stdout.rpartition(b'\n')
+        require(result.returncode == 0 and separator and status.isdigit(), 'Public HTTPS read failed; never infer absence')
+        code = int(status)
+        if code != 200:
+            raise urllib.error.HTTPError(url, code, 'HTTPS response', None, io.BytesIO(body))
+        return body
+
+
+def registry(version):
+    try:
+        return json.loads(http('https://registry.npmjs.org/hd-garden/' + version))
+    except urllib.error.HTTPError as error:
+        if error.code == 404:
+            return None
+        raise
+
+
+def api(path, root):
+    return json.loads(command(['gh', 'api', path], root))
+
+
+def tar_files(data):
+    with tarfile.open(fileobj=io.BytesIO(data), mode='r:gz') as archive:
+        return {m.name.removeprefix('package/'): archive.extractfile(m).read()
+                for m in archive.getmembers() if m.isfile()}
+
+
+def package_audit(data, version, assets=None):
+    files = tar_files(data)
+    require(json.loads(files['package.json'])['version'] == version, 'npm version mismatch')
+    paths = [f'editors/dist/vscode/garden-ui-{version}.vsix', f'editors/dist/garden-typora-{version}.zip']
+    for p in paths:
+        require(p in files, 'Missing packaged editor: ' + p)
+        if assets is not None:
+            require(files[p] == assets[Path(p).name], 'Editor bytes mismatch: ' + p)
+    with zipfile.ZipFile(io.BytesIO(files[paths[0]])) as archive:
+        require(json.loads(archive.read('extension/package.json'))['version'] == version, 'VSIX version mismatch')
+    with zipfile.ZipFile(io.BytesIO(files[paths[1]])) as archive:
+        manifests = [p for p in archive.namelist() if p.endswith('/manifest.json')]
+        require(len(manifests) == 1 and json.loads(archive.read(manifests[0]))['version'] == version,
+                'Typora version mismatch')
+    return {p: digest(files[p]) for p in paths}
+
+
+def source_audit(root, data):
+    tracked = set(git(root, 'ls-files', '-z').split('\0'))
+    compared = 0
+    for name, content in tar_files(data).items():
+        if name in tracked:
+            require((root / name).read_bytes() == content, 'Packed source differs from clean commit: ' + name)
+            compared += 1
+    require(compared > 0, 'No source files verified in archive')
+    return compared
+
+
+def linux_evidence(root, commit):
+    runs = api(f'repos/{ENGINE}/actions/runs?head_sha={commit}&per_page=100', root)['workflow_runs']
+    good = [r for r in runs if r['head_sha'] == commit and r.get('head_branch') == 'main'
+            and r.get('event') == 'push' and r.get('path') == '.github/workflows/verify.yml'
+            and r.get('status') == 'completed' and r.get('conclusion') == 'success']
+    require(good, 'No successful main Linux full-test workflow for this exact commit; do not tag')
+    run = max(good, key=lambda r: r['id'])
+    jobs = api(f'repos/{ENGINE}/actions/runs/{run["id"]}/jobs?per_page=100', root)['jobs']
+    job = next((j for j in jobs if j['name'] == 'verify'), None)
+    require(job and job['conclusion'] == 'success' and any(s.startswith('ubuntu') for s in job['labels']),
+            'Linux verify job missing, skipped, or failed')
+    steps = {s['name']: s.get('conclusion') for s in job['steps']}
+    for name in ['Run npm test', 'A new site from garden init installs the packed engine and builds', 'Verify GitHub Pages export']:
+        require(steps.get(name) == 'success', 'Required CI step did not pass: ' + name)
+    return {'run': run['html_url'], 'commit': commit}
+
+
+def tag_plan(root, version, commit):
+    proof = linux_evidence(root, commit)
+    require(registry(version) is None, 'Version already published: never overwrite or republish')
+    require(not git(root, 'ls-remote', '--tags', 'upstream', 'refs/tags/v' + version), 'Remote tag already exists')
+    local = command(['git', 'tag', '--list', 'v' + version], root)
+    require(not local, 'Local tag already exists; reconcile manually, never delete or overwrite')
+    require(git(root, 'ls-remote', 'upstream', 'refs/heads/main').split()[0] == commit,
+            'upstream/main must equal the tested commit')
+    return {**proof, 'manualOnly': [f'git tag -a v{version} {commit} -m "Release {version}"',
+                                   f'git push upstream refs/tags/v{version}']}
+
+
+def npm_archive(metadata):
+    require(metadata['dist']['tarball'].startswith('https://registry.npmjs.org/hd-garden/-/'), 'Unexpected npm artifact URL')
+    data = http(metadata['dist']['tarball'])
+    integrity = 'sha512-' + base64.b64encode(hashlib.sha512(data).digest()).decode()
+    require(integrity in metadata['dist']['integrity'].split(), 'Official npm SHA512 mismatch')
+    return data
+
+
+def published(root, version, commit):
+    metadata = registry(version)
+    require(metadata and metadata.get('gitHead') == commit, 'Published gitHead mismatch or version absent')
+    remote = git(root, 'ls-remote', 'upstream', 'refs/tags/v' + version + '^{}')
+    require(remote and remote.split()[0] == commit, 'Annotated release tag does not resolve to source commit')
+    data = npm_archive(metadata)
+    release = api(f'repos/{ENGINE}/releases/tags/v{version}', root)
+    require(not release['draft'] and not release['prerelease'], 'Not a formal Release')
+    assets = {a['name']: http(a['browser_download_url']) for a in release['assets']
+              if a['name'] in [f'garden-ui-{version}.vsix', f'garden-typora-{version}.zip']}
+    hashes = package_audit(data, version, assets)
+    return {'gitHead': commit, 'npmSHA256': digest(data), 'sourceFiles': source_audit(root, data), 'release': release['html_url'], 'editorSHA256': hashes}
+
+
+def consumer(blog, version):
+    require(json.loads((blog / 'package.json').read_text())['dependencies']['hd-garden'] == '^' + version,
+            'First explicitly install hd-garden@^VERSION from registry; this tool never changes dependencies')
+    installed = blog / 'node_modules/hd-garden'
+    require(installed.is_dir() and not installed.is_symlink(), 'Consumer must not be a local file link')
+    lock = json.loads((blog / 'package-lock.json').read_text())['packages']['node_modules/hd-garden']
+    metadata = registry(version)
+    require(metadata and lock.get('version') == version and not lock.get('link')
+            and lock.get('resolved') == metadata['dist']['tarball']
+            and lock.get('integrity') == metadata['dist']['integrity'], 'Registry consumer lock mismatch')
+    require(json.loads((installed / 'package.json').read_text())['version'] == version, 'Installed version mismatch')
+    for name, data in tar_files(npm_archive(metadata)).items():
+        p = installed / name
+        require(p.resolve().is_relative_to(installed.resolve()) and p.is_file() and not p.is_symlink()
+                and p.read_bytes() == data, 'Installed registry bytes differ: ' + name)
+
+
+def deployed(root, blog):
+    commit = git(blog, 'rev-parse', 'HEAD')
+    require(git(blog, 'ls-remote', 'origin', 'refs/heads/main').split()[0] == commit, 'Blog is not pushed normally yet')
+    def successful(repo, sha, path):
+        runs = api(f'repos/{repo}/actions/runs?head_sha={sha}&per_page=100', root)['workflow_runs']
+        good = [r for r in runs if r.get('head_sha') == sha and r.get('path') == path
+                and r.get('status') == 'completed' and r.get('conclusion') == 'success']
+        require(good, 'No successful deployment for ' + repo + ' at ' + sha)
+        return max(good, key=lambda r: r['id'])['html_url']
+    source_run = successful(BLOG, commit, '.github/workflows/pages.yml')
+    branch = api(f'repos/{PAGES}/branches/main', root)['commit']
+    require(branch['commit']['message'] == 'Deploy ' + commit, 'Public snapshot is not this blog commit')
+    pages_run = successful(PAGES, branch['sha'], 'dynamic/pages/pages-build-deployment')
+    tree = api(f'repos/{PAGES}/git/trees/{branch["sha"]}?recursive=1', root)
+    require(not tree.get('truncated'), 'Incomplete snapshot tree')
+    from html.parser import HTMLParser
+    from urllib.parse import unquote, urljoin, urlsplit
+    blobs = {x['path']: x['sha'] for x in tree['tree'] if x['type'] == 'blob'}
+    assets = set()
+    class Resources(HTMLParser):
+        def handle_starttag(self, tag, attributes):
+            a = dict(attributes)
+            value = a.get('src') if tag == 'script' else a.get('href') if tag == 'link' else None
+            if value:
+                u = urlsplit(urljoin('https://hedon.top/', value))
+                if u.netloc == 'hedon.top' and u.path.endswith(('.css', '.js')):
+                    assets.add(unquote(u.path).lstrip('/'))
+    def check(path):
+        url = 'https://hedon.top/' + path.removesuffix('index.html')
+        data = http(url)
+        sha = hashlib.sha1(b'blob ' + str(len(data)).encode() + b'\0' + data).hexdigest()
+        require(blobs.get(path) == sha, 'Production differs from new snapshot: ' + url)
+        return {'url': url, 'sha256': digest(data)}, data
+    pages = []
+    targets = ['index.html'] + [p for p in blobs if p.startswith('blog/') and p.endswith('/index.html') and 'inspired' in p.lower()]
+    require(len(targets) > 1, 'Expected actual Inspired article in snapshot')
+    for path in targets:
+        info, data = check(path); pages.append(info); Resources().feed(data.decode())
+    evidence = []
+    for path in sorted(assets):
+        info, _ = check(path); evidence.append(info)
+    require(evidence, 'No production CSS/JS discovered')
+    return {'sourceCI': source_run, 'pagesCI': pages_run, 'snapshot': branch['sha'], 'pages': pages, 'assets': evidence}
+
+
+def run_steps(root, directory, steps):
+    evidence = []
+    for number, (cwd, args, extra_env) in enumerate(steps):
+        receipt = directory / f'{number}.json'
+        log = directory / f'{number}.log'
+        inputs = snapshot(cwd)
+        identity = {'cwd': str(cwd), 'argv': args, 'env': extra_env, 'inputs': inputs}
+        if receipt.exists():
+            saved = json.loads(receipt.read_text())
+            if saved['identity'] == identity and saved['exit'] == 0 and log.exists() and saved['logSHA256'] == digest(log.read_bytes()):
+                evidence.append(saved); continue
+        with log.open('wb') as stream:
+            result = subprocess.run(args, cwd=cwd, env={**os.environ, **extra_env}, stdout=stream, stderr=subprocess.STDOUT)
+        saved = {'identity': identity, 'exit': result.returncode, 'logSHA256': digest(log.read_bytes())}
+        atomic_json(receipt, saved)
+        protect(inputs, snapshot(cwd))
+        require(result.returncode == 0, f'Failed {args}; see {log}; no later phase executed')
+        evidence.append(saved)
+    return evidence
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('phase', nargs='?', default='plan', choices=['plan', 'status', 'execute', *PHASES])
+    parser.add_argument('--blog', type=Path)
+    parser.add_argument('--run', action='store_true', help='run selected checks; execute mode additionally requires current approval and exact --confirm')
+    parser.add_argument('--version', help='target stable release version, execute mode only')
+    parser.add_argument('--confirm', help='exact phrase: release hd-garden VERSION; operator must have current approval')
+    parser.add_argument('--session', default='default', help='reviewed new source after a failed attempt may use a new session')
+    parser.add_argument('--retry-stage', choices=['version', 'source-push', 'tag-create', 'tag-push', 'vsix', 'blog-pin', 'blog-commit', 'blog-push'])
+    parser.add_argument('--wait-seconds', type=int, default=1200)
+    args = parser.parse_args()
+    root = Path(__file__).resolve().parent.parent
+    blog = (args.blog or root.parent / 'garden-blog').resolve()
+    if args.phase == 'execute':
+        sys.dont_write_bytecode = True
+        from release_executor import entry
+        print(json.dumps(entry(root, blog, args), ensure_ascii=False, indent=2)); return
+    version, commit = preflight(root, blog)
+    directory = root / '.garden/release' / commit
+    if args.phase in ('plan', 'status') or not args.run:
+        state = directory / 'state.json'
+        print(json.dumps({'version': version, 'commit': commit, 'phases': PHASES, 'requested': args.phase,
+                          'dryRun': True, 'recordedPhases': list(json.loads(state.read_text())['phases']) if state.exists() else [],
+                          'statePath': str(state),
+                          'externalWrites': 'Check modes never write remotely. execute --run requires current approval and exact confirmation.'}, indent=2))
+        return
+    require(not git(root, 'status', '--porcelain=v1'), 'Commit/review source first; checks must bind to clean engine HEAD')
+    directory.mkdir(parents=True, exist_ok=True)
+    with (directory / 'lock').open('w') as lock:
+        fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        state_path = directory / 'state.json'
+        before = {'engine': snapshot(root), 'blog': snapshot(blog)}
+        state = json.loads(state_path.read_text()) if state_path.exists() else {'commit': commit, 'version': version, 'protected': before, 'phases': {}}
+        require(state['commit'] == commit and state['version'] == version, 'Stale evidence identity')
+        for name in before:
+            protect(state['protected'][name], before[name], ('package.json', 'package-lock.json') if name == 'blog' else ())
+        phase_dir = directory / args.phase
+        phase_dir.mkdir(exist_ok=True)
+        atomic_json(state_path, state)
+        if args.phase == 'test':
+            result = run_steps(root, phase_dir, [(root, ['npm', 'test'], {})])
+        elif args.phase == 'pack':
+            require((directory / 'test/0.json').exists(), 'Run test phase first')
+            test = json.loads((directory / 'test/0.json').read_text())
+            require(test['exit'] == 0 and test['identity']['inputs'] == snapshot(root)
+                    and test['logSHA256'] == digest((directory / 'test/0.log').read_bytes()), 'Tests missing or stale')
+            archive_path = phase_dir / f'hd-garden-{version}.tgz'
+            old_pack = state['phases'].get('pack')
+            if not archive_path.exists() or (old_pack and (old_pack['npmSHA256'] != digest(archive_path.read_bytes()) or any(not (root / p).exists() or digest((root / p).read_bytes()) != h for p, h in old_pack['editorSHA256'].items()))):
+                (phase_dir / '0.json').unlink(missing_ok=True)
+            run_steps(root, phase_dir, [(root, ['npm', 'pack', '--json', '--pack-destination', str(phase_dir)], {})])
+            data = (phase_dir / f'hd-garden-{version}.tgz').read_bytes()
+            assets = {f'garden-ui-{version}.vsix': (root / f'editors/dist/vscode/garden-ui-{version}.vsix').read_bytes(),
+                      f'garden-typora-{version}.zip': (root / f'editors/dist/garden-typora-{version}.zip').read_bytes()}
+            result = {'npmSHA256': digest(data), 'sourceFiles': source_audit(root, data), 'editorSHA256': package_audit(data, version, assets)}
+        elif args.phase == 'linux': result = linux_evidence(root, commit)
+        elif args.phase == 'tag-plan':
+            packed = state['phases'].get('pack')
+            archive = directory / 'pack' / f'hd-garden-{version}.tgz'
+            require(packed and archive.exists() and packed['npmSHA256'] == digest(archive.read_bytes()),
+                    'Pack proof missing or artifact changed; do not tag')
+            require(packed['editorSHA256'] == package_audit(archive.read_bytes(), version), 'Package evidence changed')
+            result = tag_plan(root, version, commit)
+        elif args.phase == 'published': result = published(root, version, commit)
+        elif args.phase == 'blog-check':
+            consumer(blog, version)
+            result = run_steps(root, phase_dir, [(blog, ['node', 'scripts/check-lockfile-registry.mjs'], {}),
+                (blog, ['./node_modules/.bin/garden', 'verify'], {}), (blog, ['npm', 'run', 'build'], {'STATIC_EXPORT': '1'}),
+                (blog, ['npm', 'run', 'pages:validate'], {}), (blog, ['./node_modules/.bin/garden', 'verify', '--rendered'], {})])
+        else: result = deployed(root, blog)
+        for name, path in [('engine', root), ('blog', blog)]: protect(before[name], snapshot(path))
+        state['phases'][args.phase] = result
+        atomic_json(state_path, state)
+        print(json.dumps({'phase': args.phase, 'commit': commit, 'version': version, 'evidence': {'verifiedSteps': len(result)} if isinstance(result, list) else result, 'statePath': str(state_path)}, indent=2))
+
+
+if __name__ == '__main__':
+    try:
+        main()
+    except (RuntimeError, OSError, subprocess.CalledProcessError, subprocess.TimeoutExpired, KeyError, ValueError, tarfile.TarError, zipfile.BadZipFile) as error:
+        print('STOP:', str(error), file=sys.stderr)
+        sys.exit(1)