@sdods/cli 0.19.0 → 0.21.0

package/dist/commands/agent.js

@@ -36,7 +36,7 @@ export function register(program) {
             .option('--run-id <id>', 'run id (heal), default last', 'last')
             .option('--diff <range>', 'git range (upgrade), e.g. main..HEAD')
             .option('--files <list>', 'feature files (review)', collect, [])
-            .option('--adapter <name>', 'claude (API key) | claude-code (logged-in Claude Code CLI) | codex (logged-in Codex CLI) | openai | ollama (a model on this machine) | fake; default: auto-detect')
+            .option('--adapter <name>', 'claude (API key) | claude-code (logged-in Claude Code CLI) | codex (logged-in Codex CLI) | copilot (logged-in GitHub Copilot CLI) | openai | ollama (a model on this machine) | fake; default: auto-detect')
             .option('--model <id>', 'model override')
             .option('--profile <name>', 'auto | full | small — how many tools and how much prompt the model is given')
             .option('--browser', 'attach the browser MCP server even under the small profile (which omits it)')
@@ -162,13 +162,13 @@ export function register(program) {
     const installAction = async (opts, cmd, forced) => {
         const ctx = createContext(cmd);
         const target = (forced ?? opts.for ?? 'all');
-        if (!['claude', 'codex', 'all'].includes(target)) {
+        if (!['claude', 'codex', 'copilot', 'all'].includes(target)) {
             throw new SdodsError('NOT_SUPPORTED', `Unknown target "${target}".`, {
-                hint: 'Use --for claude, --for codex or --for all.',
+                hint: 'Use --for claude, --for codex, --for copilot or --for all.',
                 exitCode: 2,
             });
         }
-        const { installCodingAgents } = await import('@sdods/agents');
+        const { installCodingAgents, findOnPath } = await import('@sdods/agents');
         const written = installCodingAgents(ctx.rootDir, {
             for: target,
             project: opts.project,
@@ -177,7 +177,11 @@ export function register(program) {
         });
         if (opts.mcp !== false) {
             const { execa } = await import('execa');
-            const clients = target === 'all' ? ['claude', 'codex'] : [target];
+            // `all` registers with Copilot only when it is installed: its config lives in the home
+            // directory, and writing one for someone who does not use Copilot would be clutter.
+            const clients = target === 'all'
+                ? ['claude', 'codex', ...(findOnPath('copilot') ? ['copilot'] : [])]
+                : [target];
             for (const client of clients) {
                 const args = ['mcp', 'install', client];
                 if (opts.project)
@@ -200,8 +204,8 @@ export function register(program) {
     };
     agent
         .command('install')
-        .description('Set up coding-agent CLIs: --for claude writes .claude/agents/sdods-*.md + CLAUDE.md, --for codex writes AGENTS.md; both get AGENT.md/SKILL.md and the MCP registration')
-        .option('--for <client>', 'claude | codex | all', 'all')
+        .description('Set up coding-agent CLIs: --for claude writes .claude/agents/sdods-*.md + CLAUDE.md, --for codex writes AGENTS.md, --for copilot writes .github/agents/sdods-*.agent.md + AGENTS.md; all get AGENT.md/SKILL.md and the MCP registration')
+        .option('--for <client>', 'claude | codex | copilot | all', 'all')
         .option('-p, --project <slug>')
         .option('-e, --env <name>')
         .option('--force', 'overwrite existing files')

package/dist/commands/doctor.js

@@ -173,6 +173,7 @@ function tokenMatrix(cliStatus, localLlm) {
     const has = (k) => Boolean(process.env[k]);
     const claudeOk = cliStatus.find((c) => c.name === 'cli:claude')?.ok ?? false;
     const codexOk = cliStatus.find((c) => c.name === 'cli:codex')?.ok ?? false;
+    const copilotOk = cliStatus.find((c) => c.name === 'cli:copilot')?.ok ?? false;
     const agentsGroup = [
         {
             name: 'ANTHROPIC_API_KEY',
@@ -192,6 +193,12 @@ function tokenMatrix(cliStatus, localLlm) {
             detail: 'adapter codex: uses your Codex login (ChatGPT account)',
             hint: '`npm i -g @openai/codex && codex login`',
         },
+        {
+            name: 'copilot CLI login',
+            present: copilotOk,
+            detail: 'adapter copilot: uses your GitHub Copilot subscription',
+            hint: '`npm i -g @github/copilot && copilot login` (or COPILOT_GITHUB_TOKEN)',
+        },
         {
             name: 'OPENAI_API_KEY (+OPENAI_BASE_URL)',
             present: has('OPENAI_API_KEY'),
@@ -296,11 +303,11 @@ async function localModelStatus() {
         return { name, ok: false, optional: true, detail: 'agents package unavailable' };
     }
 }
-/** `cli:claude` / `cli:codex` rows: installed + logged in. Missing CLIs are not failures. */
+/** `cli:claude` / `cli:codex` / `cli:copilot` rows: installed + logged in. Missing CLIs are not failures. */
 async function codingCliStatus() {
     const rows = [];
     try {
-        const { ClaudeCodeCliAdapter, CodexCliAdapter } = await import('@sdods/agents');
+        const { ClaudeCodeCliAdapter, CodexCliAdapter, CopilotCliAdapter } = await import('@sdods/agents');
         const c = ClaudeCodeCliAdapter.loginStatus();
         rows.push({
             name: 'cli:claude',
@@ -317,6 +324,15 @@ async function codingCliStatus() {
             detail: x.detail,
             fix: x.installed ? 'codex login' : 'npm i -g @openai/codex (optional)',
         });
+        const g = CopilotCliAdapter.loginStatus();
+        rows.push({
+            name: 'cli:copilot',
+            // Copilot cannot report its login without a prompt; installed counts until a run says otherwise
+            ok: g.installed && g.loggedIn !== false,
+            optional: true,
+            detail: g.detail,
+            fix: g.installed ? 'copilot login' : 'npm i -g @github/copilot (optional)',
+        });
     }
     catch {
         rows.push({
@@ -331,6 +347,12 @@ async function codingCliStatus() {
             optional: true,
             detail: 'agents package unavailable',
         });
+        rows.push({
+            name: 'cli:copilot',
+            ok: false,
+            optional: true,
+            detail: 'agents package unavailable',
+        });
     }
     return rows;
 }

package/dist/commands/mcp.js

@@ -81,14 +81,14 @@ export function register(program) {
     });
     mcp
         .command('install <client>')
-        .description('Register the SDODS MCP server with a client: claude | codex | cursor | vscode | windsurf | gemini (merges, never clobbers)')
+        .description('Register the SDODS MCP server with a client: claude | codex | copilot | cursor | vscode | windsurf | gemini (merges, never clobbers)')
         .option('-p, --project <slug>')
         .option('-e, --env <name>')
         .option('--caps <list>')
         .option('--http-url <url>', 'configure the HTTP transport instead of stdio')
         .option('--token-placeholder <text>', 'placeholder written for the bearer token')
         .option('--with-playwright', 'also register the raw upstream Playwright MCP server (ungoverned; the sdods server already wraps it as browser_*)')
-        .option('--file', 'always write the config file instead of calling `claude mcp add` / `codex mcp add`')
+        .option('--file', 'always write the config file instead of calling `claude` / `codex` / `copilot mcp add`')
         .option('--print', 'print the snippet instead of writing files')
         .action(async (client, opts, cmd) => {
         const ctx = createContext(cmd);
@@ -120,11 +120,11 @@ export function register(program) {
             return;
         }
         // Prefer the client's own CLI so its config format stays authoritative.
-        if (!opts.file && (client === 'claude' || client === 'codex')) {
+        if (!opts.file && (client === 'claude' || client === 'codex' || client === 'copilot')) {
             const done = await registerViaClientCli(client, o, ctx.rootDir);
             if (done) {
                 ok(`Registered the sdods MCP server with ${client} (${cliCommands(o)[client]})`);
-                if (o.withPlaywright === true && client === 'codex')
+                if (o.withPlaywright === true && client !== 'claude')
                     out(pc.dim('Also registered the bundled Playwright MCP server as "playwright".'));
                 return;
             }
@@ -135,7 +135,7 @@ export function register(program) {
             out(pc.dim(`Alternative: ${s.cli}`));
     });
 }
-/** `claude mcp add` (project scope) or `codex mcp add`; false when the CLI is unavailable. */
+/** `claude mcp add` (project scope), `codex mcp add` or `copilot mcp add` (user config); false when the CLI is unavailable. */
 async function registerViaClientCli(client, o, cwd) {
     const { execa } = await import('execa');
     // `npx sdods` resolves only when the cwd happens to sit inside a checkout that has the binary in
@@ -148,7 +148,7 @@ async function registerViaClientCli(client, o, cwd) {
         stdio.push('--env', o.env);
     if (o.caps)
         stdio.push('--caps', o.caps);
-    const run = async (args) => {
+    const run = async (args, name = 'sdods') => {
         try {
             await execa(client, args, { cwd, timeout: 30_000 });
             return true;
@@ -159,7 +159,7 @@ async function registerViaClientCli(client, o, cwd) {
                 return false;
             // already registered → remove and re-add so the args are current
             if (/already exists/i.test(msg)) {
-                await execa(client, ['mcp', 'remove', args[2] ?? 'sdods'], { cwd, reject: false });
+                await execa(client, ['mcp', 'remove', name], { cwd, reject: false });
                 await execa(client, args, { cwd, timeout: 30_000 });
                 return true;
             }
@@ -170,26 +170,39 @@ async function registerViaClientCli(client, o, cwd) {
     };
     // A remote server without credentials answers 401 to every call, so the token is part of the
     // registration. Neither form writes the secret: Claude Code expands ${SDODS_TOKEN} from the
-    // environment when it reads .mcp.json, and Codex reads the variable named by
-    // --bearer-token-env-var at connect time.
-    const addArgs = client === 'claude'
+    // environment when it reads .mcp.json, Copilot keeps the ${SDODS_TOKEN} reference as written,
+    // and Codex reads the variable named by --bearer-token-env-var at connect time.
+    const addArgs = client === 'copilot'
         ? o.httpUrl
             ? [
                 'mcp',
                 'add',
-                '-s',
-                'project',
                 '--transport',
                 'http',
-                'sdods',
-                o.httpUrl,
                 '--header',
                 'Authorization: Bearer ${SDODS_TOKEN}',
+                'sdods',
+                o.httpUrl,
             ]
-            : ['mcp', 'add', '-s', 'project', 'sdods', '--', ...stdio]
-        : o.httpUrl
-            ? ['mcp', 'add', 'sdods', '--url', o.httpUrl, '--bearer-token-env-var', 'SDODS_TOKEN']
-            : ['mcp', 'add', 'sdods', '--', ...stdio];
+            : ['mcp', 'add', 'sdods', '--', ...stdio]
+        : client === 'claude'
+            ? o.httpUrl
+                ? [
+                    'mcp',
+                    'add',
+                    '-s',
+                    'project',
+                    '--transport',
+                    'http',
+                    'sdods',
+                    o.httpUrl,
+                    '--header',
+                    'Authorization: Bearer ${SDODS_TOKEN}',
+                ]
+                : ['mcp', 'add', '-s', 'project', 'sdods', '--', ...stdio]
+            : o.httpUrl
+                ? ['mcp', 'add', 'sdods', '--url', o.httpUrl, '--bearer-token-env-var', 'SDODS_TOKEN']
+                : ['mcp', 'add', 'sdods', '--', ...stdio];
     const ok1 = await run(addArgs);
     if (!ok1)
         return false;
@@ -208,7 +221,7 @@ async function registerViaClientCli(client, o, cwd) {
                 '--headless',
             ]
             : ['mcp', 'add', 'playwright', '--', 'npx', 'playwright', 'mcp', '--headless'];
-        await run(pw).catch(() => false);
+        await run(pw, 'playwright').catch(() => false);
     }
     return true;
 }

package/dist/commands/record.js

@@ -132,7 +132,7 @@ export function register(program) {
         .description('Ask the generator agent to turn a recorded spec into a feature + steps proposal (reviewed, never auto-applied)')
         .option('-p, --project <slug>', 'project slug (default: inferred from the spec path)')
         .option('--dry-run', 'print the prompt and plan without calling a model')
-        .option('--adapter <name>', 'claude | claude-code | codex | openai | ollama | fake; default: auto-detect')
+        .option('--adapter <name>', 'claude | claude-code | codex | copilot | openai | ollama | fake; default: auto-detect')
         .option('--model <id>', 'model override')
         .option('--profile <name>', 'auto | full | small — how much of the platform the model is shown')
         .action(async (spec, opts, cmd) => {

package/dist/commands/upgrade.d.ts

@@ -1,14 +1,59 @@
-import type { Command } from 'commander';
+import { type Command } from 'commander';
+import { type InstallInfo } from '../install-method.js';
 export declare const SDODS_PACKAGES: readonly ["@sdods/cli", "@sdods/core", "@sdods/contracts", "@sdods/db", "@sdods/mcp", "@sdods/agents", "@sdods/integrations", "@sdods/server"];
+export type UpgradeStatus = 'up-to-date' | 'outdated' | 'not-installed' | 'unavailable';
 export interface UpgradeRow {
     package: string;
     installed: string | null;
     latest: string | null;
-    status: 'up-to-date' | 'outdated' | 'not-installed' | 'unavailable';
+    status: UpgradeStatus;
 }
 export declare function installedVersion(rootDir: string, pkg: string): string | null;
 export declare function latestVersion(pkg: string, fetchImpl?: typeof fetch, registry?: string): Promise<string | null>;
+export declare function compare(installed: string | null, latest: string | null): UpgradeStatus;
+/** The @sdods/* packages a project depends on, compared with the registry. */
 export declare function checkUpgrades(rootDir: string, fetchImpl?: typeof fetch): Promise<UpgradeRow[]>;
+export interface CliStatus extends InstallInfo {
+    installed: string;
+    latest: string | null;
+    status: UpgradeStatus;
+}
+/** The running CLI: how it was installed and whether npm has a newer one. */
+export declare function checkCli(rootDir: string, fetchImpl?: typeof fetch, packageDir?: string): Promise<CliStatus>;
+export interface RefreshReport {
+    skills: Array<{
+        base: string;
+        targets: string[];
+        replaced: number;
+    }>;
+    /** Generated role agent files that differ from what this version writes. */
+    agents: {
+        stale: string[];
+        replaced: string[];
+    };
+}
+/**
+ * Bring the files SDODS put into a project and the home directory up to this version: the bundled
+ * skills, wherever they already are, and (with `force`) the generated `sdods-<role>` agent files.
+ * CLAUDE.md, AGENTS.md and other hand-editable files are never touched.
+ */
+export declare function refreshAssets(rootDir: string, o?: {
+    force?: boolean;
+    home?: string;
+    dryRun?: boolean;
+}): Promise<RefreshReport>;
+export interface PluginUpdate {
+    client: 'claude' | 'copilot';
+    installed: boolean;
+    command: string[];
+}
+/** The SDODS plugin in Claude Code (`sdods@sdods`) and Copilot CLI (`sdods` from marketplace `sdods`). */
+export declare function detectPlugins(): Promise<PluginUpdate[]>;
+/**
+ * The sdods to re-run after an upgrade, so the new version refreshes the assets. npm, bun and pnpm
+ * replace the package in place; a Homebrew upgrade moves to a new keg that `brew` links as `sdods`.
+ */
+export declare function upgradedBin(rootDir: string, cli: InstallInfo): string[];
 export declare function register(program: Command): void;
 export declare function detectPm(rootDir: string): 'bun' | 'pnpm' | 'npm';
 //# sourceMappingURL=upgrade.d.ts.map

package/dist/commands/upgrade.js

@@ -1,10 +1,14 @@
-import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, relative } from 'node:path';
+import { Option } from 'commander';
 import { execa } from 'execa';
 import pc from 'picocolors';
 import semver from 'semver';
 import { VERSION } from '@sdods/core';
 import { createContext } from '../context.js';
+import { detectInstallMethod, runningPackageDir } from '../install-method.js';
+import { installSkills, installedSkillTargets } from '../skills-catalog.js';
 import { json, ok, out, table, warn } from '../ui.js';
 export const SDODS_PACKAGES = [
     '@sdods/cli',
@@ -42,67 +46,238 @@ export async function latestVersion(pkg, fetchImpl = fetch, registry = process.e
         return null;
     }
 }
+export function compare(installed, latest) {
+    if (!latest)
+        return 'unavailable';
+    if (!installed)
+        return 'not-installed';
+    return semver.valid(installed) && semver.lt(installed, latest) ? 'outdated' : 'up-to-date';
+}
+/** The @sdods/* packages a project depends on, compared with the registry. */
 export async function checkUpgrades(rootDir, fetchImpl) {
-    const rows = await Promise.all(SDODS_PACKAGES.map(async (pkg) => {
-        const installed = installedVersion(rootDir, pkg) ?? (pkg === '@sdods/cli' ? VERSION : null);
+    return Promise.all(SDODS_PACKAGES.map(async (pkg) => {
+        const installed = installedVersion(rootDir, pkg);
         const latest = await latestVersion(pkg, fetchImpl);
-        let status;
-        if (!latest)
-            status = 'unavailable';
-        else if (!installed)
-            status = 'not-installed';
-        else
-            status =
-                semver.valid(installed) && semver.lt(installed, latest) ? 'outdated' : 'up-to-date';
-        return { package: pkg, installed, latest, status };
+        return { package: pkg, installed, latest, status: compare(installed, latest) };
     }));
-    return rows;
+}
+/** The running CLI: how it was installed and whether npm has a newer one. */
+export async function checkCli(rootDir, fetchImpl, packageDir = runningPackageDir()) {
+    const info = detectInstallMethod(packageDir, { rootDir });
+    const latest = await latestVersion('@sdods/cli', fetchImpl);
+    return { ...info, installed: VERSION, latest, status: compare(VERSION, latest) };
+}
+/**
+ * Bring the files SDODS put into a project and the home directory up to this version: the bundled
+ * skills, wherever they already are, and (with `force`) the generated `sdods-<role>` agent files.
+ * CLAUDE.md, AGENTS.md and other hand-editable files are never touched.
+ */
+export async function refreshAssets(rootDir, o = {}) {
+    const home = o.home ?? homedir();
+    const report = { skills: [], agents: { stale: [], replaced: [] } };
+    for (const [base, global] of [
+        [rootDir, false],
+        [home, true],
+    ]) {
+        if (global && base === rootDir)
+            continue;
+        const targets = installedSkillTargets(base, global);
+        if (!targets.length)
+            continue;
+        const done = o.dryRun ? [] : installSkills({ rootDir, home, global, targets, force: true });
+        report.skills.push({
+            base,
+            targets,
+            replaced: done.filter((d) => d.status !== 'skipped').length,
+        });
+    }
+    const { codingAgentFiles } = await import('@sdods/agents');
+    for (const { file, content } of codingAgentFiles(rootDir)) {
+        if (!existsSync(file) || readFileSync(file, 'utf8') === content)
+            continue;
+        if (o.force && !o.dryRun) {
+            writeFileSync(file, content);
+            report.agents.replaced.push(file);
+        }
+        else
+            report.agents.stale.push(file);
+    }
+    return report;
+}
+/** The SDODS plugin in Claude Code (`sdods@sdods`) and Copilot CLI (`sdods` from marketplace `sdods`). */
+export async function detectPlugins() {
+    const listJson = async (bin, args) => {
+        try {
+            const r = await execa(bin, args, { timeout: 20_000, reject: false, stdin: 'ignore' });
+            return r.exitCode === 0 ? JSON.parse(r.stdout) : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    const claude = (await listJson('claude', ['plugin', 'list', '--json']));
+    const copilot = (await listJson('copilot', ['plugin', 'list', '--json']));
+    return [
+        {
+            client: 'claude',
+            installed: Array.isArray(claude) && claude.some((p) => p.id === 'sdods@sdods'),
+            command: ['claude', 'plugin', 'update', 'sdods@sdods'],
+        },
+        {
+            client: 'copilot',
+            installed: Array.isArray(copilot) &&
+                copilot.some((p) => p.name === 'sdods' && p.marketplace === 'sdods'),
+            command: ['copilot', 'plugin', 'update', 'sdods'],
+        },
+    ];
+}
+const statusColor = (s) => s === 'outdated' ? pc.yellow(s) : s === 'up-to-date' ? pc.green(s) : pc.dim(s);
+/**
+ * The sdods to re-run after an upgrade, so the new version refreshes the assets. npm, bun and pnpm
+ * replace the package in place; a Homebrew upgrade moves to a new keg that `brew` links as `sdods`.
+ */
+export function upgradedBin(rootDir, cli) {
+    if (cli.method === 'homebrew')
+        return ['sdods'];
+    const dir = cli.method === 'project' ? join(rootDir, 'node_modules', '@sdods', 'cli') : cli.packageDir;
+    return [process.execPath, join(dir, 'bin', 'sdods.js')];
+}
+async function runRefresh(rootDir, o) {
+    const rel = (p) => relative(rootDir, p) || '.';
+    const report = await refreshAssets(rootDir, { force: o.force });
+    const plugins = await detectPlugins();
+    const ran = [];
+    for (const p of plugins.filter((x) => x.installed)) {
+        const r = await execa(p.command[0], p.command.slice(1), {
+            reject: false,
+            stdin: 'ignore',
+            timeout: 120_000,
+        }).catch(() => ({ exitCode: 1 }));
+        ran.push({ client: p.client, ok: r.exitCode === 0, command: p.command.join(' ') });
+    }
+    if (o.json) {
+        json({ version: VERSION, ...report, plugins: ran });
+        return ran.every((r) => r.ok);
+    }
+    for (const s of report.skills)
+        ok(`Skills refreshed in ${s.targets.join(', ')} (${s.base === rootDir ? 'project' : 'home directory'})`);
+    for (const f of report.agents.replaced)
+        ok(`Replaced ${rel(f)}`);
+    if (report.agents.stale.length)
+        out(pc.dim(`${report.agents.stale.length} generated agent file(s) differ from ${VERSION}: ${report.agents.stale.map(rel).join(', ')}. \`sdods upgrade --apply --force\` replaces them, edits included.`));
+    for (const r of ran) {
+        if (r.ok)
+            ok(`Updated the SDODS plugin in ${r.client === 'claude' ? 'Claude Code (restart it to load)' : 'Copilot CLI'}`);
+        else
+            warn(`Could not update the ${r.client} plugin; run: ${r.command}`);
+    }
+    return ran.every((r) => r.ok);
 }
 export function register(program) {
     program
         .command('upgrade')
-        .description('Check the npm registry for newer @sdods/* packages')
-        .option('--apply', 'install the latest versions with the package manager')
-        .option('--pm <manager>', 'bun | pnpm | npm (default: detected from lockfile)')
+        .description('Upgrade the SDODS CLI the way it was installed (Homebrew, npm, bun, pnpm, project) and refresh the skills and plugins it set up')
+        .option('--apply', 'run the upgrades and refresh skills and plugins (default: only report)')
+        .option('--pm <manager>', 'bun | pnpm | npm for project packages (default: from the lockfile)')
+        .option('--force', 'also replace generated sdods-<role> agent files that differ')
+        .option('--no-refresh', 'skip refreshing skills, agent files and plugins')
+        .addOption(new Option('--refresh-assets', 'refresh with this version only').hideHelp())
         .action(async (opts, cmd) => {
         const ctx = createContext(cmd);
-        const rows = await checkUpgrades(ctx.rootDir);
-        if (ctx.opts.json)
-            return json(rows);
-        table(rows.map((r) => ({
-            package: r.package,
-            installed: r.installed ?? pc.dim('—'),
-            latest: r.latest ?? pc.dim('?'),
-            status: r.status === 'outdated'
-                ? pc.yellow(r.status)
-                : r.status === 'up-to-date'
-                    ? pc.green(r.status)
-                    : pc.dim(r.status),
-        })));
-        const outdated = rows.filter((r) => r.status === 'outdated');
-        if (!outdated.length) {
-            if (rows.every((r) => r.status === 'unavailable'))
-                warn('Registry unreachable (offline?) — nothing compared.');
-            else
-                ok('Everything installed is up to date.');
+        // Second half of `--apply`: runs in the freshly installed binary.
+        if (opts.refreshAssets) {
+            if (!(await runRefresh(ctx.rootDir, { force: opts.force, json: ctx.opts.json })))
+                process.exitCode = 1;
             return;
         }
+        const [cli, rows] = await Promise.all([checkCli(ctx.rootDir), checkUpgrades(ctx.rootDir)]);
+        const projectRows = rows.filter((r) => r.installed);
+        const outdated = projectRows.filter((r) => r.status === 'outdated');
+        const cliOutdated = cli.status === 'outdated' && cli.method !== 'project';
+        if (ctx.opts.json && !opts.apply) {
+            const [assets, plugins] = await Promise.all([
+                opts.refresh === false ? null : refreshAssets(ctx.rootDir, { dryRun: true }),
+                opts.refresh === false ? null : detectPlugins(),
+            ]);
+            return json({ cli, packages: projectRows, assets, plugins });
+        }
+        out(`${pc.bold('sdods')} ${cli.installed} ${pc.dim(`(${cli.method})`)} → ${cli.latest ?? pc.dim('?')}  ${statusColor(cli.status)}`);
+        if (projectRows.length)
+            table(projectRows.map((r) => ({
+                package: r.package,
+                installed: r.installed ?? pc.dim('—'),
+                latest: r.latest ?? pc.dim('?'),
+                status: statusColor(r.status),
+            })));
+        if (cli.status === 'unavailable' && rows.every((r) => r.status === 'unavailable'))
+            warn('Registry unreachable (offline?): nothing compared.');
         if (!opts.apply) {
-            out(pc.dim(`Run \`sdods upgrade --apply\` to install ${outdated.map((r) => r.package).join(', ')}.`));
+            const todo = [];
+            if (cliOutdated)
+                todo.push(cli.upgrade ? cli.upgrade.join(' ') : cli.hint);
+            if (outdated.length)
+                todo.push(`project: ${outdated.map((r) => r.package).join(', ')}`);
+            if (todo.length)
+                out(pc.dim(`\`sdods upgrade --apply\` will run: ${todo.join('; ')}`));
+            else
+                ok('Everything installed is up to date.');
+            if (opts.refresh !== false)
+                out(pc.dim('`--apply` also refreshes the SDODS skills and plugins you installed.'));
             return;
         }
-        const pm = opts.pm ?? detectPm(ctx.rootDir);
-        const specs = outdated.map((r) => `${r.package}@${r.latest}`);
-        const args = pm === 'bun'
-            ? ['add', ...specs]
-            : pm === 'pnpm'
-                ? ['add', ...specs]
-                : ['install', ...specs];
-        const res = await execa(pm, args, { cwd: ctx.rootDir, stdio: 'inherit', reject: false });
-        if (res.exitCode !== 0)
+        let failed = false;
+        if (cliOutdated) {
+            if (cli.upgrade) {
+                out(pc.dim(`$ ${cli.upgrade.join(' ')}`));
+                const r = await execa(cli.upgrade[0], cli.upgrade.slice(1), {
+                    stdio: 'inherit',
+                    reject: false,
+                });
+                if (r.exitCode !== 0) {
+                    failed = true;
+                    warn(`The CLI upgrade failed; run it yourself: ${cli.upgrade.join(' ')}`);
+                }
+                else
+                    ok(`Upgraded the CLI (${cli.method}).`);
+            }
+            else
+                warn(cli.hint);
+        }
+        if (outdated.length) {
+            const pm = opts.pm ?? detectPm(ctx.rootDir);
+            const specs = outdated.map((r) => `${r.package}@${r.latest}`);
+            const args = pm === 'npm' ? ['install', ...specs] : ['add', ...specs];
+            const r = await execa(pm, args, { cwd: ctx.rootDir, stdio: 'inherit', reject: false });
+            if (r.exitCode !== 0)
+                failed = true;
+            else
+                ok(`Upgraded ${specs.length} project package(s) with ${pm}.`);
+        }
+        if (opts.refresh !== false) {
+            const upgraded = (cliOutdated && cli.upgrade && !failed) || outdated.length > 0;
+            if (!upgraded) {
+                if (!(await runRefresh(ctx.rootDir, { force: opts.force })))
+                    failed = true;
+            }
+            else {
+                // The running process is the old version; the new one knows the new skills.
+                const [bin, ...pre] = upgradedBin(ctx.rootDir, cli);
+                const args = [...pre, 'upgrade', '--refresh-assets', ...(opts.force ? ['--force'] : [])];
+                const r = await execa(bin, args, {
+                    cwd: ctx.rootDir,
+                    stdio: 'inherit',
+                    reject: false,
+                }).catch(() => ({ exitCode: 1 }));
+                if (r.exitCode !== 0) {
+                    failed = true;
+                    warn('Could not refresh skills and plugins; run: sdods upgrade --apply');
+                }
+            }
+        }
+        if (failed)
             process.exitCode = 1;
-        else
-            ok(`Upgraded ${specs.length} package(s) with ${pm}.`);
+        else if (!cliOutdated && !outdated.length)
+            ok('Everything installed is up to date.');
     });
 }
 export function detectPm(rootDir) {

package/dist/install-method.d.ts

@@ -0,0 +1,29 @@
+/**
+ * How the running `sdods` got onto this machine. `sdods upgrade` uses it to upgrade the CLI the same
+ * way it was installed, instead of only looking at a project's node_modules.
+ */
+export type InstallMethod = 'project' | 'homebrew' | 'npm' | 'bun' | 'pnpm' | 'npx' | 'installer-git' | 'checkout';
+export interface InstallInfo {
+    method: InstallMethod;
+    /** Directory of the installed @sdods/cli package (packages/cli in a checkout). */
+    packageDir: string;
+    /** The command that upgrades this install, or null when there is nothing to run. */
+    upgrade: string[] | null;
+    /** One line for people: what to do when `upgrade` is null, or what `--apply` will run. */
+    hint: string;
+}
+export interface DetectOptions {
+    rootDir: string;
+    /** $SDODS_HOME, default ~/.sdods (where the install script keeps a git checkout). */
+    sdodsHome?: string;
+    /** Test hook: does `<checkout>/.git` exist. */
+    isGitCheckout?: (dir: string) => boolean;
+}
+/** Directory of the @sdods/cli package this code is running from (src/ and dist/ sit one below it). */
+export declare function runningPackageDir(): string;
+/**
+ * Classify an installed package directory. Specific markers are checked before generic ones: a
+ * Homebrew keg and an npx cache both contain `node_modules/@sdods/cli` too.
+ */
+export declare function detectInstallMethod(packageDir: string, o: DetectOptions): InstallInfo;
+//# sourceMappingURL=install-method.d.ts.map