@rehearsal-db/core 0.1.0-beta.15 → 0.1.0-beta.17

package/dist/src/baseline/privacy_validation_shared.mjs

@@ -0,0 +1,127 @@
+/** Redacted primitive validators and closed vocabulary for privacy policy v2. */
+export const IDENTIFIER = /^[a-z][a-z0-9_]{0,62}$/u;
+export const BINDING_NAME = /^[a-z][a-z0-9-]{0,62}$/u;
+export const ENVIRONMENT_KEY = /^[A-Z][A-Z0-9_]*$/u;
+export const HEX_64 = /^[a-f0-9]{64}$/u;
+export const UUID = /^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/iu;
+export const PORTABLE_CODE = /^[A-Za-z0-9][A-Za-z0-9_-]*$/u;
+export const ACTIONS = new Set([
+    "KEEP",
+    "PSEUDONYMIZE",
+    "REPLACE",
+    "EXCLUDE",
+    "DERIVE",
+]);
+export const PSEUDONYM_FORMATS = new Set([
+    "uuid",
+    "email",
+    "text",
+    "integer",
+    "hex",
+    "gtin",
+    "url",
+]);
+export const HEX_LENGTHS = new Set([32, 64]);
+export const GTIN_LENGTHS = new Set([8, 12, 13, 14]);
+export const DATE_REPRESENTATIONS = new Set([
+    "iso-string",
+    "epoch-milliseconds",
+]);
+export const DERIVATION_KINDS = new Set([
+    "date-shift",
+    "digest",
+    "enum",
+    "validated-string",
+    "path-map",
+    "json-object",
+    "json-array",
+    "json-union",
+    "json-dictionary",
+    "approved-owner",
+    "binding-substitute",
+]);
+export const URL_PATH_PREFIX = "/rehearsal/";
+export const URL_TOKEN_LENGTH = 32;
+export const MAXIMUM_URL_LENGTH = 2_048;
+export const MAXIMUM_TEXT_SUBSTITUTION_BYTES = 65_536;
+export const LOOPBACK_HOSTNAMES = new Set([
+    "127.0.0.1",
+    "::1",
+    "[::1]",
+    "localhost",
+]);
+export const DEFAULT_PATH_MAXIMUM_BYTES = 2_048;
+export const DEFAULT_PATH_MAXIMUM_SEGMENTS = 32;
+export const MAXIMUM_POLICY_DEPTH = 16;
+export const MAXIMUM_ENUM_VALUES = 128;
+export const MAXIMUM_ENUM_STRING_BYTES = 256;
+export const isPrivacyObject = (value) => value !== null &&
+    typeof value === "object" &&
+    !Array.isArray(value) &&
+    Object.getPrototypeOf(value) === Object.prototype;
+export const assertKnownKeys = (value, allowed, label) => {
+    for (const key of Object.keys(value)) {
+        if (!allowed.includes(key))
+            throw new Error(`${label}.${key} is unknown.`);
+    }
+};
+export const validateIdentifier = (value, label) => {
+    if (typeof value !== "string" || !IDENTIFIER.test(value)) {
+        throw new Error(`${label} must be a lowercase PostgreSQL identifier.`);
+    }
+    return value;
+};
+export const validateNonEmpty = (value, label) => {
+    if (typeof value !== "string" || !value.trim()) {
+        throw new Error(`${label} must be a non-empty string.`);
+    }
+    return value.trim();
+};
+export const validatePositiveInteger = (value, label, maximum = Number.MAX_SAFE_INTEGER) => {
+    if (typeof value !== "number" ||
+        !Number.isSafeInteger(value) ||
+        value < 1 ||
+        value > maximum) {
+        throw new Error(`${label} must be an integer from 1 through ${maximum}.`);
+    }
+    return value;
+};
+export const validateReviewedScalar = (value, label) => {
+    if (typeof value === "string") {
+        if (Buffer.byteLength(value) > MAXIMUM_ENUM_STRING_BYTES) {
+            throw new Error(`${label} must contain at most ${MAXIMUM_ENUM_STRING_BYTES} UTF-8 bytes.`);
+        }
+        return value;
+    }
+    if (typeof value === "boolean")
+        return value;
+    if (typeof value === "number" &&
+        Number.isFinite(value) &&
+        !Object.is(value, -0)) {
+        return value;
+    }
+    throw new Error(`${label} must be a JSON string, finite number, or boolean.`);
+};
+export const validateHttpsLoopbackOrigin = (value, label) => {
+    if (typeof value !== "string" || value.trim() !== value || !value) {
+        throw new Error(`${label} must be a safe HTTPS loopback origin.`);
+    }
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        throw new Error(`${label} must be a safe HTTPS loopback origin.`);
+    }
+    if (parsed.protocol !== "https:" ||
+        !LOOPBACK_HOSTNAMES.has(parsed.hostname) ||
+        ![parsed.origin, `${parsed.origin}/`].includes(value) ||
+        parsed.username ||
+        parsed.password ||
+        (parsed.pathname !== "/" && parsed.pathname !== "") ||
+        parsed.search ||
+        parsed.hash) {
+        throw new Error(`${label} must be a safe HTTPS loopback origin.`);
+    }
+    return parsed.origin;
+};

package/dist/src/cli/application_command_handlers.d.mts

@@ -0,0 +1,8 @@
+/** Persistent application-session command handler. */
+import type { CommandDefinition } from "./command_contract.mjs";
+import type { createRuntimeCommands } from "./runtime_commands.mjs";
+type RuntimeCommands = ReturnType<typeof createRuntimeCommands>;
+export declare const createApplicationCommandHandlers: ({ openRuntimeApplication, }: {
+    openRuntimeApplication: RuntimeCommands["openRuntimeApplication"];
+}) => readonly CommandDefinition[];
+export {};

package/dist/src/cli/application_command_handlers.mjs

@@ -0,0 +1,52 @@
+/** Persistent application-session command handler. */
+import * as prompts from "@clack/prompts";
+import { exactCommands, renderedCommand } from "./command_contract.mjs";
+import { useStyledPrompts } from "./terminal.mjs";
+export const createApplicationCommandHandlers = ({ openRuntimeApplication, }) => [
+    exactCommands("open", ["open"], async ({ flags, planOptions, guided, state }) => {
+        if (flags.dryRun) {
+            throw new Error("--dry-run is supported only by rehearsal run.");
+        }
+        const data = await openRuntimeApplication({
+            flags,
+            planOptions,
+            session: state,
+            onReady: (ready) => {
+                const lines = [
+                    `Application: ${ready.url}`,
+                    "The verified database runtime stays running and keeps your local changes.",
+                    guided
+                        ? "Press Ctrl+C to close the app and return here, or Ctrl+Z to exit Rehearsal."
+                        : "Press Ctrl+C or Ctrl+Z to close the app. Rehearsal will leave the database runtime running.",
+                ];
+                if (useStyledPrompts(flags)) {
+                    prompts.note(lines.join("\n"), "SANDBOX READY");
+                }
+                else if (!flags.json) {
+                    console.log(["", "SANDBOX READY", ...lines, ""].join("\n"));
+                }
+            },
+        });
+        if (guided && data.application.stoppedBy === "SIGTSTP") {
+            flags.exitGuidedSession = true;
+        }
+        if (guided) {
+            state.lastGuidedDetails = [
+                data.started.output,
+                data.verified.output,
+                ...data.preparations.map((preparation) => preparation.output),
+            ]
+                .filter(Boolean)
+                .join("\n");
+        }
+        return renderedCommand({
+            data,
+            render: (result) => [
+                "SANDBOX APP CLOSED",
+                `Application stopped after ${result.application.stoppedBy}.`,
+                "The database runtime and its local database and Storage changes were preserved.",
+                "Run rehearsal open to return, rehearsal verify to check it, or rehearsal stop to stop the databases.",
+            ].join("\n"),
+        });
+    }),
+];

package/dist/src/cli/arguments.d.mts

@@ -22,13 +22,8 @@ export interface RehearsalCliFlags {
     refreshConfirmation: string | undefined;
     identityConfirmation: string | undefined;
     identityName: string | undefined;
-    runtimeTopology: unknown | undefined;
-    targetConfirmations: unknown | undefined;
     exitGuidedSession: boolean;
     guided: boolean;
-    setupPlan?: unknown;
-    preparationPlan?: unknown;
-    cleanupPlan?: unknown;
 }
 export interface ParsedArguments {
     flags: RehearsalCliFlags;

package/dist/src/cli/arguments.mjs

@@ -22,8 +22,6 @@ export const parseArguments = (arguments_) => {
         refreshConfirmation: undefined,
         identityConfirmation: undefined,
         identityName: undefined,
-        runtimeTopology: undefined,
-        targetConfirmations: undefined,
         exitGuidedSession: false,
         guided: false,
     };
@@ -97,12 +95,7 @@ export const resetGuidedFlags = (flags) => {
         refreshConfirmation: undefined,
         identityConfirmation: undefined,
         identityName: undefined,
-        runtimeTopology: undefined,
-        targetConfirmations: undefined,
         exitGuidedSession: false,
-        setupPlan: undefined,
-        preparationPlan: undefined,
-        cleanupPlan: undefined,
     });
 };
 export const commandMutatesProject = ({ command, flags, guided, }) => {
@@ -120,6 +113,8 @@ export const commandMutatesProject = ({ command, flags, guided, }) => {
         return Boolean(flags.refreshConfirmation);
     if (command === "identity claim")
         return Boolean(flags.identityConfirmation);
+    if (command === "identity connect")
+        return true;
     if (command === "run")
         return !flags.dryRun;
     return [

package/dist/src/cli/basic_command_handlers.d.mts

@@ -0,0 +1,4 @@
+/** Stable version and help handlers with no project-side effects. */
+import type { CommandDefinition } from "./command_contract.mjs";
+export declare const usage: () => string;
+export declare const createBasicCommandHandlers: () => readonly CommandDefinition[];

package/dist/src/cli/basic_command_handlers.mjs

@@ -0,0 +1,57 @@
+/** Stable version and help handlers with no project-side effects. */
+import { REHEARSAL_VERSION } from "../shared/diagnostics.mjs";
+import { exactCommands, textCommand } from "./command_contract.mjs";
+export const usage = () => `Usage: rehearsal <command> [options]
+
+Commands:
+  version                     Print the installed Rehearsal version
+  guide                       Open the interactive, state-aware home screen
+  setup [--target=] [--write] Preview or create safe first-run scaffolding
+  init [--write]              Preview or explicitly write safe starter config
+  baseline prepare --records= --ledger= [--write] Create a fail-closed policy draft
+  baseline create --records= --ledger= [--assets=] Create a baseline from safe local inputs
+  privacy key [--write]       Preview or create the owner-only pseudonym key
+  source plan                 Preview exact, temporary source access
+  source apply --confirm-source-access= Apply the reviewed source-access plan
+  source retire [--confirm-source-retirement=] Preview or retire exact source access
+  baseline refresh            Replace only the baseline from a reviewed source
+  refresh [--confirm-refresh=] Replace the database copy, reset locally, and remove old copies
+  identity plan --identity=   Preview an approved local identity association
+  identity claim --identity= --confirm-identity= Apply the exact local association
+  identity connect [--identity=] Keep the app open, detect sign-in, and connect once
+  doctor                     Check whether Rehearsal is safe and ready
+  support                    Print a safe, copy-ready support report
+  explain                    Show the immutable execution plan
+  run --dry-run              Alias the exact explain plan without mutations
+  run --confirm-candidates=  Execute reset, migration, and verification locally
+  open                       Start the runtime and keep the application open
+  candidates                 Show the exact pending migration digest
+  inspect baseline           Show verified baseline provenance
+  inspect migrations         Classify represented, applied, and candidate migrations
+  start                      Start an existing verified local runtime
+  migrate --confirm-candidates= Apply the exact candidate suffix without resetting
+  reset                      Restore and verify the immutable local baseline
+  status                     Report the disposable local runtime state
+  stop                       Stop only this project's local runtime
+  discard                    Remove only this project's disposable runtime
+  cleanup [--include-runtime] [--include-images] [--write] [--confirm-cleanup=]
+                             Preview or apply conservative disk cleanup
+  verify                     Verify the current local Rehearsal runtime
+
+Options: --help, -h --version, -V --json --verbose --debug --plain
+         --config=<path> --target=supabase|postgresql
+         --confirm-source-access=<digest> --confirm-source-retirement=<digest>
+         --confirm-refresh=<digest>`;
+export const createBasicCommandHandlers = () => [
+    {
+        id: "version",
+        matches: ({ command, flags }) => command === "version" || flags.version,
+        handle: async ({ flags }) => textCommand(flags.json
+            ? JSON.stringify({ name: "@rehearsal-db/core", version: REHEARSAL_VERSION }, null, 2)
+            : REHEARSAL_VERSION),
+    },
+    {
+        ...exactCommands("help", ["help"], async () => textCommand(usage())),
+        matches: ({ command, flags }) => command === "help" || flags.help,
+    },
+];

package/dist/src/cli/cli_commands.d.mts

@@ -0,0 +1,14 @@
+/** Assemble the CLI command families into one ordered typed registry. */
+import type { createProjectCommands } from "./project_commands.mjs";
+import type { createRuntimeCommands } from "./runtime_commands.mjs";
+import type { createRefreshWorkflow } from "./source_commands.mjs";
+type ProjectCommands = ReturnType<typeof createProjectCommands>;
+type RuntimeCommands = ReturnType<typeof createRuntimeCommands>;
+type RefreshWorkflow = ReturnType<typeof createRefreshWorkflow>;
+export declare const createCliCommandRegistry: ({ projectRoot, projectCommands, runtimeCommands, runRefreshWorkflow, }: {
+    projectRoot: string;
+    projectCommands: ProjectCommands;
+    runtimeCommands: RuntimeCommands;
+    runRefreshWorkflow: RefreshWorkflow;
+}) => import("./command_registry.mjs").CommandRegistry;
+export {};

package/dist/src/cli/cli_commands.mjs

@@ -0,0 +1,34 @@
+/** Assemble the CLI command families into one ordered typed registry. */
+import { createApplicationCommandHandlers } from "./application_command_handlers.mjs";
+import { createBasicCommandHandlers } from "./basic_command_handlers.mjs";
+import { createCommandRegistry } from "./command_registry.mjs";
+import { createIdentityCommandHandlers } from "./identity_command_handlers.mjs";
+import { createInspectionCommandHandlers } from "./inspection_command_handlers.mjs";
+import { createProjectCommandHandlers } from "./project_command_handlers.mjs";
+import { createRuntimeActionHandlers } from "./runtime_action_handlers.mjs";
+import { createSourceCommandHandlers } from "./source_command_handlers.mjs";
+export const createCliCommandRegistry = ({ projectRoot, projectCommands, runtimeCommands, runRefreshWorkflow, }) => createCommandRegistry([
+    ...createBasicCommandHandlers(),
+    ...createProjectCommandHandlers({
+        projectRoot,
+        runSetup: projectCommands.runSetup,
+        runBaselinePreparation: projectCommands.runBaselinePreparation,
+        runCleanup: projectCommands.runCleanup,
+    }),
+    ...createSourceCommandHandlers({ runRefreshWorkflow }),
+    ...createIdentityCommandHandlers({
+        loadIdentityClaimPlan: projectCommands.loadIdentityClaimPlan,
+        loadIdentityPolicy: projectCommands.loadIdentityPolicy,
+        startRuntimeApplication: runtimeCommands.startRuntimeApplication,
+    }),
+    ...createInspectionCommandHandlers(),
+    ...createApplicationCommandHandlers({
+        openRuntimeApplication: runtimeCommands.openRuntimeApplication,
+    }),
+    ...createRuntimeActionHandlers({
+        prepareCandidateConfirmation: runtimeCommands.prepareCandidateConfirmation,
+        prepareDependentTargets: runtimeCommands.prepareDependentTargets,
+        proveRuntimeStack: runtimeCommands.proveRuntimeStack,
+        runRuntimeStack: runtimeCommands.runRuntimeStack,
+    }),
+]);

package/dist/src/cli/command_contract.d.mts

@@ -0,0 +1,57 @@
+/** Typed contracts shared by CLI command handlers and the process entry point. */
+import type { RehearsalConfigPathOptions } from "../project/configuration.mjs";
+import type { RehearsalStatus } from "../shared/diagnostics.mjs";
+import type { RehearsalCliFlags, RehearsalVerbosity } from "./arguments.mjs";
+export interface CliSessionState {
+    lastGuidedDetails: string | undefined;
+    runtimeTopology: unknown | undefined;
+    targetConfirmations: unknown | undefined;
+    setupPlan: unknown | undefined;
+    preparationPlan: unknown | undefined;
+    cleanupPlan: unknown | undefined;
+}
+export declare const createCliSessionState: () => CliSessionState;
+export declare const resetCommandSessionState: (state: CliSessionState) => void;
+export interface CommandContext {
+    readonly command: string;
+    readonly flags: RehearsalCliFlags;
+    readonly planOptions: RehearsalConfigPathOptions;
+    readonly guided: boolean;
+    readonly state: CliSessionState;
+}
+export interface RenderedCommandResult {
+    readonly kind: "rendered";
+    readonly data: unknown;
+    readonly status: RehearsalStatus;
+    readonly render: (verbosity: RehearsalVerbosity) => string;
+    readonly exitCode?: number;
+}
+export interface TextCommandResult {
+    readonly kind: "text";
+    readonly output: string;
+    readonly exitCode?: number;
+}
+export interface SilentCommandResult {
+    readonly kind: "silent";
+    readonly exitCode?: number;
+}
+export type CommandResult = RenderedCommandResult | TextCommandResult | SilentCommandResult;
+export type CommandHandler = (context: CommandContext) => Promise<CommandResult>;
+export interface CommandDefinition {
+    readonly id: string;
+    readonly matches: (context: CommandContext) => boolean;
+    readonly handle: CommandHandler;
+}
+export declare const renderedCommand: <Data>({ data, render, status, exitCode, }: {
+    data: Data;
+    render: (data: Data, verbosity: RehearsalVerbosity) => string;
+    status?: RehearsalStatus;
+    exitCode?: number;
+}) => RenderedCommandResult;
+export declare const textCommand: (output: string, options?: {
+    exitCode?: number;
+}) => TextCommandResult;
+export declare const silentCommand: (options?: {
+    exitCode?: number;
+}) => SilentCommandResult;
+export declare const exactCommands: (id: string, commands: readonly string[], handle: CommandHandler) => CommandDefinition;

package/dist/src/cli/command_contract.mjs

@@ -0,0 +1,39 @@
+/** Typed contracts shared by CLI command handlers and the process entry point. */
+export const createCliSessionState = () => ({
+    lastGuidedDetails: undefined,
+    runtimeTopology: undefined,
+    targetConfirmations: undefined,
+    setupPlan: undefined,
+    preparationPlan: undefined,
+    cleanupPlan: undefined,
+});
+export const resetCommandSessionState = (state) => {
+    Object.assign(state, {
+        runtimeTopology: undefined,
+        targetConfirmations: undefined,
+        setupPlan: undefined,
+        preparationPlan: undefined,
+        cleanupPlan: undefined,
+    });
+};
+export const renderedCommand = ({ data, render, status = "success", exitCode, }) => ({
+    kind: "rendered",
+    data,
+    status,
+    render: (verbosity) => render(data, verbosity),
+    ...(exitCode === undefined ? {} : { exitCode }),
+});
+export const textCommand = (output, options = {}) => ({
+    kind: "text",
+    output,
+    ...(options.exitCode === undefined ? {} : { exitCode: options.exitCode }),
+});
+export const silentCommand = (options = {}) => ({
+    kind: "silent",
+    ...(options.exitCode === undefined ? {} : { exitCode: options.exitCode }),
+});
+export const exactCommands = (id, commands, handle) => ({
+    id,
+    matches: ({ command }) => commands.includes(command),
+    handle,
+});

package/dist/src/cli/command_output.d.mts

@@ -0,0 +1,12 @@
+/** Emit the stable JSON envelope or human result for a typed command result. */
+import type { RehearsalCliFlags } from "./arguments.mjs";
+import type { CommandResult } from "./command_contract.mjs";
+export declare const createCommandEmitter: ({ startedAt, startedMs, write, }: {
+    startedAt: Date;
+    startedMs: number;
+    write?: (output: string) => void;
+}) => ({ command, flags, result, }: {
+    command: string;
+    flags: RehearsalCliFlags;
+    result: CommandResult;
+}) => number | undefined;

package/dist/src/cli/command_output.mjs

@@ -0,0 +1,20 @@
+/** Emit the stable JSON envelope or human result for a typed command result. */
+import { performance } from "node:perf_hooks";
+import { createRehearsalResult } from "../shared/diagnostics.mjs";
+export const createCommandEmitter = ({ startedAt, startedMs, write = console.log, }) => ({ command, flags, result, }) => {
+    if (result.kind === "text")
+        write(result.output);
+    if (result.kind === "rendered") {
+        const envelope = createRehearsalResult({
+            command,
+            status: result.status,
+            data: result.data,
+            startedAt,
+            durationMs: Math.round((performance.now() - startedMs) * 100) / 100,
+        });
+        write(flags.json
+            ? JSON.stringify(envelope, null, 2)
+            : result.render(flags.verbosity));
+    }
+    return result.exitCode;
+};

package/dist/src/cli/command_registry.d.mts

@@ -0,0 +1,7 @@
+/** Resolve one CLI request to exactly one typed command handler. */
+import type { CommandContext, CommandDefinition, CommandResult } from "./command_contract.mjs";
+export interface CommandRegistry {
+    readonly ids: readonly string[];
+    execute(context: CommandContext): Promise<CommandResult | null>;
+}
+export declare const createCommandRegistry: (definitions: readonly CommandDefinition[]) => CommandRegistry;

package/dist/src/cli/command_registry.mjs

@@ -0,0 +1,14 @@
+/** Resolve one CLI request to exactly one typed command handler. */
+export const createCommandRegistry = (definitions) => {
+    const ids = definitions.map(({ id }) => id);
+    if (new Set(ids).size !== ids.length) {
+        throw new Error("CLI command registry IDs must be unique.");
+    }
+    return Object.freeze({
+        ids: Object.freeze(ids),
+        async execute(context) {
+            const definition = definitions.find((candidate) => candidate.matches(context));
+            return definition ? definition.handle(context) : null;
+        },
+    });
+};

package/dist/src/cli/guided.d.mts

@@ -3,6 +3,7 @@
  */
 import type { RehearsalConfigPathOptions } from "../project/configuration.mjs";
 import type { RehearsalCliFlags } from "./arguments.mjs";
+import type { CliSessionState } from "./command_contract.mjs";
 import type { RuntimeTopologyTarget } from "../runtime/topology.mjs";
 import type { RehearsalCleanupPlan } from "../runtime/cleanup.mjs";
 interface TopologySummary {
@@ -33,7 +34,7 @@ interface GuidedRefreshPlan {
         readonly steps: readonly string[];
     };
 }
-export declare const createGuidedHome: ({ projectRoot, topologyCandidateSummary, buildRefreshWorkflowPlan, planRuntimeStackCleanup, getLastGuidedDetails, }: {
+export declare const createGuidedHome: ({ projectRoot, topologyCandidateSummary, buildRefreshWorkflowPlan, planRuntimeStackCleanup, getLastGuidedDetails, session, }: {
     projectRoot: string;
     topologyCandidateSummary: (options: RehearsalConfigPathOptions) => Promise<TopologySummary>;
     buildRefreshWorkflowPlan: (options: RehearsalConfigPathOptions) => Promise<{
@@ -44,6 +45,7 @@ export declare const createGuidedHome: ({ projectRoot, topologyCandidateSummary,
         planOptions: RehearsalConfigPathOptions;
     }) => Promise<GuidedCleanupPlan>;
     getLastGuidedDetails: () => string | undefined;
+    session: CliSessionState;
 }) => ({ flags, planOptions, }: {
     flags: RehearsalCliFlags;
     planOptions: RehearsalConfigPathOptions;

package/dist/src/cli/guided.mjs

@@ -95,6 +95,7 @@ const inspectGuidedProject = async ({ projectRoot, planOptions, topologyCandidat
         policyAbsolutePath: loaded.paths.sanitizationPolicy,
         ...(migrationSummary === undefined ? {} : { migrationSummary }),
         refreshConfigured: Boolean(loaded.config.preparation),
+        identityConfigured: Boolean(loaded.paths.identityPolicy),
         dependentCount: topology?.dependents.length ?? 0,
         runtime: topology
             ? (await Promise.all(topology.targets.map((target) => pathExists(join(target.paths.runtimeWorkdir, "baseline.json"))))).every(Boolean)
@@ -334,6 +335,13 @@ const guidedOptions = (state, hasLastDetails) => {
         options.push({ label: "Check readiness", command: "doctor" });
     }
     if (state.node.supported && state.runtime) {
+        if (state.identityConfigured) {
+            options.push({
+                label: "Connect my copied account",
+                hint: "Sign in normally, review once, then open the copied profile",
+                command: "identity connect",
+            });
+        }
         options.push({
             label: "Open the sandbox app",
             hint: "Keep it running for hands-on testing",
@@ -415,7 +423,7 @@ const showGuidedStatus = ({ state, options, flags, }) => {
         ].join("\n"));
     }
 };
-const guideCleanup = async ({ flags, planOptions, planRuntimeStackCleanup, }) => {
+const guideCleanup = async ({ flags, planOptions, planRuntimeStackCleanup, session, }) => {
     const cleanupScope = await promptForChoice({
         message: "What may Rehearsal include in the cleanup preview?",
         flags,
@@ -444,7 +452,7 @@ const guideCleanup = async ({ flags, planOptions, planRuntimeStackCleanup, }) =>
     flags.includeRuntime = ["runtime", "all"].includes(cleanupScope.command);
     flags.includeImages = ["images", "all"].includes(cleanupScope.command);
     const cleanupPlan = await planRuntimeStackCleanup({ flags, planOptions });
-    flags.cleanupPlan = cleanupPlan;
+    session.cleanupPlan = cleanupPlan;
     console.log(`\n${renderCleanup({ mode: "preview", plan: cleanupPlan })}`);
     const selectedCount = "targets" in cleanupPlan
         ? cleanupPlan.targets.reduce((total, target) => total +
@@ -465,7 +473,7 @@ const guideCleanup = async ({ flags, planOptions, planRuntimeStackCleanup, }) =>
     flags.cleanupConfirmation = cleanupPlan.digest;
     return "cleanup";
 };
-const guideBaseline = async ({ state, selected, flags, planOptions, projectRoot, }) => {
+const guideBaseline = async ({ state, selected, flags, planOptions, projectRoot, session, }) => {
     console.log([
         "",
         terminalStyle(flags, "1", "CREATE A SAFE BASELINE"),
@@ -526,7 +534,7 @@ const guideBaseline = async ({ state, selected, flags, planOptions, projectRoot,
                 console.log("No changes made.");
                 return "home";
             }
-            flags.preparationPlan = preparationPlan;
+            session.preparationPlan = preparationPlan;
             flags.write = true;
             return "baseline prepare";
         }
@@ -567,7 +575,7 @@ const guideBaseline = async ({ state, selected, flags, planOptions, projectRoot,
         return "home";
     }
 };
-export const createGuidedHome = ({ projectRoot, topologyCandidateSummary, buildRefreshWorkflowPlan, planRuntimeStackCleanup, getLastGuidedDetails, }) => async ({ flags, planOptions, }) => {
+export const createGuidedHome = ({ projectRoot, topologyCandidateSummary, buildRefreshWorkflowPlan, planRuntimeStackCleanup, getLastGuidedDetails, session, }) => async ({ flags, planOptions, }) => {
     const state = await inspectGuidedProject({
         projectRoot,
         planOptions,
@@ -659,7 +667,12 @@ export const createGuidedHome = ({ projectRoot, topologyCandidateSummary, buildR
         return runtimeAction.command;
     }
     if (selected.command === "cleanup-guide") {
-        return guideCleanup({ flags, planOptions, planRuntimeStackCleanup });
+        return guideCleanup({
+            flags,
+            planOptions,
+            planRuntimeStackCleanup,
+            session,
+        });
     }
     if (["baseline-guide", "baseline-prepare"].includes(selected.command)) {
         return guideBaseline({
@@ -668,6 +681,7 @@ export const createGuidedHome = ({ projectRoot, topologyCandidateSummary, buildR
             flags,
             planOptions,
             projectRoot,
+            session,
         });
     }
     if (selected.command !== "setup-write")
@@ -707,7 +721,7 @@ export const createGuidedHome = ({ projectRoot, topologyCandidateSummary, buildR
         console.log("No changes made.");
         return "home";
     }
-    flags.setupPlan = setupPlan;
+    session.setupPlan = setupPlan;
     flags.write = true;
     return "setup";
 };

package/dist/src/cli/identity_command_handlers.d.mts

@@ -0,0 +1,12 @@
+/** Provider-neutral copied-account planning, application, and guided connection. */
+import type { CommandDefinition } from "./command_contract.mjs";
+import type { createProjectCommands } from "./project_commands.mjs";
+import type { createRuntimeCommands } from "./runtime_commands.mjs";
+type ProjectCommands = ReturnType<typeof createProjectCommands>;
+type RuntimeCommands = ReturnType<typeof createRuntimeCommands>;
+export declare const createIdentityCommandHandlers: ({ loadIdentityClaimPlan, loadIdentityPolicy, startRuntimeApplication, }: {
+    loadIdentityClaimPlan: ProjectCommands["loadIdentityClaimPlan"];
+    loadIdentityPolicy: ProjectCommands["loadIdentityPolicy"];
+    startRuntimeApplication: RuntimeCommands["startRuntimeApplication"];
+}) => readonly CommandDefinition[];
+export {};