@agentage/cli 0.38.1 → 0.40.0

package/dist/commands/extension/list.js

@@ -0,0 +1,102 @@
+import {} from 'commander';
+import {} from './check.js';
+import {} from './install.js';
+import {} from './remove.js';
+import { printWarnings, rowLines } from './row-lines.js';
+import { gatherExtensions, invalidProfileError } from './rows.js';
+// The rows, or the whole report as JSON, on stdout; warnings on stderr.
+export const printReport = ({ status, warnings }, json) => {
+    const rows = status.extensions.length > 0 ? rowLines(status.extensions) : ['no extensions'];
+    if (json)
+        console.log(JSON.stringify(status, null, 2));
+    else
+        for (const text of rows)
+            console.log(text);
+    printWarnings(warnings);
+};
+// The rows always print; an invalid profile.json then fails the step (exit 1).
+export const runExtensionList = async (opts = {}) => {
+    const gathered = await gatherExtensions();
+    printReport(gathered, opts.json);
+    const failure = invalidProfileError(gathered.status.profile);
+    if (failure)
+        throw failure;
+};
+const INSTALL_HELP = `
+<name> is resolved in this order: a local path (./path or /path) is a dev extension, kept in
+machine.json by its real path and loaded on this machine only, in place of an installed copy of
+the same package; http:, file:, npm: and github: are refused; an https: tarball URL and a
+package name are used as written (a name without @<range> is pinned to ^ its newest version
+whose engines.agentage fits this CLI's extension API, naming each newer version it skipped);
+a short name like memory is @agentage/extension-memory, else agentage-extension-memory. A
+package goes into profile.json (created from the default profile when absent), from the
+registry the profile names for its scope; --off keeps it from loading on this machine. Then
+installs and loads like setup, and exits 1 when an extension failed. Never signs in. On a
+machine whose profile comes from your account, the change applies to the account's newest
+profile and is pushed (with npm's lock) once everything loaded; if another machine pushed in
+between, it is replayed once on that profile.`;
+const REMOVE_HELP = `
+<name> is a package name, a short name or an extension id. Refused while another extension
+peer-depends on it. Takes it out of profile.json and this machine's off list, or out of
+machine.json for a dev extension, deletes state/<id>.json, then installs and loads the rest like
+setup, and pushes the profile to your account like install. --purge also deletes data/<id>/
+after asking; without a terminal it needs --yes.`;
+const LIST_HELP = `
+One row per extension in the profile, a dev path or the installed tree: id, state (installed,
+off, blocked, invalid, missing), what setup would change (add, update, remove; blank for
+nothing), package, installed version, wanted range, contributed commands, the last run from
+state/<id>.json, and the reason when it cannot load. Extension code is never loaded; the only
+file written is machine.json.`;
+const CHECK_HELP = `
+Loads every extension this machine can run, once, the way setup does: what an extension prints
+while loading goes to stderr, state/<id>.json is rewritten for each, and the rows show ok or
+failed with the reason (a dependent of a failed extension is blocked). Exits 1 when any
+extension failed, or on integrity drift between the lock and the installed tree.`;
+// Bare `extension` prints its help (exit 0); an unknown subcommand stays a usage error (exit 2).
+const helpOrUnknown = (_opts, group) => {
+    const name = group.args[0];
+    if (name === undefined)
+        group.help();
+    group.error(`error: unknown command '${name}'`, { code: 'commander.unknownCommand' });
+};
+const addChanges = (group, { install, remove }) => {
+    group
+        .command('install')
+        .description('Add an extension to the profile, then install and load it')
+        .argument('<name>', 'package name[@range], short name, https: tarball URL or local path')
+        .option('--off', 'install it, but do not load it on this machine')
+        .addHelpText('after', INSTALL_HELP)
+        .action((name, opts) => install({ name, ...opts }));
+    group
+        .command('remove')
+        .description('Remove an extension from the profile, then install and load the rest')
+        .argument('<name>', 'package name, short name or extension id')
+        .option('--purge', "also delete the extension's data, data/<id>/")
+        .option('--yes', 'do not ask before --purge deletes (needed without a terminal)')
+        .addHelpText('after', REMOVE_HELP)
+        .action((name, opts) => remove({ name, ...opts }));
+};
+const addReports = (group, { list, check }) => {
+    group
+        .command('list')
+        .description('Show one row per extension: state, versions, commands, last run')
+        .option('--json', 'machine-readable output')
+        .addHelpText('after', LIST_HELP)
+        .action(list);
+    group
+        .command('check')
+        .description('Load every extension once and refresh its state: ok or failed')
+        .option('--json', 'machine-readable output')
+        .addHelpText('after', CHECK_HELP)
+        .action(check);
+};
+// Help lists the subcommands in this order: install, remove, list, check.
+export const registerExtension = (program, actions) => {
+    const group = program
+        .command('extension')
+        .description('Work with the extensions on this machine')
+        .allowExcessArguments()
+        .action(helpOrUnknown);
+    addChanges(group, actions);
+    addReports(group, actions);
+};

package/dist/commands/extension/plan.d.ts

@@ -0,0 +1,8 @@
+import { type Plan } from '../../core/installer/plan.js';
+import { type Profile } from '../../core/profile/schema.js';
+export interface PlanOptions {
+    json?: boolean;
+}
+export declare const planLines: ({ extensions, summary: s }: Plan) => string[];
+export declare const printDryRun: (profile: Profile, opts: PlanOptions) => void;
+export declare const runSetupCheck: (profile: Profile, opts: PlanOptions) => void;

package/dist/commands/extension/plan.js

@@ -0,0 +1,67 @@
+import { DEFAULT_REGISTRY } from '../../core/installer/npm.js';
+import { currentDependencies, driftLines, lockDrift, pendingChanges, planChanges, } from '../../core/installer/plan.js';
+import { NO_MACHINE, readMachine } from '../../core/profile/machine.js';
+import { effective, keepMachine } from '../../core/profile/merge.js';
+import { readProfile } from '../../core/profile/profile.js';
+import {} from '../../core/profile/schema.js';
+import { line } from './install-load.js';
+// Desired: the profile, with this machine's own entry from profile.json as setup keeps it.
+const planFor = (profile, machine) => {
+    const local = readProfile();
+    const id = machine?.id ?? '';
+    const desired = keepMachine(profile, local?.ok ? local.profile : null, id);
+    return planChanges(effective(desired, machine ?? NO_MACHINE), currentDependencies());
+};
+const entryLine = ({ verb, name, wanted, current }) => {
+    if (verb === 'add')
+        return `+ add ${name} ${wanted}`;
+    if (verb === 'update')
+        return `~ update ${name} ${wanted} (was ${current})`;
+    return verb === 'remove' ? `- remove ${name}` : `o off ${name}`;
+};
+// One line per extension setup would touch or leaves off, then one summary line.
+export const planLines = ({ extensions, summary: s }) => {
+    const shown = extensions.filter((entry) => entry.verb !== 'unchanged');
+    if (shown.length === 0)
+        return ['plan: nothing to change'];
+    const total = `${s.add} to add, ${s.update} to update, ${s.remove} to remove`;
+    return [...shown.map(entryLine), `plan: ${total}, ${s.off} off, ${s.unchanged} unchanged`];
+};
+// One line per scope the profile routes, then the registry for everything else.
+const registryLines = (registries) => {
+    const all = [...Object.entries(registries), ['default', DEFAULT_REGISTRY]];
+    const width = Math.max(...all.map(([scope]) => scope.length));
+    return all.map(([scope, url]) => line('registry', `${scope.padEnd(width)}  ${url}`));
+};
+// `setup --dry-run`: reads only, never creates machine.json.
+export const printDryRun = (profile, opts) => {
+    const plan = planFor(profile, readMachine());
+    if (opts.json)
+        return console.log(JSON.stringify(plan, null, 2));
+    const header = [line('dry run', 'nothing written'), ...registryLines(profile.registries)];
+    for (const text of [...header, ...planLines(plan)])
+        console.log(text);
+};
+const LOCK_MISMATCH = 'lock mismatch: extensions/package-lock.json does not match the current tree';
+// What applying the plan would not fix: a lock that disagrees with its tree.
+const lockProblems = () => {
+    const { integrity, matches } = lockDrift();
+    if (integrity.length > 0)
+        return driftLines(integrity);
+    return matches ? [] : [LOCK_MISMATCH];
+};
+// `setup --check`: the plan, then exit 1 for anything setup would change or cannot trust.
+export const runSetupCheck = (profile, opts) => {
+    const machine = readMachine();
+    const plan = planFor(profile, machine);
+    const problems = [...(machine ? [] : ['machine.json: missing']), ...lockProblems()];
+    if (opts.json)
+        console.log(JSON.stringify({ ...plan, problems }, null, 2));
+    else
+        for (const text of planLines(plan))
+            console.log(text);
+    const changes = pendingChanges(plan.summary);
+    const pending = changes.length > 0 ? [`not converged: ${changes.join(', ')}`] : [];
+    if (problems.length + pending.length > 0)
+        throw new Error([...problems, ...pending].join('\n'));
+};

package/dist/commands/extension/remove.d.ts

@@ -0,0 +1,15 @@
+import { type EditDeps } from './sync.js';
+export interface ExtensionRemoveOptions {
+    name: string;
+    purge?: boolean;
+    yes?: boolean;
+}
+export interface ConfirmIo {
+    isTTY: boolean;
+    prompt: (question: string) => Promise<string>;
+}
+export interface ExtensionRemoveDeps extends EditDeps {
+    io: ConfirmIo;
+}
+export declare const terminalIo: () => ConfirmIo;
+export declare const runExtensionRemove: (opts: ExtensionRemoveOptions, deps: ExtensionRemoveDeps) => Promise<void>;

package/dist/commands/extension/remove.js

@@ -0,0 +1,86 @@
+import { rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { candidatesFor } from '../../core/installer/resolve.js';
+import { ID_PATTERN } from '../../core/loader/manifest.js';
+import { scan } from '../../core/loader/scan.js';
+import { dataDir, stateDir } from '../../core/paths.js';
+import { dropExtension } from '../../core/profile/edit.js';
+import { loadMachine, setDev } from '../../core/profile/machine.js';
+import { editableProfile } from '../../core/profile/profile.js';
+import { installAndLoad, line } from './install-load.js';
+import { finishEdit, pullForEdit } from './sync.js';
+const askLine = async (question) => {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        return await rl.question(question);
+    }
+    finally {
+        rl.close();
+    }
+};
+export const terminalIo = () => ({
+    isTTY: process.stdin.isTTY === true,
+    prompt: askLine,
+});
+const idOf = (pkg, found) => {
+    const id = found.found.extensions.find((e) => e.pkg === pkg)?.id ?? null;
+    return id !== null && ID_PATTERN.test(id) ? id : null;
+};
+// A package name, then the names a short name stands for, then an extension id.
+const targetOf = (input, found) => {
+    const names = new Set([...Object.keys(found.eff.install), ...Object.keys(found.eff.dev)]);
+    const pkg = [input, ...candidatesFor(input)].find((name) => names.has(name)) ??
+        found.found.extensions.find((e) => e.id === input)?.pkg;
+    if (pkg === undefined)
+        throw new Error(`${input} is not installed`);
+    return { pkg, id: idOf(pkg, found) };
+};
+// Checked against every extension the profile or a dev path names, not only what loads here.
+const refuseDependents = (pkg, found) => {
+    const dependents = found.found.extensions
+        .filter((e) => e.pkg !== pkg && e.peers.includes(pkg) && !e.optionalPeers.includes(pkg))
+        .map((e) => e.id ?? e.pkg)
+        .join(', ');
+    if (dependents)
+        throw new Error(`${pkg} is needed by ${dependents}; remove ${dependents} first`);
+};
+// Asked before anything changes, so a refusal or Ctrl+C leaves everything as it was.
+const purgeConfirmed = async (opts, target, io) => {
+    if (!opts.purge)
+        return false;
+    if (target.id === null)
+        throw new Error(`--purge needs the extension id of ${target.pkg}, which is not installed here`);
+    const data = dataDir(target.id);
+    if (opts.yes)
+        return true;
+    if (!io.isTTY)
+        throw new Error(`--purge without a terminal needs --yes (it deletes ${data})`);
+    return /^y(es)?$/i.test((await io.prompt(`delete ${data} and everything in it? [y/N] `)).trim());
+};
+// This machine's traces of it: the dev path, the state file and, with --purge, its data.
+const dropHere = async ({ pkg, id }, found, purge) => {
+    if (pkg in found.eff.dev)
+        await setDev(pkg, null);
+    if (id !== null)
+        rmSync(join(stateDir(), `${id}.json`), { force: true });
+    console.log(line('removed', pkg));
+    if (!purge || id === null)
+        return;
+    rmSync(dataDir(id), { recursive: true, force: true });
+    console.log(line('purged', dataDir(id)));
+};
+// Nothing stays loaded to dispose: the CLI process loads extensions only for one command.
+export const runExtensionRemove = async (opts, deps) => {
+    editableProfile(); // an invalid or newer profile.json stops here, before anything changes
+    const found = scan(await loadMachine());
+    const { pkg, id } = targetOf(opts.name, found);
+    refuseDependents(pkg, found);
+    const purge = await purgeConfirmed(opts, { pkg, id }, deps.io);
+    const inProfile = pkg in found.eff.install;
+    const synced = inProfile ? await pullForEdit(deps) : null;
+    await dropHere({ pkg, id }, found, purge);
+    if (!inProfile)
+        return installAndLoad(editableProfile(), deps.npm);
+    await finishEdit(synced, (profile) => dropExtension(profile, pkg, found.machine.id), deps);
+};

package/dist/commands/extension/row-lines.d.ts

@@ -0,0 +1,4 @@
+import { type ExtensionRow, type ExtensionsStatus } from './rows.js';
+export declare const summaryLines: (status: ExtensionsStatus) => string[];
+export declare const rowLines: (rows: ExtensionRow[]) => string[];
+export declare const printWarnings: (warnings: string[]) => void;

package/dist/commands/extension/row-lines.js

@@ -0,0 +1,68 @@
+import chalk from 'chalk';
+import { pendingChanges } from '../../core/installer/plan.js';
+import {} from './rows.js';
+const COLOR = {
+    installed: chalk.green,
+    ok: chalk.green,
+    off: chalk.dim,
+    blocked: chalk.yellow,
+    invalid: chalk.red,
+    failed: chalk.red,
+    missing: chalk.yellow,
+};
+const STATE_WIDTH = Math.max(...Object.keys(COLOR).map((state) => state.length));
+const line = (label, value) => `${label.padEnd(10)} ${value}`;
+const cloudText = ({ version, etag }) => chalk.yellow(`; account: version ${version}, etag ${etag} - run agentage setup`);
+const profileText = (profile) => {
+    if (profile.state === 'missing')
+        return 'no profile';
+    if (profile.state === 'invalid')
+        return chalk.red('invalid');
+    const etag = profile.etag === null ? '' : `, etag ${profile.etag}`;
+    const readOnly = profile.readOnly ? chalk.yellow(', read-only') : '';
+    const cloud = profile.cloud ? cloudText(profile.cloud) : '';
+    return `version ${profile.version} (source: ${profile.source}${etag}${readOnly})${cloud}`;
+};
+const pendingText = (plan) => {
+    const changes = pendingChanges(plan);
+    return changes.length === 0 ? '' : ` (${changes.join(', ')})`;
+};
+// The three lines `status` adds; the rows themselves belong to `extension list`.
+export const summaryLines = (status) => [
+    line('machine', `${status.machine.id} (${status.machine.name})`),
+    line('profile', profileText(status.profile)),
+    line('extensions', `${status.extensions.length}${pendingText(status.plan)}`),
+];
+const lastRunText = (run) => {
+    if (run === null)
+        return '';
+    const error = run.error === null ? '' : ` "${run.error}"`;
+    return `  last run: ${run.state}${error} at ${run.at}`;
+};
+// What setup would change; blank otherwise, and for off, which the state column already shows.
+const driftOf = (row) => row.plan === 'add' || row.plan === 'update' || row.plan === 'remove' ? row.plan : '';
+const wantedText = (row) => {
+    if (row.mode === 'dev')
+        return 'dev';
+    return row.wanted === null ? 'not in profile' : `wants ${row.wanted}`;
+};
+const rowLine = (row, widths) => {
+    const id = (row.id ?? '?').padEnd(widths.id);
+    const state = COLOR[row.state](row.state.padEnd(STATE_WIDTH));
+    const drift = widths.drift === 0 ? '' : `${driftOf(row).padEnd(widths.drift)}  `;
+    const pkg = `${row.package} ${row.installed ?? '-'} (${wantedText(row)})`;
+    const commands = row.commands.length > 0 ? `  commands: ${row.commands.join(', ')}` : '';
+    // A failed load quotes the extension's own message; the core's reasons print as they are.
+    const reason = row.state === 'failed' ? `"${row.error}"` : row.error;
+    const error = row.error === null ? '' : chalk.dim(`  ${reason}`);
+    return `${id}  ${state}  ${drift}${pkg}${commands}${lastRunText(row.lastRun)}${error}`;
+};
+export const rowLines = (rows) => {
+    const id = Math.max(0, ...rows.map((row) => (row.id ?? '?').length));
+    const drift = Math.max(0, ...rows.map((row) => driftOf(row).length));
+    return rows.map((row) => rowLine(row, { id, drift }));
+};
+export const printWarnings = (warnings) => {
+    for (const warning of warnings)
+        console.error(chalk.yellow(`warning: ${warning}`));
+};

package/dist/commands/extension/rows.d.ts

@@ -0,0 +1,56 @@
+import { type PlanSummary, type PlanVerb } from '../../core/installer/plan.js';
+import { type LoadOutcome } from '../../core/loader/load.js';
+import { type Scan } from '../../core/loader/scan.js';
+import { type StaticState } from '../../core/loader/states.js';
+import { type ProfileSource } from '../../core/profile/machine.js';
+export type RowState = StaticState | 'ok' | 'failed';
+export interface ExtensionRow {
+    id: string | null;
+    package: string;
+    mode: 'installed' | 'dev';
+    wanted: string | null;
+    installed: string | null;
+    state: RowState;
+    plan: PlanVerb | null;
+    error: string | null;
+    commands: string[];
+    lastRun: {
+        at: string;
+        state: string;
+        error: string | null;
+    } | null;
+}
+export type ProfileStatus = {
+    state: 'missing';
+} | {
+    state: 'invalid';
+    errors: string[];
+} | {
+    state: 'ok';
+    version: number;
+    source: ProfileSource;
+    readOnly: boolean;
+    etag: string | null;
+    cloud?: {
+        version: number;
+        etag: string;
+    };
+};
+export interface ExtensionsStatus {
+    machine: {
+        id: string;
+        name: string;
+        registered?: boolean | null;
+    };
+    profile: ProfileStatus;
+    plan: PlanSummary;
+    extensions: ExtensionRow[];
+}
+export interface ExtensionsGather {
+    status: ExtensionsStatus;
+    warnings: string[];
+    drift: string[];
+}
+export declare const gatherFrom: (found: Scan, runs?: ReadonlyMap<string, LoadOutcome>) => ExtensionsGather;
+export declare const gatherExtensions: () => Promise<ExtensionsGather>;
+export declare const invalidProfileError: (profile: ProfileStatus) => Error | null;

package/dist/commands/extension/rows.js

@@ -0,0 +1,61 @@
+import {} from '../../core/installer/plan.js';
+import {} from '../../core/loader/discover.js';
+import {} from '../../core/loader/load.js';
+import { scan } from '../../core/loader/scan.js';
+import { readRunState } from '../../core/loader/state.js';
+import {} from '../../core/loader/states.js';
+import { loadMachine } from '../../core/profile/machine.js';
+import {} from '../../core/profile/schema.js';
+const profileStatus = (parsed, machine) => {
+    if (parsed === null)
+        return { state: 'missing' };
+    if (!parsed.ok)
+        return { state: 'invalid', errors: parsed.errors };
+    const { version } = parsed.profile;
+    const source = machine.profileSource;
+    const etag = source === 'cloud' ? machine.profileEtag : null;
+    return { state: 'ok', version, source, readOnly: parsed.readOnly, etag };
+};
+// A row for an invalid manifest has no trustworthy id, so it never shows another extension's run.
+const lastRunOf = (p, s) => {
+    const run = p.id === null || s.state === 'invalid' ? null : readRunState(p.id);
+    return run && { at: run.at, state: run.state, error: run.error };
+};
+const toRow = (p, found, s) => ({
+    id: p.id,
+    package: p.pkg,
+    mode: p.source === 'dev' ? 'dev' : 'installed',
+    wanted: found.eff.install[p.pkg] ?? null,
+    installed: p.version,
+    state: s.state,
+    plan: p.source === 'dev' ? null : verbOf(found, p.pkg),
+    error: s.error,
+    commands: p.commands,
+    lastRun: lastRunOf(p, s),
+});
+const verbOf = (found, pkg) => found.plan.extensions.find((entry) => entry.name === pkg)?.verb ?? null;
+// A load in this process is the run itself: its state replaces the static one.
+const withRun = (row, run) => run ? { ...row, state: run.state, error: run.error, lastRun: null } : row;
+const UNKNOWN = { state: 'invalid', error: null };
+const STILL_INSTALLED = { state: 'installed', error: null };
+export const gatherFrom = (found, runs = new Map()) => {
+    const { machine, parsed, states } = found;
+    const extensions = [
+        ...found.found.extensions.map((p) => withRun(toRow(p, found, states.get(p.pkg) ?? UNKNOWN), runs.get(p.pkg))),
+        ...found.removed.map((p) => toRow(p, found, STILL_INSTALLED)),
+    ].sort((a, b) => (a.package < b.package ? -1 : 1));
+    const status = {
+        machine: { id: machine.id, name: machine.name },
+        profile: profileStatus(parsed, machine),
+        plan: found.plan.summary,
+        extensions,
+    };
+    const warnings = [...(parsed?.ok ? parsed.warnings : []), ...found.found.warnings];
+    return { status, warnings, drift: found.drift };
+};
+// Reads manifests, profile and state files; writes only a missing machine.json.
+export const gatherExtensions = async () => gatherFrom(scan(await loadMachine()));
+// The report still prints first; an invalid profile.json then fails the step.
+export const invalidProfileError = (profile) => profile.state === 'invalid'
+    ? new Error(`profile.json is invalid:\n${profile.errors.map((e) => `  ${e}`).join('\n')}`)
+    : null;

package/dist/commands/extension/secrets-prompt.d.ts

@@ -0,0 +1,6 @@
+import { type SecretKey } from '../../core/loader/secrets.js';
+export interface SecretsIo {
+    isTTY: boolean;
+    prompt: (question: string) => Promise<string>;
+}
+export declare const askSecrets: (missing: SecretKey[], io?: SecretsIo) => Promise<void>;

package/dist/commands/extension/secrets-prompt.js

@@ -0,0 +1,47 @@
+import { secretsFor } from '../../core/loader/secrets.js';
+const ENTER = ['\r', '\n', '\u0004'];
+const CTRL_C = '\u0003';
+const BACKSPACE = '\u007f';
+// One keypress: the answer so far, or null once Enter ends it.
+const typed = (answer, char) => {
+    if (ENTER.includes(char))
+        return null;
+    return char === BACKSPACE ? answer.slice(0, -1) : answer + char;
+};
+// Raw mode keeps the answer off the screen; Ctrl+C still interrupts once the terminal is restored.
+const readHidden = (question) => new Promise((resolve) => {
+    const { stdin, stderr } = process;
+    let answer = '';
+    const onData = (chunk) => {
+        for (const char of chunk.toString('utf-8')) {
+            const next = char === CTRL_C ? null : typed(answer, char);
+            if (next === null)
+                return finish(char === CTRL_C);
+            answer = next;
+        }
+    };
+    const finish = (interrupted) => {
+        stdin.off('data', onData).setRawMode(false).pause();
+        stderr.write('\n');
+        resolve(answer);
+        if (interrupted)
+            process.kill(process.pid, 'SIGINT');
+    };
+    stderr.write(question);
+    stdin.setRawMode(true).resume().on('data', onData);
+});
+const terminal = () => ({ isTTY: process.stdin.isTTY === true, prompt: readHidden });
+const nameOf = ({ id, key }) => `${id}.${key}`;
+// Before loading: a terminal is asked for each missing secret, anything else gets the list.
+export const askSecrets = async (missing, io = terminal()) => {
+    if (missing.length === 0)
+        return;
+    if (!io.isTTY)
+        return void console.log(`secrets to set: ${missing.map(nameOf).join(', ')}`);
+    for (const secret of missing) {
+        const described = secret.description === null ? '' : ` (${secret.description})`;
+        const value = await io.prompt(`${nameOf(secret)}${described}: `);
+        if (value !== '')
+            await secretsFor(secret.id).set(secret.key, value);
+    }
+};

package/dist/commands/extension/setup-cloud.d.ts

@@ -0,0 +1,6 @@
+import { type EditDeps } from './sync.js';
+export interface AccountSetupDeps extends EditDeps {
+    signOut: () => Promise<void>;
+}
+export declare const accountSetup: (deps: EditDeps) => Promise<void>;
+export declare const disconnect: (deps: AccountSetupDeps) => Promise<void>;

package/dist/commands/extension/setup-cloud.js

@@ -0,0 +1,98 @@
+import chalk from 'chalk';
+import { localProfile, NotPushedError, pullProfile, } from '../../core/profile/cloud.js';
+import { forgetAccount, loadMachine, readMachine, setAccount, setCloud, } from '../../core/profile/machine.js';
+import { defaultProfile, mutateProfile, readProfile } from '../../core/profile/profile.js';
+import { pushWithReplay } from '../../core/profile/push.js';
+import { disconnectMachine, registerMachine } from '../../core/profile/register.js';
+import {} from '../../core/profile/schema.js';
+import { installAndLoad, line } from './install-load.js';
+import { applying, checkAccount } from './sync.js';
+const FILE_NOTE = 'from a file (setup --profile), not synced with your account';
+// profile.json: null when absent; an invalid one stops setup naming each problem.
+const localCopy = () => {
+    const parsed = readProfile();
+    if (parsed === null)
+        return null;
+    if (parsed.ok)
+        return parsed.profile;
+    throw new Error(`profile.json is invalid:\n${parsed.errors.map((e) => `  ${e}`).join('\n')}`);
+};
+// The etag profile.json still mirrors: sent as If-None-Match, so an unchanged profile is a 304.
+const mirroredEtag = (machine) => machine.profileSource === 'cloud' && readProfile()?.ok === true ? machine.profileEtag : null;
+// Without the account: the local profile.json; with none, nothing to install, and setup goes on.
+const fromLocalCopy = async (reason, deps) => {
+    const local = localCopy();
+    const unavailable = 'cloud profile unavailable';
+    if (local === null)
+        return console.error(chalk.dim(`${unavailable} and no local profile.json, nothing installed (${reason})`));
+    console.error(chalk.dim(`${unavailable}, using local profile.json (${reason})`));
+    await installAndLoad(local, deps.npm);
+};
+const installPulled = async (doc, deps) => {
+    await mutateProfile(() => doc.profile);
+    console.log(line('profile', `pulled from your account (etag ${doc.etag})`));
+    await installAndLoad({ ...doc.profile, lock: doc.lock }, deps.npm, () => setCloud(doc.etag));
+};
+// A create the account did not take fails nothing: the next setup creates it.
+const notCreated = (err) => {
+    if (!(err instanceof NotPushedError))
+        throw err;
+    console.error(chalk.dim(`${err.message}; the next agentage setup tries again`));
+    return null;
+};
+// No profile in the account yet: this machine's own, or the default, becomes it once it loaded.
+const createIn = async (account, deps) => {
+    const base = localProfile(localCopy() ?? defaultProfile());
+    const apply = applying((profile) => profile, deps);
+    const done = await pushWithReplay(account.fetch, base, apply).catch(notCreated);
+    if (done === null)
+        return;
+    await setCloud(done.etag);
+    const where = done.pushed ? 'created in' : 'already in';
+    console.log(line('profile', `${where} your account (etag ${done.etag})`));
+};
+// Plain setup pulls and never pushes, except to create the account's first profile.
+const profileFrom = async (account, machine, deps) => {
+    if (machine.profileSource === 'file') {
+        console.log(line('profile', FILE_NOTE));
+        return installAndLoad(localCopy() ?? defaultProfile(), deps.npm);
+    }
+    const pulled = await pullProfile(account.fetch, mirroredEtag(machine));
+    if (pulled.kind === 'found')
+        return installPulled(pulled.doc, deps);
+    if (pulled.kind === 'none')
+        return createIn(account, deps);
+    if (pulled.kind === 'current')
+        return installAndLoad(localCopy() ?? defaultProfile(), deps.npm);
+    return fromLocalCopy(pulled.reason, deps);
+};
+// The first signed-in setup records the account; another account is refused until --disconnect.
+const connect = async (account) => {
+    const machine = await loadMachine();
+    const userId = await checkAccount(account, machine);
+    return userId === null || machine.accountId !== null ? machine : setAccount(userId);
+};
+// Registration runs alongside the profile, so it never delays setup by more than its 2 s.
+export const accountSetup = async (deps) => {
+    const account = deps.account();
+    if (account === null)
+        return fromLocalCopy('not signed in', deps);
+    const machine = await connect(account);
+    const registered = registerMachine(account.fetch, machine);
+    try {
+        await profileFrom(account, machine, deps);
+    }
+    finally {
+        await registered;
+    }
+};
+// setup --disconnect: the account marks this machine disconnected, then it forgets the account.
+export const disconnect = async (deps) => {
+    const machine = readMachine();
+    const account = deps.account();
+    if (machine !== null && account !== null)
+        await disconnectMachine(account.fetch, machine.id);
+    await deps.signOut();
+    if (machine !== null)
+        await forgetAccount();
+};

package/dist/commands/extension/setup.d.ts

@@ -0,0 +1,5 @@
+import { type SetupDeps, type SetupOptions } from '../auth/setup.js';
+import { type EditDeps } from './sync.js';
+export interface ExtensionSetupDeps extends SetupDeps, EditDeps {
+}
+export declare const runExtensionSetup: (opts: SetupOptions, deps: ExtensionSetupDeps) => Promise<void>;