@learncard/cli 3.4.17 → 3.5.1

package/src/init.ts

@@ -0,0 +1,26 @@
+import {
+    connect,
+    ensureIdentity,
+    ensureProfile,
+    loadProject,
+    type ProjectOptions,
+} from './project';
+import { out } from './out';
+
+/** Create the identity and profile every other command needs, without sending anything. */
+export const runInit = async (options: ProjectOptions): Promise<void> => {
+    const project = await loadProject(process.cwd());
+    const fresh = !project.env.SECURE_SEED;
+    const identity = await ensureIdentity(project, options);
+    const learnCard = await connect(project, options);
+    await ensureProfile(learnCard, identity, project);
+    out.set({
+        profileId: identity.profileId,
+        displayName: identity.displayName,
+        did: learnCard.id.did(),
+        created: fresh,
+        envPath: project.envPath,
+    });
+    out.log(fresh ? 'Ready. Your identity is in .env (keep it out of git).' : 'Already set up.');
+    out.log('Next: npx @learncard/cli send you@example.com');
+};

package/src/open.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'vitest';
+import { impliesNoBrowser, openPath, signInUrl } from './open';
+import { appUrlFor, PRODUCTION_NETWORK, STAGING_NETWORK } from './project';
+
+describe('open', () => {
+    it('maps networks to their app', () => {
+        expect(appUrlFor(PRODUCTION_NETWORK)).toBe('https://learncard.app');
+        expect(appUrlFor(STAGING_NETWORK)).toBe('https://staging.learncard.ai');
+        expect(appUrlFor('http://localhost:4000/trpc', 'http://localhost:3000/')).toBe(
+            'http://localhost:3000'
+        );
+    });
+
+    it('needs the matching .env value for resource targets', () => {
+        expect(openPath('portal', {})).toBe('/app-store/developer');
+        expect(openPath('template', {})).toBeNull();
+        expect(openPath('template', { TEMPLATE_URI: 'lc:network:x/trpc:boost:1' })).toBe(
+            '/app-store/developer?template=lc%3Anetwork%3Ax%2Ftrpc%3Aboost%3A1'
+        );
+    });
+
+    it('builds the sign-in URL with next as an app path, seed only in the fragment when asked', () => {
+        const plain = signInUrl('https://learncard.app', '/wallet');
+        expect(plain).toBe('https://learncard.app/developer/sign-in?next=%2Fwallet');
+        const withSeed = new URL(signInUrl('https://learncard.app', '/wallet', 'ab'.repeat(32)));
+        expect(withSeed.hash).toBe(`#seed=${'ab'.repeat(32)}`);
+        expect(withSeed.search).not.toContain('ab'.repeat(32));
+    });
+
+    it('never launches a browser when headless, --json, or --no-browser', () => {
+        // A real TTY with no flags: fine to launch.
+        expect(impliesNoBrowser({}, true)).toBe(false);
+        // --json always implies headless, even at a real TTY.
+        expect(impliesNoBrowser({ json: true }, true)).toBe(true);
+        // No TTY (piped/CI) implies headless regardless of flags.
+        expect(impliesNoBrowser({}, false)).toBe(true);
+        // Explicit --no-browser (commander's `browser: false`) always wins.
+        expect(impliesNoBrowser({ browser: false }, true)).toBe(true);
+    });
+});

package/src/open.ts

@@ -0,0 +1,186 @@
+import { spawn } from 'node:child_process';
+import clipboard from 'clipboardy';
+
+import {
+    appUrlFor,
+    loadProject,
+    PRODUCTION_NETWORK,
+    resolveServices,
+    STAGING_NETWORK,
+    type ProjectOptions,
+} from './project';
+import { out } from './out';
+
+export type OpenTarget = 'portal' | 'wallet' | 'template' | 'contract' | 'integration';
+
+export const OPEN_TARGETS: Record<OpenTarget, string> = {
+    portal: 'the Developer Portal',
+    wallet: 'your wallet',
+    template: 'the template you last sent from',
+    contract: 'your consent contract',
+    integration: "your Claim button's integration",
+};
+
+/** App path for a target, given the project's .env. Returns null when the .env lacks what the target needs. */
+export const openPath = (target: OpenTarget, env: Record<string, string>): string | null => {
+    switch (target) {
+        case 'portal':
+            return '/app-store/developer';
+        case 'wallet':
+            return '/wallet';
+        case 'template':
+            return env.TEMPLATE_URI
+                ? `/app-store/developer?template=${encodeURIComponent(env.TEMPLATE_URI)}`
+                : null;
+        case 'contract':
+            return env.CONTRACT_URI
+                ? `/app-store/developer?contract=${encodeURIComponent(env.CONTRACT_URI)}`
+                : null;
+        case 'integration':
+            return env.INTEGRATION_ID
+                ? `/app-store/developer/integrations/${encodeURIComponent(env.INTEGRATION_ID)}`
+                : null;
+    }
+};
+
+export const signInUrl = (appUrl: string, next: string, seedInFragment?: string): string => {
+    const url = new URL('/developer/sign-in', appUrl);
+    url.searchParams.set('next', next);
+    if (seedInFragment) url.hash = `seed=${seedInFragment}`;
+    return url.toString();
+};
+
+const CLIPBOARD_TTL_MS = 60_000;
+
+/** Only plain http(s) URLs may reach the OS browser launcher or seed a sign-in link. */
+const isHttpUrl = (value: string): boolean => {
+    try {
+        return ['http:', 'https:'].includes(new URL(value).protocol);
+    } catch {
+        return false;
+    }
+};
+
+const launchBrowser = (url: string): void => {
+    const [cmd, args] =
+        process.platform === 'darwin'
+            ? ['open', [url]]
+            : process.platform === 'win32'
+              ? // No shell involved: rundll32 receives the URL as a normal argv entry, so
+                // cmd.exe metacharacters (&, |, ^, etc.) in the URL are never interpreted.
+                ['rundll32', ['url.dll,FileProtocolHandler', url]]
+              : ['xdg-open', [url]];
+    spawn(cmd, args, { stdio: 'ignore', detached: true }).unref();
+};
+
+/**
+ * Clears the clipboard after the TTL, or immediately on Ctrl-C, but only if it still holds the
+ * seed we wrote (the user may have copied something else). Resolves once the clipboard is safe.
+ */
+const waitForClipboardClear = (seed: string): Promise<void> =>
+    new Promise(resolve => {
+        let settled = false;
+        const finish = async (): Promise<void> => {
+            if (settled) return;
+            settled = true;
+            clearTimeout(timer);
+            process.removeListener('SIGINT', onSigint);
+            if ((await clipboard.read().catch(() => '')) === seed)
+                await clipboard.write('').catch(() => {});
+            out.log('Clipboard cleared.');
+            resolve();
+        };
+        const onSigint = (): void => {
+            void finish();
+        };
+        const timer = setTimeout(() => void finish(), CLIPBOARD_TTL_MS);
+        process.once('SIGINT', onSigint);
+    });
+
+export interface OpenOptions extends ProjectOptions {
+    appUrl?: string;
+    urlFragment?: boolean;
+    /** commander's attribute name for `--no-browser`; false only when that flag is passed. */
+    browser?: boolean;
+}
+
+export type SeedDelivery = 'clipboard' | 'fragment' | 'none';
+
+/** A script or `--json` run has nowhere to click "paste"; never launch a browser for it. */
+export const impliesNoBrowser = (
+    options: { browser?: boolean; json?: boolean },
+    isTTY: boolean
+): boolean => options.browser === false || !isTTY || !!options.json;
+
+export const runOpen = async (
+    target: OpenTarget = 'portal',
+    options: OpenOptions
+): Promise<void> => {
+    const project = await loadProject(process.cwd());
+    const seed = project.env.SECURE_SEED;
+    if (!seed)
+        throw new Error(
+            'No SECURE_SEED in .env. Run a command that creates one first, e.g. npx @learncard/cli send you@example.com'
+        );
+
+    const path = openPath(target, project.env);
+    if (!path)
+        throw new Error(
+            `Nothing saved for "${target}" yet. Run the command that creates it first (send --template, consent-contract, or embed).`
+        );
+
+    const { network } = resolveServices(project.env, options.network);
+    if (options.appUrl && !isHttpUrl(options.appUrl))
+        throw new Error('--app-url must be a valid http(s) URL.');
+    if (!options.appUrl && network !== PRODUCTION_NETWORK && network !== STAGING_NETWORK)
+        throw new Error(
+            `${network} has no hosted LearnCard app. Pass --app-url <url> for the app connected to it.`
+        );
+    const appUrl = appUrlFor(network, options.appUrl);
+    const noBrowser = impliesNoBrowser(options, !!process.stdout.isTTY);
+
+    let url: string;
+    let seedDelivery: SeedDelivery;
+    let clipboardCleared: Promise<void> | undefined;
+    if (options.urlFragment) {
+        url = signInUrl(appUrl, path, seed);
+        out.log(
+            'Warning: --url-fragment puts your seed in the browser URL (history, screenshots).'
+        );
+        seedDelivery = 'fragment';
+    } else if (out.json) {
+        // Non-interactive: nobody is there to paste, and blocking a script for the clipboard TTL
+        // would be worse than not copying. Scripts that need the seed use --url-fragment.
+        url = signInUrl(appUrl, path);
+        out.log(
+            'Seed not copied in --json mode. Paste it from .env, or re-run with --url-fragment.'
+        );
+        seedDelivery = 'none';
+    } else {
+        url = signInUrl(appUrl, path);
+        try {
+            await clipboard.write(seed);
+            out.log(`Copied your seed to the clipboard (clears in ${CLIPBOARD_TTL_MS / 1000}s).`);
+            seedDelivery = 'clipboard';
+            clipboardCleared = waitForClipboardClear(seed);
+        } catch {
+            out.log(
+                'Clipboard unavailable. Paste the seed from .env, or re-run with --url-fragment.'
+            );
+            seedDelivery = 'none';
+        }
+    }
+
+    if (!options.urlFragment) out.log('→ Click "Paste from clipboard", then Sign in.');
+    if (!noBrowser) launchBrowser(url);
+    // Printed last so `$(cli open | tail -1)` captures this line in non-json mode.
+    out.log(
+        `Opening ${OPEN_TARGETS[target]}: ${options.urlFragment ? url.split('#')[0] + '#seed=…' : url}`
+    );
+
+    out.set({ url, target, next: path, seedDelivery });
+
+    // Keep the process alive until the clipboard is actually cleared (or Ctrl-C clears it early);
+    // index.tsx's runCommand exits right after this promise resolves.
+    await clipboardCleared;
+};

package/src/out.test.ts

@@ -0,0 +1,40 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { out } from './out';
+
+afterEach(() => {
+    out.json = false;
+    out.result = {};
+    vi.restoreAllMocks();
+});
+
+describe('out', () => {
+    it('routes log to console.log in human mode', () => {
+        const log = vi.spyOn(console, 'log').mockImplementation(() => {});
+        const error = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+        out.json = false;
+        out.log('hello', 1);
+
+        expect(log).toHaveBeenCalledWith('hello', 1);
+        expect(error).not.toHaveBeenCalled();
+    });
+
+    it('routes log to console.error in json mode, keeping stdout free for the result', () => {
+        const log = vi.spyOn(console, 'log').mockImplementation(() => {});
+        const error = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+        out.json = true;
+        out.log('hidden from stdout');
+
+        expect(error).toHaveBeenCalledWith('hidden from stdout');
+        expect(log).not.toHaveBeenCalled();
+    });
+
+    it('accumulates result patches, later keys winning on conflict', () => {
+        out.result = {};
+        out.set({ a: 1, b: 2 });
+        out.set({ b: 3 });
+
+        expect(out.result).toEqual({ a: 1, b: 3 });
+    });
+});

package/src/out.ts

@@ -0,0 +1,16 @@
+/**
+ * Shared output router for every CLI command.
+ *
+ * Human mode: `out.log(...)` behaves exactly like `console.log(...)`.
+ * `--json` mode: `out.log(...)` is redirected to stderr (so stdout stays reserved
+ * for the single JSON result line) and each command accumulates its result via
+ * `out.set(...)`. `index.tsx`'s `runCommand` prints the final `out.result` object
+ * as one JSON line on stdout after the command succeeds (or an error envelope on
+ * failure) and sets `out.json` before running the command's action.
+ */
+export const out = {
+    json: false,
+    log: (...a: unknown[]) => (out.json ? console.error(...a) : console.log(...a)),
+    result: {} as Record<string, unknown>,
+    set: (patch: Record<string, unknown>) => Object.assign(out.result, patch),
+};

package/src/phase-two.test.ts

@@ -0,0 +1,154 @@
+import { describe, expect, it, vi } from 'vitest';
+import { consentUrl } from './consent-contract';
+import { personalizeClaimButton, validateDomains } from './embed';
+import { PRODUCTION_NETWORK, STAGING_NETWORK } from './project';
+import { closeWebhookReceiver, loadWebhookModule, webhookConfig } from './webhook';
+
+describe('consent URL', () => {
+    it('encodes both parameters and selects the app for the network', () => {
+        for (const [network, origin] of [
+            [PRODUCTION_NETWORK, 'https://learncard.app'],
+            [STAGING_NETWORK, 'https://staging.learncard.ai'],
+            ['http://localhost:4000/trpc', 'https://learncard.app'],
+        ]) {
+            const url = new URL(
+                consentUrl('lc:network:contract?a&b', 'https://example.com/cb?a=1&b=2', network!)
+            );
+            expect(url.origin).toBe(origin);
+            expect(url.searchParams.get('uri')).toBe('lc:network:contract?a&b');
+            expect(url.searchParams.get('returnTo')).toBe('https://example.com/cb?a=1&b=2');
+        }
+    });
+});
+
+describe('embed helpers', () => {
+    it('uses the network domain/origin validator, including its error message', () => {
+        expect(validateDomains('http://localhost:3000, example.com')).toEqual([
+            'http://localhost:3000',
+            'example.com',
+        ]);
+        for (const invalid of [
+            '',
+            'https://example.com/path',
+            'file://example.com',
+            'https://*.example.com',
+        ]) {
+            expect(() => validateDomains(invalid)).toThrow(/Must be a valid/);
+        }
+    });
+    it('substitutes keys safely, including replacement and script-closing characters', () => {
+        const html = personalizeClaimButton("pk_$&'</script>", 'http://localhost:4000/api');
+        expect(html).not.toContain('PUBLISHABLE_KEY_PLACEHOLDER');
+        expect(html).toContain("pk_$&'\\u003c/script>");
+        expect(html).toContain('http://localhost:4000/api');
+        expect(html).toContain('LearnCard.init(');
+    });
+});
+
+describe('canonical webhook helpers', () => {
+    it('resolves trusted DID and port from the project with explicit overrides', () => {
+        const env = { PORT: '9000', EXPECTED_NETWORK_DID: 'did:key:project' };
+        expect(webhookConfig(env, {}, {})).toEqual({ port: 9000, expectedDid: 'did:key:project' });
+        expect(
+            webhookConfig(
+                env,
+                { port: '9001' },
+                { PORT: '9002', EXPECTED_NETWORK_DID: 'did:key:runtime' }
+            )
+        ).toEqual({ port: 9001, expectedDid: 'did:key:runtime' });
+        expect(() => webhookConfig({}, { port: '0' }, {})).toThrow('Port must be');
+    });
+    it('closes connections even when verification never completes', async () => {
+        const { createWebhookReceiver } = await loadWebhookModule();
+        let started!: () => void;
+        const verifying = new Promise<void>(resolve => {
+            started = resolve;
+        });
+        const server = createWebhookReceiver({
+            invoke: {
+                verifyPresentation: () => {
+                    started();
+                    return new Promise(() => {});
+                },
+            },
+        });
+        await new Promise<void>(resolve => server.listen(0, '127.0.0.1', resolve));
+        const address = server.address();
+        if (!address || typeof address === 'string') throw new Error('Expected TCP address');
+        const request = fetch(`http://127.0.0.1:${address.port}`, {
+            method: 'POST',
+            headers: { Authorization: 'Bearer pending' },
+            body: '{}',
+        }).catch(() => undefined);
+        await verifying;
+        await closeWebhookReceiver(server);
+        await request;
+        expect(server.listening).toBe(false);
+    });
+    it('rejects invalid authentication and payloads, and acknowledges duplicate events once', async () => {
+        const { createWebhookReceiver } = await loadWebhookModule();
+        const verifyPresentation = vi.fn().mockResolvedValue({ errors: [] });
+        const server = createWebhookReceiver({ invoke: { verifyPresentation } }, 'did:key:trusted');
+        const log = vi.spyOn(console, 'log').mockImplementation(() => {});
+        await new Promise<void>(resolve => server.listen(0, '127.0.0.1', resolve));
+        const address = server.address();
+        if (!address || typeof address === 'string') throw new Error('Expected TCP address');
+        const url = `http://127.0.0.1:${address.port}`;
+        const token = (iss: string): string =>
+            `header.${Buffer.from(JSON.stringify({ iss })).toString('base64url')}.signature`;
+        const post = (body: string, bearer = token('did:key:trusted')) =>
+            fetch(url, {
+                method: 'POST',
+                headers: { Authorization: `Bearer ${bearer}` },
+                body,
+            });
+        try {
+            expect((await fetch(url, { method: 'POST' })).status).toBe(401);
+            expect((await post('{}', token('did:key:other'))).status).toBe(403);
+            verifyPresentation.mockResolvedValueOnce({ errors: ['invalid signature'] });
+            expect((await post('{}')).status).toBe(401);
+            expect((await post('{')).status).toBe(400);
+            expect((await post('{}')).status).toBe(400);
+            const data = { inbox: { issuanceId: 'same-id', status: 'PENDING' } };
+            const delivered = JSON.stringify({ type: 'ISSUANCE_DELIVERED', data });
+            expect((await post(delivered)).status).toBe(200);
+            expect((await post(delivered)).status).toBe(200);
+            expect((await post(JSON.stringify({ type: 'ISSUANCE_CLAIMED', data }))).status).toBe(
+                200
+            );
+            expect(log).toHaveBeenCalledTimes(2);
+            expect(verifyPresentation).toHaveBeenCalledWith(expect.any(String), {
+                proofFormat: 'jwt',
+            });
+        } finally {
+            log.mockRestore();
+            await new Promise<void>((resolve, reject) =>
+                server.close(error => (error ? reject(error) : resolve()))
+            );
+        }
+    });
+    it('extracts only bearer credentials', async () => {
+        const { extractBearer } = await loadWebhookModule();
+        expect(extractBearer('Bearer abc.def.ghi')).toBe('abc.def.ghi');
+        expect(extractBearer('bearer   token')).toBe('token');
+        for (const invalid of [undefined, null, [], 'Basic abc', 'Bearer', 'Bearer a b']) {
+            expect(extractBearer(invalid)).toBeUndefined();
+        }
+    });
+    it('deduplicates retries without conflating delivered and claimed', async () => {
+        const { webhookDedupeKey } = await loadWebhookModule();
+        const data = { inbox: { issuanceId: 'abc' } };
+        expect(webhookDedupeKey({ type: 'ISSUANCE_DELIVERED', data })).toBe(
+            'ISSUANCE_DELIVERED:abc'
+        );
+        expect(webhookDedupeKey({ type: 'ISSUANCE_CLAIMED', data })).toBe('ISSUANCE_CLAIMED:abc');
+        for (const invalid of [
+            null,
+            {},
+            { type: 'OTHER', data },
+            { type: 'ISSUANCE_DELIVERED', data: { inbox: {} } },
+        ]) {
+            expect(webhookDedupeKey(invalid)).toBeUndefined();
+        }
+    });
+});

package/src/project.test.ts

@@ -0,0 +1,207 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import {
+    assertProjectNetwork,
+    KEYS,
+    createPrompts,
+    ensureIdentity,
+    loadProject,
+    parseEnv,
+    resolveServices,
+    saveProject,
+    upsertEnv,
+} from './project';
+
+afterEach(() => vi.restoreAllMocks());
+
+describe('createPrompts non-interactive behavior', () => {
+    const originalIsTTY = process.stdin.isTTY;
+    const originalLcYes = process.env.LC_YES;
+
+    afterEach(() => {
+        Object.defineProperty(process.stdin, 'isTTY', { value: originalIsTTY, configurable: true });
+        if (originalLcYes === undefined) delete process.env.LC_YES;
+        else process.env.LC_YES = originalLcYes;
+    });
+
+    it('returns the fallback without opening a prompt when yes is true', async () => {
+        const prompts = createPrompts(true);
+        await expect(prompts.ask('Display name', 'My Organization')).resolves.toBe(
+            'My Organization'
+        );
+        prompts.close();
+    });
+
+    it('returns the fallback when stdin is not a TTY, even without --yes', async () => {
+        Object.defineProperty(process.stdin, 'isTTY', { value: false, configurable: true });
+        const prompts = createPrompts(undefined);
+        await expect(prompts.ask('Display name', 'My Organization')).resolves.toBe(
+            'My Organization'
+        );
+        prompts.close();
+    });
+
+    it('treats LC_YES=1 as non-interactive even when stdin looks like a real TTY', async () => {
+        Object.defineProperty(process.stdin, 'isTTY', { value: true, configurable: true });
+        process.env.LC_YES = '1';
+        const prompts = createPrompts(undefined);
+        await expect(prompts.ask('Display name', 'My Organization')).resolves.toBe(
+            'My Organization'
+        );
+        prompts.close();
+    });
+
+    it('throws a descriptive error when non-interactive and no fallback exists', async () => {
+        const prompts = createPrompts(true);
+        await expect(prompts.ask('Recipient email (--to <email>)', '')).rejects.toThrow(
+            'Recipient email (--to <email>) is required when running non-interactively. Pass it as an argument or flag.'
+        );
+        prompts.close();
+    });
+});
+describe('project context', () => {
+    it('parses exported and commented seeds without changing identity', () => {
+        expect(
+            parseEnv('export SECURE_SEED="original" # keep\nPROFILE_ID=issuer # comment\n')
+        ).toEqual({ SECURE_SEED: 'original', PROFILE_ID: 'issuer' });
+        expect(upsertEnv('export PROFILE_ID=old\n', { PROFILE_ID: 'new' })).toBe(
+            'PROFILE_ID=new\n'
+        );
+        expect(() => parseEnv('SECURE_SEED=one\nSECURE_SEED=two\n')).toThrow('Conflicting');
+    });
+    it('rejects network changes when resources are already saved', () => {
+        const project = {
+            existing: '',
+            envPath: '/unused/.env',
+            env: { TEMPLATE_URI: 'lc:template' },
+        };
+        expect(() =>
+            assertProjectNetwork(project, 'https://staging.network.learncard.com/trpc')
+        ).toThrow('separate folder');
+        expect(() =>
+            assertProjectNetwork(project, 'https://network.learncard.com/trpc')
+        ).not.toThrow();
+    });
+    it('documents the stable shared keys', () => {
+        expect(Object.keys(KEYS)).toEqual([
+            'SECURE_SEED',
+            'PROFILE_ID',
+            'DISPLAY_NAME',
+            'NETWORK_URL',
+            'SIGNING_AUTHORITY_NAME',
+            'SIGNING_AUTHORITY_ENDPOINT',
+            'API_TOKEN',
+            'API_TOKEN_SCOPE',
+            'TEMPLATE_URI',
+            'CONTRACT_URI',
+            'PUBLISHABLE_KEY',
+            'INTEGRATION_ID',
+        ]);
+        expect(Object.values(KEYS)).toEqual(Object.keys(KEYS));
+    });
+    it('preserves unrelated lines and quotes scope lists', () => {
+        const result = upsertEnv('# keep\nOTHER=one\n', {
+            API_TOKEN_SCOPE: 'boosts:write inbox:read',
+        });
+        expect(result).toBe('# keep\nOTHER=one\nAPI_TOKEN_SCOPE="boosts:write inbox:read"\n');
+        expect(parseEnv(result).API_TOKEN_SCOPE).toBe('boosts:write inbox:read');
+    });
+    it('does not ask for a display name when a profile already exists', async () => {
+        const cwd = await fs.mkdtemp(path.join(os.tmpdir(), 'lc-project-'));
+        vi.spyOn(console, 'log').mockImplementation(() => {});
+        try {
+            await fs.writeFile(path.join(cwd, '.env'), 'SECURE_SEED=existing\nPROFILE_ID=issuer\n');
+            const project = await loadProject(cwd);
+            vi.spyOn(process.stdin, 'isTTY', 'get').mockReturnValue(true);
+            const identity = await Promise.race([
+                ensureIdentity(project, {}),
+                new Promise<never>((_, reject) =>
+                    setTimeout(() => reject(new Error('prompted for a display name')), 500)
+                ),
+            ]);
+            expect(identity.profileId).toBe('issuer');
+            expect((await loadProject(cwd)).env.DISPLAY_NAME).toBeUndefined();
+        } finally {
+            vi.restoreAllMocks();
+            await fs.rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it('accumulates keys, does not rewrite unchanged values, and never replaces a seed', async () => {
+        const cwd = await fs.mkdtemp(path.join(os.tmpdir(), 'lc-project-'));
+        vi.spyOn(console, 'log').mockImplementation(() => {});
+        try {
+            await fs.writeFile(
+                path.join(cwd, '.env'),
+                '# keep\nSECURE_SEED=existing\nPROFILE_ID=issuer\n'
+            );
+            await fs.writeFile(path.join(cwd, '.gitignore'), '.env\n');
+            const project = await loadProject(cwd);
+            const identity = await ensureIdentity(project, { yes: true, profileId: 'ignored' });
+            expect(identity.seed).toBe('existing');
+            expect(identity.profileId).toBe('issuer');
+            expect(console.log).not.toHaveBeenCalled();
+            await saveProject(project, { TEMPLATE_URI: 'lc:template' });
+            await saveProject(project, { API_TOKEN: 'secret' });
+            expect((await fs.stat(project.envPath)).mode & 0o777).toBe(0o600);
+            expect((await loadProject(cwd)).env).toMatchObject({
+                SECURE_SEED: 'existing',
+                TEMPLATE_URI: 'lc:template',
+                API_TOKEN: 'secret',
+            });
+            expect(console.log).toHaveBeenCalledWith('Wrote TEMPLATE_URI to .env');
+            await expect(saveProject(project, { SECURE_SEED: 'replacement' })).rejects.toThrow(
+                'Cannot replace'
+            );
+        } finally {
+            await fs.rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it('refuses stale identity writes and symlinked env files', async () => {
+        const cwd = await fs.mkdtemp(path.join(os.tmpdir(), 'lc-project-safety-'));
+        const log = vi.spyOn(console, 'log').mockImplementation(() => {});
+        try {
+            const stale = await loadProject(cwd);
+            const current = await loadProject(cwd);
+            await saveProject(current, { SECURE_SEED: 'original' });
+            await expect(saveProject(stale, { SECURE_SEED: 'different' })).rejects.toThrow(
+                'Cannot replace'
+            );
+            expect((await loadProject(cwd)).env.SECURE_SEED).toBe('original');
+            await fs.rename(current.envPath, path.join(cwd, 'target'));
+            await fs.symlink(path.join(cwd, 'target'), current.envPath);
+            await expect(loadProject(cwd)).rejects.toThrow('symlink');
+        } finally {
+            log.mockRestore();
+            await fs.rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it('resolves staging services together and preserves explicit local LCA URLs', () => {
+        expect(resolveServices({}, 'staging', {})).toEqual({
+            network: 'https://staging.network.learncard.com/trpc',
+            cloud: 'https://staging.cloud.learncard.com/trpc',
+            lcaAPI: 'https://staging.api.learncard.app/trpc',
+        });
+        expect(
+            resolveServices({ NETWORK_URL: 'http://localhost:4000/trpc' }, undefined, {
+                LCA_API_URL: 'http://localhost:5200/api',
+            }).lcaAPI
+        ).toBe('http://localhost:5200/api');
+        expect(() => resolveServices({}, 'file:///tmp/network', {})).toThrow('HTTP');
+    });
+});
+
+describe('upsertEnv value quoting', () => {
+    it('writes percent-encoded network URIs bare so shell scripts can read them', () => {
+        expect(upsertEnv('', { TEMPLATE_URI: 'lc:network:localhost%3A4000/trpc:boost:abc' })).toBe(
+            'TEMPLATE_URI=lc:network:localhost%3A4000/trpc:boost:abc\n'
+        );
+    });
+
+    it('quotes values with spaces or shell-significant characters', () => {
+        expect(upsertEnv('', { API_TOKEN_SCOPE: 'boosts:write inbox:read' })).toBe(
+            'API_TOKEN_SCOPE="boosts:write inbox:read"\n'
+        );
+    });
+});