@learncard/cli 3.5.0 → 3.6.0

package/src/org.ts

@@ -0,0 +1,124 @@
+import type { Command } from 'commander';
+import {
+    connect,
+    connectAsDidWeb,
+    connectAsDidWebSigner,
+    ensureIdentity,
+    loadProject,
+    type Project,
+    type ProjectOptions,
+} from './project';
+import { loadOrgSpec } from './org/load';
+import { applyOrg } from './org/apply';
+import { formatChanges, hasChanges } from './org/diff';
+import { out } from './out';
+import { generateRandomSeed } from './random';
+
+export type OrgApplyOptions = ProjectOptions & {
+    dryRun?: boolean;
+    secretsOut?: string;
+    cwd?: string;
+    /** Operate on this in-memory project instead of loading .env from cwd (dry-run previews). */
+    project?: Project;
+};
+
+export const runOrgApply = async (file: string, options: OrgApplyOptions): Promise<void> => {
+    const spec = await loadOrgSpec(file);
+    const project = options.project ?? (await loadProject(options.cwd ?? process.cwd()));
+
+    if (options.profileId && options.profileId !== spec.issuer.profileId)
+        throw new Error(
+            `--profile-id "${options.profileId}" does not match the spec's issuer.profileId "${spec.issuer.profileId}". Remove the flag or update the spec.`
+        );
+
+    if (project.env.PROFILE_ID && project.env.PROFILE_ID !== spec.issuer.profileId)
+        throw new Error(
+            `This project's .env is already set up for profile "${project.env.PROFILE_ID}", but the spec declares "${spec.issuer.profileId}". Use a separate folder for a different issuer.`
+        );
+
+    if (options.dryRun) {
+        if (!project.env.SECURE_SEED) {
+            out.log(
+                'Dry run: no identity in this folder yet — using a throwaway seed, nothing written.'
+            );
+            project.env.SECURE_SEED = generateRandomSeed();
+        }
+        project.env.PROFILE_ID ??= spec.issuer.profileId;
+    } else {
+        await ensureIdentity(project, {
+            ...options,
+            profileId: spec.issuer.profileId,
+            name: spec.issuer.displayName,
+        });
+    }
+    const learnCard = await connect(project, {
+        ...options,
+        lca: true,
+        readOnly: !!options.dryRun,
+    });
+
+    const result = await applyOrg(spec, learnCard, project, {
+        dryRun: options.dryRun,
+        secretsOut: options.secretsOut,
+        connectAsManager: managerDid => connectAsDidWeb(project, options, managerDid),
+        connectAsManaged: managedDid => connectAsDidWeb(project, options, managedDid),
+        connectAsManagedSigner: managedDid => connectAsDidWebSigner(project, options, managedDid),
+    });
+
+    if (options.dryRun) out.log('Dry run: no changes were made.');
+    if (hasChanges(result.changes)) {
+        for (const line of formatChanges(result.changes)) out.log(line);
+    } else {
+        out.log('No changes.');
+    }
+    out.log(`Issuer DID: ${result.outputs.issuerDid}`);
+
+    out.set({ changes: result.changes, outputs: result.outputs });
+};
+
+export const registerOrgCommand = (
+    program: Command,
+    run: (
+        command: string,
+        options: { json?: boolean },
+        action: (didkit: Promise<Buffer>) => Promise<void>
+    ) => Promise<void>
+): void => {
+    const orgCommand = program
+        .command('org')
+        .description('Manage an issuer organization declaratively.');
+
+    orgCommand
+        .command('apply <file>')
+        .description(
+            'Reconcile a YAML/JSON org spec (issuer, signing authority, districts, service accounts) against the network.'
+        )
+        .option('-y, --yes', 'accept defaults without prompting')
+        .option(
+            '--profile-id <id>',
+            'public handle for your issuer profile (default: from the spec)'
+        )
+        .option('--network <url>', 'network tRPC URL or staging (default: production)')
+        .option('--json', 'print a single JSON result on stdout')
+        .option('--dry-run', 'preview changes without applying them')
+        .option(
+            '--secrets-out <path>',
+            'write created service-account tokens to this file, e.g. ./secrets.env (mode 0600; keep it next to .env and out of git)'
+        )
+        .action(
+            (
+                file: string,
+                options: {
+                    yes?: boolean;
+                    profileId?: string;
+                    network?: string;
+                    json?: boolean;
+                    dryRun?: boolean;
+                    secretsOut?: string;
+                }
+            ) =>
+                run('org apply', options, async didkit => {
+                    await runOrgApply(file, { ...options, didkit });
+                })
+        );
+};

package/src/project.test.ts

@@ -138,7 +138,10 @@ describe('project context', () => {
             );
             await fs.writeFile(path.join(cwd, '.gitignore'), '.env\n');
             const project = await loadProject(cwd);
-            const identity = await ensureIdentity(project, { yes: true, profileId: 'ignored' });
+            await expect(
+                ensureIdentity(project, { yes: true, profileId: 'someone-else' })
+            ).rejects.toThrow(/--as someone-else/);
+            const identity = await ensureIdentity(project, { yes: true, profileId: 'issuer' });
             expect(identity.seed).toBe('existing');
             expect(identity.profileId).toBe('issuer');
             expect(console.log).not.toHaveBeenCalled();
@@ -205,3 +208,25 @@ describe('upsertEnv value quoting', () => {
         );
     });
 });
+
+describe('connectAsManaged', () => {
+    it('explains how to get a profile manager when .env has none', async () => {
+        const { connectAsManaged } = await import('./project');
+        const project = { env: { SECURE_SEED: 'seed' }, envPath: '/x/.env', existing: '' };
+        await expect(connectAsManaged(project, {}, 'cs-exampleville')).rejects.toThrow(
+            /profileManager section/
+        );
+    });
+});
+
+describe('connect readOnly', () => {
+    it('does not write NETWORK_URL to .env when readOnly is set', async () => {
+        const { connect } = await import('./project');
+        const cwd = await fs.mkdtemp(path.join(os.tmpdir(), 'lc-readonly-'));
+        vi.spyOn(console, 'log').mockImplementation(() => {});
+        const project = await loadProject(cwd);
+        project.env.SECURE_SEED = 'a'.repeat(64);
+        await connect(project, { network: 'staging', readOnly: true }).catch(() => undefined);
+        expect(await fs.readdir(cwd)).toEqual([]);
+    });
+});

package/src/project.ts

@@ -2,8 +2,12 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { createInterface } from 'node:readline/promises';
 import { randomUUID } from 'node:crypto';
-import { initLearnCard, type NetworkLearnCardFromSeed } from '@learncard/init';
-import { initLCALearnCard, type LCALearnCard } from '@learncard/lca-api-plugin';
+import {
+    initLearnCard,
+    type DidWebNetworkLearnCardFromSeed,
+    type NetworkLearnCardFromSeed,
+} from '@learncard/init';
+import { getLCAPlugin, initLCALearnCard, type LCALearnCard } from '@learncard/lca-api-plugin';
 import { generateRandomSeed } from './random';
 import { out } from './out';
 
@@ -35,9 +39,11 @@ export interface ProjectOptions {
     network?: string;
     didkit?: Promise<Buffer>;
     json?: boolean;
+    readOnly?: boolean;
 }
 
 export type NetworkCard = NetworkLearnCardFromSeed['returnValue'];
+export type DidWebCard = DidWebNetworkLearnCardFromSeed['returnValue'];
 
 export const parseEnv = (text: string): Record<string, string> => {
     const env: Record<string, string> = {};
@@ -173,6 +179,7 @@ export const createPrompts = (yes?: boolean) => {
         ? createInterface({ input: process.stdin, output: process.stdout })
         : null;
     return {
+        interactive,
         ask: async (question: string, fallback: string): Promise<string> => {
             if (rl) return (await rl.question(`${question} [${fallback}] `)).trim() || fallback;
             if (!fallback)
@@ -188,6 +195,16 @@ export const createPrompts = (yes?: boolean) => {
 };
 
 export const ensureIdentity = async (project: Project, options: ProjectOptions) => {
+    if (
+        project.env.PROFILE_ID &&
+        options.profileId &&
+        options.profileId !== project.env.PROFILE_ID
+    ) {
+        throw new Error(
+            `This folder's .env is already the profile "${project.env.PROFILE_ID}"; --profile-id ${options.profileId} would not change that. ` +
+                `To act as a profile you manage from here, use --as ${options.profileId}. To create a separate identity, run from a new folder.`
+        );
+    }
     const existingProfileId = project.env.PROFILE_ID || options.profileId;
     let displayName = options.name ?? project.env.DISPLAY_NAME ?? '';
     if (!existingProfileId && !displayName) {
@@ -219,18 +236,22 @@ export const ensureIdentity = async (project: Project, options: ProjectOptions)
         PROFILE_ID: profileId,
         ...(existingProfileId ? {} : { DISPLAY_NAME: displayName }),
     });
-    const gitignorePath = path.join(path.dirname(project.envPath), '.gitignore');
+    await ensureGitignored(path.dirname(project.envPath), '.env');
+    return { seed, profileId, displayName };
+};
+
+export const ensureGitignored = async (dir: string, entry: string): Promise<void> => {
+    const gitignorePath = path.join(dir, '.gitignore');
     const gitignore = await readOptional(gitignorePath);
     if (await fs.stat(gitignorePath).catch(() => null)) {
-        if (!gitignore.split('\n').some(line => line.trim() === '.env')) {
-            await fs.writeFile(gitignorePath, `${gitignore.replace(/\n?$/, '\n')}.env\n`);
-            out.log('Added .env to .gitignore');
+        if (!gitignore.split('\n').some(line => line.trim() === entry)) {
+            await fs.writeFile(gitignorePath, `${gitignore.replace(/\n?$/, '\n')}${entry}\n`);
+            out.log(`Added ${entry} to .gitignore`);
         }
     } else {
-        await fs.writeFile(gitignorePath, '.env\n');
-        out.log('Created .gitignore with .env');
+        await fs.writeFile(gitignorePath, `${entry}\n`);
+        out.log(`Created .gitignore with ${entry}`);
     }
-    return { seed, profileId, displayName };
 };
 
 export const PRODUCTION_NETWORK = 'https://network.learncard.com/trpc';
@@ -349,7 +370,7 @@ export async function connect(
     if (!seed) throw new Error('Create an identity before connecting.');
     const services = resolveServices(project.env, options.network);
     assertProjectNetwork(project, services.network);
-    if (services.network !== PRODUCTION_NETWORK || project.env.NETWORK_URL) {
+    if (!options.readOnly && (services.network !== PRODUCTION_NETWORK || project.env.NETWORK_URL)) {
         await saveProject(project, {
             NETWORK_URL: services.network === PRODUCTION_NETWORK ? '' : services.network,
         });
@@ -372,6 +393,80 @@ export async function connect(
           });
 }
 
+/**
+ * Open a second wallet on the same seed that authenticates as a `did:web` the
+ * network issued to this seed (e.g. a profile manager). Manager-only routes
+ * reject the seed's base did:key, so `connect()` alone cannot call them.
+ */
+export const connectAsDidWeb = async (
+    project: Project,
+    options: ProjectOptions,
+    didWeb: string
+): Promise<DidWebCard> => {
+    const seed = project.env.SECURE_SEED;
+    if (!seed) throw new Error('Create an identity before connecting.');
+    const services = resolveServices(project.env, options.network);
+    return initLearnCard({
+        seed,
+        network: services.network === PRODUCTION_NETWORK ? true : services.network,
+        didWeb,
+        ...(services.cloud && { cloud: { url: services.cloud } }),
+        ...(options.didkit && { didkit: options.didkit }),
+    });
+};
+
+/**
+ * Like `connectAsDidWeb`, plus the LCA plugin so the managed profile can create and
+ * register its own hosted signing authority (tokens acting as it have no key to sign with).
+ */
+export const connectAsDidWebSigner = async (
+    project: Project,
+    options: ProjectOptions,
+    didWeb: string
+): Promise<LCALearnCard> => {
+    const seed = project.env.SECURE_SEED;
+    if (!seed) throw new Error('Create an identity before connecting.');
+    const services = resolveServices(project.env, options.network);
+    const learnCard = await initLearnCard({
+        seed,
+        network: services.network === PRODUCTION_NETWORK ? true : services.network,
+        didWeb,
+        ...(services.cloud && { cloud: { url: services.cloud } }),
+        ...(options.didkit && { didkit: options.didkit }),
+    });
+    const lcaAPI = services.lcaAPI?.replace(/\/api\/?$/, '/trpc');
+    return learnCard.addPlugin(
+        await getLCAPlugin(
+            learnCard as unknown as Parameters<typeof getLCAPlugin>[0],
+            lcaAPI ?? 'https://api.learncard.app/trpc'
+        )
+    ) as unknown as LCALearnCard;
+};
+
+export const connectAsManaged = async (
+    project: Project,
+    options: ProjectOptions,
+    managedProfileId: string
+): Promise<DidWebCard> => {
+    const managerDid = project.env.ORG_PROFILE_MANAGER_DID;
+    if (!managerDid) {
+        throw new Error(
+            `--as ${managedProfileId} needs a profile manager in this folder. Run \`org apply\` with a profileManager section first.`
+        );
+    }
+    const manager = await connectAsDidWeb(project, options, managerDid);
+    let cursor: string | undefined;
+    do {
+        const page = await manager.invoke.getManagedProfiles({ limit: 100, cursor });
+        const match = page.records.find(record => record.profileId === managedProfileId);
+        if (match) return connectAsDidWeb(project, options, match.did);
+        cursor = page.hasMore ? (page.cursor ?? undefined) : undefined;
+    } while (cursor);
+    throw new Error(
+        `"${managedProfileId}" is not a profile managed from this folder. Add it under profileManager.managed in your org spec and run \`org apply\`.`
+    );
+};
+
 export const ensureProfile = async (
     learnCard: { invoke: Pick<NetworkCard['invoke'], 'getProfile' | 'createProfile'> },
     identity: { profileId: string; displayName: string },

package/src/promote.test.ts

@@ -0,0 +1,142 @@
+import path from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { PRODUCTION_NETWORK, STAGING_NETWORK } from './project';
+import { assertSourceNetwork, assertTargetSeed, planPromotion, PROMOTE_CHECKLIST } from './promote';
+
+describe('planPromotion', () => {
+    it('places the target under the supplied working directory', () => {
+        expect(planPromotion('staging', 'production', '/tmp/source-project').targetDir).toBe(
+            path.join('/tmp/source-project', '.learncard', 'production')
+        );
+    });
+    it('defaults the working directory to process.cwd()', () => {
+        expect(planPromotion('staging', 'production').targetDir).toBe(
+            path.join(process.cwd(), '.learncard', 'production')
+        );
+    });
+    it('resolves staging -> production and targets a project folder named after it', () => {
+        const plan = planPromotion('staging', 'production');
+        expect(plan.fromNetwork).toBe(STAGING_NETWORK);
+        expect(plan.toNetwork).toBe(PRODUCTION_NETWORK);
+        expect(plan.targetDir.endsWith(`${path.sep}production`)).toBe(true);
+    });
+
+    it('names the target folder after the hostname for a custom network URL', () => {
+        const plan = planPromotion('staging', 'https://network.example.org:8443/trpc');
+        expect(plan.toNetwork).toBe('https://network.example.org:8443/trpc');
+        expect(plan.targetDir.endsWith(`${path.sep}network.example.org`)).toBe(true);
+    });
+
+    it('throws when --from and --to resolve to the same network', () => {
+        expect(() => planPromotion('staging', 'staging')).toThrow('same network');
+        expect(() => planPromotion('production', PRODUCTION_NETWORK)).toThrow('same network');
+    });
+});
+
+describe('PROMOTE_CHECKLIST', () => {
+    it('lists the per-network resources that must be recreated on the target', () => {
+        expect(PROMOTE_CHECKLIST).toContain('API tokens');
+        expect(PROMOTE_CHECKLIST).toContain('Signing authority registrations');
+    });
+});
+
+describe('assertSourceNetwork', () => {
+    it('accepts a staging .env for --from staging (alias or full URL)', () => {
+        expect(() =>
+            assertSourceNetwork({ NETWORK_URL: 'staging' }, 'staging', STAGING_NETWORK)
+        ).not.toThrow();
+        expect(() =>
+            assertSourceNetwork({ NETWORK_URL: STAGING_NETWORK }, 'staging', STAGING_NETWORK)
+        ).not.toThrow();
+    });
+
+    it('accepts an .env with no NETWORK_URL for --from production', () => {
+        expect(() => assertSourceNetwork({}, 'production', PRODUCTION_NETWORK)).not.toThrow();
+    });
+
+    it('throws when the source folder is on a different network than --from', () => {
+        expect(() => assertSourceNetwork({}, 'staging', STAGING_NETWORK)).toThrow(
+            `--from staging does not match this folder's network (${PRODUCTION_NETWORK})`
+        );
+    });
+});
+
+describe('assertTargetSeed', () => {
+    const seed = 'a'.repeat(64);
+
+    it('accepts an empty target or one already bound to the same seed', () => {
+        expect(() => assertTargetSeed({}, seed, '/t')).not.toThrow();
+        expect(() => assertTargetSeed({ SECURE_SEED: seed }, seed, '/t')).not.toThrow();
+    });
+
+    it('rejects a target already bound to a different seed', () => {
+        expect(() => assertTargetSeed({ SECURE_SEED: 'b'.repeat(64) }, seed, '/t')).toThrow(
+            `${path.join('/t', '.env')} already holds a different SECURE_SEED`
+        );
+    });
+});
+
+describe('runPromote --dry-run', () => {
+    it('uses options.cwd without changing process.cwd and leaves the source untouched', async () => {
+        const fs = await import('node:fs/promises');
+        const os = await import('node:os');
+        const { vi } = await import('vitest');
+        const log = vi.spyOn(console, 'log').mockImplementation(() => {});
+        const cwd = await fs.mkdtemp(path.join(os.tmpdir(), 'lc-promote-'));
+        const previousCwd = process.cwd();
+        const before = `SECURE_SEED=${'a'.repeat(64)}\nPROFILE_ID=exde\nNETWORK_URL=http://localhost:4000/trpc\n`;
+        const runOrgApply = vi.fn().mockResolvedValue(undefined);
+        vi.doMock('./org', () => ({ runOrgApply }));
+        vi.doMock('./doctor', () => ({ runDoctor: vi.fn() }));
+        vi.resetModules();
+        try {
+            await fs.writeFile(path.join(cwd, '.env'), before);
+            const org = path.join(cwd, 'org.yaml');
+            await fs.writeFile(
+                org,
+                'issuer:\n  profileId: exde\n  displayName: Ex\n  signingAuthority: { type: learncard-hosted, name: ex }\n'
+            );
+            const { runPromote } = await import('./promote');
+            await runPromote({
+                cwd,
+                from: 'http://localhost:4000/trpc',
+                to: 'staging',
+                org,
+                dryRun: true,
+            });
+            const targetDir = path.join(cwd, '.learncard', 'staging');
+            expect(runOrgApply).toHaveBeenCalledWith(
+                org,
+                expect.objectContaining({
+                    project: expect.objectContaining({ envPath: path.join(targetDir, '.env') }),
+                    secretsOut: path.join(targetDir, 'secrets.env'),
+                })
+            );
+            expect(process.cwd()).toBe(previousCwd);
+            expect(await fs.readFile(path.join(cwd, '.env'), 'utf8')).toBe(before);
+            expect(await fs.readdir(cwd)).toEqual(['.env', 'org.yaml']);
+
+            runOrgApply.mockClear();
+            await fs.mkdir(targetDir, { recursive: true });
+            await fs.writeFile(path.join(targetDir, '.env'), `SECURE_SEED=${'b'.repeat(64)}\n`);
+            for (const dryRun of [true, false]) {
+                await expect(
+                    runPromote({
+                        cwd,
+                        from: 'http://localhost:4000/trpc',
+                        to: 'staging',
+                        org,
+                        dryRun,
+                    })
+                ).rejects.toThrow('already holds a different SECURE_SEED');
+            }
+            expect(runOrgApply).not.toHaveBeenCalled();
+        } finally {
+            vi.doUnmock('./org');
+            vi.doUnmock('./doctor');
+            vi.resetModules();
+            log.mockRestore();
+            await fs.rm(cwd, { recursive: true, force: true });
+        }
+    }, 20_000);
+});

package/src/promote.ts

@@ -0,0 +1,202 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import type { Command } from 'commander';
+
+import {
+    loadProject,
+    saveProject,
+    resolveServices,
+    PRODUCTION_NETWORK,
+    STAGING_NETWORK,
+    type Project,
+    type ProjectOptions,
+} from './project';
+import { loadOrgSpec } from './org/load';
+import { runOrgApply } from './org';
+import { runDoctor, type RunCommand } from './doctor';
+import { out } from './out';
+
+/**
+ * Per-network resources that must be recreated on the target network after a promotion.
+ * See docs/how-to-guides/deploy-infrastructure/test-safely.md §"What carries over". The
+ * one thing that IS portable — your seed, and therefore the resulting did:key — is
+ * printed separately by `runPromote` rather than listed here.
+ */
+export const PROMOTE_CHECKLIST: readonly string[] = [
+    'Profile & profile ID',
+    'API tokens',
+    'Signing authority registrations',
+    'Credential templates',
+    'ConsentFlow contracts',
+    'Issued & claimed credentials',
+    'did:web (host-bound)',
+];
+
+const NETWORK_ALIASES: Record<string, string> = {
+    staging: STAGING_NETWORK,
+    production: PRODUCTION_NETWORK,
+};
+
+/** `resolveServices` only special-cases the literal string "staging"; translate "production" too. */
+const resolveNetworkUrl = (network: string): string =>
+    resolveServices({}, NETWORK_ALIASES[network] ?? network, {}).network;
+
+const NETWORK_DIR_NAMES: Record<string, string> = {
+    [STAGING_NETWORK]: 'staging',
+    [PRODUCTION_NETWORK]: 'production',
+};
+
+/** One project folder per network (`assertProjectNetwork` enforces this); named after the alias when known. */
+const networkDirName = (network: string): string =>
+    NETWORK_DIR_NAMES[network] ?? new URL(network).hostname;
+
+/** Pure: resolves --from/--to to network URLs and picks the target project folder. */
+export const planPromotion = (
+    from: string,
+    to: string,
+    cwd: string = process.cwd()
+): { fromNetwork: string; toNetwork: string; targetDir: string } => {
+    const fromNetwork = resolveNetworkUrl(from);
+    const toNetwork = resolveNetworkUrl(to);
+    if (fromNetwork === toNetwork)
+        throw new Error(`--from and --to resolve to the same network (${toNetwork}).`);
+    const targetDir = path.join(cwd, '.learncard', networkDirName(toNetwork));
+    return { fromNetwork, toNetwork, targetDir };
+};
+
+/** Pure: the source folder's `.env` must actually be on `--from`, or the wrong seed's org gets promoted. */
+export const assertSourceNetwork = (
+    sourceEnv: Record<string, string>,
+    from: string,
+    fromNetwork: string
+): void => {
+    const actual = resolveServices(sourceEnv, undefined, {}).network;
+    if (actual !== fromNetwork)
+        throw new Error(
+            `--from ${from} does not match this folder's network (${actual}). Run promote from the folder that is on ${from}.`
+        );
+};
+
+/** Pure: a target folder already bound to another seed would be provisioned as a different identity than the preview shows. */
+export const assertTargetSeed = (
+    targetEnv: Record<string, string>,
+    seed: string,
+    targetDir: string
+): void => {
+    if (targetEnv.SECURE_SEED && targetEnv.SECURE_SEED !== seed)
+        throw new Error(
+            `${path.join(targetDir, '.env')} already holds a different SECURE_SEED. Promotion carries this folder's seed; move that .env aside or pick a different target before re-running.`
+        );
+};
+
+export type PromoteOptions = ProjectOptions & {
+    cwd?: string;
+    from: string;
+    to: string;
+    org: string;
+    secretsOut?: string;
+    dryRun?: boolean;
+    skipDoctor?: boolean;
+};
+
+export const runPromote = async (options: PromoteOptions): Promise<void> => {
+    const { from, to, org, dryRun, skipDoctor } = options;
+    const { fromNetwork, toNetwork, targetDir } = planPromotion(from, to, options.cwd);
+    const secretsOut = options.secretsOut ?? path.join(targetDir, 'secrets.env');
+    out.log(`Promoting ${org} from ${from} to ${to}`);
+    out.log(`Target: ${targetDir}`);
+
+    const sourceProject = await loadProject(options.cwd ?? process.cwd());
+    if (!sourceProject.env.SECURE_SEED)
+        throw new Error(
+            `No SECURE_SEED in .env here. Run \`org apply\` against ${from} in this folder first.`
+        );
+    assertSourceNetwork(sourceProject.env, from, fromNetwork);
+
+    // Only the seed (and, if present, the matching profile ID) carries over — every
+    // other resource (tokens, signing authority, templates, contracts) is per-network
+    // and must be recreated by `org apply` against the target network below.
+    const carried = {
+        SECURE_SEED: sourceProject.env.SECURE_SEED,
+        ...(sourceProject.env.PROFILE_ID ? { PROFILE_ID: sourceProject.env.PROFILE_ID } : {}),
+        NETWORK_URL: toNetwork,
+    };
+
+    const targetProject = await loadProject(targetDir);
+    assertTargetSeed(targetProject.env, carried.SECURE_SEED, targetDir);
+
+    const spec = await loadOrgSpec(org);
+    if (spec.serviceAccounts?.length && !dryRun)
+        out.log(`Any new service-account tokens for ${to} go to ${secretsOut}`);
+
+    if (dryRun) {
+        out.log(
+            `Dry run: ${targetDir} is not created; previewing against ${to} with the carried-over seed.`
+        );
+        const preview: Project = {
+            env: { ...targetProject.env, ...carried },
+            envPath: targetProject.envPath,
+            existing: '',
+        };
+        await runOrgApply(org, {
+            ...options,
+            project: preview,
+            network: toNetwork,
+            dryRun,
+            secretsOut,
+        });
+    } else {
+        await fs.mkdir(targetDir, { recursive: true });
+        await saveProject(targetProject, carried);
+        await runOrgApply(org, {
+            ...options,
+            cwd: targetDir,
+            network: toNetwork,
+            dryRun,
+            secretsOut,
+        });
+    }
+
+    if (!skipDoctor && !dryRun) {
+        await runDoctor({ ...options, cwd: targetDir, network: toNetwork });
+    }
+
+    out.log(`Does not carry over from ${from} — recreate on ${to}:`);
+    for (const item of PROMOTE_CHECKLIST) out.log(`  - ${item}`);
+    out.log('Carries over: your seed → the same did:key.');
+    out.log(`Next: cd ${targetDir} && npx @learncard/cli doctor --network ${to}`);
+
+    out.set({ from: fromNetwork, to: toNetwork, targetDir, checklist: PROMOTE_CHECKLIST });
+};
+
+export const registerPromoteCommand = (program: Command, run: RunCommand): void => {
+    program
+        .command('promote')
+        .description('Move an issuer org from one network to another (e.g. staging to production).')
+        .requiredOption('--from <network>', 'source network tRPC URL or staging|production')
+        .requiredOption('--to <network>', 'target network tRPC URL or staging|production')
+        .requiredOption('--org <file>', 'org spec to re-apply on the target network')
+        .option(
+            '--secrets-out <path>',
+            'where to write the new service-account tokens (default: <target>/secrets.env, mode 0600)'
+        )
+        .option('--dry-run', 'preview changes without applying them')
+        .option('--skip-doctor', 'skip running doctor against the target network afterward')
+        .option('-y, --yes', 'accept defaults without prompting')
+        .option('--json', 'print a single JSON result on stdout')
+        .action(
+            (options: {
+                from: string;
+                to: string;
+                org: string;
+                secretsOut?: string;
+                dryRun?: boolean;
+                skipDoctor?: boolean;
+                yes?: boolean;
+                json?: boolean;
+            }) =>
+                run('promote', options, async didkit => {
+                    await runPromote({ ...options, didkit });
+                })
+        );
+};