@pikku/cli 0.12.103 → 0.12.105

package/dist/src/functions/commands/scenario.js

@@ -3,20 +3,20 @@ import { resolve, join } from 'node:path';
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { pikkuSessionlessFunc } from '#pikku';
 import { InMemoryWorkflowService } from '@pikku/core/services';
-import { createHttpPersonas } from '@pikku/core/persona';
-import { PikkuScenarioService } from '@pikku/core/scenario';
+import { createHttpPersonas } from '@pikku/core/ecosystem/persona';
+import { PikkuScenarioService } from '@pikku/core/ecosystem/scenario';
 import { pikkuState, getAllPackageStates } from '@pikku/core/ecosystem';
-import { resolveFeatureScenarios } from '@pikku/core/scenario';
+import { resolveFeatureScenarios } from '@pikku/core/ecosystem/scenario';
 import { loadScenarioBootstrap } from './load-user-project.js';
 import { collectScenarioStepProse, scenarioBrowserSteps, scenarioFailureFromSteps, scenarioStepRows, scenarioStepsWithoutBinding, scenarioSurfaceCoverage, } from './scenario-ladder.js';
-import { SCENARIO_SURFACES } from '@pikku/core/scenario';
+import { SCENARIO_SURFACES } from '@pikku/core/ecosystem/scenario';
 import { formatScenarioReport } from './scenario-formatter.js';
 import { resolveScenarioBrowserProvider, scenarioBrowserLifecycle, } from './scenario-browser.js';
 import { resolvePersonas } from '../../utils/resolve-personas.js';
 import { spawnDevServer } from '../../server/spawn-dev-server.js';
 import { buildScenarioPlan } from './scenario-plan.js';
 import { resolveEnvironment } from './environment.js';
-import { createDevAIAgentRunner } from './dev-ai-runner.js';
+import { createDevAgentRunner } from './dev-agent-runner.js';
 const isScenario = (wf) => wf?.scenario === true;
 const listScenarios = (state) => Object.entries(state.workflows?.meta ?? {})
     .filter(([, wf]) => isScenario(wf))
@@ -88,7 +88,7 @@ export const scenarioList = pikkuSessionlessFunc({
     },
 });
 export const scenarioRun = pikkuSessionlessFunc({
-    func: async ({ logger, config, getInspectorState, variables }, { environment, flows, features, tags, excludeTags, coverage, browser = true, run: runSurface = 'default', strict = false, spawn = false, keepAlive = false, trace = false, screenshots = false, video = false, apiUrl, appUrl, }) => {
+    func: async ({ logger, config, getInspectorState, variables }, { environment, flows, features, tags, excludeTags, coverage, run: runSurface = 'default', strict = false, spawn = false, keepAlive = false, trace = false, screenshots = false, video = false, apiUrl, appUrl, }) => {
         if (!SCENARIO_SURFACES.includes(runSurface)) {
             throw new Error(`Unknown --run surface '${runSurface}'. Expected one of: ${SCENARIO_SURFACES.join(', ')}.`);
         }
@@ -191,49 +191,44 @@ export const scenarioRun = pikkuSessionlessFunc({
             scenarioBrowserSteps(state.workflows?.meta?.[name], functionsMeta),
         ])
             .filter(([, steps]) => steps.length > 0));
-        // `--no-browser` is the blunt form of `--run default`: a machine with no
-        // browser takes the server-side path rather than skipping the scenario.
-        const effectiveSurface = browser === false && runSurface === 'browser' ? 'default' : runSurface;
         const unrunnableStepsByFlow = new Map([...scenarioNames]
             .map((name) => [
             name,
-            scenarioStepsWithoutBinding(state.workflows?.meta?.[name], functionsMeta, effectiveSurface),
+            scenarioStepsWithoutBinding(state.workflows?.meta?.[name], functionsMeta, runSurface),
         ])
             .filter(([, steps]) => steps.length > 0));
-        // Two reasons a scenario is held back, both reported as SKIP rather than
-        // failed. `--no-browser` is the direct replacement for cucumber's `@console`
-        // tag, so a standard run stays green on a machine with no browser; a `skip`
-        // on the scenario itself is the project quarantining it, and the plan has
-        // already cleared that reason for anything named directly with `--flows`.
-        const skipReasonFor = (entry) => {
-            if (entry.skip)
-                return entry.skip;
-            const unrunnable = unrunnableStepsByFlow.get(entry.scenarioName);
-            if (unrunnable?.length) {
-                return `no ${effectiveSurface} or default binding: ${unrunnable.join(', ')}`;
-            }
-            return undefined;
-        };
-        const skipped = [];
+        // A `skip` is the project quarantining a scenario on purpose and stays
+        // green; no binding for the run surface is a misconfigured run and fails.
+        const quarantined = [];
+        const unrunnable = [];
         groups = groups
             .map((group) => ({
             ...group,
             entries: group.entries.filter((entry) => {
-                const reason = skipReasonFor(entry);
-                if (!reason)
-                    return true;
-                skipped.push({ name: entry.scenarioName, reason });
-                return false;
+                if (entry.skip) {
+                    quarantined.push({ name: entry.scenarioName, reason: entry.skip });
+                    return false;
+                }
+                const steps = unrunnableStepsByFlow.get(entry.scenarioName);
+                if (steps?.length) {
+                    unrunnable.push({
+                        name: entry.scenarioName,
+                        reason: `no ${runSurface} or default binding: ${steps.join(', ')}`,
+                    });
+                    return false;
+                }
+                return true;
             }),
         }))
             .filter((group) => group.entries.length > 0);
+        const skipped = [...quarantined, ...unrunnable];
         const workflowService = new InMemoryWorkflowService();
         const scenarioService = workflowService.setRunExtension((engine) => new PikkuScenarioService(engine));
         scenarioService.setScenarioEnvironment({
             apiUrl: env.apiUrl,
             appUrl: env.appUrl,
         });
-        scenarioService.setRunSurface(effectiveSurface);
+        scenarioService.setRunSurface(runSurface);
         // Scenario steps run here, not on the target — everything they touch of the
         // app goes over HTTP through an actor, which is what `guardRpc` below
         // enforces. `actor.converse` is the exception, and the reason this is not
@@ -242,8 +237,8 @@ export const scenarioRun = pikkuSessionlessFunc({
         // before it says anything. Built the same way `pikku dev` builds its own,
         // and only when the project declares agents, so a project with no agents
         // does not have to have AI env set to run scenarios.
-        const aiAgentRunner = Object.keys(state.agents?.agentsMeta ?? {}).length > 0
-            ? await createDevAIAgentRunner({
+        const agentRunner = Object.keys(state.agents?.agentsMeta ?? {}).length > 0
+            ? await createDevAgentRunner({
                 logger,
                 projectRoot: config.rootDir,
                 variables,
@@ -253,7 +248,7 @@ export const scenarioRun = pikkuSessionlessFunc({
             logger,
             workflowService,
             workflowRunService: workflowService,
-            ...(aiAgentRunner ? { aiAgentRunner } : {}),
+            ...(agentRunner ? { agentRunner } : {}),
         });
         const refuseInternal = (rpcName) => {
             throw new Error(`Scenario tried to run '${rpcName}' as an internal step. Every workflow.do ` +
@@ -283,7 +278,7 @@ export const scenarioRun = pikkuSessionlessFunc({
         // Only a browser run launches one. Under `--run default` a step with a
         // browser binding takes its default path instead, so there is nothing to
         // drive and nothing to pay for.
-        const needsBrowser = effectiveSurface === 'browser' &&
+        const needsBrowser = runSurface === 'browser' &&
             groups.some((group) => group.entries.some((entry) => browserStepsByFlow.has(entry.scenarioName)));
         const failureDir = join(resolve(config.rootDir, config.outDir), 'scenario-failures');
         // Artifacts are filed under the run, not the scenario, so one run's output
@@ -542,14 +537,14 @@ export const scenarioRun = pikkuSessionlessFunc({
         const surfaceCoverage = { onSurface: 0, total: 0 };
         const unwitnessed = new Set();
         for (const name of scenarioNames) {
-            const scenario = scenarioSurfaceCoverage(state.workflows?.meta?.[name], functionsMeta, effectiveSurface);
+            const scenario = scenarioSurfaceCoverage(state.workflows?.meta?.[name], functionsMeta, runSurface);
             surfaceCoverage.onSurface += scenario.onSurface;
             surfaceCoverage.total += scenario.total;
             for (const step of scenario.unwitnessed)
                 unwitnessed.add(step);
         }
-        if (effectiveSurface !== 'default' && surfaceCoverage.total > 0) {
-            const line = `${surfaceCoverage.onSurface}/${surfaceCoverage.total} steps ran on ${effectiveSurface}`;
+        if (runSurface !== 'default' && surfaceCoverage.total > 0) {
+            const line = `${surfaceCoverage.onSurface}/${surfaceCoverage.total} steps ran on ${runSurface}`;
             if (unwitnessed.size === 0) {
                 logger.info(line);
             }
@@ -558,9 +553,16 @@ export const scenarioRun = pikkuSessionlessFunc({
                 write(`${line} — asserted server-side only: ${[...unwitnessed].join(', ')}`);
             }
         }
+        // Exiting 0 here makes "62 held back" and "62 passed" indistinguishable
+        // to CI, which is how a whole browser suite went unrun.
+        if (unrunnable.length > 0) {
+            logger.error(`${unrunnable.length} scenario(s) could not run on '${runSurface}' — no binding for that surface and no default to fall back to. ` +
+                `Run them on the surface they are written for (--run browser), or hold them back explicitly with --exclude-tags.`);
+        }
         const failed = results.filter((r) => r.status === 'failed');
         if (failed.length > 0 ||
             hookFailures.length > 0 ||
+            unrunnable.length > 0 ||
             (strict && unwitnessed.size > 0)) {
             process.exitCode = 1;
         }

package/dist/src/functions/commands/scopes-prune.js

@@ -40,7 +40,7 @@ export const scopesPrune = pikkuSessionlessFunc({
             logger.info('');
             logger.info(`scopes prune: removed ${pruned.length} scope(s)`);
             if (granted.length > 0) {
-                logger.warn(`Revoked from ${affectedRoles.size} role(s). Users holding those roles lose these scopes on their next request.`);
+                logger.warn(`Revoked from ${affectedRoles.size} role(s). Users holding those roles lose these scopes on their next request — unless mapSession sets scopes itself, in which case it is authoritative and they keep them.`);
             }
         }
         finally {

package/dist/src/functions/commands/scopes-shared.d.ts

@@ -1,5 +1,5 @@
 import type { Kysely } from 'kysely';
-import type { FlatScope } from '@pikku/core/scope';
+import type { FlatScope } from '@pikku/core/ecosystem/scope';
 import { KyselyScopeService } from '@pikku/kysely';
 import type { KyselyPikkuDB } from '@pikku/kysely';
 type Logger = {

package/dist/src/functions/commands/scopes-shared.js

@@ -1,5 +1,5 @@
 import { readFile } from 'node:fs/promises';
-import { flattenScopeDefinitions } from '@pikku/core/scope';
+import { flattenScopeDefinitions } from '@pikku/core/ecosystem/scope';
 import { KyselyScopeService } from '@pikku/kysely';
 import { createKysely, resolveDb } from '../db/local-db.js';
 import { loadUserConfigForDb } from './db-shared.js';

package/dist/src/functions/commands/semver-render.d.ts

@@ -0,0 +1,2 @@
+import type { SemverResult } from './semver.js';
+export declare const renderSemver: (_services: unknown, result: SemverResult) => void;

package/dist/src/functions/commands/semver-render.js

@@ -0,0 +1,60 @@
+import { added, changed, dim, removed, table } from '../../fabric/lib/output.js';
+const STATUS_COLOUR = {
+    added,
+    removed,
+    modified: changed,
+};
+const verdictColour = (verdict) => verdict === 'major'
+    ? removed(verdict)
+    : verdict === 'minor'
+        ? changed(verdict)
+        : dim(verdict);
+export const renderSemver = (_services, result) => {
+    if (result.mode === 'emit') {
+        // No `--out`: the snapshot itself is the output, so it can be redirected.
+        if (!result.written) {
+            console.log(JSON.stringify(result.surface));
+            return;
+        }
+        const counts = [
+            `${Object.keys(result.surface.functions).length} functions`,
+            `${Object.keys(result.surface.schemas).length} schemas`,
+        ].join(', ');
+        console.log(`Surface snapshot written to ${result.written}  ${dim(counts)}`);
+        return;
+    }
+    const lines = [''];
+    if (result.changes.length === 0) {
+        lines.push(`${verdictColour('patch')}  no surface change against ${result.baseline}`, dim('   only internals moved'), '');
+        lines.push(dim(`   written to ${result.written}`));
+        console.log(lines.join('\n'));
+        return;
+    }
+    const rows = result.changes.map((change) => [
+        change.breaking ? removed('breaking') : dim('compatible'),
+        change.kind,
+        STATUS_COLOUR[change.status](change.status),
+        change.id,
+        change.reasons[0] ?? '',
+    ]);
+    lines.push(table(['', 'Kind', 'Status', 'Id', 'Reason'], rows));
+    // Only the first reason fits the table; a function whose schema moved in
+    // several ways gets the rest listed underneath so nothing is lost to layout.
+    for (const change of result.changes) {
+        if (change.reasons.length <= 1)
+            continue;
+        lines.push('', `${change.kind} ${change.id}`);
+        for (const reason of change.reasons) {
+            lines.push(dim(`   ${reason}`));
+        }
+    }
+    const { breaking, added: addedCount, removed: removedCount, modified, } = result.summary;
+    const summary = [
+        `${breaking} breaking`,
+        `${addedCount} added`,
+        `${removedCount} removed`,
+        `${modified} modified`,
+    ].join('  ');
+    lines.push('', '─'.repeat(40), `${verdictColour(result.verdict)} against ${result.baseline}`, dim(`   ${summary}`), dim(`   written to ${result.written}`));
+    console.log(lines.join('\n'));
+};

package/dist/src/functions/commands/semver.d.ts

@@ -0,0 +1,25 @@
+import { type Surface } from '../../utils/surface.js';
+import { type SurfaceChanges } from '../../utils/surface-diff.js';
+/**
+ * `pikku semver` — what does this build owe the clients of another one?
+ *
+ * The baseline is deliberately external: a deployed environment, not the
+ * previous commit. Comparing against production is what makes the answer
+ * actionable, and pointing `--against` somewhere else is how you ask the same
+ * question about staging.
+ */
+export type SemverInput = {
+    against?: string;
+    emit?: boolean;
+    out?: string;
+    failOn?: string;
+};
+export type SemverResult = {
+    mode: 'emit';
+    surface: Surface;
+    written: string | null;
+} | ({
+    mode: 'compare';
+    written: string;
+} & SurfaceChanges);
+export declare const pikkuSemver: import("#pikku").PikkuFunctionConfig<SemverInput, SemverResult, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<SemverInput, SemverResult, "rpc" | "session", import("#pikku").WiredServices, unknown> | import("#pikku").PikkuFunction<SemverInput, SemverResult, "rpc" | "session", import("#pikku").WiredServices>, undefined, undefined>;

package/dist/src/functions/commands/semver.js

@@ -0,0 +1,50 @@
+import { mkdirSync, writeFileSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+import { pikkuSessionlessFunc } from '#pikku';
+import { loadManifest } from '../../utils/contract-versions.js';
+import { loadSurface, readSurface } from '../../utils/surface.js';
+import { computeSurfaceDiff, } from '../../utils/surface-diff.js';
+const FAIL_LEVELS = ['major', 'minor', 'patch'];
+// Ordered by severity, so `--fail-on minor` also fails on major.
+const SEVERITY = { patch: 0, minor: 1, major: 2 };
+async function currentSurface(rootDir, outDir) {
+    const manifest = await loadManifest(join(rootDir, 'versions.pikku.json'));
+    return readSurface(outDir, manifest);
+}
+function writeJson(path, value) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(value, null, 2) + '\n', 'utf-8');
+}
+export const pikkuSemver = pikkuSessionlessFunc({
+    func: async ({ config }, input) => {
+        const outDir = resolve(config.rootDir, config.outDir);
+        const out = input?.out ? resolve(config.rootDir, input.out) : null;
+        if (input?.emit === true) {
+            const surface = await currentSurface(config.rootDir, outDir);
+            if (out)
+                writeJson(out, surface);
+            return { mode: 'emit', surface, written: out };
+        }
+        const against = input?.against;
+        if (!against) {
+            throw new Error("Nothing to compare against. Pass `--against <path|url>` — a `.pikku` directory, a snapshot file, or a snapshot URL — or `--emit` to produce this build's snapshot.");
+        }
+        const [before, after] = await Promise.all([
+            loadSurface(against),
+            currentSurface(config.rootDir, outDir),
+        ]);
+        const changes = computeSurfaceDiff(before, after, against);
+        const changesPath = out ?? join(outDir, 'changes.gen.json');
+        writeJson(changesPath, changes);
+        const failOn = input?.failOn;
+        if (failOn) {
+            if (!FAIL_LEVELS.includes(failOn)) {
+                throw new Error(`--fail-on must be one of ${FAIL_LEVELS.join(', ')}, got '${failOn}'.`);
+            }
+            if (SEVERITY[changes.verdict] >= SEVERITY[failOn]) {
+                throw new Error(`Release is ${changes.verdict} against ${against}, at or above --fail-on ${failOn}. See ${changesPath}.`);
+            }
+        }
+        return { mode: 'compare', written: changesPath, ...changes };
+    },
+});

package/dist/src/functions/commands/serve.js

@@ -1,10 +1,11 @@
 import { join, resolve } from 'path';
 import { pikkuSessionlessFunc } from '#pikku';
-import { ConsoleLogger, LocalEmailService, InMemoryQueueService, InMemoryWorkflowService, InMemoryTriggerService, InMemoryAIRunStateService, QueueWebhookService, } from '@pikku/core/services';
-import { KyselyAIStorageService, KyselyAIRunStateService, KyselyAgentRunService, } from '@pikku/kysely';
+import { ConsoleLogger, LocalEmailService, InMemoryQueueService, InMemoryWorkflowService, InMemoryTriggerService, QueueWebhookService, } from '@pikku/core/services';
+import { InMemoryAgentRunStateService } from '@pikku/core/ecosystem/services';
+import { KyselyAgentStorageService, KyselyAgentRunStateService, KyselyAgentRunService, } from '@pikku/kysely';
 import { stopSingletonServices } from '@pikku/core';
 import { pikkuState } from '@pikku/core/ecosystem';
-import { wireAIScorerQueueWorkers } from '@pikku/core/ai-scorer';
+import { wireAgentScorerQueueWorkers } from '@pikku/core/ecosystem/agent-scorer';
 import { LocalMetaService } from '@pikku/core/services/local-meta';
 import { LocalContent, } from '@pikku/core/services/local-content';
 import { InMemorySchedulerService } from '@pikku/schedule';
@@ -12,7 +13,7 @@ import { resolveDb, createKysely, parseDatabaseUrl, } from '../db/local-db.js';
 import { loadUserBootstrap, loadUserModule } from './load-user-project.js';
 import { registerScenarioInstrumentation } from '../wirings/scenarios/register-scenario-instrumentation.js';
 import { resolveScaffoldFeature } from '../../utils/resolve-scaffold-feature.js';
-import { createDevAIAgentRunner } from './dev-ai-runner.js';
+import { createDevAgentRunner } from './dev-agent-runner.js';
 import { resolveConsoleMount } from './serve-console.js';
 import { serverReadyLine } from '../../server/server-ready.js';
 import { createEphemeralContentSigningJWT } from '../../server/content-signing-jwt.js';
@@ -75,24 +76,24 @@ export const serve = pikkuSessionlessFunc({
             ? new LocalContent(localContentConfig, logger, contentSigningJWT)
             : undefined;
         const schedulerService = new InMemorySchedulerService();
-        const aiStorage = kysely
-            ? new KyselyAIStorageService(kysely)
+        const agentStorage = kysely
+            ? new KyselyAgentStorageService(kysely)
             : undefined;
-        const aiRunState = kysely
-            ? new KyselyAIRunStateService(kysely)
-            : new InMemoryAIRunStateService();
+        const agentRunState = kysely
+            ? new KyselyAgentRunStateService(kysely)
+            : new InMemoryAgentRunStateService();
         const agentRunService = kysely
             ? new KyselyAgentRunService(kysely)
             : undefined;
-        if (aiStorage)
-            await aiStorage.init();
-        if ('init' in aiRunState && typeof aiRunState.init === 'function') {
-            await aiRunState.init();
+        if (agentStorage)
+            await agentStorage.init();
+        if ('init' in agentRunState && typeof agentRunState.init === 'function') {
+            await agentRunState.init();
         }
         const devLogger = new ConsoleLogger();
         const hasAgents = Object.keys(inspectorState.agents.agentsMeta).length > 0;
-        const aiAgentRunner = hasAgents
-            ? await createDevAIAgentRunner({
+        const agentRunner = hasAgents
+            ? await createDevAgentRunner({
                 logger,
                 projectRoot: config.rootDir,
                 variables,
@@ -102,7 +103,7 @@ export const serve = pikkuSessionlessFunc({
         const serveQueueService = new InMemoryQueueService();
         const inMemoryServices = {
             logger: devLogger,
-            ...(aiAgentRunner ? { aiAgentRunner } : {}),
+            ...(agentRunner ? { agentRunner } : {}),
             emailService: new LocalEmailService(),
             metaService: new LocalMetaService(pikkuDir),
             schedulerService,
@@ -111,8 +112,8 @@ export const serve = pikkuSessionlessFunc({
             workflowService,
             workflowRunService: workflowService,
             triggerService: new InMemoryTriggerService(),
-            aiStorage,
-            aiRunState,
+            agentStorage,
+            agentRunState,
             agentRunService,
             eventHub,
             ...(kysely ? { kysely } : {}),
@@ -128,7 +129,7 @@ export const serve = pikkuSessionlessFunc({
         };
         pikkuState(null, 'package', 'singletonServices', resolvedServices);
         resolvedServices.workflowService?.wireQueueWorkers?.();
-        wireAIScorerQueueWorkers();
+        wireAgentScorerQueueWorkers();
         const { serverLifecycleFactory } = inspectorState.filesAndMethods;
         const loadLifecycle = async () => {
             if (!serverLifecycleFactory)

package/dist/src/functions/commands/start-coverage.d.ts

@@ -1,4 +1,4 @@
-import type { CoverageService } from '@pikku/core/services';
+import type { CoverageService } from '@pikku/core/ecosystem/services';
 interface CoverageLogger {
     info(message: string): void;
     warn(message: string): void;

package/dist/src/functions/commands/start-coverage.js

@@ -1,5 +1,5 @@
-import { V8CoverageService } from '@pikku/core/services/v8-coverage';
-import { IstanbulCoverageService } from '@pikku/core/services/istanbul-coverage';
+import { V8CoverageService } from '@pikku/core/ecosystem/services/v8-coverage';
+import { IstanbulCoverageService } from '@pikku/core/ecosystem/services/istanbul-coverage';
 import { registerBunCoverageLoader } from './bun-coverage-loader.js';
 import { mapPreciseCoverage, mapLineHitsToReport, } from '../../utils/precise-coverage-map.js';
 const isBunRuntime = () => typeof globalThis.Bun !== 'undefined';

package/dist/src/functions/commands/update-render.d.ts

@@ -0,0 +1,2 @@
+import type { UpdateResult } from './update.js';
+export declare const renderUpdate: (_services: unknown, result: UpdateResult) => void;

package/dist/src/functions/commands/update-render.js

@@ -0,0 +1,102 @@
+import { added, changed, dim, removed, table } from '../../fabric/lib/output.js';
+const STATUS_LABEL = {
+    current: dim('current'),
+    outdated: changed('outdated'),
+    'stale-install': changed('stale install'),
+    linked: dim('linked'),
+    manual: dim('manual'),
+    unresolved: removed('unresolved'),
+};
+/**
+ * A linked package is a deliberate local checkout, not a decision waiting on
+ * the user — so it is counted but never listed. Listing it buries the two rows
+ * that matter under twenty that don't, which is what a monorepo run looks like.
+ */
+const QUIET = ['current', 'linked'];
+export const renderUpdate = (_services, result) => {
+    const { entries, peers, summary, applied } = result;
+    if (entries.length === 0) {
+        console.log(dim('No @pikku/* dependencies found.'));
+        return;
+    }
+    const multiManifest = new Set(entries.map((entry) => entry.manifest)).size > 1;
+    const interesting = entries.filter((entry) => !QUIET.includes(entry.status));
+    const rows = (interesting.length > 0 ? interesting : entries).map((entry) => [
+        entry.package,
+        entry.range,
+        entry.installed ?? dim('—'),
+        entry.latest ?? dim('—'),
+        entry.target ? added(entry.target) : dim('—'),
+        STATUS_LABEL[entry.status],
+        ...(multiManifest ? [dim(entry.manifest)] : []),
+    ]);
+    console.log(table([
+        'Package',
+        'Range',
+        'Installed',
+        'Latest',
+        applied ? 'Written' : 'Update to',
+        'Status',
+        ...(multiManifest ? ['Manifest'] : []),
+    ], rows));
+    for (const entry of entries) {
+        if (entry.reason &&
+            entry.status !== 'stale-install' &&
+            !QUIET.includes(entry.status)) {
+            console.log(`${dim('•')} ${entry.package}: ${dim(entry.reason)}`);
+        }
+    }
+    if (peers.length > 0) {
+        console.log();
+        console.log(changed(`${peers.length} unsatisfied peer requirement(s):`));
+        for (const peer of peers) {
+            const has = peer.found
+                ? `has ${peer.found}${peer.resolved ? dim(` (${peer.resolved})`) : ''}`
+                : removed('not declared');
+            console.log(`  ${peer.package} needs ${peer.peer}@${peer.required} — ${has}`);
+        }
+        if (!applied && peers.some((peer) => peer.found)) {
+            console.log(dim('  run with --update-peers to write the ranges you already declare'));
+        }
+        if (peers.some((peer) => !peer.found)) {
+            console.log(dim('  a peer you do not declare is yours to add — update never adds one'));
+        }
+    }
+    console.log('─'.repeat(40));
+    const counts = [
+        dim(`${summary.checked} @pikku dependenc${summary.checked === 1 ? 'y' : 'ies'}`),
+    ];
+    if (summary.outdated > 0)
+        counts.push(changed(`${summary.outdated} outdated`));
+    if (summary.staleInstall > 0)
+        counts.push(changed(`${summary.staleInstall} stale install`));
+    if (summary.linked > 0)
+        counts.push(dim(`${summary.linked} linked`));
+    if (summary.manual > 0)
+        counts.push(dim(`${summary.manual} manual`));
+    if (summary.unresolved > 0)
+        counts.push(removed(`${summary.unresolved} unresolved`));
+    console.log(counts.join('  '));
+    if (applied) {
+        if (result.written.length === 0) {
+            console.log(added('✓') + '  ' + dim('nothing to write — already current'));
+        }
+        else {
+            console.log(added('✓') +
+                `  ${result.written.length} package.json file${result.written.length !== 1 ? 's' : ''} updated`);
+            console.log(result.installed
+                ? added('✓') +
+                    '  ' +
+                    dim(`${result.packageManager} install completed`)
+                : dim(result.packageManager === 'unknown'
+                    ? '   no lockfile found — install with your package manager'
+                    : `   skipped install — run \`${result.packageManager} install\``));
+        }
+    }
+    else if (summary.outdated > 0 || summary.staleInstall > 0) {
+        console.log(dim('   run `pikku update --update` to apply'));
+    }
+    else {
+        console.log(added('✓') + '  ' + dim('every @pikku dependency is current'));
+    }
+};

package/dist/src/functions/commands/update.d.ts

@@ -0,0 +1,99 @@
+export type PackageManager = 'bun' | 'npm' | 'yarn' | 'pnpm' | 'unknown';
+export type DependencyField = 'dependencies' | 'devDependencies' | 'peerDependencies' | 'optionalDependencies';
+export type UpdateStatus = 'current' | 'outdated' | 'stale-install' | 'linked' | 'manual' | 'unresolved';
+export type UpdateEntry = {
+    package: string;
+    /** package.json holding the range, relative to the project root. */
+    manifest: string;
+    field: DependencyField;
+    range: string;
+    /** Version resolved in node_modules, when the project has been installed. */
+    installed: string | null;
+    latest: string | null;
+    /** The range `--update` would write, or null when there is nothing to write. */
+    target: string | null;
+    status: UpdateStatus;
+    reason?: string;
+};
+export type PeerFinding = {
+    /** The @pikku package that declares the peer. */
+    package: string;
+    peer: string;
+    required: string;
+    /** The range the project declares for the peer, or null when it declares none. */
+    found: string | null;
+    resolved: string | null;
+    manifest: string;
+    optional: boolean;
+    /** The range `--update-peers` would write. */
+    target: string;
+};
+export type UpdateResult = {
+    root: string;
+    registry: string;
+    tag: string;
+    packageManager: PackageManager;
+    entries: UpdateEntry[];
+    peers: PeerFinding[];
+    applied: boolean;
+    /** Manifests rewritten by `--update`, relative to the project root. */
+    written: string[];
+    installed: boolean;
+    summary: {
+        checked: number;
+        outdated: number;
+        staleInstall: number;
+        linked: number;
+        manual: number;
+        unresolved: number;
+        peerIssues: number;
+    };
+};
+export type UpdateInput = {
+    update?: boolean;
+    updatePeers?: boolean;
+    install?: boolean;
+    tag?: string;
+    registry?: string;
+};
+export type Packument = {
+    'dist-tags'?: Record<string, string>;
+    versions?: Record<string, {
+        peerDependencies?: Record<string, string>;
+        peerDependenciesMeta?: Record<string, {
+            optional?: boolean;
+        }>;
+    }>;
+};
+export type FetchPackument = (name: string) => Promise<Packument | null>;
+/** The range `--update` writes for `latest`, or null when the range is not ours to move. */
+export declare const rewriteRange: (range: string, latest: string) => string | null;
+export declare const findProjectRoot: (startDir: string, exists?: (path: string) => boolean) => string;
+/**
+ * Where `install` has to run: the nearest directory at or above the project
+ * root that says which package manager owns the tree. In a monorepo that is the
+ * workspace root, not the package the command was invoked in.
+ *
+ * The corepack `packageManager` field wins over lockfiles — it states intent
+ * before a lockfile exists, and a project can carry a stale one from another
+ * tool. Guessing wrong is not a soft failure: the install spawns a binary that
+ * isn't on PATH.
+ */
+export declare const findInstallRoot: (root: string, exists?: (path: string) => boolean, read?: (path: string) => any | null) => {
+    dir: string;
+    packageManager: PackageManager;
+};
+/** Every package.json the run covers: the project root, plus its workspaces. */
+export declare const collectManifestPaths: (root: string) => Promise<string[]>;
+/** Version resolved in node_modules, walking up from the manifest's own directory. */
+export declare const resolveInstalled: (manifestDir: string, name: string, read?: (path: string) => any | null) => string | null;
+export declare const runUpdate: ({ rootDir, apply, updatePeers, install, tag, registry, fetchPackument, }: {
+    rootDir: string;
+    apply: boolean;
+    updatePeers: boolean;
+    install: boolean;
+    tag: string;
+    registry: string;
+    fetchPackument?: FetchPackument;
+}) => Promise<UpdateResult>;
+export declare const pikkuUpdate: import("#pikku").PikkuFunctionConfig<UpdateInput, UpdateResult, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<UpdateInput, UpdateResult, "rpc" | "session", import("#pikku").WiredServices, unknown> | import("#pikku").PikkuFunction<UpdateInput, UpdateResult, "rpc" | "session", import("#pikku").WiredServices>, undefined, undefined>;