docs: establish canonical documentation architecture (#1210)

packages/mosaic/src/installation-documentation.spec.ts

@@ -0,0 +1,56 @@
+import { readFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const repositoryRoot = resolve(packageRoot, '..', '..');
+
+const CURRENT_INSTALLATION_PAGES = ['docs/USER-GUIDE/getting-started/quickstart.md'] as const;
+
+const UNSAFE_REMOTE_EXECUTION_PATTERNS = [
+  {
+    name: 'pipe a remote response directly to a shell',
+    pattern: /\bcurl\b[^\n|]*\|\s*(?:ba|z|k)?sh\b/i,
+  },
+  {
+    name: 'execute a remote response through shell process substitution',
+    pattern: /\b(?:ba|z|k)?sh\s*<\(\s*curl\b/i,
+  },
+  {
+    name: 'fetch an installer from a mutable main or next branch',
+    pattern:
+      /(?:\/raw\/branch\/(?:main|next)\/|\/raw\/(?:refs\/heads\/)?(?:main|next)\/|\/-\/raw\/(?:main|next)\/)/i,
+  },
+] as const;
+
+function unsafeRemoteExecutionFindings(markdown: string): string[] {
+  return UNSAFE_REMOTE_EXECUTION_PATTERNS.filter(({ pattern }) => pattern.test(markdown)).map(
+    ({ name }) => name,
+  );
+}
+
+describe('current installation documentation safety', (): void => {
+  it.each(CURRENT_INSTALLATION_PAGES)(
+    'keeps %s current without mutable remote-script execution',
+    async (relativePath): Promise<void> => {
+      const markdown = await readFile(resolve(repositoryRoot, relativePath), 'utf8');
+
+      expect(markdown).toMatch(/^---\n[\s\S]*?\nstatus: current\n[\s\S]*?\n---\n/);
+      expect(unsafeRemoteExecutionFindings(markdown)).toEqual([]);
+    },
+  );
+
+  it('proves the control reddens for each prohibited installation shape', (): void => {
+    const unsafeExamples = [
+      'curl -fsSL https://example.invalid/install.sh | bash',
+      'bash <(curl -fsSL https://example.invalid/install.sh)',
+      'curl -fsSL https://example.invalid/project/raw/branch/main/install.sh -o install.sh',
+      'curl -fsSL https://example.invalid/project/-/raw/next/install.sh -o install.sh',
+    ];
+
+    for (const example of unsafeExamples) {
+      expect(unsafeRemoteExecutionFindings(example), example).not.toEqual([]);
+    }
+  });
+});

packages/mosaic/src/lease-broker/framework_skill_portability_unittest.py

@@ -14,8 +14,8 @@ REPOSITORY = MOSAIC.parents[1]
 SKILLS = MOSAIC / "framework/skills"
 REFRESH_SKILL = SKILLS / "mosaic-context-refresh/SKILL.md"
 GATE_PATH = MOSAIC / "framework/tools/lease-broker/mutator-gate.py"
-COMPACTION_THREAT = REPOSITORY / "docs/architecture/compaction-revocation.md"
-RECEIPT_PROTOCOL = REPOSITORY / "docs/architecture/lease-broker-protocol.md"
+COMPACTION_THREAT = REPOSITORY / "docs/DEVELOPER-GUIDE/architecture/compaction-revocation.md"
+RECEIPT_PROTOCOL = REPOSITORY / "docs/DEVELOPER-GUIDE/architecture/lease-broker-protocol.md"
 OPERATOR_HOME = re.compile(r"/home/[^/\s]+/")
 RECOVERY_PLACEHOLDER = "/absolute/path/to/mosaic/tools/lease-broker/recover-context.py"
 CONSTRUCTION_PLACEHOLDER = "/absolute/path/to/mosaic-context-refresh-construction.json"

packages/mosaic/src/mutator-gate/mutator-gate.acceptance.spec.ts

@@ -40,7 +40,10 @@ const gatePath = join(frameworkRoot, 'tools/lease-broker/mutator-gate.py');
 const launchGuardPath = join(frameworkRoot, 'tools/lease-broker/check-runtime-launches.py');
 const launcherPath = join(frameworkRoot, 'tools/lease-broker/launch-runtime.py');
 const revokerPath = join(frameworkRoot, 'tools/lease-broker/revoke-lease.py');
-const compactionThreatPath = join(repositoryRoot, 'docs/architecture/compaction-revocation.md');
+const compactionThreatPath = join(
+  repositoryRoot,
+  'docs/DEVELOPER-GUIDE/architecture/compaction-revocation.md',
+);
 const claudeSettingsPath = join(frameworkRoot, 'runtime/claude/settings.json');
 const piExtensionPath = join(frameworkRoot, 'runtime/pi/mosaic-extension.ts');
 const piLifecyclePath = join(frameworkRoot, 'runtime/pi/lease-lifecycle.ts');