@lotics/cli 0.86.2 → 0.87.0

package/dist/package_commands.js

@@ -1,1096 +0,0 @@
-/**
- * The package CONSUMER + registry surface (see docs/packages.md). Nothing starts
- * as a package, and nothing is authored as a local package PROJECT: an app is
- * first-released with `lotics app publish`, and a content package (a SET of live
- * knowledge docs + templates) is published with the `publish_content` /
- * `release_content` tools (`lotics run publish_content …`). This module
- * implements only what operates published packages + installations:
- *
- *   install / uninstall / upgrade   the high-traffic consumer verbs, dispatched
- *     from the TOP LEVEL (`lotics install|uninstall|upgrade`). `upgrade` folds in
- *     the whole-fleet path (a `package_id` upgrades every org installation).
- *   doctor / eject / config / list-content / yank / show   the low-traffic
- *     ops, under `lotics package <verb>`. (Re-pointing a live role rides
- *     `upgrade --resolve roles.<alias>=<grp_id>` — no separate verb.)
- *
- * Author verbs live on `lotics app` (`publish` / `release` / `unpublish`), and the
- * app-development loop lives entirely in `lotics app *`: pull an installed origin
- * (`lotics app pull <app_id>`), edit + `lotics app deploy`, then
- * `lotics app release <app_id>` cuts the next version.
- */
-import fs from "node:fs";
-import path from "node:path";
-import "./client.js";
-import { contractConfigEntrySchema, knowledgeEntryNeedsConsent, validKnowledgeResolutions, } from "@lotics/shared/schemas/packages";
-function packageJsonPath(projectDir) {
-    return path.join(projectDir, "package.json");
-}
-function isPlainObject(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-/**
- * Read the local APP project's manifest (`package.json#lotics.app_id` +
- * `lotics.knowledge` + `lotics.config`) — what `lotics app pull` writes.
- * `lotics app publish` / `release` run from a pulled app project resolve the app
- * id from it and forward the package-managed knowledge declaration AND the config
- * knob declarations to the server — both are declarations extract cannot invert
- * from artifacts (agents reference docs by free text; a config knob has no concrete
- * artifact), so the author declares them. Each `lotics.config` entry is validated
- * against the shared `contractConfigEntrySchema` so a malformed knob fails LOUDLY
- * client-side naming the alias, never silently dropped. Returns null when the dir
- * has no package.json. `app_id` is null when the manifest is a package/non-app
- * project.
- */
-export function readLocalAppManifest(projectDir) {
-    const pkgPath = packageJsonPath(projectDir);
-    if (!fs.existsSync(pkgPath))
-        return null;
-    const parsed = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
-    if (!isPlainObject(parsed))
-        return null;
-    const lotics = isPlainObject(parsed.lotics) ? parsed.lotics : {};
-    const app_id = typeof lotics.app_id === "string" ? lotics.app_id : null;
-    const knowledge = [];
-    if (Array.isArray(lotics.knowledge)) {
-        for (const entry of lotics.knowledge) {
-            if (isPlainObject(entry) && typeof entry.alias === "string" && typeof entry.doc_id === "string") {
-                knowledge.push({ alias: entry.alias, doc_id: entry.doc_id });
-            }
-        }
-    }
-    const config = [];
-    if (Array.isArray(lotics.config)) {
-        for (const entry of lotics.config) {
-            const result = contractConfigEntrySchema.safeParse(entry);
-            if (!result.success) {
-                const alias = isPlainObject(entry) && typeof entry.alias === "string" ? entry.alias : "?";
-                throw new Error(`Invalid lotics.config knob "${alias}" in package.json: ` +
-                    result.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; "));
-            }
-            config.push(result.data);
-        }
-    }
-    return { app_id, knowledge, config };
-}
-/** Parse repeated `--rename old=new` flags into `{ from, to }[]` (first-publish alias fixes). */
-export function parseRenameFlags(renames) {
-    return renames.map((entry) => {
-        const eq = entry.indexOf("=");
-        if (eq <= 0 || eq === entry.length - 1) {
-            throw new Error(`Invalid --rename "${entry}" — expected old=new (an alias to rename before v1 freezes it).`);
-        }
-        return { from: entry.slice(0, eq), to: entry.slice(eq + 1) };
-    });
-}
-/**
- * Render a package-extract report grouped by severity (errors, then warnings,
- * then info), one `  [<severity>] <area>: <message>` line each, and classify
- * whether any `error` finding is present. Shared by the release preview display.
- * Pure — the command prints `lines` to stderr and gates on `hasError`.
- */
-export function formatExtractReport(report) {
-    const order = ["error", "warning", "info"];
-    const lines = order.flatMap((severity) => report
-        .filter((f) => f.severity === severity)
-        .map((f) => `  [${f.severity}] ${f.area}: ${f.message}`));
-    return { lines, hasError: report.some((f) => f.severity === "error") };
-}
-/**
- * Resolve the installation to operate on: an explicit app id is required (there
- * is no dev-workspace pin to fall back to).
- */
-function resolveInstallationAppId(explicit) {
-    if (explicit)
-        return explicit;
-    throw new Error("Pass an app id — e.g. lotics package doctor <app_id>.");
-}
-const RESOLVE_VERBS = new Set(["recreate", "revert", "keep", "apply", "archive", "unbind"]);
-/**
- * Parse repeated `--resolve <key>=<value>` flags into the ONE namespaced
- * resolutions map every upgrade wire takes. Keys pass through verbatim — a
- * drifted binding entry (`<namespace>.<alias>`), a modified artifact
- * (`<kind>.<alias>`), a bundled/standalone knowledge doc (`knowledge.<alias>`),
- * or a live-role re-point (`roles.<alias>`). A value that is one of the
- * resolution verbs stays a verb; anything else is a `{ bind_to }` id. The
- * server validates value-kind against what each key resolves.
- */
-export function parseResolveFlags(resolve) {
-    const resolutions = {};
-    for (const entry of resolve) {
-        const eq = entry.indexOf("=");
-        if (eq <= 0 || eq === entry.length - 1) {
-            throw new Error(`Invalid --resolve "${entry}" — expected <key>=<verb> (recreate|revert|keep|apply|archive|unbind) or <key>=<existing_id>.`);
-        }
-        const key = entry.slice(0, eq);
-        const value = entry.slice(eq + 1);
-        resolutions[key] = RESOLVE_VERBS.has(value)
-            ? value
-            : { bind_to: value };
-    }
-    return resolutions;
-}
-/**
- * Health check: version pin vs. registry latest + binding drift. Exits
- * non-zero when drift is found so scripts can gate on it. An `apg_` PACKAGE id
- * resolves THIS workspace's standalone content installation — the same
- * package-id addressing `upgrade`/`uninstall` speak.
- */
-export async function packageDoctor(client, args) {
-    if (args.app_id !== undefined && args.app_id.startsWith("apg_")) {
-        await contentDoctor(client, args.app_id);
-        return;
-    }
-    const app_id = resolveInstallationAppId(args.app_id);
-    const health = await client.getPackageHealth(app_id);
-    console.error(`${health.package_name} — installation ${health.app_id}` +
-        (health.is_origin ? " (origin — this app IS installation #1, the release working copy)" : ""));
-    console.error(`  Installed: v${health.installed_version}   Latest: v${health.latest_version}` +
-        (health.update_available ? "   → update available" : ""));
-    if (health.drift.length === 0) {
-        console.error("  Binding: healthy — every bound alias resolves.");
-    }
-    else {
-        console.error(`  Binding drift (${health.drift.length}):`);
-        for (const d of health.drift) {
-            console.error(`    - ${d.namespace}.${d.alias} → ${d.id} (missing from the workspace)`);
-        }
-        console.error(`  Resolve while upgrading:\n    lotics upgrade ${app_id}` +
-            ` --resolve <namespace.alias>=recreate   (or =<existing_id> to re-point)`);
-        process.exitCode = 1;
-    }
-    if (health.modified.length === 0) {
-        console.error(health.is_origin
-            ? "  Package artifacts: no changes since the last release.\n" +
-                `  (schema additions aren't fingerprinted — preview them with: lotics app release ${app_id})`
-            : "  Package artifacts: pristine — no local edits an upgrade would revert.");
-    }
-    else if (health.is_origin) {
-        // The origin IS the author's working copy — edits since the last release are
-        // the NEXT release's payload, not consumer drift, and never fail the check.
-        console.error(`  Changed since v${health.installed_version} (${health.modified.length}) — a release will publish these:`);
-        for (const m of health.modified) {
-            console.error(`    - ${m.kind}.${m.alias}`);
-        }
-        console.error(`  Cut the next version:  lotics app release ${app_id} -m "<what changed>"`);
-    }
-    else {
-        console.error(`  Locally modified package artifacts (${health.modified.length}):`);
-        for (const m of health.modified) {
-            console.error(`    - ${m.kind}.${m.alias} (an upgrade overwrites this unless kept)`);
-        }
-        console.error(`  Consent while upgrading:\n    lotics upgrade ${app_id}` +
-            ` --resolve <kind.alias>=revert   (or =keep to retain the edit)`);
-        process.exitCode = 1;
-    }
-    // Package-managed knowledge (bundled with this app install): drift + local edits
-    // + unmet expects. All advisory; resolved through the app's package upgrade.
-    if (health.knowledge_drift.length > 0) {
-        console.error(`  Knowledge binding drift (${health.knowledge_drift.length}):`);
-        for (const d of health.knowledge_drift) {
-            console.error(`    - ${d.alias} "${d.name}" → ${d.doc_id ?? "(unbound)"} (missing from the workspace)`);
-        }
-    }
-    if (health.knowledge_modified.length > 0) {
-        if (health.is_origin) {
-            console.error(`  Knowledge changed since v${health.installed_version} (${health.knowledge_modified.length}) — a release will re-snapshot these:`);
-            for (const m of health.knowledge_modified) {
-                console.error(`    - ${m.alias} "${m.name}"`);
-            }
-        }
-        else {
-            console.error(`  Locally edited package knowledge (${health.knowledge_modified.length}):`);
-            for (const m of health.knowledge_modified) {
-                console.error(`    - ${m.alias} "${m.name}" (an upgrade overwrites this unless kept)`);
-            }
-        }
-    }
-    if (health.missing_expected_docs.length > 0) {
-        console.error(`  Missing expected knowledge docs (${health.missing_expected_docs.length}):`);
-        for (const name of health.missing_expected_docs) {
-            console.error(`    - "${name}" (the package's agents route to this name; no matching doc exists)`);
-        }
-    }
-    // Drift is genuine breakage on the origin too (a bound id vanished); edited
-    // knowledge on the origin is staged release work, not a failure.
-    if (health.knowledge_drift.length > 0 || (health.knowledge_modified.length > 0 && !health.is_origin)) {
-        process.exitCode = 1;
-    }
-    if (health.knowledge_drift.length === 0 &&
-        health.knowledge_modified.length === 0 &&
-        health.missing_expected_docs.length === 0) {
-        console.error("  Knowledge: healthy — bound docs resolve, none locally edited, expects met.");
-    }
-    if (health.update_available) {
-        console.error(`  Upgrade: lotics upgrade ${app_id}`);
-    }
-}
-/**
- * Preview-then-apply an app-installation upgrade. Prints the additive plan +
- * informational removals + any bundled-knowledge changes; refuses (exit 1, with
- * the exact --resolve syntax) while any binding drift, modified core artifact, or
- * consent-requiring bundled-knowledge doc lacks a resolution.
- *
- * `--resolve` speaks ONE namespaced grammar, passed to the server verbatim: a
- * drifted binding entry (`<namespace>.<alias>`), a modified artifact
- * (`<kind>.<alias>`), a bundled knowledge doc (`knowledge.<alias>` —
- * apply|keep|archive|recreate|unbind), or a live-role re-point
- * (`roles.<alias>=<grp_id>`). `--bind-to` consents an added-knowledge-doc name
- * collision; `--apply-all` accepts the package's version for every
- * consent-requiring knowledge doc (overwriting local edits).
- */
-export async function packageUpgrade(client, args) {
-    const preview = await client.previewPackageUpgrade(args.app_id, {
-        ...(args.version !== undefined ? { version: args.version } : {}),
-    });
-    console.error(`Upgrade v${preview.from_version} → v${preview.to_version}` +
-        (preview.changelog ? ` — ${preview.changelog}` : ""));
-    const summarize = (sets) => Object.entries(sets)
-        .filter(([, entries]) => entries.length > 0)
-        .map(([kind, entries]) => `${entries.length} ${kind}`)
-        .join(", ");
-    const added = summarize(preview.diff.added);
-    const removed = summarize(preview.diff.removed);
-    if (added)
-        console.error(`  Adds: ${added}`);
-    if (removed)
-        console.error(`  Unbinds (workspace data kept): ${removed}`);
-    if (preview.knowledge.length > 0) {
-        console.error(`  Knowledge docs (${preview.knowledge.length}):`);
-        for (const entry of preview.knowledge) {
-            console.error(`    ${formatKnowledgeEntryLine(entry)}`);
-        }
-    }
-    // Breaking contract changes are NOT resolvable via --resolve — scaffold would
-    // refuse them on a bound alias, and there is no in-flow remediation. Report
-    // every entry and the only two real remedies, then hard-stop.
-    if (preview.diff.breaking.length > 0) {
-        console.error("  Breaking contract changes — NOT resolvable via --resolve (a bound alias's shape changed):");
-        for (const b of preview.diff.breaking) {
-            console.error(`    - ${b.entity}.${b.alias} (${b.kind}): ${b.from} → ${b.to}`);
-        }
-        console.error("  There is no in-flow resolution for this class. The package author must publish a version\n" +
-            "  that keeps these aliases' shape stable, or eject this app (severing the package link)\n" +
-            `  before making the change:  lotics package eject ${args.app_id}`);
-        process.exit(1);
-    }
-    // ONE namespaced grammar — the flags pass to the server verbatim. `--bind-to`
-    // is sugar for `knowledge.<alias>={bind_to}`; `--apply-all` fills the
-    // remaining consent-requiring knowledge entries with the accept verb.
-    const resolutions = parseResolveFlags(args.resolve);
-    for (const [alias, id] of Object.entries(parseBindToFlags(args.bindTo))) {
-        resolutions[`knowledge.${alias}`] = { bind_to: id };
-    }
-    if (args.applyAll) {
-        for (const entry of preview.knowledge) {
-            if (knowledgeEntryNeedsConsent(entry) && resolutions[`knowledge.${entry.alias}`] === undefined) {
-                resolutions[`knowledge.${entry.alias}`] = knowledgeAcceptResolution(entry.change);
-            }
-        }
-    }
-    const unresolvedDrift = preview.drift.filter((d) => resolutions[`${d.namespace}.${d.alias}`] === undefined);
-    const unresolvedModified = preview.modified.filter((m) => resolutions[`${m.kind}.${m.alias}`] === undefined);
-    const unresolvedKnowledge = preview.knowledge.filter((e) => knowledgeEntryNeedsConsent(e) && resolutions[`knowledge.${e.alias}`] === undefined);
-    if (unresolvedDrift.length > 0 ||
-        unresolvedModified.length > 0 ||
-        unresolvedKnowledge.length > 0) {
-        if (unresolvedDrift.length > 0) {
-            console.error("  Binding drift must be resolved before upgrading:");
-            for (const d of unresolvedDrift) {
-                console.error(`    --resolve ${d.namespace}.${d.alias}=recreate   (or =<existing_id> to re-point; was ${d.id})`);
-            }
-        }
-        if (unresolvedModified.length > 0) {
-            console.error("  Locally modified package artifacts need consent before upgrading:");
-            for (const m of unresolvedModified) {
-                console.error(`    --resolve ${m.kind}.${m.alias}=revert   (overwrite the local edit; or =keep to retain it)`);
-            }
-        }
-        if (unresolvedKnowledge.length > 0) {
-            console.error("  Bundled knowledge docs need consent before upgrading (or --apply-all to accept the package's version for all):");
-            for (const entry of unresolvedKnowledge) {
-                console.error(formatKnowledgeResolveHint(entry));
-            }
-        }
-        process.exit(1);
-    }
-    const app = await client.upgradePackage(args.app_id, {
-        ...(args.version !== undefined ? { version: args.version } : {}),
-        ...(Object.keys(resolutions).length > 0 ? { resolutions } : {}),
-    });
-    console.error(`Upgraded ${app.name} → v${app.package_version} (${app.id}).`);
-}
-/** `--apply-all`'s accept-the-package resolution for a consent-requiring entry. */
-function knowledgeAcceptResolution(change) {
-    switch (change) {
-        case "changed":
-            return "apply";
-        case "removed":
-            return "archive";
-        case "drifted":
-            return "recreate";
-        case "added":
-            return "apply"; // unreachable (added never needs consent), kept total.
-    }
-}
-/** The install-consent trust line: official > your own org > third-party. */
-function trustBadge(pkg) {
-    if (pkg.is_official)
-        return "official Lotics package";
-    if (pkg.owned_by_caller === true)
-        return "your organization's package";
-    return "third-party package (runs under your authority once installed)";
-}
-/**
- * `lotics package show <package_id>` — registry metadata + version history
- * (trust badge, retirement, per-version channel/yank/changelog). The read
- * surface for "what is this package and what shipped when". Kind-agnostic — a
- * content package shows here the same way.
- */
-export async function packageShow(client, args) {
-    const pkg = await client.getPackage(args.package_id);
-    const { versions } = await client.listPackageVersions(args.package_id);
-    console.error(`${pkg.name} (${pkg.id}) — ${trustBadge(pkg)}`);
-    if (pkg.description)
-        console.error(`  ${pkg.description}`);
-    if (pkg.retired_at)
-        console.error(`  RETIRED ${pkg.retired_at}`);
-    console.error(`  latest installable: ${pkg.latest_version > 0 ? `v${pkg.latest_version}` : "none"}`);
-    console.error("");
-    for (const v of versions) {
-        const marks = [
-            v.version === pkg.latest_version ? "*" : " ",
-            v.channel === "dev" ? "dev" : "   ",
-            v.yanked_at ? "YANKED" : "      ",
-        ].join(" ");
-        console.log(`${marks} v${v.version}  ${v.created_at}  ${v.changelog ?? ""}`.trimEnd());
-    }
-    if (versions.length === 0)
-        console.error("  (no published versions)");
-}
-/**
- * One preview line for a knowledge upgrade entry — `[change] alias "name"` with
- * `modified` / `needs consent` marks. Shared verbatim by the standalone (`pci_`)
- * and the app-install upgrade previews so both speak one vocabulary; the caller
- * owns the leading indent.
- */
-function formatKnowledgeEntryLine(entry) {
-    const marks = [
-        entry.modified ? "modified" : null,
-        knowledgeEntryNeedsConsent(entry) ? "needs consent" : null,
-    ].filter((m) => m !== null);
-    return `[${entry.change}] ${entry.alias} "${entry.name}"${marks.length ? ` (${marks.join(", ")})` : ""}`;
-}
-/**
- * The exact `--resolve <alias>=<valid options>` remediation line for a
- * consent-requiring knowledge entry (options from the shared
- * `validKnowledgeResolutions`). Shared by both upgrade paths' gate output.
- */
-function formatKnowledgeResolveHint(entry) {
-    const note = entry.change === "changed" || entry.change === "removed"
-        ? "   (a local edit — apply/archive overwrites it; keep retains it)"
-        : "   (bound doc is gone; recreate from the package, or unbind)";
-    return `    --resolve knowledge.${entry.alias}=${validKnowledgeResolutions(entry.change).join("|")}${note}`;
-}
-/** The `--resolve template.<alias>=revert|keep` remediation line for a consent-requiring template. */
-function formatTemplateResolveHint(entry) {
-    const note = entry.baseline_unknown
-        ? "   (can't verify the local edit — older package version; revert overwrites, keep retains)"
-        : "   (a local edit — revert overwrites it with the package's version; keep retains it)";
-    return `    --resolve template.${entry.alias}=revert|keep${note}`;
-}
-/**
- * Health report for a STANDALONE content installation, addressed by PACKAGE id.
- * Composed client-side from the surfaces the consumer verbs already speak: the
- * list row (pin vs registry latest) and the upgrade preview against latest
- * (which carries per-alias drift + local-edit detection even when the pin is
- * current — the repair view). Exits non-zero on drift, mirroring the app
- * doctor's gate semantics.
- */
-async function contentDoctor(client, package_id) {
-    const installation = await resolveWorkspaceContentInstallation(client, package_id);
-    const preview = await client.previewContentInstallationUpgrade(installation.id, {});
-    const name = installation.package_registry?.name ?? package_id;
-    console.error(`${name} — content installation of ${package_id} (this workspace)`);
-    console.error(`  Installed: v${preview.from_version}   Latest: v${preview.to_version}` +
-        (preview.to_version > preview.from_version ? "   → update available" : ""));
-    const drifted = preview.entries.filter((e) => e.change === "drifted");
-    if (drifted.length === 0) {
-        console.error("  Binding: healthy — every bound doc resolves.");
-    }
-    else {
-        console.error(`  Binding drift (${drifted.length}):`);
-        for (const entry of drifted) {
-            console.error(`    - knowledge.${entry.alias} "${entry.name}" (bound doc is gone)`);
-        }
-        console.error(`  Resolve while upgrading:\n    lotics upgrade ${package_id}` +
-            ` --resolve knowledge.<alias>=recreate|unbind   (or --bind-to <alias>=<kdc_id> to re-point)`);
-        process.exitCode = 1;
-    }
-    const editedDocs = preview.entries.filter((e) => e.modified);
-    const editedTemplates = preview.templates;
-    if (editedDocs.length === 0 && editedTemplates.length === 0) {
-        console.error("  Content: pristine — no local edits an upgrade would ask about.");
-    }
-    else {
-        console.error(`  Local edits (${editedDocs.length + editedTemplates.length}) — each takes a keep/overwrite consent at upgrade:`);
-        for (const entry of editedDocs)
-            console.error(`    - knowledge.${entry.alias} "${entry.name}"`);
-        for (const entry of editedTemplates)
-            console.error(`    - template.${entry.alias}`);
-    }
-}
-/**
- * Resolve a STANDALONE content package's installation in the CURRENT workspace
- * from its PACKAGE id. `UNIQUE (workspace_id, package_id)` means the package id
- * fully determines the anchor row, so consumers address content by package id and
- * the `pci_` resource id never surfaces (the server keeps it — resource identity —
- * and the CLI resolves it here through the list endpoint; zero backend change).
- * Throws a clear "not installed" error (pointing at `lotics install`) when the
- * package has no content installation in this workspace.
- */
-async function resolveWorkspaceContentInstallation(client, package_id) {
-    const workspaceId = client.getWorkspaceId();
-    if (!workspaceId) {
-        throw new Error("No workspace selected. Pass --workspace <ws> (or select one) to operate on its content installation.");
-    }
-    const installations = await client.listContentInstallations(workspaceId);
-    const match = installations.find((inst) => inst.package_id === package_id);
-    if (!match) {
-        throw new Error(`Package ${package_id} is not installed in this workspace — install it first:  lotics install ${package_id}`);
-    }
-    return match;
-}
-/**
- * CLEAN BREAK for an explicit `pci_` argument on `upgrade` / `uninstall`: the
- * `pci_` resource id is retired from human sight — content installs are addressed
- * by their PACKAGE id. Prints a loud redirect, best-effort resolving the `pci_`
- * back to its package id (via list-content) so the exact command is spelled out.
- * The header prints synchronously first, so the redirect is observable even when
- * the best-effort resolution can't reach the registry.
- */
-export async function redirectContentPciForm(client, pci_id, verb) {
-    console.error(`Content installations are addressed by their PACKAGE id now — ${pci_id} is a server-internal resource id.`);
-    const workspaceId = client.getWorkspaceId();
-    const match = workspaceId
-        ? (await client.listContentInstallations(workspaceId)).find((inst) => inst.id === pci_id)
-        : undefined;
-    if (match) {
-        console.error(`  Run:  lotics ${verb} ${match.package_id}`);
-    }
-    else {
-        console.error("  Find the package id:  lotics package list-content");
-        console.error(`  Then run:  lotics ${verb} <package_id>`);
-    }
-    process.exit(1);
-}
-/**
- * `lotics upgrade <apg_>` — the package-id upgrade path, kind-branched. `kind` is a
- * DERIVED display hint (`contractHasAppSurface`): `'content'` means no app surface.
- *   - a CONTENT package upgrades THIS workspace's standalone content installation
- *     (resolved from the package id — the anchor is unique per workspace, so the
- *     `pci_` never surfaces), through the same content review gate.
- *   - an APP-surface package FLEET-upgrades every installation across the org
- *     (unchanged) — the resolve/bind/apply-all flags don't apply to a fleet run.
- */
-export async function packageUpgradeByPackageId(client, args) {
-    const pkg = await client.getPackage(args.package_id);
-    if (pkg.kind === "content") {
-        const installation = await resolveWorkspaceContentInstallation(client, args.package_id);
-        await packageUpgradeKnowledge(client, {
-            installation_id: installation.id,
-            package_id: pkg.id,
-            package_name: pkg.name,
-            version: args.version,
-            resolve: args.resolve,
-            bind_to: parseBindToFlags(args.bindTo),
-            applyAll: args.applyAll,
-        });
-        return;
-    }
-    await packageFleetUpgrade(client, {
-        package_id: args.package_id,
-        ...(args.version !== undefined ? { version: args.version } : {}),
-    });
-}
-/**
- * Preview-then-apply a STANDALONE content installation upgrade — knowledge docs
- * AND document templates behind one review gate. Prints the per-alias plan;
- * refuses (exit 1, with the exact `--resolve` syntax) while any consent-requiring
- * entry lacks a resolution — a modified knowledge change/removal or drift, or a
- * locally-edited changed template. `--apply-all` auto-resolves EVERY consent entry
- * by accepting the package's version (knowledge changed→apply, removed→archive,
- * drifted→recreate; template→revert) — an explicit bulk "take upstream" that
- * discards local edits. `--resolve knowledge.<alias>=<value>` /
- * `--resolve template.<alias>=revert|keep` and `--bind-to <alias>=<kdc_id>`
- * resolve entries individually — the ONE namespaced grammar, passed to the
- * server verbatim.
- */
-async function packageUpgradeKnowledge(client, args) {
-    const preview = await client.previewContentInstallationUpgrade(args.installation_id, {
-        ...(args.version !== undefined ? { version: args.version } : {}),
-    });
-    console.error(`Content upgrade v${preview.from_version} → v${preview.to_version}` +
-        (preview.changelog ? ` — ${preview.changelog}` : ""));
-    const apply = async (resolutions) => {
-        const updated = await client.applyContentInstallationUpgrade(args.installation_id, {
-            ...(args.version !== undefined ? { version: args.version } : {}),
-            resolutions,
-        });
-        console.error(`Upgraded ${args.package_name} (${args.package_id}) → v${updated.package_version}.`);
-    };
-    if (preview.entries.length === 0 && preview.templates.length === 0) {
-        if (preview.to_version === preview.from_version) {
-            console.error("  Already up to date — no content changes.");
-            return;
-        }
-        console.error("  No changes needing consent — advancing the version pin; clean template updates apply automatically.");
-        await apply({});
-        return;
-    }
-    for (const entry of preview.entries) {
-        console.error(`  ${formatKnowledgeEntryLine(entry)}`);
-    }
-    for (const entry of preview.templates) {
-        console.error(`  [template] ${entry.alias} (modified — needs consent)`);
-    }
-    // ONE namespaced grammar — the flags pass to the server verbatim. `--bind-to`
-    // is sugar for `knowledge.<alias>={bind_to}`; `--apply-all` fills the
-    // remaining consent entries with the accept verb (template → revert).
-    const resolutions = parseResolveFlags(args.resolve);
-    for (const [alias, id] of Object.entries(args.bind_to)) {
-        resolutions[`knowledge.${alias}`] = { bind_to: id };
-    }
-    if (args.applyAll) {
-        for (const entry of preview.entries) {
-            if (knowledgeEntryNeedsConsent(entry) && resolutions[`knowledge.${entry.alias}`] === undefined) {
-                resolutions[`knowledge.${entry.alias}`] = knowledgeAcceptResolution(entry.change);
-            }
-        }
-        for (const entry of preview.templates) {
-            if (resolutions[`template.${entry.alias}`] === undefined) {
-                resolutions[`template.${entry.alias}`] = "revert";
-            }
-        }
-    }
-    const unresolvedKnowledge = preview.entries.filter((entry) => knowledgeEntryNeedsConsent(entry) && resolutions[`knowledge.${entry.alias}`] === undefined);
-    const unresolvedTemplates = preview.templates.filter((entry) => resolutions[`template.${entry.alias}`] === undefined);
-    if (unresolvedKnowledge.length > 0 || unresolvedTemplates.length > 0) {
-        console.error("  These need a resolution before upgrading (or pass --apply-all to accept the package's version for all):");
-        for (const entry of unresolvedKnowledge)
-            console.error(formatKnowledgeResolveHint(entry));
-        for (const entry of unresolvedTemplates)
-            console.error(formatTemplateResolveHint(entry));
-        process.exit(1);
-    }
-    await apply(resolutions);
-}
-/** Parse repeated `--bind-to alias=kdc_id` flags into an alias → doc-id consent map. */
-export function parseBindToFlags(bindTo) {
-    const map = {};
-    for (const entry of bindTo) {
-        const eq = entry.indexOf("=");
-        if (eq <= 0 || eq === entry.length - 1) {
-            throw new Error(`Invalid --bind-to "${entry}" — expected <alias>=<kdc_id>.`);
-        }
-        map[entry.slice(0, eq)] = entry.slice(eq + 1);
-    }
-    return map;
-}
-/** Print advisory `knowledge_expects` misses loudly (never blocks the install). */
-function warnMissingExpectedDocs(missing) {
-    if (missing.length === 0)
-        return;
-    console.error(`  ⚠ ${missing.length} expected knowledge doc(s) the package's agents route to are missing from this workspace:`);
-    for (const name of missing)
-        console.error(`      - "${name}"`);
-    console.error("    The package installed, but those agents will degrade until a doc with each name exists.");
-}
-export async function packageInstall(client, args) {
-    // Surface the trust badge at the consent point: installing materializes the
-    // package's workflows/agents (or its doc corpus) under YOUR authority.
-    const pkg = await client.getPackage(args.package_id);
-    // The kind hint only earns a mention when it adds information (content —
-    // no app materializes); "(package)" after "third-party package" is noise.
-    const kindSuffix = pkg.kind === "content" ? " (content — docs/templates, no app)" : "";
-    console.error(`Installing ${pkg.name} — ${trustBadge(pkg)}${kindSuffix}...`);
-    const result = await client.installPackage(args.package_id, {
-        ...(args.version !== undefined ? { version: args.version } : {}),
-        ...(args.bind_to && Object.keys(args.bind_to).length > 0 ? { bind_to: args.bind_to } : {}),
-        ...(args.config && Object.keys(args.config).length > 0 ? { config: args.config } : {}),
-    });
-    if (result.kind === "content") {
-        const { installation, warnings } = result;
-        const docs = installation.binding.knowledge;
-        const templates = installation.binding.templates;
-        console.error(`Installed ${pkg.name} v${installation.package_version} (workspace ${installation.workspace_id}).`);
-        const docAliases = Object.keys(docs);
-        if (docAliases.length > 0) {
-            console.error(`  ${docAliases.length} doc(s) live: ${docAliases.map((a) => `${a}→${docs[a]}`).join(", ")}`);
-        }
-        const templateAliases = Object.keys(templates);
-        if (templateAliases.length > 0) {
-            console.error(`  ${templateAliases.length} template(s) live: ${templateAliases.map((a) => `${a}→${templates[a]}`).join(", ")}`);
-        }
-        warnMissingExpectedDocs(warnings.missing_expected_docs);
-        console.error(`  Upgrade later:  lotics upgrade ${args.package_id}`);
-        console.error(`  Uninstall:      lotics uninstall ${args.package_id} [--keep-content]`);
-        return;
-    }
-    const { app, knowledge_warnings } = result;
-    const versionLabel = app.package_version !== null ? `v${app.package_version}` : "(unknown version)";
-    console.error(`Installed ${app.name} ${versionLabel} → ${app.id} (workspace ${app.workspace_id}).`);
-    console.error("  The data model, queries, workflows, and agents are live.");
-    warnMissingExpectedDocs(knowledge_warnings.missing_expected_docs);
-    // Follow-up ops key on the NEW installation id (app_), not the package id typed
-    // at `install` — signpost each one with the id inlined (the content branch above
-    // does the same), so the id switch is never a silent trap.
-    console.error(`  Pull it for local editing:  lotics app pull ${app.id}`);
-    console.error(`  Upgrade later:              lotics upgrade ${app.id}`);
-    console.error(`  Health / uninstall:         lotics package doctor ${app.id}  ·  lotics uninstall ${app.id} [--archive-tables]`);
-}
-/**
- * `lotics uninstall <app_id|package_id>` — ONE top-level command over both
- * installation kinds, dispatched by the id form (mirrors `lotics upgrade`):
- *   - a package id (`apg_`) → THIS workspace's STANDALONE CONTENT installation
- *     (content installs are addressed by package id, UNIQUE per workspace, so the
- *     `pci_` resource id never surfaces): deletes the row and (unless
- *     `--keep-content`) archives its package-bound docs AND templates, listing each
- *     archived id.
- *   - anything else (an `app_id`) → an APP installation: archives its workflow
- *     artifacts and — with `--archive-tables` — the scaffolded entity tables
- *     (provenance- + reference-gated server-side).
- * A flag used on the wrong path is a loud error, never silently ignored.
- */
-export async function packageUninstall(client, args) {
-    if (args.id.startsWith("apg_")) {
-        if (args.archive_tables) {
-            throw new Error("--archive-tables applies only to an app installation (<app_id>). A content package " +
-                "has no scaffolded tables — use --keep-content to retain its docs/templates.");
-        }
-        const pkg = await client.getPackage(args.id);
-        // kind is a DERIVED display hint (contractHasAppSurface): 'content' = no app.
-        if (pkg.kind !== "content") {
-            throw new Error(`Package ${args.id} is an app package — uninstall an app installation by its app id:  lotics uninstall <app_id>.`);
-        }
-        const installation = await resolveWorkspaceContentInstallation(client, args.id);
-        const result = await client.uninstallContentPackage(installation.id, {
-            keep_content: args.keep_content,
-        });
-        if (args.keep_content) {
-            console.error(`Uninstalled ${pkg.name} (${pkg.id}) — its docs and templates were kept as ordinary workspace content.`);
-        }
-        else {
-            console.error(`Uninstalled ${pkg.name} (${pkg.id}) — archived ` +
-                `${result.archived_doc_ids.length} doc(s) and ${result.archived_template_ids.length} template(s).`);
-            for (const docId of result.archived_doc_ids)
-                console.error(`    ${docId}`);
-            for (const templateId of result.archived_template_ids)
-                console.error(`    ${templateId}`);
-        }
-        return;
-    }
-    if (args.keep_content) {
-        throw new Error("--keep-content applies only to a content package (apg_). An app installation " +
-            "(<app_id>) uses --archive-tables to also archive its scaffolded tables.");
-    }
-    const app = await client.getApp(args.id);
-    if (!app.package_id) {
-        throw new Error(`App ${args.id} is not a package installation — use the app delete flow for a bespoke app.`);
-    }
-    const lifecycleCount = Object.keys(app.binding?.workflows ?? {}).length;
-    const boundCount = Object.keys(app.workflows ?? {}).length;
-    const tableCount = Object.keys(app.binding?.entities ?? {}).length;
-    console.error(`Uninstalling ${app.name} (${app.id}):`);
-    console.error(`  Archives ${boundCount + lifecycleCount} workflow(s) (${boundCount} app, ${lifecycleCount} lifecycle).`);
-    console.error(args.archive_tables
-        ? `  Archives ${tableCount} scaffolded table(s) — refused if they were adopted or are still referenced.`
-        : `  Leaves the data model (${tableCount} table(s)) intact. Pass --archive-tables to also archive them.`);
-    const result = await client.uninstallAppPackage(args.id, {
-        archive_tables: args.archive_tables,
-    });
-    console.error(`Uninstalled ${app.name} (${app.id}).`);
-    if (result.archived_table_ids.length > 0) {
-        console.error(`  Archived tables: ${result.archived_table_ids.join(", ")}`);
-    }
-}
-/**
- * `lotics package list-content` — list the selected workspace's STANDALONE
- * content installations (an app-bundled corpus rides its app's
- * `binding.knowledge` and shows on the Apps surface instead), each with its
- * registry status. The what-is-installed listing: each row leads with the PACKAGE
- * id — the address for `lotics upgrade <package_id>` / `lotics uninstall
- * <package_id>` (the `pci_` resource id stays hidden).
- */
-export async function packageListContent(client) {
-    const workspaceId = client.getWorkspaceId();
-    if (!workspaceId) {
-        throw new Error("No workspace selected. Pass --workspace <ws> (or select one) to list its content installations.");
-    }
-    const installations = await client.listContentInstallations(workspaceId);
-    if (installations.length === 0) {
-        console.error(`No package-managed content installations in workspace ${workspaceId}.`);
-        return;
-    }
-    console.error(`Content installations in workspace ${workspaceId} (${installations.length}):`);
-    for (const inst of installations) {
-        const name = inst.package_registry?.name ?? "(unknown package)";
-        const latest = inst.package_registry?.latest_version;
-        const updateAvailable = inst.package_registry?.update_available ?? false;
-        const versionLabel = latest !== undefined && latest !== inst.package_version
-            ? `v${inst.package_version} → latest v${latest}`
-            : `v${inst.package_version}`;
-        console.error(`  ${inst.package_id}  ${name}  ${versionLabel}` +
-            (updateAvailable ? "  → update available" : ""));
-    }
-}
-export async function packageEject(client, args) {
-    const app = await client.ejectPackage(args.app_id);
-    console.error(`Ejected ${app.name} → ${app.id} (workspace ${app.workspace_id}).`);
-    console.error("  The package link is severed — it's now a normal bespoke app and can no longer be upgraded.");
-    console.error("  Its data model, queries, workflows, and templates are unchanged.");
-    console.error("  Pull the pinned source for local editing:  lotics app pull " + app.id);
-}
-/**
- * Parse one `key=value` config assignment. When the knob's type is known (from
- * the stored value at `package config --set`) the value is parsed to that type
- * loudly; otherwise (`lotics install --config`) it is inferred (true/false →
- * boolean, numeric → number, else string) and the server validates it against
- * the contract.
- */
-function parseConfigAssignment(entry, flag, knownType) {
-    const eq = entry.indexOf("=");
-    if (eq <= 0 || eq === entry.length - 1) {
-        throw new Error(`Invalid ${flag} "${entry}" — expected key=value.`);
-    }
-    const key = entry.slice(0, eq);
-    const raw = entry.slice(eq + 1);
-    if (knownType === "number") {
-        const n = Number(raw);
-        if (!Number.isFinite(n))
-            throw new Error(`Config key "${key}" is a number knob — "${raw}" is not numeric.`);
-        return { key, value: n };
-    }
-    if (knownType === "boolean") {
-        if (raw !== "true" && raw !== "false") {
-            throw new Error(`Config key "${key}" is a boolean knob — expected true or false, got "${raw}".`);
-        }
-        return { key, value: raw === "true" };
-    }
-    if (knownType === "string")
-        return { key, value: raw };
-    // Inferred (install override): the server re-validates against the contract.
-    if (raw === "true" || raw === "false")
-        return { key, value: raw === "true" };
-    if (/^-?\d+(\.\d+)?$/.test(raw))
-        return { key, value: Number(raw) };
-    return { key, value: raw };
-}
-/** `--config key=value` (install): inferred types, server-validated. */
-export function parseInstallConfigFlags(config) {
-    const out = {};
-    for (const entry of config) {
-        const { key, value } = parseConfigAssignment(entry, "--config");
-        out[key] = value;
-    }
-    return out;
-}
-/**
- * `lotics package config <app_id>` — show the installation's effective config;
- * with `--set key=value` (repeatable) partial-merge edits, each value parsed by
- * the knob's current type. No `--set` prints the values.
- */
-export async function packageConfig(client, args) {
-    const app = await client.getApp(args.app_id);
-    if (!app.package_id) {
-        throw new Error(`App ${args.app_id} is not a package installation — it has no config.`);
-    }
-    const current = app.config ?? {};
-    if (args.sets.length === 0) {
-        const keys = Object.keys(current).sort();
-        if (keys.length === 0) {
-            console.error(`${app.name} (${app.id}) — no config knobs.`);
-            return;
-        }
-        console.error(`${app.name} (${app.id}) config:`);
-        for (const key of keys)
-            console.log(`  ${key} = ${JSON.stringify(current[key])}`);
-        return;
-    }
-    const overrides = {};
-    for (const entry of args.sets) {
-        const key = entry.slice(0, Math.max(0, entry.indexOf("=")));
-        const knownType = typeof current[key];
-        const { value } = parseConfigAssignment(entry, "--set", knownType === "number" || knownType === "boolean" || knownType === "string" ? knownType : undefined);
-        overrides[key] = value;
-    }
-    const { config } = await client.updateAppPackageConfig(args.app_id, { config: overrides });
-    console.error(`Updated config for ${app.name} (${app.id}):`);
-    for (const key of Object.keys(config).sort()) {
-        const marker = key in overrides ? " *" : "";
-        console.log(`  ${key} = ${JSON.stringify(config[key])}${marker}`);
-    }
-}
-/**
- * `lotics app unpublish <app_id|package_id> [--undo]` — take a published package
- * off the shelf (or `--undo` restore it): new installs refuse it and it hides
- * from other orgs, while existing installations keep working and may still
- * upgrade. Given an app id (an installation of the package) it resolves the
- * package from the app; a package id targets it directly. Owner-org admin-only.
- */
-export async function appUnpublish(client, args) {
-    let packageId = args.id;
-    if (args.id.startsWith("app_")) {
-        const app = await client.getApp(args.id);
-        if (!app.package_id) {
-            throw new Error(`App ${args.id} is not a package installation — it has no package to unpublish. ` +
-                `Pass the package id directly.`);
-        }
-        packageId = app.package_id;
-    }
-    const pkg = await client.retirePackage(packageId, { undo: args.undo });
-    if (pkg.retired_at !== null) {
-        console.error(`Unpublished ${pkg.name} (${pkg.id}). New installs refuse it and it is hidden from other orgs; ` +
-            `existing installations keep working and may still upgrade. Undo: lotics app unpublish ${pkg.id} --undo`);
-    }
-    else {
-        console.error(`Re-published ${pkg.name} (${pkg.id}) — installable again.`);
-    }
-}
-/**
- * `lotics app publish [app_id|.] [--rename old=new ...] [-m <changelog>] [--yes]` —
- * FIRST-RELEASE a bespoke app as a package (docs/packages.md § Promotion). Nothing
- * starts as a package. Mirrors `app release`'s preview→apply UX: it first shows the
- * dry-run preview (GET, no writes) — the package name, the auto-minted RENAMABLE
- * aliases (the exact `--rename` keys, so v1's frozen aliases are inspected first,
- * never a blind publish), and the extract findings — then APPLIES only with
- * `--yes` (else exits 1 with the re-run hint). On apply the server extracts the
- * contract, creates the registry package, publishes v1 from the DEPLOYED source +
- * dist, and pins the origin as installation #1. `--rename old=new` fixes an
- * auto-minted alias before v1 freezes it; an `error` finding blocks the apply. An
- * already-linked app releases with `lotics app release` instead. The app id is the
- * positional (`.`/omitted → resolved from the local app project manifest).
- */
-export async function appPublish(client, args) {
-    const projectDir = path.resolve(args.projectDir ?? process.cwd());
-    const local = readLocalAppManifest(projectDir);
-    const explicit = args.app_id !== undefined && args.app_id !== "." ? args.app_id : undefined;
-    const appId = explicit ?? local?.app_id ?? null;
-    if (appId === null) {
-        throw new Error("No app id. Run `lotics app publish` from a pulled app project (lotics app pull <app_id>), " +
-            "or pass one: lotics app publish <app_id>.");
-    }
-    // Forward the app's package-managed knowledge + config declarations ONLY when the
-    // local manifest is this app's own project (both are declarations extract can't
-    // invert, so the author declares them). A bare id published from elsewhere ships
-    // without them — publish from the app dir to include them.
-    const knowledge = local && local.app_id === appId ? local.knowledge : [];
-    const config = local && local.app_id === appId ? local.config : [];
-    const renames = parseRenameFlags(args.renames);
-    // Preview first (GET, no writes) — the same preview→--yes flow as `app release`,
-    // so the aliases v1 freezes forever are never a blind publish and `--rename`
-    // targets are inspectable before committing.
-    const preview = await client.previewPublishAppPackage(appId, { renames, knowledge, config });
-    const { lines, hasError } = formatExtractReport(preview.findings);
-    console.error(`Publish preview — ${appId} as new package "${preview.package_name}" (v1):`);
-    const groups = [
-        ["entities", preview.renamable_aliases.entities],
-        ["fields", preview.renamable_aliases.fields],
-        ["options", preview.renamable_aliases.options],
-        ["roles", preview.renamable_aliases.roles],
-        ["templates", preview.renamable_aliases.templates],
-        ["workflows", preview.renamable_aliases.workflows],
-    ];
-    if (groups.some(([, vals]) => vals.length > 0)) {
-        console.error("  Auto-minted aliases — rename any with --rename <alias>=<new> before v1 freezes them:");
-        for (const [label, vals] of groups) {
-            if (vals.length > 0)
-                console.error(`    ${`${label}:`.padEnd(11)} ${vals.join(", ")}`);
-        }
-        console.error("  (query / app-workflow / agent runtime aliases are fixed — the shipped source calls them verbatim.)");
-    }
-    else {
-        console.error("  No renamable aliases.");
-    }
-    if (config.length > 0) {
-        console.error(`  Config knobs (${config.length}): ${config.map((c) => `${c.alias} (${c.type})`).join(", ")}`);
-    }
-    if (lines.length > 0) {
-        console.error(`  Findings (${preview.findings.length}):`);
-        for (const line of lines)
-            console.error(line);
-    }
-    if (hasError) {
-        console.error("\nExtract found error findings — the app cannot be published as-is. Fix them in the app, redeploy, and retry.");
-        process.exitCode = 1;
-        return;
-    }
-    if (!args.yes) {
-        const idArg = explicit ?? ".";
-        const renameArgs = args.renames.map((r) => ` --rename ${r}`).join("");
-        const mArg = args.changelog ? ` -m ${JSON.stringify(args.changelog)}` : "";
-        console.error(`\nRe-run with --yes to publish v1:`);
-        console.error(`  lotics app publish ${idArg}${renameArgs}${mArg} --yes`);
-        process.exitCode = 1;
-        return;
-    }
-    const result = await client.publishAppAsPackage(appId, {
-        renames,
-        changelog: args.changelog ?? null,
-        knowledge,
-        config,
-    });
-    console.error(`Published ${result.package_id} v${result.version} from app ${appId}.`);
-    console.error(`  The app is now installation #1 — develop it in place, then release the next version:`);
-    console.error(`    lotics app pull ${appId}   # edit, then lotics app deploy`);
-    console.error(`    lotics app release ${appId} -m "<what changed>"`);
-    console.error(`  Install it elsewhere:  lotics install ${result.package_id}`);
-}
-/**
- * `lotics app release [app_id|.] -m <changelog> [--yes]` — snapshot an
- * adopted/installed origin app into its next registry version (docs/packages.md
- * § Promotion). The origin is the permanent working copy; a release binding-aware-
- * extracts it (stable aliases), repackages its DEPLOYED source + dist as the
- * bundle, publishes the next version, and re-pins the origin. Prints the preview
- * first (next version, new + changed aliases, the bundled-knowledge delta,
- * findings); applies only with `--yes`, else exits 1 so a review step can't be
- * skipped. An `error` finding blocks the apply.
- *
- * Run from the pulled app project, the manifest's `lotics.knowledge` (alias →
- * doc_id) is the bundle DECLARATION — it re-declares which docs the package owns
- * (add/drop/re-snapshot). Forwarded only when non-empty; empty (or a bare id from
- * elsewhere) sends nothing, so the current corpus is reconstructed from the pin
- * (never silently dropped).
- */
-export async function appRelease(client, args) {
-    const projectDir = path.resolve(args.projectDir ?? process.cwd());
-    const local = readLocalAppManifest(projectDir);
-    const explicit = args.app_id !== undefined && args.app_id !== "." ? args.app_id : undefined;
-    const appId = explicit ?? local?.app_id ?? null;
-    if (appId === null) {
-        throw new Error("No app id. Run this from a pulled app project (lotics app pull <app_id>), or pass an app id explicitly.");
-    }
-    // Forward the manifest's knowledge + config DECLARATIONS only from this app's own
-    // project AND only when non-empty — an empty/absent declaration is "no change"
-    // (reconstruct knowledge from the pin / carry config forward), never "drop them".
-    const knowledge = local && local.app_id === appId && local.knowledge.length > 0 ? local.knowledge : undefined;
-    const config = local && local.app_id === appId && local.config.length > 0 ? local.config : undefined;
-    const preview = await client.previewPackageRelease(appId, { knowledge, config });
-    const { lines, hasError } = formatExtractReport(preview.findings);
-    console.error(`Release preview — ${appId} → ${preview.package_id} v${preview.version}:`);
-    if (preview.added_aliases.length > 0) {
-        console.error(`  New (${preview.added_aliases.length}): ${preview.added_aliases.join(", ")}`);
-    }
-    if (preview.changed_artifacts.length > 0) {
-        console.error(`  Changed (${preview.changed_artifacts.length}): ${preview.changed_artifacts.join(", ")}`);
-    }
-    // Deploy-skew boundary: a pre-declaration server omits the echo field. Silent
-    // skew is dangerous exactly when a declaration was SENT — the server ignored it
-    // and the preview would misread as "no changes"; say so loudly, per surface.
-    if (preview.knowledge === undefined && knowledge !== undefined) {
-        console.error("  WARNING: the server ignored the knowledge declaration (it predates bundled-knowledge releases) — the bundle will NOT change. Retry after the platform deploy completes.");
-    }
-    if (preview.config === undefined && config !== undefined) {
-        console.error("  WARNING: the server ignored the config declaration (it predates manifest config declarations) — the knobs will NOT change. Retry after the platform deploy completes.");
-    }
-    const k = preview.knowledge ?? { added: [], removed: [], changed: [] };
-    if (k.added.length > 0 || k.removed.length > 0 || k.changed.length > 0) {
-        const parts = [
-            k.added.length > 0 ? `+${k.added.join(", ")}` : null,
-            k.removed.length > 0 ? `dropped ${k.removed.join(", ")}` : null,
-            k.changed.length > 0 ? `changed ${k.changed.join(", ")}` : null,
-        ].filter((p) => p !== null);
-        console.error(`  Knowledge: ${parts.join("; ")}`);
-    }
-    const cfg = preview.config ?? { added: [], removed: [], changed: [] };
-    if (cfg.added.length > 0 || cfg.removed.length > 0 || cfg.changed.length > 0) {
-        const parts = [
-            cfg.added.length > 0 ? `+${cfg.added.join(", ")}` : null,
-            cfg.removed.length > 0 ? `dropped ${cfg.removed.join(", ")}` : null,
-            cfg.changed.length > 0 ? `changed ${cfg.changed.join(", ")}` : null,
-        ].filter((p) => p !== null);
-        console.error(`  Config: ${parts.join("; ")}`);
-    }
-    if (preview.added_aliases.length === 0 &&
-        preview.changed_artifacts.length === 0 &&
-        k.added.length === 0 &&
-        k.removed.length === 0 &&
-        k.changed.length === 0 &&
-        cfg.added.length === 0 &&
-        cfg.removed.length === 0 &&
-        cfg.changed.length === 0) {
-        console.error("  No contract changes since the current version (a fresh code/dist snapshot still ships).");
-    }
-    if (lines.length > 0) {
-        console.error(`  Findings (${preview.findings.length}):`);
-        for (const line of lines)
-            console.error(line);
-    }
-    if (hasError) {
-        console.error("\nExtract found error findings — the origin cannot be released as-is. Fix them in the app and retry.");
-        process.exitCode = 1;
-        return;
-    }
-    if (!args.yes) {
-        console.error(`\nRe-run with --yes to publish v${preview.version}:`);
-        console.error(`  lotics app release ${args.app_id ?? "."} -m ${JSON.stringify(args.changelog)} --yes`);
-        process.exitCode = 1;
-        return;
-    }
-    const result = await client.releasePackage(appId, { changelog: args.changelog, knowledge, config });
-    console.error(`Released ${result.package_id} v${result.version}.`);
-    console.error(`  The origin was re-pinned to v${result.version} — verify:  lotics package doctor ${appId}`);
-}
-/**
- * `lotics package yank <package_id> <version> [--undo]` — mark a published
- * version uninstallable (or restore it). New installs/upgrades/adopts refuse a
- * yanked version and "latest" skips it; installations already pinned keep
- * running. Owner-org admin-only.
- */
-export async function packageYank(client, args) {
-    const result = await client.yankPackageVersion(args.package_id, args.version, !args.undo);
-    if (result.yanked_at !== null) {
-        console.error(`Yanked ${result.package_id} v${result.version} (${result.yanked_at}). ` +
-            `New installs/upgrades refuse it; pinned installations keep running.`);
-    }
-    else {
-        console.error(`Restored ${result.package_id} v${result.version} — installable again.`);
-    }
-    console.error(`  Latest installable version: ${result.latest_version === 0 ? "none" : `v${result.latest_version}`}`);
-}
-/**
- * `lotics upgrade <package_id> [--version N]` (fleet path) — bring every
- * installation of the package across the caller's org to the target version.
- * Hands-off applies only where the preview is clean; skipped/failed
- * installations are reported per line and the process exits 1 so a release
- * script can gate on "fleet fully current".
- */
-async function packageFleetUpgrade(client, args) {
-    const result = await client.fleetUpgradePackage(args.package_id, {
-        ...(args.version !== undefined ? { version: args.version } : {}),
-    });
-    console.error(`Fleet upgrade of ${result.package_id} → v${result.target_version}:`);
-    if (result.installations.length === 0) {
-        console.error("  No installations of this package in your organization.");
-        return;
-    }
-    const counts = { upgraded: 0, up_to_date: 0, skipped: 0, failed: 0 };
-    for (const inst of result.installations) {
-        counts[inst.outcome]++;
-        const from = inst.from_version === null ? "?" : `v${inst.from_version}`;
-        const line = `  [${inst.outcome}] ${inst.workspace_name} — ${inst.app_name} (${from} → v${result.target_version})`;
-        if (inst.outcome === "skipped" && inst.blockers) {
-            console.error(`${line}: breaking=${inst.blockers.breaking} drift=${inst.blockers.drift} modified=${inst.blockers.modified} knowledge=${inst.blockers.knowledge}`);
-            console.error(`      resolve via:  lotics upgrade ${inst.app_id} --version ${result.target_version} ...`);
-        }
-        else if (inst.message) {
-            console.error(`${line}: ${inst.message}`);
-        }
-        else {
-            console.error(line);
-        }
-    }
-    console.error(`Done: ${counts.upgraded} upgraded, ${counts.up_to_date} already current, ${counts.skipped} skipped, ${counts.failed} failed.`);
-    if (counts.skipped > 0 || counts.failed > 0) {
-        process.exitCode = 1;
-    }
-}