@lotics/cli 0.76.0 → 0.83.0

package/dist/generate_package_fields.test.js

@@ -1,24 +1,24 @@
 import { describe, expect, it } from "vitest";
 import { generatePackageAppFields } from "./generate_package_fields.js";
-const contract = {
-    entities: [
-        {
-            alias: "tasks",
-            fields: [
-                { alias: "title" },
-                {
-                    alias: "status",
-                    options: [{ alias: "to_do" }, { alias: "doing" }, { alias: "done" }],
-                },
-            ],
-        },
-        { alias: "projects", fields: [{ alias: "name" }] },
-    ],
-    roles: [{ alias: "approver" }],
+// A live installation binding — fully-qualified alias → concrete id. The
+// generator sources the alias SET here (never a contract file); the emitted
+// module resolves the SAME keys through `getAppBinding()` at runtime.
+const binding = {
+    fields: {
+        "tasks.title": "fld_title",
+        "tasks.status": "fld_status",
+        "projects.name": "fld_name",
+    },
+    options: {
+        "tasks.status:to_do": "opt_todo",
+        "tasks.status:doing": "opt_doing",
+        "tasks.status:done": "opt_done",
+    },
+    roles: { approver: "grp_approver" },
 };
 describe("generatePackageAppFields", () => {
-    it("emits runtime-resolved F/OPT/ROLE keyed by contract aliases", () => {
-        const src = generatePackageAppFields(contract);
+    it("emits runtime-resolved F/OPT/ROLE keyed by the binding's aliases", () => {
+        const src = generatePackageAppFields(binding);
         // Resolves through the SDK binding at module load (top-level await).
         expect(src).toContain('import { getAppBinding } from "@lotics/app-sdk";');
         expect(src).toContain("const binding = await getAppBinding();");
@@ -31,21 +31,29 @@ describe("generatePackageAppFields", () => {
         expect(src).toContain('to_do: bound(binding.options, "tasks.status:to_do", "option")');
         expect(src).toContain('done: bound(binding.options, "tasks.status:done", "option")');
         expect(src).not.toContain('"tasks.title:');
-        // ROLE map from contract roles.
+        // ROLE map from the binding's roles.
         expect(src).toContain('approver: bound(binding.roles, "approver", "role")');
         // No concrete id in any VALUE position — the module is workspace-agnostic.
         // (Doc comments legitimately name the id prefixes, so match quoted ids.)
         expect(src).not.toMatch(/"(fld|opt|tbl|grp)_/);
     });
-    it("emits valid empty maps for an empty contract", () => {
-        const src = generatePackageAppFields({});
+    it("emits valid empty maps for an empty binding", () => {
+        const src = generatePackageAppFields({ fields: {}, options: {}, roles: {} });
         expect(src).toContain("export const F = {} as const;");
         expect(src).toContain("export const OPT = {} as const;");
         expect(src).toContain("export const ROLE = {} as const;");
         // Still imports the SDK so the module shape is uniform.
         expect(src).toContain("const binding = await getAppBinding();");
     });
-    it("is deterministic — same contract, same bytes", () => {
-        expect(generatePackageAppFields(contract)).toBe(generatePackageAppFields(contract));
+    it("quotes an alias that is not a valid identifier", () => {
+        const src = generatePackageAppFields({
+            fields: { "tasks.2nd_field": "fld_x" },
+            options: {},
+            roles: {},
+        });
+        expect(src).toContain('"2nd_field": bound(binding.fields, "tasks.2nd_field", "field")');
+    });
+    it("is deterministic — same binding, same bytes", () => {
+        expect(generatePackageAppFields(binding)).toBe(generatePackageAppFields(binding));
     });
 });

package/dist/package_commands.d.ts

@@ -1,164 +1,46 @@
-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`.
+import { LoticsClient, type ExtractFinding } from "./client.js";
+import { type UpgradeResolutions } from "@lotics/shared/schemas/packages";
+/**
+ * Read the local APP project's manifest (`package.json#lotics.app_id` +
+ * `lotics.knowledge`) — what `lotics app pull` writes. `lotics app publish` /
+ * `release` run from a pulled app project resolve the app id from it, and
+ * `publish` forwards the package-managed knowledge declaration to the server
+ * (agents reference docs by free text, so the author declares which the package
+ * owns). Returns null when the dir has no package.json. `app_id` is null when the
+ * manifest is a package/non-app project.
+ */
+export declare function readLocalAppManifest(projectDir: string): {
+    app_id: string | null;
+    knowledge: Array<{
+        alias: string;
+        doc_id: string;
+    }>;
+} | null;
+/** Parse repeated `--rename old=new` flags into `{ from, to }[]` (first-publish alias fixes). */
+export declare function parseRenameFlags(renames: string[]): Array<{
+    from: string;
+    to: string;
+}>;
+/**
+ * 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 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.
+ * 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 declare function parseResolveFlags(resolve: string[]): Record<string, UpgradeResolutionValue>;
+export declare function parseResolveFlags(resolve: string[]): UpgradeResolutions;
 /**
  * Health check: version pin vs. registry latest + binding drift. Exits
  * non-zero when drift is found so scripts can gate on it.
@@ -167,28 +49,90 @@ 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.
+ * 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 declare function packageUpgrade(client: LoticsClient, args: {
     app_id: string;
     version?: number;
-    resolutions: Record<string, UpgradeResolutionValue>;
+    resolve: string[];
+    bindTo: string[];
+    applyAll: boolean;
 }): Promise<void>;
 /**
  * `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".
+ * surface for "what is this package and what shipped when". Kind-agnostic — a
+ * content package shows here the same way.
  */
 export declare function packageShow(client: LoticsClient, args: {
     package_id: string;
 }): Promise<void>;
+/**
+ * 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.
+ */
+export declare function packageUpgradeKnowledge(client: LoticsClient, args: {
+    installation_id: string;
+    version?: number;
+    /** Raw `--resolve <alias>=<value>` flags, routed to knowledge/templates after the preview. */
+    resolve: string[];
+    bind_to: Record<string, string>;
+    applyAll: boolean;
+}): Promise<void>;
+/** Parse repeated `--bind-to alias=kdc_id` flags into an alias → doc-id consent map. */
+export declare function parseBindToFlags(bindTo: string[]): Record<string, string>;
 export declare function packageInstall(client: LoticsClient, args: {
     package_id: string;
     version?: number;
+    /** Content-kind only: adopt a same-named workspace doc on a knowledge collision. */
+    bind_to?: Record<string, string>;
+    /** App-kind only: per-knob config overrides applied over the contract defaults. */
     config?: Record<string, string | number | boolean>;
 }): Promise<void>;
+/**
+ * `lotics uninstall <app_id|pci_id>` — ONE top-level command over both installation
+ * kinds, dispatched by the id form (mirrors `lotics upgrade`):
+ *   - a `pci_` id → a STANDALONE CONTENT installation: 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 declare function packageUninstall(client: LoticsClient, args: {
+    id: string;
+    keep_content: boolean;
+    archive_tables: boolean;
+}): Promise<void>;
+/**
+ * `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 read surface that surfaces a `pci_` id for
+ * `upgrade` / `uninstall` (install prints it once; nothing else did before).
+ */
+export declare function packageListContent(client: LoticsClient): Promise<void>;
 export declare function packageEject(client: LoticsClient, args: {
     app_id: string;
 }): Promise<void>;
@@ -204,59 +148,53 @@ export declare function packageConfig(client: LoticsClient, args: {
     sets: string[];
 }): Promise<void>;
 /**
- * `lotics package uninstall <app_id> [--archive-tables]` — remove a package
- * installation. Prints what will be archived (workflow artifacts, plus the
- * scaffolded tables when the flag is set), then uninstalls.
- */
-export declare function packageUninstall(client: LoticsClient, args: {
-    app_id: string;
-    archive_tables: boolean;
-}): Promise<void>;
-/**
- * `lotics package retire <package_id> [--undo]` — retire (or un-retire) a
- * registry package. Owner-org admin-only.
+ * `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 declare function packageRetire(client: LoticsClient, args: {
-    package_id: string;
+export declare function appUnpublish(client: LoticsClient, args: {
+    id: string;
     undo: boolean;
 }): 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;
+ * `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 declare function appPublish(client: LoticsClient, args: {
+    app_id?: string;
+    renames: string[];
+    changelog?: string;
+    yes: boolean;
+    projectDir?: 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.
+ * `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, findings); applies only with
+ * `--yes`, else exits 1 so a review step can't be skipped. An `error` finding
+ * blocks the apply.
  */
-export declare function packageAdopt(client: LoticsClient, args: {
-    app_id: string;
-    version?: number;
+export declare function appRelease(client: LoticsClient, args: {
+    app_id?: string;
+    changelog: string;
+    yes: boolean;
     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".
- */
 /**
  * `lotics package yank <package_id> <version> [--undo]` — mark a published
  * version uninstallable (or restore it). New installs/upgrades/adopts refuse a
@@ -268,8 +206,14 @@ export declare function packageYank(client: LoticsClient, args: {
     version: number;
     undo: boolean;
 }): Promise<void>;
+/**
+ * `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".
+ */
 export declare function packageFleetUpgrade(client: LoticsClient, args: {
     package_id: string;
     version?: number;
 }): Promise<void>;
-export {};