docs: restore stable Registryctl install URL (#638)

Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>

Author: jeremi

crates/registryctl/README.md

@@ -3,18 +3,25 @@
 `registryctl` is the adopter CLI for authoring, testing, reviewing, developing,
 and packaging Registry Stack projects.
 
-Install a pinned release without cloning the repository:
+Download the latest released installer without cloning the repository:
 
 ```sh
-tag=vX.Y.Z
-curl -fsSLO "https://github.com/registrystack/registry-stack/releases/download/${tag}/registryctl-${tag}-install.sh"
-bash "./registryctl-${tag}-install.sh"
+curl -fsSLo registryctl-install.sh https://docs.registrystack.org/install.sh
 ```
 
-The quick installer trusts GitHub and TLS, then verifies downloaded artifacts
-against the release checksums. Use [`release/VERIFY.md`](../../release/VERIFY.md)
-when you need to authenticate release signatures and provenance before
-installation.
+The stable URL serves the installer from the latest promoted Registry Stack
+documentation release. The quick installer trusts Registry Docs hosting,
+GitHub, and TLS, then verifies downloaded artifacts against the release
+checksums. The separate download and execution steps preserve download
+failures and let you inspect the installer's tag-frozen `verify_url` before
+running it. Use [`release/VERIFY.md`](../../release/VERIFY.md) when you need to
+authenticate release signatures and provenance before installation.
+
+Run the installer after applying the verification policy you need:
+
+```sh
+bash registryctl-install.sh
+```
 
 ## Newcomer workflow
 

docs/site/.gitignore

@@ -9,6 +9,7 @@ npm-debug.log*
 # Pulled product docs (build artifacts, regenerated by scripts/sync-repo-docs.mjs)
 src/content/docs/products/
 public/products/
+public/install.sh
 .repo-docs-cache/
 .archive-bundles/
 .release-docsets/

docs/site/.markdownlint-cli2.yaml

@@ -29,6 +29,7 @@ config:
       - LegendList
       - HomeLanding
       - QuickstartMeta
+      - RegistryctlInstallCommand
       - ProjectStarterSequence
       - ProjectWorkspaceJourneys
       - AuthoringConfigurationReference

docs/site/package.json

@@ -17,8 +17,8 @@
     "smoke:deployment": "node scripts/smoke-docs-deployment.mjs",
     "archive:snapshot": "node scripts/archive-lock.mjs snapshot",
     "preview": "astro preview",
-    "generate": "node scripts/generate-data.mjs && node scripts/generate-project-starters.mjs && node scripts/generate-registryctl-example-overlays.mjs && node scripts/generate-authoring-reference.mjs && node scripts/generate-diagnostic-references.mjs && node scripts/fetch-openapi.mjs && node scripts/sync-repo-docs.mjs && node scripts/generate-sidebar.mjs",
-    "generate:archive": "node scripts/generate-data.mjs && node scripts/generate-registryctl-example-overlays.mjs && node scripts/fetch-openapi.mjs && node scripts/sync-repo-docs.mjs && node scripts/generate-sidebar.mjs",
+    "generate": "node scripts/generate-data.mjs && node scripts/generate-project-starters.mjs && node scripts/generate-registryctl-installer.mjs && node scripts/generate-registryctl-example-overlays.mjs && node scripts/generate-authoring-reference.mjs && node scripts/generate-diagnostic-references.mjs && node scripts/fetch-openapi.mjs && node scripts/sync-repo-docs.mjs && node scripts/generate-sidebar.mjs",
+    "generate:archive": "node scripts/generate-data.mjs && node scripts/generate-registryctl-installer.mjs && node scripts/generate-registryctl-example-overlays.mjs && node scripts/fetch-openapi.mjs && node scripts/sync-repo-docs.mjs && node scripts/generate-sidebar.mjs",
     "pretest": "cargo --version",
     "test": "node --test \"scripts/**/*.test.mjs\"",
     "check:llms:built": "node scripts/check-llms.mjs",

docs/site/scripts/check-tutorial.sh

@@ -174,9 +174,9 @@ done
 # inside `sh` fences. Bump the expected count when you intentionally add or
 # remove a documented command.
 REGISTRYCTL_TUTORIALS=(
-	"author-registry-project:74"
+	"author-registry-project:69"
 	"configure-project-script-adapter:49"
-	"publish-spreadsheet-secured-registry-api:20"
+	"publish-spreadsheet-secured-registry-api:15"
 	"use-your-spreadsheet:9"
 	"verify-opencrvs-claims:45"
 )

docs/site/scripts/generate-registryctl-installer.mjs

@@ -0,0 +1,45 @@
+import { mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+const siteRoot = resolve(scriptDir, '..');
+const repoRoot = resolve(siteRoot, '../..');
+const canonicalInstaller = resolve(repoRoot, 'crates/registryctl/install.sh');
+const publicInstaller = resolve(siteRoot, 'public/install.sh');
+
+export async function generateRegistryctlInstaller({
+  source = canonicalInstaller,
+  destination = publicInstaller,
+  docset = process.env.DOCS_DOCSET,
+} = {}) {
+  let contents = await readFile(source, 'utf8');
+  if (!contents.startsWith('#!/usr/bin/env bash')) {
+    throw new Error(`registryctl installer has an unexpected interpreter: ${source}`);
+  }
+  if (/^v\d+\.\d+\.\d+$/.test(docset ?? '')) {
+    const versionPattern = /^default_version="v\d+\.\d+\.\d+"$/gm;
+    const matches = contents.match(versionPattern) ?? [];
+    if (matches.length !== 1) {
+      throw new Error(`registryctl installer must declare one default_version: ${source}`);
+    }
+    contents = contents.replace(versionPattern, `default_version="${docset}"`);
+  }
+
+  await mkdir(dirname(destination), { recursive: true });
+  const temporary = `${destination}.${process.pid}.tmp`;
+  try {
+    await writeFile(temporary, contents, { flag: 'wx', mode: 0o755 });
+    await rename(temporary, destination);
+  } catch (error) {
+    await unlink(temporary).catch(() => {});
+    throw error;
+  }
+
+  return contents;
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  await generateRegistryctlInstaller();
+  console.log('Generated public Registryctl installer -> public/install.sh');
+}

docs/site/scripts/generate-registryctl-installer.test.mjs

@@ -0,0 +1,47 @@
+import assert from 'node:assert/strict';
+import { mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, resolve } from 'node:path';
+import test from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+import { generateRegistryctlInstaller } from './generate-registryctl-installer.mjs';
+
+const siteRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const repoRoot = resolve(siteRoot, '../..');
+
+test('publishes the canonical Registryctl installer byte for byte for current docs', async (t) => {
+  const root = await mkdtemp(resolve(tmpdir(), 'registryctl-public-installer-'));
+  t.after(() => rm(root, { recursive: true, force: true }));
+  const source = resolve(repoRoot, 'crates/registryctl/install.sh');
+  const destination = resolve(root, 'public/install.sh');
+
+  await generateRegistryctlInstaller({ source, destination });
+
+  assert.equal(await readFile(destination, 'utf8'), await readFile(source, 'utf8'));
+  assert.notEqual((await stat(destination)).mode & 0o111, 0);
+});
+
+test('binds a release-docset installer to that exact version', async (t) => {
+  const root = await mkdtemp(resolve(tmpdir(), 'registryctl-release-installer-'));
+  t.after(() => rm(root, { recursive: true, force: true }));
+  const source = resolve(root, 'install.sh');
+  const destination = resolve(root, 'public/install.sh');
+  await writeFile(source, '#!/usr/bin/env bash\ndefault_version="v0.16.3"\necho "$default_version"\n');
+
+  await generateRegistryctlInstaller({ source, destination, docset: 'v0.17.0' });
+
+  assert.equal(
+    await readFile(destination, 'utf8'),
+    '#!/usr/bin/env bash\ndefault_version="v0.17.0"\necho "$default_version"\n',
+  );
+  assert.notEqual((await stat(destination)).mode & 0o111, 0);
+});
+
+test('current and archived docs generation publish the stable installer URL', async () => {
+  const packageJson = JSON.parse(await readFile(resolve(siteRoot, 'package.json'), 'utf8'));
+  const generator = 'node scripts/generate-registryctl-installer.mjs';
+
+  assert.match(packageJson.scripts.generate, new RegExp(generator.replaceAll('.', '\\.')));
+  assert.match(packageJson.scripts['generate:archive'], new RegExp(generator.replaceAll('.', '\\.')));
+});

docs/site/scripts/page-markdown.test.mjs

@@ -78,6 +78,28 @@ test('raw body content is included verbatim', () => {
   assert.ok(out.includes(body), 'body content not found in output');
 });
 
+test('expands the Registryctl installer component for machine-readable Markdown', () => {
+  const body = 'Install:\n\n<RegistryctlInstallCommand />\n\nThen continue.';
+  const current = buildPageMarkdown('Title', undefined, body);
+  const archived = buildPageMarkdown('Title', undefined, body, '/v/0.17.0/');
+
+  assert.match(
+    current,
+    /curl -fsSLo registryctl-install\.sh https:\/\/docs\.registrystack\.org\/install\.sh/,
+  );
+  assert.match(
+    archived,
+    /curl -fsSLo registryctl-install\.sh https:\/\/docs\.registrystack\.org\/v\/0\.17\.0\/install\.sh/,
+  );
+  assert.doesNotMatch(current, /RegistryctlInstallCommand/);
+  assert.doesNotMatch(archived, /RegistryctlInstallCommand/);
+});
+
+test('per-page Markdown route binds component expansion to the build base path', () => {
+  const routeSource = readFileSync(routePath, 'utf8');
+  assert.match(routeSource, /entry\.body \?\? '',\s*import\.meta\.env\.BASE_URL,/);
+});
+
 test('full output structure: header + title + description + body', () => {
   const out = buildPageMarkdown('My Page', 'Summary here.', 'Page body.');
   const lines = out.split('\n');

docs/site/scripts/registryctl-tutorial.test.mjs

@@ -488,19 +488,23 @@ test('current reader pages keep public starters and current command roots', () =
     read('src/content/docs/tutorials/verify-opencrvs-claims.mdx'),
   ];
   const currentText = pages.join('\n');
+  const installerCommand = read('src/components/RegistryctlInstallCommand.astro');
 
-  assert.match(currentText, /tag="v<major>\.<minor>\.<patch>"/);
-  assert.match(currentText, /registryctl-\$\{tag\}-install\.sh/);
+  assert.match(currentText, /RegistryctlInstallCommand/);
+  assert.match(installerCommand, /import\.meta\.env\.BASE_URL/);
+  assert.match(installerCommand, /curl -fsSLo registryctl-install\.sh/);
+  assert.match(currentText, /bash registryctl-install\.sh/);
+  assert.doesNotMatch(installerCommand, /\| bash/);
   assert.match(currentText, /release\/VERIFY\.md/);
-  assert.match(currentText, /quick installation path trusts GitHub and TLS/);
+  assert.match(currentText, /quick installation path trusts Registry Docs hosting, GitHub, and TLS/);
   assert.match(currentText, /--template http/);
   assert.match(currentText, /--template spreadsheet/);
   assert.match(currentText, /registryctl dev smoke/);
   assert.match(currentText, /registryctl check/);
   assert.match(currentText, /registryctl build/);
   assert.doesNotMatch(
     currentText,
-    /registryctl (?:preflight|start|stop|restart|smoke|add notary)|init --from|test --live|Bruno/,
+    /tag="v<major>|installer=|curl --proto|releases\/download\/.*install\.sh|bash "\$installer"|registryctl (?:preflight|start|stop|restart|smoke|add notary)|init --from|test --live|Bruno/,
   );
   assert.doesNotMatch(currentText, /TODO:|Evidence:/);
 });

docs/site/src/components/RegistryctlInstallCommand.astro

@@ -0,0 +1,9 @@
+---
+const installerUrl = new URL(
+  `${import.meta.env.BASE_URL}install.sh`,
+  'https://docs.registrystack.org',
+).href;
+const command = `curl -fsSLo registryctl-install.sh ${installerUrl}`;
+---
+
+<pre><code class="language-sh">{command}</code></pre>