@agentage/cli 0.38.1 → 0.40.0

package/README.md

@@ -2,18 +2,19 @@
 
 ![Connect this machine to agentage from the terminal](https://github.com/agentage/cli/raw/master/docs/banner.svg)
 
-Connect this machine to your [agentage](https://agentage.io) account from the terminal. One
-command signs you in through your browser, and from then on the machine is known to your account.
+Connect this machine to your [agentage](https://agentage.io) account from the terminal, and
+install the extensions your account's profile names. One command signs you in through your
+browser; the same profile then gives you the same extensions on every machine you set up.
 
 ## What is this?
 
-agentage gives your AI tools a shared, account-backed home. Every machine you use needs to be
-connected to that account once: this package does that connection. It keeps your sign-in on
-the machine (OAuth 2.1 with PKCE, nothing typed into the terminal), tells you whether the
-machine is connected, and keeps itself up to date.
+agentage gives your AI tools a shared, account-backed home. Every machine you use is connected
+to that account once, by this package. It keeps your sign-in on the machine (OAuth 2.1 with
+PKCE, nothing typed into the terminal), tells you whether the machine is connected, and keeps
+itself up to date.
 
-It is intentionally **small**: sign-in, status and update. Everything else arrives as plugins
-that the CLI installs for you.
+The CLI itself stays **small**: sign-in, status, update, and an extension manager. Everything
+else, memory included, arrives as an extension the CLI installs for you.
 
 ## Get started
 
@@ -33,7 +34,7 @@ agentage status
 ### On a server or in CI (no browser)
 
 ```bash
-agentage setup --no-browser        # prints the sign-in URL to open elsewhere
+agentage setup --no-browser              # prints the sign-in URL to open elsewhere
 AGENTAGE_TOKEN=aga_... agentage status   # or use a personal access token
 ```
 
@@ -44,34 +45,116 @@ AGENTAGE_TOKEN=aga_... agentage status   # or use a personal access token
 
 ## Commands
 
-| Command                       | What it does                                                            |
-| ----------------------------- | ----------------------------------------------------------------------- |
-| `agentage setup`              | Sign in through your browser, then show status                          |
-| `agentage setup --no-browser` | Print the sign-in URL instead of opening a browser                      |
-| `agentage setup --reauth`     | Force a fresh sign-in                                                   |
-| `agentage setup --disconnect` | Sign out and remove local credentials                                   |
-| `agentage status`             | Version, update, target, sign-in state, endpoint (`--json` for scripts) |
-| `agentage update`             | Install the latest published version (`--check` only reports)           |
+| Command                       | What it does                                                                  |
+| ----------------------------- | ----------------------------------------------------------------------------- |
+| `agentage setup`              | Sign in through your browser, install your account's profile, show status     |
+| `agentage setup --no-browser` | Print the sign-in URL instead of opening a browser                            |
+| `agentage setup --reauth`     | Force a fresh sign-in                                                         |
+| `agentage setup --disconnect` | Sign out and remove local credentials                                         |
+| `agentage status`             | Version, update, target, sign-in, endpoint, then machine, profile, extensions |
+| `agentage update`             | Install the latest published version (`--check` only reports)                 |
+
+For extensions (see below):
+
+| Command                                      | What it does                                                     |
+| -------------------------------------------- | ---------------------------------------------------------------- |
+| `agentage setup --profile <file>`            | Install and load the extensions a profile file names, no sign-in |
+| `agentage setup --profile <file> --dry-run`  | Show what would be installed, write nothing                      |
+| `agentage setup --latest`                    | Update each extension to the newest version its range allows     |
+| `agentage extension install <name> [--off]`  | Add an extension to the profile, install and load it             |
+| `agentage extension remove <name> [--purge]` | Take it out of the profile and reinstall the rest                |
+| `agentage extension list`                    | One row per extension: state, version, commands, last run        |
+| `agentage extension check`                   | Load every extension once and refresh the states                 |
+| `agentage <command>`                         | Run a command an installed extension contributes                 |
 
 Flags, exit codes and token auth are in [`docs/reference.md`](docs/reference.md).
 
+## Extensions
+
+An extension is an npm package that adds to the CLI: commands today, more later. Extensions are
+on by default. A machine whose profile names no extensions has none, and `setup`, `status` and
+`update` work as described above, with three more `status` lines: `machine`, `profile` and
+`extensions`.
+
+The model is simple. A **profile** says what this account wants: which extensions, at which
+version ranges, and which ones are switched off on which machine. The CLI brings the machine
+to that state: `setup` installs what the profile names, loads each extension once and prints
+whether it loaded (`ok`) or why not. `extension install` and `extension remove` edit the
+profile and then do the same. Nothing installs itself on a timer; the state only changes when
+you run a command.
+
+Once you are signed in, `setup` reads the profile your account holds, when it has one, so every
+machine you set up gets the same extensions, and `extension install` and `extension remove` save
+the change there. When your account has no profile to give, `setup` says so on one line and
+carries on. Each machine you run `setup` on appears in your account as one of its machines.
+
+```bash
+agentage setup --profile ./profile.json            # install and load the extensions a profile names
+agentage setup --profile ./profile.json --dry-run  # show the plan, write nothing
+agentage setup --check                             # exit 1 when this machine differs from its profile
+agentage setup --latest                            # newest versions the ranges allow, diff printed
+agentage extension install @agentage/example       # add one extension, install and load it
+agentage extension install ./my-extension          # a local folder, for development
+agentage extension remove @agentage/example        # take it out again
+agentage extension list                            # state per extension, with what setup would change
+agentage hello                                     # a command the hello extension contributes
+```
+
+The plan is what `setup` would change, one line per extension (`+ add`, `~ update`, `- remove`,
+`o off`) and a summary such as `plan: 1 to add, 0 to update, 0 to remove, 0 off, 2 unchanged`.
+`setup --dry-run` prints it, `setup --check` exits 1 when anything would change, `extension list`
+shows it per extension and `status` sums it up, for example `extensions 2 (1 to add)`.
+
+`setup --latest` moves each extension to the newest version its range allows and prints one line
+per change, such as `~ update @agentage/example 1.0.0 -> 1.0.1`. The new versions take over only
+after every extension loaded from them cleanly; until then the installed ones stay. A version
+that needs a newer extension API than this CLI has is skipped, here and by `extension install`.
+
+A profile is a JSON file that maps package names to version ranges. `registries` is optional
+and routes a scope to another npm-compatible registry; everything else comes from npm's public
+registry.
+
+```json
+{
+  "version": 1,
+  "extensions": { "@agentage/example": "^1.0.0" },
+  "registries": { "@acme": "https://npm.acme.example" }
+}
+```
+
+Extensions run in the CLI process with your privileges, so install only extensions you trust.
+npm runs with `--ignore-scripts`, and the account token is removed from the environment before
+any extension code loads. Everything lives in the config directory:
+
+| Path                       | What                                                           |
+| -------------------------- | -------------------------------------------------------------- |
+| `~/.agentage/profile.json` | the profile: what this account wants                           |
+| `~/.agentage/machine.json` | this machine's id, name, development extensions and account    |
+| `~/.agentage/extensions/`  | installed extensions; `extensions/current` names the live tree |
+| `~/.agentage/state/`       | the last run of each extension                                 |
+| `~/.agentage/data/<id>/`   | what each extension keeps                                      |
+
+Every state an extension can be in, and every flag, is in [`docs/reference.md`](docs/reference.md).
+To write an extension, start with [`docs/extensions.md`](docs/extensions.md).
+
 ## How it works
 
 This is the **terminal client for an agentage account**. `setup` registers a one-off OAuth
 client, opens the authorization page in your browser and waits on a localhost callback; the
 tokens land in `~/.agentage/auth.json` with owner-only permissions and are refreshed
 automatically. `status` validates the session against the account's introspection endpoint
-and reports version, update, target host and connectivity. Nothing runs in the background and
-nothing is installed beyond this package.
+and reports version, update, target host and connectivity. Nothing runs in the background, and
+nothing is installed beyond this package unless your profile names extensions.
 
 ## Configuration
 
-| Env                   | Default       | Purpose                                            |
-| --------------------- | ------------- | -------------------------------------------------- |
-| `AGENTAGE_SITE_FQDN`  | `agentage.io` | Target host                                        |
-| `AGENTAGE_CONFIG_DIR` | `~/.agentage` | Config and credentials directory                   |
-| `AGENTAGE_TOKEN`      | -             | Personal access token for CI and headless machines |
-| `NO_COLOR`            | -             | Disable colored output                             |
+| Env                       | Default               | Purpose                                            |
+| ------------------------- | --------------------- | -------------------------------------------------- |
+| `AGENTAGE_SITE_FQDN`      | `agentage.io`         | Target host                                        |
+| `AGENTAGE_CONFIG_DIR`     | `~/.agentage`         | Config and credentials directory                   |
+| `AGENTAGE_TOKEN`          | -                     | Personal access token for CI and headless machines |
+| `AGENTAGE_EXTENSIONS_DIR` | `<config>/extensions` | Where extensions are installed                     |
+| `NO_COLOR`                | -                     | Disable colored output                             |
 
 ## Develop
 
@@ -81,6 +164,9 @@ npm run verify
 npm run build && npm run test:e2e -- --grep @offline
 ```
 
+The e2e specs under `e2e/core/` read as scenarios: each title names the command and what must
+hold. They run against a loopback registry that serves the extensions under `fixtures/`.
+
 ## Release
 
 Releases publish to npm via GitHub Actions when a `chore(release): X.Y.Z` commit that touches

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

@@ -2,11 +2,17 @@ import { type Command } from 'commander';
 import { type SignInOptions, type SignInResult } from '../../lib/auth/sign-in.js';
 export interface SetupOptions extends SignInOptions {
     disconnect?: boolean;
+    profile?: string;
+    dryRun?: boolean;
+    check?: boolean;
+    latest?: boolean;
+    json?: boolean;
 }
 export interface SetupDeps {
     ensureSignedIn: (opts: SignInOptions) => Promise<SignInResult>;
     signOut: () => Promise<void>;
-    printStatus: () => Promise<void>;
+    printStatus: (opts?: {
+        token?: string;
+    }) => Promise<void>;
 }
-export declare const runSetup: (opts: SetupOptions, deps: SetupDeps) => Promise<void>;
 export declare const registerSetup: (program: Command, action: (opts: SetupOptions) => Promise<void>) => void;

package/dist/commands/auth/setup.js

@@ -1,11 +1,36 @@
-import {} from 'commander';
+import { Option } from 'commander';
 import {} from '../../lib/auth/sign-in.js';
-export const runSetup = async (opts, deps) => {
-    if (opts.disconnect)
-        return deps.signOut();
-    await deps.ensureSignedIn({ reauth: opts.reauth, browser: opts.browser });
-    await deps.printStatus();
-};
+const EXTENSIONS_HELP = `
+Extensions: --profile <file> validates a profile (schema v1), saves it as profile.json and
+installs its extensions with npm, without signing in. --dry-run prints the plan, what setup
+would change (+ add, ~ update, - remove, o off, then one summary line), and writes nothing;
+--check prints the plan and exits 1 when anything would change, the lock in the extensions
+directory does not match the installed tree, or machine.json is missing; it writes nothing.
+Neither signs in. Plain setup signs in, then pulls the profile from your account (creating it
+from this machine's profile.json, or the default, when the account has none), registers this
+machine in the account and installs; it never pushes a change. When the account cannot be
+reached it installs from the local profile.json, or, with none, installs nothing and says so on
+one line. A profile from --profile stays local: setup neither pulls nor pushes it. Each package
+comes from the registry the profile's registries map names for its scope (default
+https://registry.npmjs.org) into AGENTAGE_EXTENSIONS_DIR (default ~/.agentage/extensions). After
+installing, setup lists the secrets extensions declare and this machine has not set (asking for
+them on a terminal), then loads every extension once and prints ok or failed for each; it exits
+1 when any failed. Signed in to another account than the one this machine is connected to, setup
+exits 1; run setup --disconnect first, which also marks this machine disconnected in your
+account.
+
+--latest runs npm update in a staged copy of the installed tree: each extension moves to the
+newest version its range allows, unless that version needs another extension API (then it is
+kept, saying so). It prints one line per changed extension and a summary, loads the new tree and
+makes it current only when every extension loaded clean, then pushes the profile with the new
+lock to your account when the profile comes from it. With nothing newer it only prints
+"latest: nothing to update". It never signs in.`;
+const latestOption = () => new Option('--latest', 'update extensions to the newest versions their ranges allow').conflicts([
+    'profile',
+    'dryRun',
+    'check',
+    'disconnect',
+]);
 export const registerSetup = (program, action) => {
     program
         .command('setup')
@@ -13,5 +38,11 @@ export const registerSetup = (program, action) => {
         .option('--disconnect', 'sign out and remove local credentials')
         .option('--reauth', 'force a fresh sign-in')
         .option('--no-browser', 'print the sign-in URL instead of opening a browser')
+        .option('--profile <file>', 'install the extensions a profile file names; never signs in')
+        .option('--dry-run', 'print what setup would change and write nothing')
+        .option('--check', 'exit 1 when setup would change anything; write nothing')
+        .addOption(latestOption())
+        .option('--json', 'with --dry-run or --check: the plan as JSON')
+        .addHelpText('after', EXTENSIONS_HELP)
         .action(action);
 };

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

@@ -0,0 +1,5 @@
+import { type Account } from '../../core/profile/cloud.js';
+export type AccountOf = (opts?: {
+    token?: string;
+}) => Account | null;
+export declare const signedInAccount: AccountOf;

package/dist/commands/extension/account.js

@@ -0,0 +1,18 @@
+import {} from '../../core/profile/cloud.js';
+import { authedFetch } from '../../lib/auth/api.js';
+import { resolveAuth } from '../../lib/auth/credentials.js';
+import { detectEnvMismatch } from '../../lib/auth/env-match.js';
+import { introspectToken } from '../../lib/auth/introspect.js';
+import { apiOrigin, links, siteFqdn } from '../../lib/net/origins.js';
+const CLIENT = { 'x-client-type': 'cli' };
+// Read before any extension loads: the token is captured here, the fetch at CLI start.
+export const signedInAccount = (opts = {}) => {
+    const auth = resolveAuth(opts);
+    const fqdn = siteFqdn();
+    if (auth === null || detectEnvMismatch(auth, fqdn) !== null)
+        return null;
+    const target = links(fqdn);
+    const fetch = (path, { headers, timeoutMs, ...init } = {}) => authedFetch(auth, target, `${apiOrigin(fqdn)}${path}`, { ...init, headers: { ...CLIENT, ...headers } }, { timeoutMs });
+    const id = () => introspectToken(auth, target).then((s) => s.userId ?? null, () => null);
+    return { fetch, id };
+};

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

@@ -0,0 +1,10 @@
+import { type DiscoveredExtension } from '../../core/loader/discover.js';
+import { type ExtensionRow, type ExtensionsGather } from './rows.js';
+export interface ExtensionCheckOptions {
+    json?: boolean;
+}
+type BeforeLoad = (extensions: DiscoveredExtension[]) => Promise<void>;
+export declare const loadAndGather: (beforeLoad?: BeforeLoad, tree?: string) => Promise<ExtensionsGather>;
+export declare const failedError: (rows: ExtensionRow[]) => Error | null;
+export declare const runExtensionCheck: (opts?: ExtensionCheckOptions) => Promise<void>;
+export {};

package/dist/commands/extension/check.js

@@ -0,0 +1,35 @@
+import { driftLines } from '../../core/installer/plan.js';
+import {} from '../../core/loader/discover.js';
+import { loadExtensions } from '../../core/loader/load.js';
+import { loadSet, scan } from '../../core/loader/scan.js';
+import { loadMachine } from '../../core/profile/machine.js';
+import { printReport } from './list.js';
+import { gatherFrom, invalidProfileError, } from './rows.js';
+// Loads what can load, once: state files rewritten, rows carrying this run's ok and failed.
+// `tree` loads that tree instead of the current one.
+export const loadAndGather = async (beforeLoad = async () => undefined, tree) => {
+    const found = scan(await loadMachine(), tree);
+    const extensions = loadSet(found);
+    await beforeLoad(extensions);
+    const session = await loadExtensions(extensions);
+    await session.dispose();
+    return gatherFrom(found, session.outcomes);
+};
+export const failedError = (rows) => {
+    const failed = rows.filter((row) => row.state === 'failed').map((row) => row.id ?? row.package);
+    if (failed.length === 0)
+        return null;
+    const count = `${failed.length} extension${failed.length === 1 ? '' : 's'}`;
+    return new Error(`${count} failed to load: ${failed.join(', ')}`);
+};
+// Integrity drift: the extensions it names were not loaded, and setup refuses to build on it.
+const driftError = (drift) => drift.length === 0 ? null : new Error(driftLines(drift).join('\n'));
+// The rows always print; an invalid profile.json, integrity drift or a failed load fails the step.
+export const runExtensionCheck = async (opts = {}) => {
+    const gathered = await loadAndGather();
+    printReport(gathered, opts.json);
+    const { profile, extensions } = gathered.status;
+    const failure = invalidProfileError(profile) ?? driftError(gathered.drift) ?? failedError(extensions);
+    if (failure)
+        throw failure;
+};

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

@@ -0,0 +1,4 @@
+import { type Command } from 'commander';
+type Wrap = (fn: () => Promise<void>) => (opts: unknown) => Promise<void>;
+export declare const registerDelegates: (program: Command, argv: string[], wrap: Wrap) => void;
+export {};

package/dist/commands/extension/delegate.js

@@ -0,0 +1,45 @@
+import {} from 'commander';
+import {} from '../../core/loader/discover.js';
+import { loadExtensions } from '../../core/loader/load.js';
+import { loadOrder } from '../../core/loader/order.js';
+import { loadSet, scan } from '../../core/loader/scan.js';
+import { NO_MACHINE, readMachine } from '../../core/profile/machine.js';
+// Loads the command's extension and its peers only, then hands it the whole command line.
+const runDelegated = async (ext, name, extensions, program, argv) => {
+    const session = await loadExtensions(loadOrder([ext], extensions), program);
+    try {
+        const loaded = session.loaded.get(ext.id ?? '');
+        const run = session.outcomes.get(ext.pkg);
+        if (!loaded)
+            throw new Error(`extension ${ext.id} ${run?.state}: ${run?.error}`);
+        if (!loaded.program.commands.some((command) => command.name() === name))
+            throw new Error(`extension ${ext.id} did not add the command ${name}`);
+        await loaded.program.parseAsync(argv);
+    }
+    finally {
+        await session.dispose();
+    }
+};
+// Usage, exit 2: the core commands, then one line per extension with what it contributes.
+const unknownCommand = (program, core, extensions) => (operands) => {
+    const lines = [`error: unknown command '${operands[0]}'`, `core: ${core.join(', ')}`];
+    for (const ext of extensions.filter((e) => e.commands.length > 0))
+        lines.push(`${ext.id}: ${ext.commands.join(', ')}`);
+    program.error(lines.join('\n'), { code: 'commander.unknownCommand', exitCode: 2 });
+};
+// Manifests only, never code: each stub hands the command line, --help included, to the extension.
+export const registerDelegates = (program, argv, wrap) => {
+    const core = program.commands.map((command) => command.name());
+    const extensions = loadSet(scan(readMachine() ?? NO_MACHINE));
+    for (const ext of extensions)
+        for (const name of ext.commands)
+            program
+                .command(name)
+                .description(`from the ${ext.id} extension`)
+                .helpGroup(`${ext.id}:`)
+                .helpOption(false)
+                .allowUnknownOption()
+                .allowExcessArguments()
+                .action(wrap(() => runDelegated(ext, name, extensions, program, argv)));
+    program.on('command:*', unknownCommand(program, core, extensions));
+};

package/dist/commands/extension/install-load.d.ts

@@ -0,0 +1,7 @@
+import { type InstallSet } from '../../core/installer/installer.js';
+import { type Npm } from '../../core/installer/npm.js';
+import { type DiscoveredExtension } from '../../core/loader/discover.js';
+export declare const line: (label: string, value: string) => string;
+export declare const counted: (n: number) => string;
+export declare const listSecrets: (extensions: DiscoveredExtension[]) => Promise<void>;
+export declare const installAndLoad: (set: InstallSet, npm: () => Promise<Npm>, installed?: () => Promise<unknown>) => Promise<void>;

package/dist/commands/extension/install-load.js

@@ -0,0 +1,33 @@
+import { install } from '../../core/installer/installer.js';
+import {} from '../../core/installer/npm.js';
+import {} from '../../core/loader/discover.js';
+import { missingSecrets } from '../../core/loader/secrets.js';
+import { failedError, loadAndGather } from './check.js';
+import { printWarnings, rowLines } from './row-lines.js';
+import { gatherExtensions } from './rows.js';
+import { askSecrets } from './secrets-prompt.js';
+export const line = (label, value) => `${label.padEnd(10)} ${value}`;
+export const counted = (n) => n === 0 ? 'no extensions' : `${n} extension${n === 1 ? '' : 's'}`;
+const installLine = (result) => {
+    const how = result.reused ? 'reused' : result.npm ? `npm ${result.npm}` : 'npm skipped';
+    return line('install', `${counted(result.count)} in tree ${result.tree} (${how})`);
+};
+// Asks for, or lists, the secrets the extensions about to load declare and this machine lacks.
+export const listSecrets = (extensions) => askSecrets(missingSecrets(extensions));
+// Rows print either way, only a good install loads; `installed` runs before anything loads.
+export const installAndLoad = async (set, npm, installed = async () => undefined) => {
+    const outcome = await install(set, npm).then((result) => ({ result, error: null }), (error) => ({ result: null, error }));
+    if (outcome.result)
+        console.log(installLine(outcome.result));
+    if (outcome.result)
+        await installed();
+    const gathered = outcome.result ? await loadAndGather(listSecrets) : await gatherExtensions();
+    for (const text of rowLines(gathered.status.extensions))
+        console.log(text);
+    printWarnings(gathered.warnings);
+    if (outcome.error)
+        throw outcome.error;
+    const failed = failedError(gathered.status.extensions);
+    if (failed)
+        throw failed;
+};

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

@@ -0,0 +1,10 @@
+import { type NpmManifest } from '../../core/installer/npm.js';
+import { type EditDeps } from './sync.js';
+export interface ExtensionInstallOptions {
+    name: string;
+    off?: boolean;
+}
+export interface ExtensionInstallDeps extends EditDeps {
+    manifest: () => Promise<NpmManifest>;
+}
+export declare const runExtensionInstall: (opts: ExtensionInstallOptions, deps: ExtensionInstallDeps) => Promise<void>;

package/dist/commands/extension/install.js

@@ -0,0 +1,35 @@
+import { needs } from '../../core/installer/compat.js';
+import {} from '../../core/installer/npm.js';
+import { registryLookup, resolveName } from '../../core/installer/resolve.js';
+import { addExtension } from '../../core/profile/edit.js';
+import { loadMachine, setDev } from '../../core/profile/machine.js';
+import { editableProfile } from '../../core/profile/profile.js';
+import {} from '../../core/profile/schema.js';
+import { installAndLoad, line } from './install-load.js';
+import { finishEdit, pullForEdit } from './sync.js';
+const addPackage = async (target, off, deps) => {
+    for (const newer of target.skipped)
+        console.log(line('skipped', needs(newer)));
+    const synced = await pullForEdit(deps);
+    const { id } = await loadMachine();
+    const note = line('added', `${target.name} ${target.spec}${off ? ' (off on this machine)' : ''}`);
+    const add = (profile) => addExtension(profile, target.name, target.spec, id, off);
+    await finishEdit(synced, add, deps, note);
+};
+// A dev extension is this machine's own: it replaces an installed copy, and never syncs.
+const addDev = async (target, off, deps) => {
+    if (off)
+        throw new Error(`--off does not apply to ${target.path}: a dev extension always loads`);
+    await setDev(target.name, target.path);
+    console.log(line('dev', `${target.name} ${target.path}`));
+    await installAndLoad(editableProfile(), deps.npm);
+};
+// Never signs in: the name is looked up in the registries the local profile routes.
+export const runExtensionInstall = async (opts, deps) => {
+    const { registries } = editableProfile();
+    const target = await resolveName(opts.name, registryLookup(deps.manifest, registries));
+    if (target.kind === 'dev')
+        await addDev(target, opts.off === true, deps);
+    else
+        await addPackage(target, opts.off === true, deps);
+};

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

@@ -0,0 +1,2 @@
+import { type EditDeps } from './sync.js';
+export declare const runSetupLatest: (deps: EditDeps) => Promise<void>;

package/dist/commands/extension/latest.js

@@ -0,0 +1,70 @@
+import {} from '../../core/installer/installer.js';
+import { updateLatest, } from '../../core/installer/latest.js';
+import {} from '../../core/installer/npm.js';
+import { editableProfile, mutateProfile } from '../../core/profile/profile.js';
+import { pushBody } from '../../core/profile/push.js';
+import { loadAndGather } from './check.js';
+import { line, listSecrets } from './install-load.js';
+import { printWarnings, rowLines } from './row-lines.js';
+import {} from './rows.js';
+import { localLock, pullForEdit, pushApplied } from './sync.js';
+const changeLine = ({ name, from, to }) => {
+    if (from === null)
+        return `+ add ${name} ${to}`;
+    if (to === null)
+        return `- remove ${name} ${from}`;
+    return `~ update ${name} ${from} -> ${to}`;
+};
+const heldLine = ({ name, version, newer, engine }) => line('kept', `${name} ${version} (${newer} needs extension API ${engine})`);
+const printDiff = (result, tree) => {
+    for (const held of result.held)
+        console.log(heldLine(held));
+    for (const change of result.changes)
+        console.log(changeLine(change));
+    const counts = `${result.changes.length} updated, ${result.unchanged} unchanged`;
+    console.log(tree === null ? 'latest: nothing to update' : `latest: ${counts} in tree ${tree}`);
+};
+// Clean: nothing in the new tree failed to load or is invalid.
+const notClean = (rows) => {
+    const bad = rows.filter((row) => row.state === 'failed' || row.state === 'invalid');
+    if (bad.length === 0)
+        return null;
+    const named = bad.map((row) => `${row.id ?? row.package} ${row.state}`).join(', ');
+    return new Error(`not updated: ${named}; extensions/current is unchanged`);
+};
+// Runs inside the install lock: the diff, then the new tree loaded before it becomes current.
+const loadStaged = (outcome) => async (staged) => {
+    printDiff(staged, staged.tree);
+    const gathered = await loadAndGather(listSecrets, staged.dir);
+    for (const text of rowLines(gathered.status.extensions))
+        console.log(text);
+    printWarnings(gathered.warnings);
+    outcome.failure = notClean(gathered.status.extensions);
+    return outcome.failure === null;
+};
+// One `npm update` of `set`; throws when the new tree did not load clean.
+const latestOnce = async (set, npm) => {
+    const outcome = { failure: null };
+    const result = await updateLatest(set, npm, loadStaged(outcome));
+    if (result.tree === null)
+        printDiff(result, null);
+    if (outcome.failure)
+        throw outcome.failure;
+    return result;
+};
+// The account's profile as it is, with the lock of the new tree once it loaded.
+const applyLatest = (deps) => async (base) => {
+    await mutateProfile(() => base.profile);
+    const result = await latestOnce({ ...base.profile, lock: base.lock }, deps.npm);
+    const kept = { lock: base.lock, npmMajor: base.npmMajor };
+    return pushBody(base.profile, base, result.current ? await localLock(deps) : kept);
+};
+// `setup --latest`: never signs in; a copy of the account's profile is pushed after a clean load.
+export const runSetupLatest = async (deps) => {
+    const synced = await pullForEdit(deps);
+    if (synced === null)
+        return void (await latestOnce(editableProfile(), deps.npm));
+    const done = await pushApplied(synced, applyLatest(deps), { lockCounts: true });
+    if (done.pushed)
+        console.log(line('profile', `pushed to your account (etag ${done.etag})`));
+};

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

@@ -0,0 +1,17 @@
+import { type Command } from 'commander';
+import { type ExtensionCheckOptions } from './check.js';
+import { type ExtensionInstallOptions } from './install.js';
+import { type ExtensionRemoveOptions } from './remove.js';
+import { type ExtensionsGather } from './rows.js';
+export interface ExtensionListOptions {
+    json?: boolean;
+}
+export declare const printReport: ({ status, warnings }: ExtensionsGather, json?: boolean) => void;
+export declare const runExtensionList: (opts?: ExtensionListOptions) => Promise<void>;
+export interface ExtensionActions {
+    install: (opts: ExtensionInstallOptions) => Promise<void>;
+    remove: (opts: ExtensionRemoveOptions) => Promise<void>;
+    list: (opts: ExtensionListOptions) => Promise<void>;
+    check: (opts: ExtensionCheckOptions) => Promise<void>;
+}
+export declare const registerExtension: (program: Command, actions: ExtensionActions) => void;