@lotics/cli 0.70.0 → 0.73.0

package/dist/package_commands.d.ts

@@ -0,0 +1,227 @@
+import { LoticsClient, type PackageBinding, type ExtractFinding } from "./client.js";
+/** One dev workspace's pinned installation of this package (manifest bookkeeping). */
+interface PackageDevInstallation {
+    app_id: string;
+    version: number;
+}
+/**
+ * The `package.json#lotics.package` block of a package project. `id` is null
+ * until the first publish (which creates the registry package); `version` tracks
+ * the latest version this project has published; `dev` maps a dev workspace id to
+ * the installation it scaffold-syncs into.
+ */
+interface PackageManifest {
+    id: string | null;
+    name: string;
+    description: string | null;
+    version: number | null;
+    dev: Record<string, PackageDevInstallation>;
+}
+interface PackageProjectFile {
+    /** Parsed package.json, carrying the `lotics.package` manifest under `lotics`. */
+    pkgJson: Record<string, unknown>;
+    manifest: PackageManifest;
+}
+/** Read the package project's manifest, failing loud when the dir isn't one. */
+export declare function readPackageProject(projectDir: string): PackageProjectFile;
+/** Persist an updated manifest back into the project's package.json (atomic write). */
+export declare function writePackageManifest(projectDir: string, project: PackageProjectFile): void;
+/**
+ * The package.json to ship INSIDE `source.tar.gz`: the on-disk manifest with the
+ * author-local `lotics.package.dev` map stripped. `dev` is the author's private
+ * dev-workspace → installation bookkeeping; it must never reach a consumer (every
+ * install carries the source, and `lotics app pull` ejects it). Returns a
+ * sanitized copy — the on-disk package.json is left untouched. `id`/`name`/
+ * `description`/`version` are the package's stable identity and stay.
+ */
+export declare function sanitizePackageJsonForSource(pkgJson: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Transform an app project's package.json (the source archive `lotics app pull`
+ * downloads, carrying the `lotics.app_id`/`workspace_id` app manifest) into a
+ * package project's `PackageProjectFile`: the app manifest is stripped ENTIRELY
+ * and a fresh, unpublished `lotics.package` manifest (id/version null) is
+ * grafted. Pure — returns a new value, never mutates the input;
+ * `writePackageManifest` writes it (atomic). The bespoke→package promotion's
+ * manifest inversion.
+ */
+export declare function draftPackageProjectFromApp(appPkgJson: Record<string, unknown>, args: {
+    name: string;
+    description: string | null;
+}): PackageProjectFile;
+/**
+ * Parse + validate `.lotics/adopt_binding.json` against the app being adopted.
+ * REFUSES a pin recorded for a different app: a binding maps ONE workspace's
+ * concrete ids, so replaying it onto another app would bind the wrong objects.
+ * Pure; the CLI never interprets the binding, only round-trips it to the server.
+ */
+export declare function parseAdoptBindingFile(raw: unknown, expectedAppId: string): {
+    app_id: string;
+    workspace_id: string;
+    binding: PackageBinding;
+};
+/**
+ * Render an extraction report grouped by severity (errors, then warnings, then
+ * info), one `  [<severity>] <area>: <message>` line each, and classify whether
+ * any `error` finding is present. An `error` ⇒ the draft is not publishable
+ * as-is, so `lotics package extract` exits non-zero. Pure — the command prints
+ * `lines` to stderr and gates on `hasError`.
+ */
+export declare function formatExtractReport(report: ExtractFinding[]): {
+    lines: string[];
+    hasError: boolean;
+};
+/**
+ * Copy the project's source tree into `sourceStage` with explicit TOP-LEVEL
+ * excludes, writing a sanitized `package.json` in place of the on-disk one.
+ * Deliberately not tar `--exclude` flags: those match at any depth (a nested
+ * `templates/dist/` would be silently dropped) and GNU tar vs bsdtar (macOS)
+ * disagree on `./`-prefixed patterns, which broke the sanitized-package.json
+ * graft on macOS.
+ */
+export declare function stagePackageSource(projectDir: string, sourceStage: string): void;
+/** The minimal, valid starting contract a `package new` scaffold ships. */
+export declare function starterContract(name: string): Record<string, unknown>;
+/**
+ * `lotics package new <name> [path]` — scaffold a package project. Reuses the
+ * app starter (Vite+React+TS) for the code surface, swaps its app manifest for a
+ * package manifest, and adds a starter `contract.json`. The project publishes
+ * with `lotics package publish` and runs against a dev workspace with
+ * `lotics package dev`.
+ */
+export declare function packageNew(args: {
+    name: string;
+    targetPath?: string;
+}): Promise<void>;
+/**
+ * `lotics package build [path]` — build the publishable bundle and write it to
+ * `bundle.tar.gz` in the project. Mostly a local sanity check / CI artifact;
+ * `publish` and `dev`/`sync` build the bundle in memory directly.
+ */
+export declare function packageBuild(args: {
+    projectDir?: string;
+}): Promise<void>;
+/**
+ * `lotics package publish [path] [-m <changelog>]` — publish a new version.
+ */
+export declare function packagePublish(client: LoticsClient, args: {
+    projectDir?: string;
+    changelog?: string;
+}): Promise<void>;
+/**
+ * Fail loud unless `workspace` is a throwaway dev workspace. The dev/sync
+ * scaffold path publishes a new version and scaffold-installs package tables into
+ * the resolved workspace, so the target MUST be a dev workspace — this mirrors
+ * the server-side `package reset` gate so a forgotten `--workspace` (prod
+ * selected) can never scaffold package tables into prod. Fails closed: an absent
+ * `is_dev` (a server that doesn't yet serialize it) is treated as non-dev.
+ */
+export declare function assertDevWorkspace(workspace: {
+    id: string;
+    name: string;
+    is_dev?: boolean;
+}): void;
+/**
+ * `lotics package sync [path]` — re-run the scaffold-sync into the dev workspace
+ * (the continuous loop: edit contract → sync additively migrates + re-materializes).
+ */
+export declare function packageSync(client: LoticsClient, args: {
+    projectDir?: string;
+}): Promise<void>;
+/**
+ * `lotics package dev [path] [--workspace <dev_ws>] [--view-as <member>]` —
+ * scaffold-sync the package into the dev workspace, then run the existing app
+ * dev server against the resulting installation (HMR over the local source, RPC
+ * forwarded to the live installation). The inner loop: edit contract → re-run to
+ * sync; edit code → hot reload.
+ */
+export declare function packageDev(client: LoticsClient, args: {
+    projectDir?: string;
+    port?: number;
+    vitePort?: number;
+}): Promise<void>;
+/**
+ * `lotics package reset [path]` — DEV-ONLY, hard-gated. Drops the dev
+ * installation's package-owned scaffolded tables and re-scaffolds them clean. The
+ * backend refuses any workspace not flagged as a dev workspace, so this can never
+ * erase a real workspace's data. The dev installation is resolved from the
+ * project manifest's pin for the selected workspace.
+ */
+export declare function packageReset(client: LoticsClient, args: {
+    projectDir?: string;
+}): Promise<void>;
+export type UpgradeResolutionValue = "recreate" | "revert" | "keep" | {
+    bind_to: string;
+};
+/**
+ * Parse repeated `--resolve <key>=<value>` flags. Drift entries
+ * (`<namespace>.<alias>`) take `recreate` or an existing id; modified
+ * artifacts (`<kind>.<alias>`) take `revert` or `keep`. Any other value is a
+ * bind_to id; the server validates value-kind against what the key resolves.
+ */
+export declare function parseResolveFlags(resolve: string[]): Record<string, UpgradeResolutionValue>;
+/**
+ * Health check: version pin vs. registry latest + binding drift. Exits
+ * non-zero when drift is found so scripts can gate on it.
+ */
+export declare function packageDoctor(client: LoticsClient, args: {
+    app_id?: string;
+}): Promise<void>;
+/**
+ * Preview-then-apply upgrade. Prints the additive plan + informational
+ * removals; refuses (exit 1, with the exact --resolve syntax) while any
+ * binding drift lacks a resolution.
+ */
+export declare function packageUpgrade(client: LoticsClient, args: {
+    app_id: string;
+    version?: number;
+    resolutions: Record<string, UpgradeResolutionValue>;
+}): Promise<void>;
+export declare function packageInstall(client: LoticsClient, args: {
+    package_id: string;
+    version?: number;
+}): Promise<void>;
+export declare function packageEject(client: LoticsClient, args: {
+    app_id: string;
+}): Promise<void>;
+/**
+ * `lotics package extract <app_id> [path]` — promote a bespoke app to a DRAFT
+ * package project (docs/app_packages.md § Promotion). Calls the extract read,
+ * prints the findings report grouped by severity, then ALWAYS emits the draft
+ * project (a broken contract is still the reviewable starting point): the app's
+ * current source archive (same mechanics as `lotics app pull`) with the app
+ * manifest swapped for an unpublished package manifest, `contract.json`, the
+ * file-backed templates staged at their `bytes_ref` paths, and
+ * `.lotics/adopt_binding.json` (the origin pin the `adopt` step reads back).
+ * Exits non-zero when any `error` finding exists — the draft is written, but
+ * publish re-validates and nothing should ship unreviewed.
+ */
+export declare function packageExtract(client: LoticsClient, args: {
+    app_id: string;
+    targetPath?: string;
+}): Promise<void>;
+/**
+ * `lotics package adopt <app_id> [path]` — bind the published package project
+ * onto the origin app (docs/app_packages.md § Promotion). Reads the project
+ * manifest (must be published — refuses otherwise), resolves the version
+ * (`--version N` else the manifest's), and reads `.lotics/adopt_binding.json`,
+ * REFUSING a pin recorded for a different app. On success the app becomes
+ * installation #1 and is upgradeable again; a server ConflictError (naming the
+ * unfaithful aliases) surfaces verbatim.
+ */
+export declare function packageAdopt(client: LoticsClient, args: {
+    app_id: string;
+    version?: number;
+    projectDir?: string;
+}): Promise<void>;
+/**
+ * `lotics package fleet-upgrade <package_id> [--version N]` — 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".
+ */
+export declare function packageFleetUpgrade(client: LoticsClient, args: {
+    package_id: string;
+    version?: number;
+}): Promise<void>;
+export {};