@inventarch/cli 0.0.0-stage → 1.0.0

package/dist/distribute.d.ts

@@ -0,0 +1,163 @@
+import type { Dependency, DistributionLock } from '@inventarch/db/distribution';
+import type { InstallationPlan } from '@inventarch/distribution/install';
+import type { RegistryChoice, RegistryLevel } from '@inventarch/distribution/registry';
+import type { Context, Host, Result } from './consumer.js';
+import type { HostName } from './host-projection.js';
+import type { Capabilities } from './render.js';
+export type Operation = 'install' | 'update' | 'remove' | 'restore';
+/** §2.8: the id grammar is `provider/name`, and a positional may pin it with `@<range>`. */
+export declare const REQUEST: RegExp;
+/** A positional with no range asks for whatever the source offers; nothing in the tree supplies another default. */
+export declare const ANY_VERSION = "*";
+export interface Applied {
+    readonly status: string;
+    readonly generation: string;
+    readonly counter: number;
+    readonly host: string;
+}
+export interface ChangeRow {
+    readonly kind: 'added' | 'removed' | 'updated' | 'shadowed';
+    readonly id: string;
+    readonly version: string;
+    readonly archive: string | null;
+    readonly origin: string;
+}
+/**
+ * Registry spec §6.1: the registry that answered for one provider — its HTTPS URL or absolute directory — and the §4
+ * level that chose it (`flag`, `env`, `workspace`, `user` or `default`).
+ */
+export interface RegistrySource {
+    readonly provider: string;
+    readonly base: string;
+    readonly level: RegistryLevel;
+}
+export interface PlanView {
+    readonly operation: Operation;
+    readonly root: string;
+    readonly plan: InstallationPlan;
+    readonly rows: readonly ChangeRow[];
+    readonly applied: Applied | null;
+    /** Accepted withdrawn releases: bare ids from a catalog restore, `id@version` pins from a registry restore. */
+    readonly withdrawn: readonly string[];
+    /** The registries this command read, one per provider, sorted; empty when a catalog or the cache was the source. */
+    readonly registries: readonly RegistrySource[];
+    /** The exact command that would apply this plan; §7.6's `\` breaks are chosen here, not by the wrapper. */
+    readonly invocation: string;
+    readonly planOut: string | null;
+    /** Hosts whose projection this workspace owns; `applyPlan` refreshes each after the install commits. */
+    readonly refresh: readonly HostName[];
+    /** Whether `--root` was given, so every `ia host` command printed carries it (`rootedNext`). */
+    readonly rooted: boolean;
+}
+/** §2.8's join. `changes` carries ids; every other column is looked up, and an absent value is never invented. */
+export declare function changeRows(plan: InstallationPlan, previous: DistributionLock | undefined): readonly ChangeRow[];
+/**
+ * Acquisition is the only phase that can reach class 4, so it is the only phase wrapped. A DistributionError keeps
+ * its own code (§4.1). The service reports a transport failure — DNS, TLS, or its own 30-second timeout — as
+ * IA-DIST-ARTIFACT-UNAVAILABLE naming the URL (registry spec §6.4); anything that still arrives without an IA code
+ * is reported as a CLI failure at class 4 rather than relabelled with a service code the service never raised.
+ *
+ * The next action depends on the route the failure arrived on, because the repair does. On the catalog route the
+ * archive remedy applies: retry, or name the archive in a local catalog entry and resolve from that catalog offline.
+ * On the registry route — the default since registry discovery — a catalog-only remedy is wrong twice over: `--offline`
+ * without `--catalog` reads no catalog, and the failure is the registry's. Registry-route failures therefore name the
+ * registry sources, whether the failure was an index, `ia-registry.json` ("Registry request …") or an artifact fetched
+ * from an HTTPS registry ("Artifact request …"). The other registry failures each have their own remedy: the built-in
+ * default that is not available ("The default registry …"), a document over the 4 MiB bound ("Registry document …",
+ * a limit a retry cannot fix), and a directory registry that lists a release whose artifact file it lacks. All of
+ * these stay class 4: remote or registry content the user cannot fix in the workspace. Two registry refusals are
+ * class 3 and carry the remedy §4 and §7 name for them: an unmapped provider, and a request only a licensed release
+ * satisfies.
+ *
+ * Every other refusal passes through with its code and class, located at the file it names when the service located
+ * it (`.path`, e.g. `.ia/registries.json`), so §4.3's `where` is null only when there is genuinely no location.
+ */
+export type Route = 'catalog' | 'registry';
+/** Registry spec §4's remedy for an unmapped provider; `ia doctor` names the same one. */
+export declare const UNMAPPED = "Every requested and locked package's provider needs a registry. Map the provider to an HTTPS URL or a workspace directory in .ia/registries.json, or pass --registry <url|dir>.";
+export interface PlanRequest {
+    readonly signal?: AbortSignal | undefined;
+    readonly root: string;
+    readonly operation: Operation;
+    readonly ids: readonly string[];
+    readonly requestsFile: string | undefined;
+    readonly catalog: string | undefined;
+    readonly offline: boolean;
+    readonly to: string | undefined;
+    readonly allowWithdrawn: boolean;
+    readonly planOut: string | undefined;
+    readonly invocation: string;
+    /** Whether the invocation named `--root`; commands printed for a registered projection then carry it. */
+    readonly rooted?: boolean;
+    /** The registered projections, when the caller already found them; otherwise they are found here. */
+    readonly refresh?: readonly HostName[];
+    /**
+     * Registry spec §4: the command's one chooser (`registryChooser`), which reads the configuration once. It is needed
+     * only when registries are the source — `install` and `update` without `--catalog` or `--offline`, and `restore`
+     * online without `--catalog` — and the caller builds it from the host, because this function never reads the process.
+     */
+    readonly choose?: ((id: string) => RegistryChoice) | undefined;
+}
+/** §2.8: a positional adds or repins one direct request; `--requests` supplies the whole set the native path reads. */
+export declare function mergeRequests(previous: DistributionLock | undefined, ids: readonly string[]): readonly Dependency[];
+/**
+ * Host registration spec §4: the hosts whose projection this workspace owns. Ownership is the state file's presence,
+ * as `ia host` and `ia doctor` decide it. `restore` changes no admitted system, so it has none to refresh.
+ */
+export declare const registeredProjections: (root: string, operation: Operation) => readonly HostName[];
+/**
+ * Host registration spec §4: `--apply` refuses before any install write when a registered projection would refuse.
+ * A hand edit to an owned file is the refusal the refresh would raise (§6.3), so it is found here, before
+ * acquisition, the saved plan or the lock is touched; the remedy is the one `ia host` and `ia doctor` name for it.
+ * Missing, outdated and unowned files do not block: the refresh rewrites the first two and never touches the third.
+ * A file the mechanism cannot read — an unreadable ownership state, an aliased or oversized managed file — would
+ * refuse the refresh too, so it is refused here, located at that file, with the repair `ia host` names for it.
+ */
+export declare function requireProjectionsClean(root: string, hosts: readonly HostName[], rooted: boolean): void;
+export declare function collectPlan(request: PlanRequest): Promise<PlanView>;
+/**
+ * §2.8 rule 2's second half, separated from the first so rule 3's question can sit between them. `collectPlan`
+ * never writes installation state; this is the only call in the consumer that does, and `applyInstallation`
+ * re-runs the installer's own staleness check before it writes anything. Host registration spec §4 then refreshes
+ * each registered projection; that writes only the projection's own files and state, never installation state. A
+ * refused refresh is class 3 naming the first refusal, and the count when more than one host refused (file comment).
+ */
+export declare function applyPlan(view: PlanView): PlanView;
+/**
+ * The `--json` envelope (§2.8): `{version: 1, command, plan, applied?, refresh?, registries?, withdrawn?, planOut?}`.
+ *
+ * - `plan` is the planner's own value, unchanged.
+ * - `registries` (registry spec §6.1) is present only when registries were the source: one `{provider, base, level}`
+ *   per provider, sorted by provider, then base. `base` is the HTTPS URL or the absolute directory; `level` is the §4
+ *   level that chose it, `flag`, `env`, `workspace`, `user` or `default`. For `restore` it names the registries asked
+ *   whether a locked release was withdrawn. A package's registry is the entry for its provider.
+ * - `withdrawn` lists the withdrawn releases `--allow-withdrawn` accepted, and its entries differ by source: a catalog
+ *   restore names bare package ids, as it always has; a registry restore names `id@version` pins (§6.3).
+ */
+export declare function planEnvelope(view: PlanView): unknown;
+export declare function renderPlan(view: PlanView, caps: Capabilities): string;
+/** §2.8 rule 3's one question, asked once and only where an answer can arrive. */
+export declare const CONFIRMATION = "Apply these changes? [y/N] ";
+/**
+ * The change summary rule 3 requires the question to show: what the preview shows about what would change, without
+ * the preview's "nothing has been written" note or its next-action footer, because the question *is* the action.
+ * It is the same blocks the preview builds, so a column the preview prints and this one does not cannot exist.
+ */
+export declare const renderSummary: (view: PlanView, caps: Capabilities) => string;
+/**
+ * A declined question is an answer, not a failure: §2.8 rule 3 asked, the user said no, and the command reports
+ * that and exits 0. The summary was on stderr, so what stdout carries is the outcome and the way to get the other
+ * one. `--plan-out` was already written, because a declined apply is exactly the plan-only run rule 1 describes.
+ */
+export declare const renderDeclined: (view: PlanView, caps: Capabilities) => string;
+/**
+ * Registry spec §4: the one chooser a command builds, from the host rather than the process, so every verb that
+ * reports or uses registry routing (`install`, `update`, `restore`, `doctor`) picks the same base for an id. A
+ * relative `--registry` or `IA_REGISTRY` directory is the caller's (`host.cwd`), and the user file is found from the
+ * host's environment: `IA_CONFIG_HOME`, else the per-OS directory under the home `os.homedir()` would use —
+ * `USERPROFILE` on Windows, `HOME` elsewhere — and, when that variable is unset, `os.homedir()` itself. Construction
+ * reads nothing: the configuration is read on first use, once per command.
+ */
+export declare function hostRegistryChooser(host: Pick<Host, 'env' | 'cwd'>, root: string, flag?: string): (id: string) => RegistryChoice;
+export declare function runDistribute(operation: Operation): (context: Context) => Promise<Result>;
+//# sourceMappingURL=distribute.d.ts.map

package/dist/distribute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"distribute.d.ts","sourceRoot":"","sources":["../src/distribute.ts"],"names":[],"mappings":"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"}