@grada-run/grada 0.32.0 → 0.33.0

package/tests/helpers/clack.js

@@ -0,0 +1,103 @@
+// Centralized `@clack/prompts` mock for the test suite.
+//
+// Every handle is a stable per-file singleton (Vitest isolates modules per
+// test file), so tests can import handles directly:
+//
+//   import { clackPromptsMockFactory, mockConfirm } from './helpers/clack.js';
+//   vi.mock('@clack/prompts', () => clackPromptsMockFactory());
+//
+// Rules preserved from the previously hand-rolled blocks:
+// - Bare defaults: no preset return values. Tests needing a specific answer
+//   override per-test (e.g. `mockConfirm.mockResolvedValue(true)`).
+// - `isCancel` keeps the real behavior (`typeof value === 'symbol'`), wrapped
+//   in a `vi.fn` so files like apply.test.js can still override it.
+// - The spinner returns a fresh per-call instance (isolated start/stop/
+//   message) that also forwards into the shared aggregate handles, so both
+//   per-instance assertions (`spin.stop`) and aggregate assertions
+//   (`mockSpinnerStart`) keep working. Every instance is pushed to
+//   `createdSpinners` for message-sequence assertions.
+import { vi } from 'vitest';
+
+export const mockIntro = vi.fn();
+export const mockOutro = vi.fn();
+export const mockText = vi.fn();
+export const mockSelect = vi.fn();
+export const mockConfirm = vi.fn();
+export const mockPassword = vi.fn();
+export const mockMultiselect = vi.fn();
+export const mockNote = vi.fn();
+export const mockGroup = vi.fn();
+export const mockCancel = vi.fn();
+export const mockIsCancel = vi.fn((value) => typeof value === 'symbol');
+
+export const mockSpinnerStart = vi.fn();
+export const mockSpinnerStop = vi.fn();
+export const mockSpinnerMessage = vi.fn();
+
+export const mockLogInfo = vi.fn();
+export const mockLogWarn = vi.fn();
+export const mockLogMessage = vi.fn();
+export const mockLogSuccess = vi.fn();
+export const mockLogError = vi.fn();
+
+export const createdSpinners = [];
+
+export const mockSpinner = vi.fn(() => {
+    const instance = {
+        start: vi.fn((...args) => mockSpinnerStart(...args)),
+        stop: vi.fn((...args) => mockSpinnerStop(...args)),
+        message: vi.fn((...args) => mockSpinnerMessage(...args)),
+    };
+    createdSpinners.push(instance);
+    return instance;
+});
+
+// Back-compat handle map for files written against the `clack.mockXxx`
+// hoisted-object naming (apply, destroy, gc, headless). Import as:
+//   import { clackMocks as clack } from './helpers/clack.js';
+export const clackMocks = {
+    mockIntro,
+    mockOutro,
+    mockText,
+    mockSelect,
+    mockConfirm,
+    mockPassword,
+    mockMultiselect,
+    mockNote,
+    mockGroup,
+    mockCancel,
+    mockIsCancel,
+    mockSpinner,
+    mockSpinnerStart,
+    mockSpinnerStop,
+    mockSpinnerMessage,
+    mockLogInfo,
+    mockLogWarn,
+    mockLogMessage,
+    mockLogSuccess,
+    mockLogError,
+};
+
+export function clackPromptsMockFactory() {
+    return {
+        intro: mockIntro,
+        outro: mockOutro,
+        text: mockText,
+        select: mockSelect,
+        confirm: mockConfirm,
+        password: mockPassword,
+        multiselect: mockMultiselect,
+        note: mockNote,
+        group: mockGroup,
+        cancel: mockCancel,
+        isCancel: mockIsCancel,
+        spinner: mockSpinner,
+        log: {
+            info: mockLogInfo,
+            warn: mockLogWarn,
+            message: mockLogMessage,
+            success: mockLogSuccess,
+            error: mockLogError,
+        },
+    };
+}

package/tests/helpers/console.js

@@ -0,0 +1,41 @@
+// Centralized process/console spy helpers for the test suite.
+//
+// The recurring trio (`process.exit` + `console.log` + `console.error`) is
+// available as one bundle; individual spies cover the pair/single cases.
+// Bespoke variants (e.g. an exit spy that throws) stay inline in their files.
+//
+// Usage:
+//   import { mockConsoleTrio } from './helpers/console.js';
+//   let spies;
+//   beforeEach(() => { spies = mockConsoleTrio(); });
+//   afterEach(() => { spies.restore(); });
+//   // assertions read spies.exitSpy / spies.logSpy / spies.errorSpy
+import { vi } from 'vitest';
+
+export function mockProcessExit() {
+    return vi.spyOn(process, 'exit').mockImplementation(() => {});
+}
+
+export function mockConsoleLog() {
+    return vi.spyOn(console, 'log').mockImplementation(() => {});
+}
+
+export function mockConsoleError() {
+    return vi.spyOn(console, 'error').mockImplementation(() => {});
+}
+
+export function mockConsoleTrio() {
+    const exitSpy = mockProcessExit();
+    const logSpy = mockConsoleLog();
+    const errorSpy = mockConsoleError();
+    return {
+        exitSpy,
+        logSpy,
+        errorSpy,
+        restore() {
+            exitSpy.mockRestore();
+            logSpy.mockRestore();
+            errorSpy.mockRestore();
+        },
+    };
+}

package/tests/helpers/telemetry.js

@@ -0,0 +1,37 @@
+// Centralized `src/core/telemetry.js` mock for the test suite.
+//
+// Usage (one-liner per test file):
+//   import { telemetryMockFactory } from './helpers/telemetry.js';
+//   vi.mock('../src/core/telemetry.js', (importOriginal) => telemetryMockFactory(importOriginal));
+//
+// `trackSuccess`/`trackFailure` mirror the real delegation (calling through
+// to `trackEvent` + `flushTelemetry`) so success/failure-path assertions that
+// observe `trackEvent.mock.calls` keep working. `isActiveEnvValue` and
+// `detectCiProvider` pass through to the real module, covering the union of
+// what mocked consumers import (add, doctor, domain).
+//
+// Do NOT use this in tests/telemetry.test.js (it tests the real module).
+import { vi } from 'vitest';
+
+export const mockTrackEvent = vi.fn();
+export const mockFlushTelemetry = vi.fn().mockResolvedValue();
+export const mockTrackSuccess = vi.fn(async (event, properties) => {
+    mockTrackEvent(event, { ...properties, success: true });
+    await mockFlushTelemetry();
+});
+export const mockTrackFailure = vi.fn(async (event, properties) => {
+    mockTrackEvent(event, { ...properties, success: false });
+    await mockFlushTelemetry();
+});
+
+export async function telemetryMockFactory(importOriginal) {
+    const actual = await importOriginal();
+    return {
+        trackEvent: mockTrackEvent,
+        flushTelemetry: mockFlushTelemetry,
+        trackSuccess: mockTrackSuccess,
+        trackFailure: mockTrackFailure,
+        isActiveEnvValue: actual.isActiveEnvValue,
+        detectCiProvider: actual.detectCiProvider,
+    };
+}

package/tests/helpers/tmpdir.js

@@ -0,0 +1,36 @@
+// Centralized tmpdir fixture helper for the test suite.
+//
+// Usage:
+//   import { createTmpDirTracker } from './helpers/tmpdir.js';
+//   const tmp = createTmpDirTracker();
+//   beforeEach(() => { tmp.reset(); });
+//   afterEach(() => { tmp.cleanup(); });
+//   // tests create dirs with: const dir = tmp.makeTmp('my-test-');
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+export function makeTmpDir(prefix) {
+    return fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+}
+
+export function createTmpDirTracker() {
+    const dirs = [];
+    return {
+        dirs,
+        makeTmp(prefix) {
+            const dir = makeTmpDir(prefix);
+            dirs.push(dir);
+            return dir;
+        },
+        reset() {
+            dirs.length = 0;
+        },
+        cleanup() {
+            for (const dir of dirs) {
+                fs.rmSync(dir, { recursive: true, force: true });
+            }
+            dirs.length = 0;
+        },
+    };
+}

package/tests/logs.test.js

@@ -1,4 +1,7 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+// NOTE: helper imports must stay above src imports: vi.mock factories run
+// during module evaluation and need the factories initialized.
+import { telemetryMockFactory } from './helpers/telemetry.js';
 import fs from 'fs';
 import os from 'os';
 import path from 'path';
@@ -46,21 +49,7 @@ vi.mock('@aws-sdk/client-cloudwatch-logs', () => ({
     DescribeLogStreamsCommand: MockDescribeLogStreamsCommand,
 }));
 
-vi.mock('../src/core/telemetry.js', () => {
-    const trackEvent = vi.fn();
-    const flushTelemetry = vi.fn(() => Promise.resolve());
-    // Mirrors the real trackSuccess delegation so success-path assertions
-    // keep observing trackEvent (the real helper is unit-tested separately).
-    const trackSuccess = vi.fn(async (event, properties) => {
-        trackEvent(event, { ...properties, success: true });
-        await flushTelemetry();
-    });
-    const trackFailure = vi.fn(async (event, properties) => {
-        trackEvent(event, { ...properties, success: false });
-        await flushTelemetry();
-    });
-    return { trackEvent, flushTelemetry, trackSuccess, trackFailure };
-});
+vi.mock('../src/core/telemetry.js', (importOriginal) => telemetryMockFactory(importOriginal));
 
 function makeEvents(count, prefix = 'log line') {
     const base = Date.now() - count * 1000;

package/tests/resolvers.test.js

@@ -1,25 +1,22 @@
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { createTmpDirTracker } from './helpers/tmpdir.js';
 import fs from 'fs';
 import os from 'os';
 import path from 'path';
 import { readFileSafe, readTerraformProjectName, readTerraformRegion, resolveProjectName, resolveRegion, resolveLogGroup, resolveHeadless, resolveAppName, resolveCwd, resolveCluster, resolveService, resolveWorkspaceSuffix, detectComputeTargetFromMainTf, readTerraformComputeTarget } from '../src/utils/resolvers.js';
 
-let tmpDirs = [];
+const tmp = createTmpDirTracker();
 
 function makeTmp() {
-    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'resolvers-test-'));
-    tmpDirs.push(dir);
-    return dir;
+    return tmp.makeTmp('resolvers-test-');
 }
 
 beforeEach(() => {
-    tmpDirs = [];
+    tmp.reset();
 });
 
 afterEach(() => {
-    for (const dir of tmpDirs) {
-        fs.rmSync(dir, { recursive: true, force: true });
-    }
+    tmp.cleanup();
 });
 
 describe('readTerraformProjectName', () => {

package/tests/rollback.test.js

@@ -1,4 +1,8 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+// NOTE: helper imports must stay above src imports: vi.mock factories run
+// during module evaluation and need the factories initialized.
+import { clackPromptsMockFactory, createdSpinners } from './helpers/clack.js';
+import { telemetryMockFactory } from './helpers/telemetry.js';
 import fs from 'fs';
 import os from 'os';
 import path from 'path';
@@ -14,35 +18,9 @@ import { trackEvent, flushTelemetry } from '../src/core/telemetry.js';
 import { select } from '@clack/prompts';
 import { handleAwsAuthError } from '../src/utils/aws.js';
 
-const createdSpinners = vi.hoisted(() => []);
-
-vi.mock('@clack/prompts', () => ({
-    intro: vi.fn(),
-    outro: vi.fn(),
-    spinner: () => {
-        const instance = { start: vi.fn(), stop: vi.fn(), message: vi.fn() };
-        createdSpinners.push(instance);
-        return instance;
-    },
-    select: vi.fn(),
-    isCancel: (value) => typeof value === 'symbol',
-}));
+vi.mock('@clack/prompts', () => clackPromptsMockFactory());
 
-vi.mock('../src/core/telemetry.js', () => {
-    const trackEvent = vi.fn();
-    const flushTelemetry = vi.fn().mockResolvedValue();
-    // Mirrors the real trackSuccess delegation so success-path assertions
-    // keep observing trackEvent (the real helper is unit-tested separately).
-    const trackSuccess = vi.fn(async (event, properties) => {
-        trackEvent(event, { ...properties, success: true });
-        await flushTelemetry();
-    });
-    const trackFailure = vi.fn(async (event, properties) => {
-        trackEvent(event, { ...properties, success: false });
-        await flushTelemetry();
-    });
-    return { trackEvent, flushTelemetry, trackSuccess, trackFailure };
-});
+vi.mock('../src/core/telemetry.js', (importOriginal) => telemetryMockFactory(importOriginal));
 
 vi.mock('../src/utils/aws.js', () => ({
     hasAwsCli: vi.fn().mockReturnValue(true),

package/tests/secrets.test.js

@@ -1,4 +1,8 @@
 import { vi, describe, it, expect, beforeEach, afterEach } from 'vitest';
+// NOTE: helper imports must stay above src imports: vi.mock factories run
+// during module evaluation and need the factories initialized.
+import { clackPromptsMockFactory, mockConfirm, mockOutro, mockSpinnerStart, mockSpinnerStop } from './helpers/clack.js';
+import { telemetryMockFactory } from './helpers/telemetry.js';
 import fs from 'fs/promises';
 import path from 'path';
 import { pushSecrets, pullSecrets, auditSecrets, resolveSecretsRegion } from '../src/commands/secrets.js';
@@ -22,13 +26,6 @@ const { mockSend, MockSecretsManagerClient, MockUpdateSecretCommand, MockGetSecr
     };
 });
 
-const { mockConfirm, mockOutro, mockSpinnerStart, mockSpinnerStop } = vi.hoisted(() => ({
-    mockConfirm: vi.fn(),
-    mockOutro: vi.fn(),
-    mockSpinnerStart: vi.fn(),
-    mockSpinnerStop: vi.fn(),
-}));
-
 const { mockEcsSend, MockECSClient, MockUpdateServiceCommand } = vi.hoisted(() => {
     const ecsSendFn = vi.fn().mockResolvedValue({});
     return {
@@ -56,30 +53,10 @@ vi.mock('@aws-sdk/client-ecs', () => ({
 }));
 
 // 3. Mock @clack/prompts to prevent hangs on user input during testing
-vi.mock('@clack/prompts', () => ({
-    spinner: vi.fn(() => ({ start: mockSpinnerStart, stop: mockSpinnerStop, message: vi.fn() })),
-    confirm: (...args) => mockConfirm(...args),
-    outro: (...args) => mockOutro(...args),
-    intro: vi.fn(),
-    isCancel: (value) => typeof value === 'symbol',
-}));
+vi.mock('@clack/prompts', () => clackPromptsMockFactory());
 
 // 4. Mock telemetry to prevent real network calls during testing
-vi.mock('../src/core/telemetry.js', () => {
-    const trackEvent = vi.fn();
-    const flushTelemetry = vi.fn().mockResolvedValue();
-    // Mirrors the real trackSuccess delegation so success-path assertions
-    // keep observing trackEvent (the real helper is unit-tested separately).
-    const trackSuccess = vi.fn(async (event, properties) => {
-        trackEvent(event, { ...properties, success: true });
-        await flushTelemetry();
-    });
-    const trackFailure = vi.fn(async (event, properties) => {
-        trackEvent(event, { ...properties, success: false });
-        await flushTelemetry();
-    });
-    return { trackEvent, flushTelemetry, trackSuccess, trackFailure };
-});
+vi.mock('../src/core/telemetry.js', (importOriginal) => telemetryMockFactory(importOriginal));
 
 describe('Secrets Push Command', () => {
     const originalCwd = process.cwd();

package/tests/sleep-wake.test.js

@@ -1,4 +1,9 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+// NOTE: helper imports must stay above src imports: vi.mock factories run
+// during module evaluation and need the factories initialized.
+import { clackPromptsMockFactory } from './helpers/clack.js';
+import { telemetryMockFactory } from './helpers/telemetry.js';
+import { createTmpDirTracker } from './helpers/tmpdir.js';
 import fs from 'fs';
 import os from 'os';
 import path from 'path';
@@ -25,42 +30,21 @@ import {
     setWorkerScalingSuspended,
 } from '../src/utils/sleep-targets.js';
 
-vi.mock('@clack/prompts', () => ({
-    intro: vi.fn(),
-    outro: vi.fn(),
-    spinner: () => ({ start: vi.fn(), stop: vi.fn(), message: vi.fn() }),
-    confirm: vi.fn(),
-    cancel: vi.fn(),
-    isCancel: (value) => typeof value === 'symbol',
-}));
+vi.mock('@clack/prompts', () => clackPromptsMockFactory());
 
-vi.mock('../src/core/telemetry.js', () => {
-    const trackEvent = vi.fn();
-    const flushTelemetry = vi.fn().mockResolvedValue();
-    const trackSuccess = vi.fn(async (event, properties) => {
-        trackEvent(event, { ...properties, success: true });
-        await flushTelemetry();
-    });
-    const trackFailure = vi.fn(async (event, properties) => {
-        trackEvent(event, { ...properties, success: false });
-        await flushTelemetry();
-    });
-    return { trackEvent, flushTelemetry, trackSuccess, trackFailure };
-});
+vi.mock('../src/core/telemetry.js', (importOriginal) => telemetryMockFactory(importOriginal));
 
 vi.mock('../src/utils/aws.js', () => ({
     handleAuthErrorBranch: () => false,
     resolveClient: (injected) => injected,
 }));
 
-let tmpDirs = [];
+const tmp = createTmpDirTracker();
 let exitSpy;
 let logSpy;
 
 function makeTmp() {
-    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'sleep-wake-test-'));
-    tmpDirs.push(dir);
-    return dir;
+    return tmp.makeTmp('sleep-wake-test-');
 }
 
 // Minimal ECS/RDS recorder: `ecs` maps service names to service objects,
@@ -125,7 +109,7 @@ function activeService(name, desiredCount) {
 }
 
 beforeEach(() => {
-    tmpDirs = [];
+    tmp.reset();
     vi.clearAllMocks();
     exitSpy = vi.spyOn(process, 'exit').mockImplementation(() => {});
     logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
@@ -134,9 +118,7 @@ beforeEach(() => {
 afterEach(() => {
     exitSpy.mockRestore();
     logSpy.mockRestore();
-    for (const dir of tmpDirs) {
-        fs.rmSync(dir, { recursive: true, force: true });
-    }
+    tmp.cleanup();
 });
 
 describe('parseSleepArgs / parseWakeArgs', () => {

package/tests/status.test.js

@@ -1,4 +1,8 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+// NOTE: helper imports must stay above src imports: vi.mock factories run
+// during module evaluation and need the factories initialized.
+import { clackPromptsMockFactory } from './helpers/clack.js';
+import { telemetryMockFactory } from './helpers/telemetry.js';
 import fs from 'fs';
 import os from 'os';
 import path from 'path';
@@ -10,27 +14,9 @@ vi.mock('../src/commands/diagnose.js', () => ({
     runDiagnose: vi.fn().mockResolvedValue({ healthy: false }),
 }));
 
-vi.mock('@clack/prompts', () => ({
-    intro: vi.fn(),
-    outro: vi.fn(),
-    spinner: () => ({ start: vi.fn(), stop: vi.fn(), message: vi.fn() }),
-}));
+vi.mock('@clack/prompts', () => clackPromptsMockFactory());
 
-vi.mock('../src/core/telemetry.js', () => {
-    const trackEvent = vi.fn();
-    const flushTelemetry = vi.fn().mockResolvedValue();
-    // Mirrors the real trackSuccess delegation so success-path assertions
-    // keep observing trackEvent (the real helper is unit-tested separately).
-    const trackSuccess = vi.fn(async (event, properties) => {
-        trackEvent(event, { ...properties, success: true });
-        await flushTelemetry();
-    });
-    const trackFailure = vi.fn(async (event, properties) => {
-        trackEvent(event, { ...properties, success: false });
-        await flushTelemetry();
-    });
-    return { trackEvent, flushTelemetry, trackSuccess, trackFailure };
-});
+vi.mock('../src/core/telemetry.js', (importOriginal) => telemetryMockFactory(importOriginal));
 
 function mockEcsClient(serviceDesc) {
     return { send: vi.fn().mockResolvedValue({ services: [serviceDesc] }) };

package/tests/visualizer.test.js

@@ -1,4 +1,9 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+// NOTE: helper imports must stay above src imports: vi.mock factories run
+// during module evaluation and need the factories initialized.
+import { clackPromptsMockFactory, mockNote } from './helpers/clack.js';
+import { telemetryMockFactory } from './helpers/telemetry.js';
+import { createTmpDirTracker } from './helpers/tmpdir.js';
 import fs from 'fs';
 import os from 'os';
 import path from 'path';
@@ -15,33 +20,14 @@ import { ADDON_REGISTRY } from '../src/utils/addons.js';
 import { trackEvent, flushTelemetry } from '../src/core/telemetry.js';
 import { confirm } from '@clack/prompts';
 
-const { mockNote } = vi.hoisted(() => ({ mockNote: vi.fn() }));
-
-vi.mock('@clack/prompts', () => ({
-    note: mockNote,
-    confirm: vi.fn(),
-    isCancel: (value) => typeof value === 'symbol',
-    cancel: vi.fn(),
-}));
-
-vi.mock('../src/core/telemetry.js', () => {
-    const trackEvent = vi.fn();
-    const flushTelemetry = vi.fn().mockResolvedValue();
-    // Mirrors the real trackFailure delegation so failure-path assertions
-    // keep observing trackEvent (the real helper is unit-tested separately).
-    const trackFailure = vi.fn(async (event, properties) => {
-        trackEvent(event, { ...properties, success: false });
-        await flushTelemetry();
-    });
-    return { trackEvent, flushTelemetry, trackFailure };
-});
+vi.mock('@clack/prompts', () => clackPromptsMockFactory());
+
+vi.mock('../src/core/telemetry.js', (importOriginal) => telemetryMockFactory(importOriginal));
 
-let tmpDirs = [];
+const tmp = createTmpDirTracker();
 
 function makeTmp() {
-    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'visualizer-test-'));
-    tmpDirs.push(dir);
-    return dir;
+    return tmp.makeTmp('visualizer-test-');
 }
 
 function writeTf(dir, files = {}) {
@@ -73,14 +59,12 @@ function stripAnsi(text) {
 }
 
 beforeEach(() => {
-    tmpDirs = [];
+    tmp.reset();
     vi.clearAllMocks();
 });
 
 afterEach(() => {
-    for (const dir of tmpDirs) {
-        fs.rmSync(dir, { recursive: true, force: true });
-    }
+    tmp.cleanup();
 });
 
 describe('parseTerraformConfig', () => {

package/vitest.config.js

@@ -1,9 +1,10 @@
-import { defineConfig } from 'vitest/config';
+import { defineConfig, defaultExclude } from 'vitest/config';
 
 export default defineConfig({
     test: {
         env: {
             FORCE_COLOR: '1',
         },
+        exclude: [...defaultExclude, 'tests/e2e/**'],
     },
 });

package/vitest.e2e.tier0.config.js

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+    test: {
+        include: ['tests/e2e/tier0.e2e.test.js'],
+        testTimeout: 300000,
+    },
+});

package/vitest.e2e.tier1.config.js

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+    test: {
+        include: ['tests/e2e/tier1.live.e2e.test.js'],
+        testTimeout: 1200000,
+    },
+});

package/specs/deploy-stack-to-grada-run-rebrand.md

@@ -1,45 +0,0 @@
-# Specification: The Grada Brand Transition
-
-## 1. Overview
-Transition the `deploy-stack` codebase to the new brand identity: **Grada**. 
-Existing deployments must not break; implement robust dual-read fallbacks for state files, machine markers, and tags. Version bump to `0.32.0`.
-
-## 2. NPM, Repository & Binary Renaming
-- `package.json`: Update name to `grada-run`. Update `author` and `keywords` to include Grada terminology. 
-- `package.json`: Map the `bin` field to: `"grada": "./bin/cli.js"`, `"grada-run": "./bin/cli.js"`, and a deprecated fallback `"deploy-stack": "./bin/cli.js"`.
-- `package.json` fields (`repository`, `bugs`, `homepage`) must point to `[https://github.com/grada-run/grada](https://github.com/grada-run/grada)`.
-- Replace hardcoded `anton-codes-iac/deploy-stack` GitHub URLs across the codebase (error logs, docs) with `grada-run/grada`.
-- Rename `CLI_ENTRY_BASENAMES` in `src/core/telemetry.js` to include `grada` and `grada-run`.
-- Update CLI banner texts, `.muserules` title, AI rules filenames (write new ones, do not delete user legacy ones), and help texts to use `Grada` / `npx grada-run`.
-
-## 3. Dual-Read Local State & Env Vars
-Read from `.grada/` first, fall back to `.deploy-stack/`. Write new state to `.grada/`.
-- **Telemetry:** Check `~/.grada/telemetry-id` (raw text file) -> fallback to `~/.deploy-stack/telemetry-id`. Copy to new path on fallback.
-- **Sleep Ledger:** Check `.grada/sleep-state.json` -> fallback to `.deploy-stack/sleep-state.json`. In `ensureSleepGitignore`, append `.grada/` but leave `.deploy-stack/`.
-- **Bedrock Cache:** Check `~/.grada/bedrock-models-cache.json` -> fallback `~/.deploy-stack/bedrock-models-cache.json`.
-- **Env Vars:** Rename `DEPLOY_STACK_TELEMETRY_ID_PATH` -> `GRADA_TELEMETRY_ID_PATH`, `DEPLOY_STACK_FRAMEWORK` -> `GRADA_FRAMEWORK`, and `DEPLOY_STACK_BEDROCK_CACHE_PATH` -> `GRADA_BEDROCK_CACHE_PATH` (all with legacy read fallbacks). Leave `DO_NOT_TRACK` as the sole telemetry opt-out. Rename `DEPLOY_STACK_BYPASS` in the Svelte template to `GRADA_BYPASS`.
-
-## 4. Machine Markers (Dual-Read)
-The CLI must parse both `deploy-stack` and `grada` variants for existing files, but write `grada` for new ones.
-- Domain mode: `# deploy-stack:domain-mode=` / `# grada:domain-mode=` AND `# deploy-stack:zone-id=` / `# grada:zone-id=`
-- Migrate gate: `# deploy-stack:db-migrate-start` / `# grada:db-migrate-start` AND `# deploy-stack:db-migrate-end` / `# grada:db-migrate-end`
-- AI Context: Dual read both HTML (`<!-- BEGIN GRADA CONTEXT -->` / `<!-- END GRADA CONTEXT -->`) and hash (`# BEGIN GRADA CONTEXT` / `# END GRADA CONTEXT`) block variants.
-
-## 5. Templates, Tagging & Eject
-- Rename *all* cosmetic occurrences of the brand in templates (e.g., `npx deploy-stack` -> `npx grada-run`, `Generated by deploy-stack`, `# deploy-stack generated infrastructure`, `# deploy-stack addon:`, `deploy-stack-cron`, and git commit messages).
-- Update `ManagedBy = "grada"` for new writes in templates, S3 state buckets, RDS snapshots, and providers. Rename `startedBy` to `grada-db-*`.
-- In `src/commands/eject.js`, ensure the cleanup regex strips *both variants* of all four block types: `ManagedBy` tag blocks, cosmetic addon headers, `# deploy-stack backups` gitignore comments, and `# deploy-stack generated infrastructure` main.tf headers.
-
-## 6. Documentation & Generators
-- **Docs Site (`apps/docs/`):** Update `astro.config.mjs` (`site: '[https://grada.run](https://grada.run)'`, remove the `base` property entirely, update `title`, `editLink`, `social` hrefs, redirects, and sidebar labels). Execute Astro build to regenerate `apps/docs/dist/`. Update internal `/deploy-stack/` links across `README.md`, `release_notes.md`, and all `apps/docs/src/` pages.
-- **Generator Fallback Doc:** Rename fallback constant to `GRADA.md`. `resolveDocDest` precedence chain: `README.md` -> `DEPLOYMENT.md` -> `GRADA.md` -> legacy `DEPLOY-STACK.md` (returning the first missing-or-managed). 
-- **Cost Sync:** `syncDocCostEstimate` must scan `GRADA.md` and legacy `DEPLOY-STACK.md` in addition to `README.md` and `DEPLOYMENT.md`.
-
-## 7. GitHub Actions & CI
-- Update `uses:` step from `anton-codes-iac/deploy-stack-action@v1` to `grada-run/grada-action@v1`.
-- Update `scripts/test-iac.js` and `iac-validation.yml` to assert the new `grada` migrate markers.
-- Validate that `.github/workflows/publish.yml` publishes `grada-run` and the scoped alias `@grada-run/grada`.
-
-## 8. Testing
-- Use `npm run test:update` to carefully update the 131 legacy snapshot matches across the 12 test files.
-- Add unit tests asserting the dual-read marker logic, telemetry fallback, sleep ledger fallback, and `eject` multi-brand cleanup.