@lotics/cli 0.86.0 → 0.86.2

package/dist/dev/upload_relay.js

@@ -0,0 +1,61 @@
+/**
+ * Dev-only upload relay: the bookkeeping that lets `lotics app dev` upload a file.
+ *
+ * Dev runs against the PROD bucket (there is no dev bucket), whose CORS allowlist
+ * holds the real app origins (`https://*.lotics.app`), not `http://localhost:<port>`.
+ * A browser PUT straight to the presigned URL is blocked before it leaves the page,
+ * so without a relay no file-touching app can be exercised locally at all.
+ *
+ * The dev server therefore relays the bytes: the wrapper page PUTs same-origin (no
+ * preflight, no CORS) and Node — which has no same-origin policy — forwards them on.
+ *
+ * The security property, and the reason the page never names its destination: a
+ * relay that forwarded to a client-supplied URL would be an open proxy. So the page
+ * sends only a `file_id`, and the relay writes ONLY to a presigned URL it minted
+ * itself for that id, moments earlier, via its own authenticated API call. There is
+ * no client-controlled target — hence nothing to allowlist, and no SSRF surface.
+ *
+ * Production is untouched: it PUTs direct-to-storage, keeping every byte off the
+ * API server.
+ */
+/**
+ * How long a mint is worth keeping. This is a pruning window, not a correctness gate —
+ * storage is the authority on whether a presign is still valid (an expired one is refused
+ * there, and the wrapper surfaces that). It only needs to outlive the presign (~10 min) so
+ * the relay never 404s a PUT that storage would still have accepted.
+ */
+const PRESIGN_TTL_MS = 15 * 60 * 1000;
+export function createUploadRelay(now = Date.now) {
+    const minted = new Map();
+    const prune = (at) => {
+        for (const [id, entry] of minted) {
+            if (at - entry.mintedAt > PRESIGN_TTL_MS)
+                minted.delete(id);
+        }
+    };
+    return {
+        rewriteMint(result) {
+            const mint = result;
+            if (typeof mint?.file_id !== "string" || typeof mint?.upload_url !== "string")
+                return result;
+            const at = now();
+            prune(at);
+            minted.set(mint.file_id, { url: mint.upload_url, mintedAt: at });
+            return { ...mint, upload_url: `/_upload/${encodeURIComponent(mint.file_id)}` };
+        },
+        destinationFor(fileId) {
+            const entry = minted.get(fileId);
+            if (!entry)
+                return null;
+            if (now() - entry.mintedAt > PRESIGN_TTL_MS) {
+                minted.delete(fileId);
+                return null;
+            }
+            return entry.url;
+        },
+        settle(fileId) {
+            minted.delete(fileId);
+        },
+        size: () => minted.size,
+    };
+}

package/dist/dev/upload_relay.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/dev/upload_relay.test.js

@@ -0,0 +1,76 @@
+import { describe, it, expect } from "vitest";
+import { createUploadRelay } from "./upload_relay.js";
+const MINT = {
+    file_id: "fil_abc",
+    file_storage_key: "org/files/fil_abc/photo.jpg",
+    upload_url: "https://production.r2.cloudflarestorage.com/org/files/fil_abc/photo.jpg?X-Amz-Signature=deadbeef",
+};
+describe("upload relay — the page PUTs same-origin", () => {
+    it("hands the page a same-origin URL and keeps everything else it needs to finalize", () => {
+        const relay = createUploadRelay();
+        const seen = relay.rewriteMint(MINT);
+        expect(seen.upload_url).toBe("/_upload/fil_abc");
+        // file_storage_key + file_id still reach the page — `upload_complete` needs both.
+        expect(seen.file_id).toBe("fil_abc");
+        expect(seen.file_storage_key).toBe(MINT.file_storage_key);
+    });
+    it("does not mutate the mint it was handed", () => {
+        const relay = createUploadRelay();
+        relay.rewriteMint(MINT);
+        expect(MINT.upload_url).toContain("r2.cloudflarestorage.com");
+    });
+});
+describe("upload relay — it writes ONLY where it was told to by itself", () => {
+    it("relays to the presigned URL it minted for that id", () => {
+        const relay = createUploadRelay();
+        relay.rewriteMint(MINT);
+        expect(relay.destinationFor("fil_abc")).toBe(MINT.upload_url);
+    });
+    it("refuses an id it never minted — there is no client-supplied destination to honour", () => {
+        const relay = createUploadRelay();
+        expect(relay.destinationFor("fil_never_seen")).toBeNull();
+    });
+    it("refuses a mint that has aged past its presign", () => {
+        let clock = 1_000_000;
+        const relay = createUploadRelay(() => clock);
+        relay.rewriteMint(MINT);
+        clock += 16 * 60 * 1000; // presigns die at ~10 min; the relay holds 15
+        expect(relay.destinationFor("fil_abc")).toBeNull();
+    });
+});
+describe("upload relay — lifecycle", () => {
+    it("forgets a mint once its bytes have landed", () => {
+        const relay = createUploadRelay();
+        relay.rewriteMint(MINT);
+        relay.settle("fil_abc");
+        expect(relay.destinationFor("fil_abc")).toBeNull();
+        expect(relay.size()).toBe(0);
+    });
+    it("keeps the mint on a failed PUT so the page's retry can reuse it", () => {
+        const relay = createUploadRelay();
+        relay.rewriteMint(MINT);
+        // No settle() — the storage PUT 5xx'd and the wrapper page retries.
+        expect(relay.destinationFor("fil_abc")).toBe(MINT.upload_url);
+    });
+    it("prunes dead mints instead of growing forever across a long dev session", () => {
+        let clock = 0;
+        const relay = createUploadRelay(() => clock);
+        relay.rewriteMint({ ...MINT, file_id: "fil_old" });
+        clock += 16 * 60 * 1000;
+        relay.rewriteMint({ ...MINT, file_id: "fil_new" });
+        expect(relay.size()).toBe(1); // the stale one was swept on the next mint
+        expect(relay.destinationFor("fil_new")).toBe(MINT.upload_url);
+    });
+});
+describe("upload relay — a response that carries no mint", () => {
+    it("passes through untouched rather than inventing a relay for it", () => {
+        const relay = createUploadRelay();
+        const odd = { message: "upstream changed shape" };
+        expect(relay.rewriteMint(odd)).toBe(odd);
+        expect(relay.size()).toBe(0);
+    });
+    it("tolerates null without throwing", () => {
+        const relay = createUploadRelay();
+        expect(relay.rewriteMint(null)).toBeNull();
+    });
+});

package/dist/dev/wrapper_page.js

@@ -120,7 +120,13 @@ export function buildWrapperPage(args) {
 
       // The iframe SDK sends one "upload" op carrying a File. A File can't
       // cross the JSON /_rpc hop, so the upload runs here in the browser:
-      // mint a presigned URL, PUT the bytes to storage, then finalize.
+      // mint an upload URL, PUT the bytes, then finalize.
+      //
+      // In dev the minted URL is same-origin (/_upload/<file_id>) — the dev
+      // server relays the bytes to storage on our behalf, because the prod
+      // bucket's CORS does not admit a localhost origin. Production PUTs the
+      // presigned storage URL directly. Same three lines either way: the page
+      // PUTs wherever the mint points.
       //
       // Retry policy parity with the production SDK
       // (packages/app-sdk/src/upload/transport.ts): 3 PUT attempts with

package/dist/package_commands.d.ts

@@ -1,13 +1,17 @@
 import { LoticsClient, type ExtractFinding } from "./client.js";
-import { type UpgradeResolutions } from "@lotics/shared/schemas/packages";
+import { type ContractConfigEntry, 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.
+ * `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 declare function readLocalAppManifest(projectDir: string): {
     app_id: string | null;
@@ -15,6 +19,7 @@ export declare function readLocalAppManifest(projectDir: string): {
         alias: string;
         doc_id: string;
     }>;
+    config: ContractConfigEntry[];
 } | null;
 /** Parse repeated `--rename old=new` flags into `{ from, to }[]` (first-publish alias fixes). */
 export declare function parseRenameFlags(renames: string[]): Array<{
@@ -43,7 +48,9 @@ export declare function formatExtractReport(report: ExtractFinding[]): {
 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.
+ * 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 declare function packageDoctor(client: LoticsClient, args: {
     app_id?: string;

package/dist/package_commands.js

@@ -21,7 +21,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import "./client.js";
-import { knowledgeEntryNeedsConsent, validKnowledgeResolutions, } from "@lotics/shared/schemas/packages";
+import { contractConfigEntrySchema, knowledgeEntryNeedsConsent, validKnowledgeResolutions, } from "@lotics/shared/schemas/packages";
 function packageJsonPath(projectDir) {
     return path.join(projectDir, "package.json");
 }
@@ -30,12 +30,16 @@ function isPlainObject(value) {
 }
 /**
  * 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.
+ * `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);
@@ -54,7 +58,19 @@ export function readLocalAppManifest(projectDir) {
             }
         }
     }
-    return { app_id, knowledge };
+    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) {
@@ -115,9 +131,15 @@ export function parseResolveFlags(resolve) {
 }
 /**
  * Health check: version pin vs. registry latest + binding drift. Exits
- * non-zero when drift is found so scripts can gate on it.
+ * 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}` +
@@ -376,6 +398,47 @@ function formatTemplateResolveHint(entry) {
         : "   (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
@@ -816,16 +879,17 @@ export async function appPublish(client, args) {
         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 declaration ONLY when the local
-    // manifest is this app's own project (agents reference docs by free text, so the
-    // author declares which the package owns). A bare id published from elsewhere
-    // ships without a bundled corpus — publish from the app dir to include it.
+    // 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 });
+    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 = [
@@ -847,6 +911,9 @@ export async function appPublish(client, args) {
     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)
@@ -870,6 +937,7 @@ export async function appPublish(client, args) {
         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:`);
@@ -901,11 +969,12 @@ export async function appRelease(client, args) {
     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 DECLARATION only from this app's own project
-    // AND only when it lists docs — an empty/absent declaration is "no change"
-    // (reconstruct from the pin), never "drop the bundle".
+    // 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 preview = await client.previewPackageRelease(appId, { knowledge });
+    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) {
@@ -914,7 +983,15 @@ export async function appRelease(client, args) {
     if (preview.changed_artifacts.length > 0) {
         console.error(`  Changed (${preview.changed_artifacts.length}): ${preview.changed_artifacts.join(", ")}`);
     }
-    // Deploy-skew boundary: a pre-knowledge-declaration server omits the field.
+    // 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 = [
@@ -924,11 +1001,23 @@ export async function appRelease(client, args) {
         ].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) {
+        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) {
@@ -947,7 +1036,7 @@ export async function appRelease(client, args) {
         process.exitCode = 1;
         return;
     }
-    const result = await client.releasePackage(appId, { changelog: args.changelog, knowledge });
+    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}`);
 }
@@ -990,7 +1079,7 @@ async function packageFleetUpgrade(client, args) {
         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}`);
+            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) {