@sdods/cli 0.20.0 → 0.22.0

package/dist/commands/report.js

@@ -3,7 +3,7 @@ import { tmpdir } from 'node:os';
 import { basename, dirname, extname, join, resolve } from 'node:path';
 import { execa } from 'execa';
 import pc from 'picocolors';
-import { legacyRunFiles, runFiles, } from '@sdods/contracts';
+import { legacyRunFiles, parseVersioned, runFiles, } from '@sdods/contracts';
 import { SdodsError, collectGateEvidence, evaluateGates, gateReportsFromRunnerJson, gateTotalsFromRunnerStats, hasGates, ingestGateJudge, } from '@sdods/core';
 import { createContext } from '../context.js';
 import { gateFailedError, printGates } from '../gates.js';
@@ -168,11 +168,12 @@ export function register(program) {
     });
     report
         .command('ingest [files...]')
-        .description('Ingest cucumber messages NDJSON and runner JSON results into the database')
+        .description('Ingest cucumber messages NDJSON, runner JSON and JUnit XML results into the database')
         .requiredOption('--run-id <id>', 'run id (directory name under the artifacts root)')
         .option('-p, --project <slug>', 'project slug when run.json is missing')
         .option('--manifest <file>', 'explicit run.json path')
-        .option('--format <fmt>', 'auto|cucumber|runner-json (alias: pw-json)', 'auto')
+        .option('--format <fmt>', 'auto|cucumber|runner-json (alias: pw-json)|junit', 'auto')
+        .option('--approved-skips <file>', 'approved-skip registry (approved-skips/v1); a skip it does not approve makes the run INFRASTRUCTURE_ERROR')
         .option('--artifacts-dir <dir>', 'artifacts root (default .sdods/runs)')
         .option('--replace', 'delete previously ingested rows of this run first')
         .option('-e, --env <name>', 'environment name when run.json is missing')
@@ -192,13 +193,18 @@ export function register(program) {
             const { basename } = await import('node:path');
             const form = new FormData();
             let count = 0;
-            for (const f of files) {
+            for (const [i, f] of files.entries()) {
                 const abs = resolve(ctx.rootDir, f);
                 if (!existsSync(abs))
                     continue;
-                form.append('files', new Blob([readFileSync(abs)]), basename(abs));
+                // The server accepts result files by name; a JUnit file goes up under the name it reads.
+                const junit = ingestFormat(opts.format, abs) === 'junit' &&
+                    !/^junit(\.shard-\d+)?\.xml$/.test(basename(abs));
+                form.append('files', new Blob([readFileSync(abs)]), junit ? `junit.shard-${i}.xml` : basename(abs));
                 count++;
             }
+            if (opts.approvedSkips)
+                form.append('files', new Blob([readFileSync(resolve(ctx.rootDir, opts.approvedSkips))]), 'approved-skips.json');
             if (!count)
                 throw new SdodsError('CONFIG_INVALID', 'No existing files to upload.', { exitCode: 2 });
             const url = `${serverUrl.replace(/\/$/, '')}/api/runs/${encodeURIComponent(opts.runId)}/ingest`;
@@ -223,19 +229,15 @@ export function register(program) {
             const root = opts.artifactsDir
                 ? resolve(ctx.rootDir, opts.artifactsDir)
                 : artifactsRoot(ctx.rootDir);
-            const ndjson = [];
-            const runnerJson = [];
+            const paths = { cucumber: [], 'runner-json': [], junit: [] };
             for (const f of files) {
                 const abs = resolve(ctx.rootDir, f);
-                const fmt = opts.format === 'auto'
-                    ? abs.endsWith('.ndjson')
-                        ? 'cucumber'
-                        : 'runner-json'
-                    : // `pw-json` is the pre-1.0 name, still accepted
-                        opts.format === 'pw-json'
-                            ? 'runner-json'
-                            : opts.format;
-                (fmt === 'cucumber' ? ndjson : runnerJson).push(abs);
+                const fmt = ingestFormat(opts.format, abs);
+                if (!paths[fmt])
+                    throw new SdodsError('CONFIG_INVALID', `Unknown --format "${opts.format}".`, {
+                        exitCode: 2,
+                    });
+                paths[fmt].push(abs);
             }
             const manifest = opts.manifest
                 ? readJsonFile(resolve(ctx.rootDir, opts.manifest))
@@ -244,8 +246,12 @@ export function register(program) {
                 runId: opts.runId,
                 projectSlug: opts.project,
                 manifest,
-                ndjsonPaths: ndjson,
-                runnerJsonPaths: runnerJson,
+                ndjsonPaths: paths.cucumber,
+                runnerJsonPaths: paths['runner-json'],
+                junitPaths: paths.junit,
+                approvedSkips: opts.approvedSkips
+                    ? parseVersioned('approved-skips', readJsonFile(resolve(ctx.rootDir, opts.approvedSkips))).skips
+                    : undefined,
                 artifactsRoot: root,
                 replace: Boolean(opts.replace),
                 env: opts.env,
@@ -260,7 +266,9 @@ export function register(program) {
                 return json(res);
             ok(`Ingested run ${res.runId} (${res.projectSlug}): ${res.scenarios} scenario(s), ${res.attempts} attempt(s), ${res.steps} step(s), ${res.artifacts} artifact(s), ${res.healEvents} heal event(s)`);
             const t = res.totals;
-            out(`${pc.green(`${t.passed} passed`)}  ${pc.red(`${t.failed} failed`)}  ${pc.yellow(`${t.flaky} flaky`)}  ${pc.dim(`${t.skipped} skipped`)}  → ${res.status}`);
+            out(`${pc.green(`${t.passed} passed`)}  ${pc.red(`${t.failed} failed`)}  ${pc.yellow(`${t.flaky} flaky`)}  ${pc.dim(`${t.skipped} skipped`)}  → ${res.status} (${res.outcome})`);
+            for (const r of res.outcomeReasons)
+                out(pc.yellow(`  ${r.code}${r.test ? ` · ${r.test}` : ''}${r.detail ? `: ${r.detail}` : ''}`));
             if (res.gates)
                 out(`gates · process ${res.gates.process}: ${res.gates.passed
                     ? pc.green('passed')
@@ -478,4 +486,11 @@ export function register(program) {
         await execa(file, argv, { stdio: 'inherit', cwd: ctx.rootDir });
     });
 }
+/** The format of one `report ingest` file: `--format`, or its extension under `auto`. */
+function ingestFormat(format, file) {
+    if (format === 'auto')
+        return file.endsWith('.ndjson') ? 'cucumber' : file.endsWith('.xml') ? 'junit' : 'runner-json';
+    // `pw-json` is the pre-1.0 name, still accepted
+    return format === 'pw-json' ? 'runner-json' : format;
+}
 //# sourceMappingURL=report.js.map

package/dist/commands/steps.d.ts

@@ -1,5 +1,10 @@
 import type { Command } from 'commander';
 import type { StepDef } from '@sdods/contracts';
+/**
+ * The line of a failed `bddgen export` that says why, so the error names the cause rather than
+ * only "could not list" (SDO-71): the first `Error:` line of a stack, else the last line printed.
+ */
+export declare function failureReason(output: string): string | undefined;
 /** Parse `bddgen export` output (`* Given ...` lines) into StepDef[]. */
 export declare function listSteps(rootDir: string, slug: string, opts?: {
     unused?: boolean;

package/dist/commands/steps.js

@@ -4,6 +4,17 @@ import { SdodsError, coreStepsDir } from '@sdods/core';
 import { createContext } from '../context.js';
 import { json, table } from '../ui.js';
 import { toolCommand } from '../workspace-bin.js';
+/**
+ * The line of a failed `bddgen export` that says why, so the error names the cause rather than
+ * only "could not list" (SDO-71): the first `Error:` line of a stack, else the last line printed.
+ */
+export function failureReason(output) {
+    const lines = output
+        .split('\n')
+        .map((l) => l.trim())
+        .filter(Boolean);
+    return lines.find((l) => /^\w*Error\b/.test(l)) ?? lines.at(-1);
+}
 /** Parse `bddgen export` output (`* Given ...` lines) into StepDef[]. */
 export async function listSteps(rootDir, slug, opts = {}) {
     const env = {
@@ -19,6 +30,7 @@ export async function listSteps(rootDir, slug, opts = {}) {
     const result = await execa(file, argv, { cwd: rootDir, env, reject: false, all: true });
     if (result.exitCode !== 0) {
         throw new SdodsError('RUN_FAILED', `Could not list the step definitions of ${slug}.`, {
+            hint: failureReason(result.all ?? ''),
             details: { output: result.all?.slice(-2000) },
         });
     }

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

package/dist/install-method.js

@@ -0,0 +1,62 @@
+import { existsSync, realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const INSTALLER_GIT_HINT = 'Re-run the install script, which updates its checkout in place: curl -fsSL https://sdods.com/install.sh | sh -s -- --source git';
+/** Directory of the @sdods/cli package this code is running from (src/ and dist/ sit one below it). */
+export function runningPackageDir() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const dir = resolve(here, '..');
+    try {
+        return realpathSync(dir);
+    }
+    catch {
+        return dir;
+    }
+}
+/** Forward slashes, so one set of markers works on macOS, Linux and Windows paths. */
+function norm(p) {
+    return p.split(sep).join('/').replace(/\\/g, '/');
+}
+function within(child, parent) {
+    const c = norm(child).replace(/\/+$/, '');
+    const p = norm(parent).replace(/\/+$/, '');
+    return c === p || c.startsWith(`${p}/`);
+}
+/**
+ * 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 function detectInstallMethod(packageDir, o) {
+    const p = norm(packageDir);
+    const home = o.sdodsHome ?? process.env.SDODS_HOME ?? join(homedir(), '.sdods');
+    const isGit = o.isGitCheckout ?? ((dir) => existsSync(join(dir, '.git')));
+    const make = (method, upgrade, hint) => ({
+        method,
+        packageDir,
+        upgrade,
+        hint,
+    });
+    if (within(packageDir, join(o.rootDir, 'node_modules')))
+        return make('project', null, 'Upgraded with the project package step below.');
+    if (/\/_npx\//.test(p))
+        return make('npx', null, 'npx fetches @sdods/cli on each run; use `npx -y @sdods/cli@latest`.');
+    if (/\/Cellar\/sdods\//i.test(p) || /\/(?:homebrew|linuxbrew)\/.*\/libexec\//i.test(p))
+        return make('homebrew', ['brew', 'upgrade', 'sdods'], 'brew upgrade sdods');
+    if (/\/\.bun\/install\/global\//.test(p))
+        return make('bun', ['bun', 'add', '-g', '@sdods/cli@latest'], 'bun add -g @sdods/cli@latest');
+    if (/\/pnpm\/global\//i.test(p) || /\/\.pnpm\/@sdods\+cli@/.test(p))
+        return make('pnpm', ['pnpm', 'add', '-g', '@sdods/cli@latest'], 'pnpm add -g @sdods/cli@latest');
+    if (/\/node_modules\/@sdods\/cli$/.test(p.replace(/\/+$/, '')))
+        return make('npm', ['npm', 'install', '-g', '@sdods/cli@latest'], 'npm install -g @sdods/cli@latest');
+    // packages/cli inside a clone of the monorepo
+    const checkout = resolve(packageDir, '..', '..');
+    if (/\/packages\/cli$/.test(p.replace(/\/+$/, ''))) {
+        if (within(checkout, join(home, 'app')))
+            return make('installer-git', null, INSTALLER_GIT_HINT);
+        if (isGit(checkout))
+            return make('checkout', null, `Development checkout: git -C ${checkout} pull, then install.`);
+    }
+    return make('npm', ['npm', 'install', '-g', '@sdods/cli@latest'], 'npm install -g @sdods/cli@latest');
+}
+//# sourceMappingURL=install-method.js.map

package/dist/skills-catalog.d.ts

@@ -27,6 +27,13 @@ export declare const SKILL_TARGETS: {
 };
 export type SkillTarget = keyof typeof SKILL_TARGETS;
 export declare const DEFAULT_SKILL_TARGETS: SkillTarget[];
+/** The directory a target resolves to, under a project root or (with `global`) the home directory. */
+export declare function skillTargetDir(base: string, target: SkillTarget, global?: boolean): string;
+/**
+ * Targets that already hold at least one bundled SDODS skill. `sdods upgrade` refreshes exactly
+ * these, so it updates what someone installed without spreading skills into new folders.
+ */
+export declare function installedSkillTargets(base: string, global?: boolean, source?: string): SkillTarget[];
 export interface InstallSkillsOptions {
     rootDir: string;
     targets?: SkillTarget[];

package/dist/skills-catalog.js

@@ -49,6 +49,18 @@ export const SKILL_TARGETS = {
 export const DEFAULT_SKILL_TARGETS = ['claude', 'agents'];
 /** GitHub Copilot's user-level directory is `~/.copilot/skills`, not `~/.github/skills`. */
 const GLOBAL_OVERRIDES = { copilot: '.copilot/skills' };
+/** The directory a target resolves to, under a project root or (with `global`) the home directory. */
+export function skillTargetDir(base, target, global = false) {
+    return join(base, (global && GLOBAL_OVERRIDES[target]) || SKILL_TARGETS[target]);
+}
+/**
+ * Targets that already hold at least one bundled SDODS skill. `sdods upgrade` refreshes exactly
+ * these, so it updates what someone installed without spreading skills into new folders.
+ */
+export function installedSkillTargets(base, global = false, source) {
+    const names = listBundledSkills(source).map((s) => s.name);
+    return Object.keys(SKILL_TARGETS).filter((t) => names.some((n) => existsSync(join(skillTargetDir(base, t, global), n, 'SKILL.md'))));
+}
 export function installSkills(o) {
     const available = listBundledSkills(o.source);
     const wanted = o.skills?.length ? o.skills : available.map((s) => s.name);
@@ -58,9 +70,9 @@ export function installSkills(o) {
     const base = o.global ? (o.home ?? homedir()) : o.rootDir;
     const results = [];
     for (const target of o.targets?.length ? o.targets : DEFAULT_SKILL_TARGETS) {
-        const rel = (o.global && GLOBAL_OVERRIDES[target]) || SKILL_TARGETS[target];
+        const dir = skillTargetDir(base, target, o.global);
         for (const skill of available.filter((s) => wanted.includes(s.name))) {
-            const path = join(base, rel, skill.name);
+            const path = join(dir, skill.name);
             const exists = existsSync(join(path, 'SKILL.md'));
             if (exists && !o.force) {
                 results.push({ skill: skill.name, target, path, status: 'skipped' });