claude-account-sync 0.3.0 → 0.5.0

package/dist/commands/bundle.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import { type CliContext } from '../context.js';
+export declare function registerBundleCommands(program: Command, ctx: CliContext): void;

package/dist/commands/bundle.js

@@ -1,7 +1,8 @@
-import { exportBundle, importBundle, collectAssets, writeAssets, parseManifest, serializeManifest, saveManifest, discoverProfiles, planApply, executeApply, backupFiles, } from 'ccprofiles-core';
+import { exportBundle, importBundle, collectAssets, writeAssets, parseManifest, serializeManifest, saveManifest, executeApply, backupFiles, } from 'ccprofiles-core';
 import { readFile, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { requireManifest } from '../context.js';
+import { planActions, planActionsPreflight } from '../plan.js';
 function stamp() { return new Date().toISOString().replace(/[:.]/g, '-'); }
 export function registerBundleCommands(program, ctx) {
     program.command('export <file>').description('export manifest + assets as a portable bundle (no secrets)')
@@ -26,12 +27,13 @@ export function registerBundleCommands(program, ctx) {
             process.exitCode = 1;
             return;
         }
+        await planActionsPreflight(ctx, m); // abort before touching local state if the bundle has an unresolvable secret ref
         if (!opts.dryRun) {
             await backupFiles([join(ctx.manifestRoot, 'manifest.yaml')], ctx.backupRoot, stamp());
             await saveManifest(ctx.manifestRoot, m);
             await writeAssets(assets, m, ctx.platform);
         }
-        const actions = planApply(m, await discoverProfiles(ctx.home), ctx.platform);
+        const actions = await planActions(ctx, m);
         const res = await executeApply(actions, { backupRoot: ctx.backupRoot, stamp: stamp(), dryRun: !!opts.dryRun });
         for (const line of res.performed)
             console.log(`${opts.dryRun ? '[dry-run] ' : ''}${line}`);

package/dist/commands/manifest.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import { type CliContext } from '../context.js';
+export declare function registerManifestCommands(program: Command, ctx: CliContext): void;

package/dist/commands/manifest.js

@@ -1,10 +1,14 @@
-import { discoverProfiles, buildManifest, saveManifest, planApply, executeApply, } from 'ccprofiles-core';
+import { discoverProfiles, buildManifest, saveManifest, loadManifest, preserveSecretRefs, executeApply, } from 'ccprofiles-core';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
 import { requireManifest } from '../context.js';
+import { planActions } from '../plan.js';
+import { secretsStore } from './secrets.js';
 function stamp() { return new Date().toISOString().replace(/[:.]/g, '-'); }
 export function registerManifestCommands(program, ctx) {
     program.command('status').description('show live-vs-manifest drift').action(async () => {
         const m = await requireManifest(ctx);
-        const actions = planApply(m, await discoverProfiles(ctx.home), ctx.platform);
+        const actions = await planActions(ctx, m);
         if (actions.length === 0) {
             console.log('in sync');
             return;
@@ -17,7 +21,7 @@ export function registerManifestCommands(program, ctx) {
         .option('--dry-run')
         .action(async (opts) => {
         const m = await requireManifest(ctx);
-        const actions = planApply(m, await discoverProfiles(ctx.home), ctx.platform);
+        const actions = await planActions(ctx, m);
         if (actions.length === 0) {
             console.log('in sync — nothing to do');
             return;
@@ -30,6 +34,11 @@ export function registerManifestCommands(program, ctx) {
     });
     program.command('snapshot').description('overwrite manifest from live state').action(async () => {
         const m = buildManifest(await discoverProfiles(ctx.home), ctx.platform);
+        if (existsSync(join(ctx.manifestRoot, 'manifest.yaml'))) {
+            const oldM = await loadManifest(ctx.manifestRoot);
+            let store = null;
+            await preserveSecretRefs(m, oldM, async (name) => { store ??= await secretsStore(ctx); return store.get(name); });
+        }
         await saveManifest(ctx.manifestRoot, m);
         console.log(`snapshot: ${m.profiles.length} profiles, ${Object.keys(m.mcpServers).length} mcp servers`);
     });
@@ -50,9 +59,10 @@ export function registerManifestCommands(program, ctx) {
             env: {},
             links: src ? { ...src.links } : (m.hub ? { skills: 'hub', commands: 'hub' } : {}),
             mcp: src ? [...src.mcp] : [],
+            settingsEnv: {},
         });
         await saveManifest(ctx.manifestRoot, m);
-        const actions = planApply(m, await discoverProfiles(ctx.home), ctx.platform);
+        const actions = await planActions(ctx, m);
         await executeApply(actions, { backupRoot: ctx.backupRoot, stamp: stamp() });
         console.log(`profile "${name}" created — launcher: cl-${name} (restart your shell)`);
     });

package/dist/commands/mcp.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import { type CliContext } from '../context.js';
+export declare function registerMcpCommands(program: Command, ctx: CliContext): void;

package/dist/commands/mcp.js

@@ -1,8 +1,9 @@
-import { discoverProfiles, saveManifest, planApply, executeApply, } from 'ccprofiles-core';
+import { saveManifest, executeApply, } from 'ccprofiles-core';
 import { requireManifest } from '../context.js';
+import { planActions } from '../plan.js';
 function stamp() { return new Date().toISOString().replace(/[:.]/g, '-'); }
 async function applyNow(ctx, m, dryRun) {
-    const actions = planApply(m, await discoverProfiles(ctx.home), ctx.platform);
+    const actions = await planActions(ctx, m);
     const res = await executeApply(actions, { backupRoot: ctx.backupRoot, stamp: stamp(), dryRun });
     for (const line of res.performed)
         console.log(`${dryRun ? '[dry-run] ' : ''}${line}`);

package/dist/commands/profiles.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import type { CliContext } from '../context.js';
+export declare function registerProfileCommands(program: Command, ctx: CliContext): void;

package/dist/commands/profiles.js

@@ -1,7 +1,8 @@
-import { discoverProfiles, buildManifest, saveManifest, loadManifest, ensureRootGitignore } from 'ccprofiles-core';
+import { discoverProfiles, buildManifest, saveManifest, loadManifest, preserveSecretRefs, ensureRootGitignore } from 'ccprofiles-core';
 import { existsSync, readFileSync, lstatSync, readlinkSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { execFileSync } from 'node:child_process';
+import { KEY_VARS, secretsStore } from './secrets.js';
 export function registerProfileCommands(program, ctx) {
     program.command('list').description('list Claude Code profiles').action(async () => {
         const live = await discoverProfiles(ctx.home);
@@ -24,6 +25,11 @@ export function registerProfileCommands(program, ctx) {
             console.log('Re-run with --yes to write the manifest.');
             return;
         }
+        if (existsSync(join(ctx.manifestRoot, 'manifest.yaml'))) {
+            const oldM = await loadManifest(ctx.manifestRoot);
+            let store = null;
+            await preserveSecretRefs(manifest, oldM, async (name) => { store ??= await secretsStore(ctx); return store.get(name); });
+        }
         if (!existsSync(join(ctx.manifestRoot, '.git'))) {
             try {
                 execFileSync('git', ['init', ctx.manifestRoot], { stdio: 'ignore' });
@@ -37,7 +43,10 @@ export function registerProfileCommands(program, ctx) {
     program.command('doctor').description('check setup health').action(async () => {
         const problems = [];
         const live = await discoverProfiles(ctx.home);
-        for (const lp of live)
+        let m = null;
+        if (existsSync(join(ctx.manifestRoot, 'manifest.yaml')))
+            m = await loadManifest(ctx.manifestRoot);
+        for (const lp of live) {
             for (const name of readdirSync(lp.dir)) {
                 const f = join(lp.dir, name);
                 try {
@@ -46,20 +55,27 @@ export function registerProfileCommands(program, ctx) {
                 }
                 catch { /* ignore */ }
             }
+            const pname = lp.dirName === '.claude' ? 'default' : lp.dirName.slice('.claude-'.length);
+            const decl = m?.profiles.find(p => p.name === pname) ?? null;
+            for (const varName of KEY_VARS) {
+                if (lp.settingsEnv[varName] && !decl?.settingsEnv[varName])
+                    problems.push(`plaintext token ${varName} in ${join(lp.dir, 'settings.json')} — adopt profile then run: secrets migrate`);
+                if (decl?.settingsEnv[varName] && !decl.settingsEnv[varName].startsWith('secret://'))
+                    problems.push(`plaintext token ${varName} in manifest for profile "${pname}" — run: secrets migrate`);
+            }
+        }
         if (existsSync(ctx.platform.rcFile)) {
             const rc = readFileSync(ctx.platform.rcFile, 'utf8');
             const outsideBlock = rc.split('# >>> ccprofiles managed >>>')[0] + (rc.split('# <<< ccprofiles managed <<<')[1] ?? '');
             if (/sk-ant-/.test(outsideBlock))
                 problems.push(`plaintext Anthropic key found in ${ctx.platform.rcFile} — run: ccprofiles secrets migrate`);
         }
-        if (existsSync(join(ctx.manifestRoot, 'manifest.yaml'))) {
-            const m = await loadManifest(ctx.manifestRoot);
+        if (m)
             for (const pr of m.profiles) {
                 const dir = pr.dir.replace('{home}', ctx.home);
                 if (!existsSync(dir))
                     problems.push(`manifest profile "${pr.name}" missing on disk: ${dir} — run: ccprofiles apply`);
             }
-        }
         if (problems.length === 0) {
             console.log('ok: no problems found');
             return;

package/dist/commands/secrets.d.ts

@@ -0,0 +1,14 @@
+import type { Command } from 'commander';
+import { SecretsStore } from 'ccprofiles-core';
+import type { CliContext } from '../context.js';
+export declare function secretsStore(ctx: CliContext): Promise<SecretsStore>;
+export declare const KEY_VARS: string[];
+/** Move plaintext keys out of the shell rc file into the secrets store. Shared by the CLI and the UI API. */
+export declare function migrateRcSecrets(ctx: CliContext, opts?: {
+    dryRun?: boolean;
+}): Promise<string[]>;
+/** Move plaintext token values in manifest settingsEnv into the secrets store as secret:// refs. */
+export declare function migrateSettingsSecrets(ctx: CliContext, opts?: {
+    dryRun?: boolean;
+}): Promise<string[]>;
+export declare function registerSecretsCommands(program: Command, ctx: CliContext): void;

package/dist/commands/secrets.js

@@ -1,6 +1,7 @@
-import { SecretsStore, FileBackend, defaultBackend, backupFiles, atomicWrite } from 'ccprofiles-core';
+import { SecretsStore, FileBackend, defaultBackend, backupFiles, atomicWrite, loadManifest, saveManifest, executeApply } from 'ccprofiles-core';
 import { readFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
+import { join } from 'node:path';
 export async function secretsStore(ctx) {
     const pw = ctx.env.CCPROFILES_PASSPHRASE;
     const backend = pw
@@ -11,7 +12,7 @@ export async function secretsStore(ctx) {
         });
     return new SecretsStore(backend, ctx.secretsIndexPath);
 }
-const KEY_VARS = ['ANTHROPIC_API_KEY', 'CLAUDE_CODE_OAUTH_TOKEN', 'ANTHROPIC_AUTH_TOKEN'];
+export const KEY_VARS = ['ANTHROPIC_API_KEY', 'CLAUDE_CODE_OAUTH_TOKEN', 'ANTHROPIC_AUTH_TOKEN'];
 // posix: export VAR="sk-..."   powershell: $env:VAR = "sk-..."
 const MIGRATE_RE_POSIX = new RegExp(`^(\\s*(?:export\\s+)?(${KEY_VARS.join('|')})\\s*=\\s*)"?(sk-[A-Za-z0-9_-]+)"?(.*)$`);
 const MIGRATE_RE_PWSH = new RegExp(`^(\\s*\\$env:(${KEY_VARS.join('|')})\\s*=\\s*)"?(sk-[A-Za-z0-9_-]+)"?(.*)$`);
@@ -47,6 +48,29 @@ export async function migrateRcSecrets(ctx, opts = {}) {
     }
     return migrated;
 }
+/** Move plaintext token values in manifest settingsEnv into the secrets store as secret:// refs. */
+export async function migrateSettingsSecrets(ctx, opts = {}) {
+    if (!existsSync(join(ctx.manifestRoot, 'manifest.yaml')))
+        return [];
+    const m = await loadManifest(ctx.manifestRoot);
+    const store = await secretsStore(ctx);
+    const migrated = [];
+    for (const pr of m.profiles) {
+        for (const varName of KEY_VARS) {
+            const v = pr.settingsEnv[varName];
+            if (!v || v.startsWith('secret://'))
+                continue;
+            const secretName = `${varName.toLowerCase().replaceAll('_', '-')}-${pr.name}`;
+            if (!opts.dryRun)
+                await store.set(secretName, v);
+            pr.settingsEnv[varName] = `secret://${secretName}`;
+            migrated.push(secretName);
+        }
+    }
+    if (migrated.length && !opts.dryRun)
+        await saveManifest(ctx.manifestRoot, m);
+    return migrated;
+}
 export function registerSecretsCommands(program, ctx) {
     const sec = program.command('secrets').description('manage secrets (values never stored in configs)');
     sec.command('set <name> [value]').action(async (name, value) => {
@@ -76,12 +100,22 @@ export function registerSecretsCommands(program, ctx) {
         console.log(`removed ${name}`);
     });
     sec.command('migrate').option('--dry-run').action(async (opts) => {
-        const migrated = await migrateRcSecrets(ctx, opts);
+        const migrated = [...await migrateRcSecrets(ctx, opts), ...await migrateSettingsSecrets(ctx, opts)];
         if (migrated.length === 0) {
             console.log('no plaintext keys found');
             return;
         }
         for (const n of migrated)
             console.log(`${opts.dryRun ? '[dry-run] ' : ''}migrated ${n}`);
+        // Apply so the manifest's newly-minted secret:// refs are (re-)resolved and written back
+        // out — dynamic import avoids a static circular import (plan.ts imports this module for secretsStore).
+        if (!opts.dryRun && existsSync(join(ctx.manifestRoot, 'manifest.yaml'))) {
+            const { planActions } = await import('../plan.js');
+            const m = await loadManifest(ctx.manifestRoot);
+            const actions = await planActions(ctx, m);
+            const res = await executeApply(actions, { backupRoot: ctx.backupRoot, stamp: new Date().toISOString().replace(/[:.]/g, '-') });
+            for (const line of res.performed)
+                console.log(`applied: ${line}`);
+        }
     });
 }

package/dist/commands/sync.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import type { CliContext } from '../context.js';
+export declare function registerSyncCommands(program: Command, ctx: CliContext): void;

package/dist/commands/sync.js

@@ -1,6 +1,7 @@
-import { startSyncServer, pairWithServer, fetchRemote, fetchSecrets, loadDevices, saveDevices, parseManifest, saveManifest, writeAssets, discoverProfiles, planApply, executeApply, backupFiles, } from 'ccprofiles-core';
+import { startSyncServer, pairWithServer, fetchRemote, fetchSecrets, loadDevices, saveDevices, parseManifest, saveManifest, writeAssets, executeApply, backupFiles, } from 'ccprofiles-core';
 import { join } from 'node:path';
 import { secretsStore } from './secrets.js';
+import { planActions, planActionsPreflight } from '../plan.js';
 function stamp() { return new Date().toISOString().replace(/[:.]/g, '-'); }
 export function registerSyncCommands(program, ctx) {
     program.command('serve').description('serve this device for pairing/sync')
@@ -62,22 +63,30 @@ export function registerSyncCommands(program, ctx) {
         const { manifestYaml, assets } = await fetchRemote(device);
         const m = parseManifest(manifestYaml); // validate before touching anything
         console.log(`pulled manifest: ${m.profiles.length} profiles, ${Object.keys(m.mcpServers).length} mcp servers, ${Object.keys(assets).length} asset files`);
+        // Fetch+store secrets BEFORE touching local state, so a preflight below that needs a
+        // just-transferred secret succeeds instead of failing after the manifest is overwritten.
+        let values = {};
+        if (opts.withSecrets) {
+            values = await fetchSecrets(device, []);
+            if (!opts.dryRun) {
+                const store = await secretsStore(ctx);
+                for (const [k, v] of Object.entries(values))
+                    await store.set(k, v);
+            }
+        }
+        // Validate the pulled manifest resolves cleanly before saving/applying anything — abort
+        // (propagating the Error) rather than leave the local manifest overwritten and broken.
+        await planActionsPreflight(ctx, m);
         if (!opts.dryRun) {
             await backupFiles([join(ctx.manifestRoot, 'manifest.yaml')], ctx.backupRoot, stamp());
             await saveManifest(ctx.manifestRoot, m);
             await writeAssets(assets, m, ctx.platform);
         }
-        const actions = planApply(m, await discoverProfiles(ctx.home), ctx.platform);
+        const actions = await planActions(ctx, m);
         const res = await executeApply(actions, { backupRoot: ctx.backupRoot, stamp: stamp(), dryRun: !!opts.dryRun });
         for (const line of res.performed)
             console.log(`${opts.dryRun ? '[dry-run] ' : ''}${line}`);
         if (opts.withSecrets) {
-            const values = await fetchSecrets(device, []);
-            if (!opts.dryRun) {
-                const store = await secretsStore(ctx);
-                for (const [k, v] of Object.entries(values))
-                    await store.set(k, v);
-            }
             console.log(`${opts.dryRun ? '[dry-run] ' : ''}secrets transferred: ${Object.keys(values).join(', ') || 'none'}`);
         }
     });

package/dist/context.d.ts

@@ -0,0 +1,15 @@
+import { Command } from 'commander';
+import { type Manifest, type Platform } from 'ccprofiles-core';
+export interface CliContext {
+    home: string;
+    platform: Platform;
+    manifestRoot: string;
+    secretsIndexPath: string;
+    secretsFilePath: string;
+    backupRoot: string;
+    env: NodeJS.ProcessEnv;
+}
+export declare function makeContext(env?: NodeJS.ProcessEnv): CliContext;
+/** Load the manifest, or explain how to create one — never a raw ENOENT. */
+export declare function requireManifest(ctx: CliContext): Promise<Manifest>;
+export declare function buildProgram(ctx: CliContext): Command;

package/dist/context.js

@@ -11,7 +11,17 @@ import { registerBundleCommands } from './commands/bundle.js';
 import { registerUiCommand } from './ui/command.js';
 export function makeContext(env = process.env) {
     const testHome = env.CCPROFILES_TEST_HOME;
-    const platform = detectPlatform(testHome ? { home: testHome, shell: env.SHELL } : {});
+    // CCPROFILES_FORCE_OS is a test-only seam for simulating other platforms' secrets-backend
+    // selection from a single dev machine — never set this outside tests. It intentionally
+    // accepts any sentinel string (not just OsKind): detectPlatform/defaultBackend only ever
+    // compare it against 'darwin'/'linux'/'win32' at runtime, so a value like 'none' safely
+    // flows through as a deterministic "none of the above" platform for tests. Gated behind
+    // CCPROFILES_TEST_HOME (the existing test-only signal) so it can never affect production.
+    const forcedOs = testHome ? env.CCPROFILES_FORCE_OS : undefined;
+    const platform = detectPlatform({
+        ...(testHome ? { home: testHome, shell: env.SHELL } : {}),
+        ...(forcedOs ? { osKind: forcedOs } : {}),
+    });
     const manifestRoot = env.CCPROFILES_HOME ?? join(platform.home, '.ccprofiles');
     return {
         home: platform.home,

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/plan.d.ts

@@ -0,0 +1,6 @@
+import { type ApplyAction, type Manifest } from 'ccprofiles-core';
+import type { CliContext } from './context.js';
+/** Plan apply actions with settingsEnv secret refs resolved from the secrets store (lazily opened). */
+export declare function planActions(ctx: CliContext, m: Manifest): Promise<ApplyAction[]>;
+/** Resolve settingsEnv secrets without planning — cheap validation that refs exist. */
+export declare function planActionsPreflight(ctx: CliContext, m: Manifest): Promise<void>;

package/dist/plan.js

@@ -0,0 +1,19 @@
+import { discoverProfiles, planApply, resolveSettingsEnv } from 'ccprofiles-core';
+import { secretsStore } from './commands/secrets.js';
+/** Plan apply actions with settingsEnv secret refs resolved from the secrets store (lazily opened). */
+export async function planActions(ctx, m) {
+    let store = null;
+    const resolved = await resolveSettingsEnv(m, async (name) => {
+        store ??= await secretsStore(ctx);
+        return store.get(name);
+    });
+    return planApply(m, await discoverProfiles(ctx.home), ctx.platform, resolved);
+}
+/** Resolve settingsEnv secrets without planning — cheap validation that refs exist. */
+export async function planActionsPreflight(ctx, m) {
+    let store = null;
+    await resolveSettingsEnv(m, async (name) => {
+        store ??= await secretsStore(ctx);
+        return store.get(name);
+    });
+}

package/dist/ui/api.d.ts

@@ -0,0 +1,3 @@
+import { type CliContext } from '../context.js';
+import { type Route } from './http.js';
+export declare function buildRoutes(ctx: CliContext): Route[];

package/dist/ui/api.js

@@ -1,10 +1,11 @@
-import { discoverProfiles, buildManifest, saveManifest, planApply, executeApply, ensureRootGitignore, loadManifest, loadDevices, fetchRemote, fetchSecrets, writeAssets, parseManifest, backupFiles, renderRcBlock, upsertManagedBlock, atomicWrite, BEGIN_MARK, END_MARK, assertSafeManifest, } from 'ccprofiles-core';
+import { discoverProfiles, buildManifest, saveManifest, executeApply, ensureRootGitignore, loadManifest, loadDevices, fetchRemote, fetchSecrets, writeAssets, parseManifest, backupFiles, renderRcBlock, upsertManagedBlock, atomicWrite, BEGIN_MARK, END_MARK, assertSafeManifest, preserveSecretRefs, } from 'ccprofiles-core';
 import { existsSync, readFileSync, lstatSync, readlinkSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { requireManifest } from '../context.js';
-import { secretsStore, migrateRcSecrets } from '../commands/secrets.js';
+import { secretsStore, migrateRcSecrets, migrateSettingsSecrets, KEY_VARS } from '../commands/secrets.js';
 import { sendJson, readJson, HttpError } from './http.js';
+import { planActions, planActionsPreflight } from '../plan.js';
 function stamp() { return new Date().toISOString().replace(/[:.]/g, '-'); }
 function profileName(dirName) {
     return dirName === '.claude' ? 'default' : dirName.slice('.claude-'.length);
@@ -12,8 +13,20 @@ function profileName(dirName) {
 export function buildRoutes(ctx) {
     const routes = [];
     const add = (method, pattern, handler) => routes.push({ method, pattern, handler });
+    // A missing secret ref is a recoverable/user-facing state (not a server error) — surface as 409.
+    async function planActionsOr409(m) {
+        try {
+            return await planActions(ctx, m);
+        }
+        catch (e) {
+            const msg = e.message;
+            if (/secret not found/.test(msg))
+                throw new HttpError(409, msg);
+            throw e;
+        }
+    }
     async function applyAndReport(m) {
-        const actions = planApply(m, await discoverProfiles(ctx.home), ctx.platform);
+        const actions = await planActionsOr409(m);
         return executeApply(actions, { backupRoot: ctx.backupRoot, stamp: stamp() });
     }
     // requireManifest throws a plain Error; surface "no manifest yet" as a 409 the UI can detect.
@@ -45,6 +58,11 @@ export function buildRoutes(ctx) {
     // ── adopt / profiles / status / apply / doctor ──────────────────────────────
     add('POST', /^\/api\/adopt$/, async (_m, _req, res) => {
         const manifest = buildManifest(await discoverProfiles(ctx.home), ctx.platform);
+        if (existsSync(join(ctx.manifestRoot, 'manifest.yaml'))) {
+            const oldM = await loadManifest(ctx.manifestRoot);
+            let store = null;
+            await preserveSecretRefs(manifest, oldM, async (name) => { store ??= await secretsStore(ctx); return store.get(name); });
+        }
         if (!existsSync(join(ctx.manifestRoot, '.git'))) {
             try {
                 execFileSync('git', ['init', ctx.manifestRoot], { stdio: 'ignore' });
@@ -69,6 +87,7 @@ export function buildRoutes(ctx) {
                 launcher: decl?.launcher ?? (name === 'default' ? null : `cl-${name}`),
                 adopted: !!decl,
                 env: decl?.env ?? {}, links: decl?.links ?? {}, mcpNames: decl?.mcp ?? [],
+                settingsEnv: decl?.settingsEnv ?? {}, liveSettingsEnv: lp.settingsEnv,
             };
         });
         sendJson(res, 200, rows);
@@ -87,6 +106,7 @@ export function buildRoutes(ctx) {
             name, dir: `{home}/.claude-${name}`, launcher: `cl-${name}`, auth: 'env', env: {},
             links: src ? { ...src.links } : (m.hub ? { skills: 'hub', commands: 'hub' } : {}),
             mcp: src ? [...src.mcp] : [],
+            settingsEnv: {},
         });
         assertSafe(m);
         await saveManifest(ctx.manifestRoot, m);
@@ -112,7 +132,19 @@ export function buildRoutes(ctx) {
         }
         if (body.launcher !== undefined)
             pr.launcher = body.launcher;
+        if (body.settingsEnv) {
+            for (const v of Object.values(body.settingsEnv))
+                if (typeof v !== 'string')
+                    throw new HttpError(400, 'settingsEnv values must be strings');
+            pr.settingsEnv = body.settingsEnv;
+        }
         assertSafe(m);
+        try {
+            await planActionsPreflight(ctx, m);
+        }
+        catch (e) {
+            throw new HttpError(400, e.message);
+        }
         await saveManifest(ctx.manifestRoot, m);
         await applyAndReport(m);
         sendJson(res, 200, { ok: true });
@@ -136,7 +168,7 @@ export function buildRoutes(ctx) {
     });
     add('GET', /^\/api\/status$/, async (_m, _req, res) => {
         const m = await mustManifest();
-        const actions = planApply(m, await discoverProfiles(ctx.home), ctx.platform);
+        const actions = await planActionsOr409(m);
         const r = await executeApply(actions, { backupRoot: ctx.backupRoot, stamp: stamp(), dryRun: true });
         sendJson(res, 200, { inSync: actions.length === 0, pending: r.performed });
     });
@@ -148,7 +180,10 @@ export function buildRoutes(ctx) {
     add('GET', /^\/api\/doctor$/, async (_m, _req, res) => {
         const problems = [];
         const live = await discoverProfiles(ctx.home);
-        for (const lp of live)
+        let man = null;
+        if (existsSync(join(ctx.manifestRoot, 'manifest.yaml')))
+            man = await loadManifest(ctx.manifestRoot);
+        for (const lp of live) {
             for (const nm of readdirSync(lp.dir)) {
                 const f = join(lp.dir, nm);
                 try {
@@ -157,20 +192,26 @@ export function buildRoutes(ctx) {
                 }
                 catch { /* skip */ }
             }
+            const decl = man?.profiles.find(p => p.name === profileName(lp.dirName)) ?? null;
+            for (const varName of KEY_VARS) {
+                if (lp.settingsEnv[varName] && !decl?.settingsEnv[varName])
+                    problems.push(`plaintext token ${varName} in ${join(lp.dir, 'settings.json')} — adopt profile then run: secrets migrate`);
+                if (decl?.settingsEnv[varName] && !decl.settingsEnv[varName].startsWith('secret://'))
+                    problems.push(`plaintext token ${varName} in manifest for profile "${profileName(lp.dirName)}" — run: secrets migrate`);
+            }
+        }
         if (existsSync(ctx.platform.rcFile)) {
             const rc = readFileSync(ctx.platform.rcFile, 'utf8');
             const outside = rc.split('# >>> ccprofiles managed >>>')[0] + (rc.split('# <<< ccprofiles managed <<<')[1] ?? '');
             if (/sk-ant-/.test(outside))
                 problems.push(`plaintext Anthropic key in ${ctx.platform.rcFile} — run secrets migrate`);
         }
-        if (existsSync(join(ctx.manifestRoot, 'manifest.yaml'))) {
-            const m = await loadManifest(ctx.manifestRoot);
-            for (const pr of m.profiles) {
+        if (man)
+            for (const pr of man.profiles) {
                 const dir = pr.dir.replace('{home}', ctx.home);
                 if (!existsSync(dir))
                     problems.push(`manifest profile "${pr.name}" missing on disk: ${dir} — run apply`);
             }
-        }
         sendJson(res, 200, { problems });
     });
     // ── shell rc ────────────────────────────────────────────────────────────────
@@ -263,7 +304,13 @@ export function buildRoutes(ctx) {
     });
     // ── secrets ─────────────────────────────────────────────────────────────────
     add('GET', /^\/api\/secrets$/, async (_m, _req, res) => {
-        const store = await secretsStore(ctx);
+        let store;
+        try {
+            store = await secretsStore(ctx);
+        }
+        catch (e) {
+            return sendJson(res, 200, { names: [], backend: 'unavailable', error: e.message });
+        }
         sendJson(res, 200, { names: await store.list(), backend: store.backendName });
     });
     add('GET', /^\/api\/secrets\/([^/]+)$/, async (mtch, _req, res) => {
@@ -282,12 +329,31 @@ export function buildRoutes(ctx) {
         sendJson(res, 200, { ok: true });
     });
     add('DELETE', /^\/api\/secrets\/([^/]+)$/, async (mtch, _req, res) => {
+        const name = decodeURIComponent(mtch[1]);
+        const ref = `secret://${name}`;
+        if (existsSync(join(ctx.manifestRoot, 'manifest.yaml'))) {
+            const m = await loadManifest(ctx.manifestRoot);
+            for (const pr of m.profiles) {
+                for (const [k, v] of Object.entries(pr.env))
+                    if (v === ref)
+                        throw new HttpError(409, `secret "${name}" is referenced by profile "${pr.name}" (${k}) — detach it first`);
+                for (const [k, v] of Object.entries(pr.settingsEnv))
+                    if (v === ref)
+                        throw new HttpError(409, `secret "${name}" is referenced by profile "${pr.name}" (${k}) — detach it first`);
+            }
+        }
         const store = await secretsStore(ctx);
-        await store.delete(decodeURIComponent(mtch[1]));
+        await store.delete(name);
         sendJson(res, 200, { ok: true });
     });
     add('POST', /^\/api\/secrets\/migrate$/, async (_m, _req, res) => {
-        sendJson(res, 200, { migrated: await migrateRcSecrets(ctx) });
+        const migrated = [...await migrateRcSecrets(ctx), ...await migrateSettingsSecrets(ctx)];
+        // Apply so the manifest's newly-minted secret:// refs are (re-)resolved and written back out.
+        if (migrated.length && existsSync(join(ctx.manifestRoot, 'manifest.yaml'))) {
+            const m = await loadManifest(ctx.manifestRoot);
+            await applyAndReport(m);
+        }
+        sendJson(res, 200, { migrated });
     });
     // ── devices / sync ──────────────────────────────────────────────────────────
     add('GET', /^\/api\/devices$/, async (_m, _req, res) => {
@@ -300,13 +366,8 @@ export function buildRoutes(ctx) {
             throw new HttpError(400, `unknown device: ${from}`);
         const { manifestYaml, assets } = await fetchRemote(device);
         const m = parseManifest(manifestYaml);
-        if (!dryRun) {
-            await backupFiles([join(ctx.manifestRoot, 'manifest.yaml')], ctx.backupRoot, stamp());
-            await saveManifest(ctx.manifestRoot, m);
-            await writeAssets(assets, m, ctx.platform);
-        }
-        const actions = planApply(m, await discoverProfiles(ctx.home), ctx.platform);
-        const r = await executeApply(actions, { backupRoot: ctx.backupRoot, stamp: stamp(), dryRun: !!dryRun });
+        // Fetch+store secrets BEFORE touching local state, so a preflight below that needs
+        // a just-transferred secret succeeds instead of failing after the manifest is overwritten.
         let secrets = [];
         if (withSecrets) {
             const values = await fetchSecrets(device, []);
@@ -317,6 +378,21 @@ export function buildRoutes(ctx) {
             }
             secrets = Object.keys(values);
         }
+        // Validate the pulled manifest resolves cleanly before saving/applying anything — a peer
+        // manifest with a settingsEnv secret ref we don't have must not overwrite local state.
+        try {
+            await planActionsPreflight(ctx, m);
+        }
+        catch (e) {
+            throw new HttpError(409, e.message);
+        }
+        if (!dryRun) {
+            await backupFiles([join(ctx.manifestRoot, 'manifest.yaml')], ctx.backupRoot, stamp());
+            await saveManifest(ctx.manifestRoot, m);
+            await writeAssets(assets, m, ctx.platform);
+        }
+        const actions = await planActions(ctx, m);
+        const r = await executeApply(actions, { backupRoot: ctx.backupRoot, stamp: stamp(), dryRun: !!dryRun });
         sendJson(res, 200, { performed: r.performed, secrets });
     });
     return routes;

package/dist/ui/command.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import type { CliContext } from '../context.js';
+export declare function registerUiCommand(program: Command, ctx: CliContext): void;

package/dist/ui/http.d.ts

@@ -0,0 +1,20 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+export declare class HttpError extends Error {
+    status: number;
+    constructor(status: number, message: string);
+}
+export declare class BadRequest extends HttpError {
+    constructor(message?: string);
+}
+export declare function readBody(req: IncomingMessage): Promise<string>;
+export declare function readJson<T = any>(req: IncomingMessage): Promise<T>;
+export declare function sendJson(res: ServerResponse, code: number, body: unknown): void;
+export type Route = {
+    method: string;
+    pattern: RegExp;
+    handler: (m: RegExpMatchArray, req: IncomingMessage, res: ServerResponse) => Promise<void>;
+};
+export declare function matchRoute(routes: Route[], method: string, path: string): {
+    route: Route;
+    match: RegExpMatchArray;
+} | null;