@lotics/cli 0.75.0 → 0.76.1

package/dist/package_commands.d.ts

@@ -1,20 +1,74 @@
 import { LoticsClient, type PackageBinding, type ExtractFinding } from "./client.js";
+import { type KnowledgeUpgradeEntry, type KnowledgeResolution, type ModificationResolution } from "@lotics/shared/schemas/packages";
 /** One dev workspace's pinned installation of this package (manifest bookkeeping). */
 interface PackageDevInstallation {
     app_id: string;
     version: number;
 }
+/**
+ * One package-managed knowledge doc's authoring metadata, from
+ * `package.json#lotics.package.knowledge` (alias → this). The content lives in a
+ * sibling `knowledge/<alias>.md` file; `build`/`publish` sha256 the file and fold
+ * both into the contract's `knowledge` namespace. Round-trips through the manifest
+ * so a manifest write (e.g. stamping the package id on first publish) never drops
+ * it — and it therefore ships in `source.tar.gz` for eject/extract.
+ */
+interface PackageKnowledgeManifestEntry {
+    name: string;
+    description: string | null;
+    active_by_default: boolean;
+}
+/** The 5 document-template kinds a package template may declare (== the contract's). */
+export type PackageTemplateKind = "html" | "email" | "excel" | "word" | "pdf-form";
+/**
+ * One package-managed document template's authoring metadata, from
+ * `package.json#lotics.package.templates` (alias → this). The template file lives
+ * at `templates/<file>`; `build`/`publish` fold it into the contract's
+ * `templates` namespace — an inline kind (html/email) reads the file as `content`,
+ * a file-backed kind (excel/word/pdf-form) records `bytes_ref: templates/<file>`
+ * (the bytes ride in `source.tar.gz`, like a knowledge doc's content) — then
+ * `foldTemplateShasIntoContract` computes each `content_sha256`. This is how a
+ * CONTENT package declares standalone templates (an app package authors them in
+ * `contract.json` directly). Round-trips through the manifest so a manifest write
+ * never drops it.
+ */
+interface PackageTemplateManifestEntry {
+    name: string;
+    type: PackageTemplateKind;
+    /** The template file's name within the project's `templates/` dir. */
+    file: string;
+}
 /**
  * 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.
  */
+/** A package project's kind — mirrors the registry `packages.kind` (immutable after create). */
+export type PackageKind = "app" | "content";
 interface PackageManifest {
     id: string | null;
     name: string;
     description: string | null;
+    /**
+     * 'app' (the full materialized blueprint) | 'content' (a standalone content
+     * package). Threaded to `createPackage` on first publish and used locally to
+     * gate the build (a content package has no app source to compile). Defaults to
+     * 'app' for a manifest written before content packaging.
+     */
+    kind: PackageKind;
     version: number | null;
+    /** alias → knowledge-doc authoring metadata (content in `knowledge/<alias>.md`). */
+    knowledge: Record<string, PackageKnowledgeManifestEntry>;
+    /** alias → document-template authoring metadata (file in `templates/<file>`). */
+    templates: Record<string, PackageTemplateManifestEntry>;
+    /**
+     * Doc NAMES the package's agents route to but the package does not own —
+     * install/health WARN when a name has no doc in the workspace. Lives under
+     * `lotics.package` (one coherent home for everything package-related), NOT a
+     * sibling of it.
+     */
+    knowledge_expects: string[];
     dev: Record<string, PackageDevInstallation>;
 }
 interface PackageProjectFile {
@@ -58,6 +112,7 @@ export declare function parseAdoptBindingFile(raw: unknown, expectedAppId: strin
     app_id: string;
     workspace_id: string;
     binding: PackageBinding;
+    knowledge_binding: Record<string, string>;
 };
 /**
  * Render an extraction report grouped by severity (errors, then warnings, then
@@ -70,6 +125,48 @@ export declare function formatExtractReport(report: ExtractFinding[]): {
     lines: string[];
     hasError: boolean;
 };
+/**
+ * Fold a package project's knowledge corpus into its contract before publish:
+ * per `lotics.package.knowledge` alias, read `knowledge/<alias>.md`, sha256 the
+ * bytes, and emit the contract's `knowledge` namespace (alias → {name,
+ * description, content_ref, content_sha256, active_by_default}) +
+ * `knowledge_expects` (from `lotics.package.knowledge_expects`). This is the ONE
+ * place the sha is computed — it can't be hand-authored, which is why knowledge
+ * (unlike a template `bytes_ref`) is derived rather than written into
+ * contract.json. The content files themselves ride in `source.tar.gz`
+ * automatically: `knowledge/` is a top-level dir, so `stagePackageSource` copies
+ * it like any other source (the same mechanism that carries template bytes). Pure
+ * w.r.t. `contract` — returns a new object; the server re-validates the folded
+ * namespace at publish.
+ */
+export declare function foldKnowledgeIntoContract(projectDir: string, project: PackageProjectFile, contract: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Fold a CONTENT package's manifest-declared templates into its contract before
+ * publish: per `lotics.package.templates` alias, an INLINE kind (html/email) reads
+ * `templates/<file>` into the contract template's `content`; a FILE-BACKED kind
+ * (excel/word/pdf-form) records `bytes_ref: templates/<file>` (the bytes ride in
+ * `source.tar.gz` — `templates/` is a top-level dir `stagePackageSource` copies,
+ * the same mechanism that carries knowledge content + app-package template bytes).
+ * The per-template `content_sha256` is NOT computed here — `foldTemplateShasIntoContract`
+ * runs after and derives it (inline: the utf-8 content; file-backed: the file bytes).
+ *
+ * Appends to any templates the contract already declares (an app package authors
+ * templates in `contract.json` directly; the manifest path is how a content
+ * package — with no `contract.json` templates — declares them). An alias in BOTH
+ * is a loud error. Pure w.r.t. `contract` — returns a new object.
+ */
+export declare function foldTemplatesIntoContract(projectDir: string, project: PackageProjectFile, contract: unknown): Record<string, unknown>;
+/**
+ * Fold a freshly-computed `content_sha256` into every template of a package
+ * contract before publish — the modified-detection reference the install/upgrade
+ * flow compares live content against. Like knowledge's sha (foldKnowledge…), it
+ * can't be hand-authored: an INLINE template's sha covers its utf-8 `content`; a
+ * FILE-BACKED template's sha covers the `bytes_ref` file's bytes (the same bytes
+ * that ride in `source.tar.gz` and install stores verbatim). Always recomputed
+ * (never trusted from contract.json), so the published contract's sha is exact.
+ * Pure w.r.t. `contract` — returns a new object; the server re-validates.
+ */
+export declare function foldTemplateShasIntoContract(projectDir: string, contract: Record<string, unknown>): Record<string, unknown>;
 /**
  * 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.
@@ -82,15 +179,16 @@ export declare function stagePackageSource(projectDir: string, sourceStage: stri
 /** 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`.
+ * `lotics package new <name> [path] [--kind content]` — scaffold a package
+ * project. An `app` package 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`; a `content` package scaffolds a docs-only corpus (no app
+ * source). The project publishes with `lotics package publish`.
  */
 export declare function packageNew(args: {
     name: string;
     targetPath?: string;
+    kind?: PackageKind;
 }): Promise<void>;
 /**
  * `lotics package build [path]` — build the publishable bundle and write it to
@@ -167,41 +265,142 @@ 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` is shared across the finding classes: a key naming a bundled
+ * knowledge doc routes to `knowledge_resolutions` (apply|keep|archive|recreate|
+ * unbind), everything else to core `resolutions`; `--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". Kind-agnostic — a
+ * content package shows here the same way.
+ */
+export declare function packageShow(client: LoticsClient, args: {
+    package_id: string;
+}): Promise<void>;
+/**
+ * Route an app-install upgrade's `--resolve` entries into the core-artifact
+ * bucket vs the bundled-knowledge bucket. `--resolve` is shared between the two
+ * finding classes, so each key is matched against the preview: a key that names a
+ * bundled knowledge doc resolves that doc (its value validated against the doc's
+ * change class here — the app path has no separate knowledge-only parser);
+ * anything else stays a core resolution (a `<namespace>.<alias>` drift, a
+ * `<kind>.<alias>` modified core, or a key the server validates). A key that is
+ * BOTH a knowledge alias and a core-artifact key is ambiguous — throw rather than
+ * guess which the operator meant.
+ */
+export declare function routeAppUpgradeResolve(resolve: string[], knowledgeEntries: KnowledgeUpgradeEntry[], coreKeys: ReadonlySet<string>): {
+    coreResolve: string[];
+    knowledgeResolutions: Record<string, KnowledgeResolution>;
+};
+/**
+ * Route a STANDALONE content upgrade's shared `--resolve <alias>=<value>` flags
+ * into the knowledge vs templates buckets by matching each alias against the two
+ * preview namespaces. A doc alias takes apply|keep|archive|recreate|unbind; a
+ * template alias takes revert|keep. An alias present in BOTH namespaces is
+ * ambiguous → loud error (no guess). An alias in NEITHER → error. The value is
+ * validated against the namespace it routes to. Exported for testing.
+ */
+export declare function routeContentResolveFlags(resolve: string[], knowledgeAliases: ReadonlySet<string>, templateAliases: ReadonlySet<string>): {
+    knowledge: Record<string, KnowledgeResolution>;
+    templates: Record<string, ModificationResolution>;
+};
+/**
+ * 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 <alias>=<value>` and `--bind-to <alias>=<kdc_id>`
+ * resolve entries individually (`--resolve` is routed to the right namespace by
+ * matching the alias against the preview).
+ */
+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 package uninstall <app_id|pci_id>` — ONE command over both installation
+ * kinds, dispatched by the id form (mirrors `package 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 package-managed
+ * content installations (standalone `pci_` corpora + app-bundled ones), each
+ * with its registry status. The read surface that surfaces a standalone `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>;
+/** `--config key=value` (install): inferred types, server-validated. */
+export declare function parseInstallConfigFlags(config: string[]): Record<string, string | number | boolean>;
+/**
+ * `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 declare function packageConfig(client: LoticsClient, args: {
+    app_id: string;
+    sets: 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.
+ * `lotics package retire <package_id> [--undo]` — retire (or un-retire) a
+ * registry package. Owner-org admin-only.
  */
+export declare function packageRetire(client: LoticsClient, args: {
+    package_id: string;
+    undo: boolean;
+}): Promise<void>;
 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
+ * onto the origin app (docs/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