@lotics/cli 0.75.0 → 0.76.0

package/dist/package_commands.js

@@ -25,9 +25,9 @@ import fs from "node:fs";
 import path from "node:path";
 import { tmpdir } from "node:os";
 import "./client.js";
-import { buildStarterTemplate, STARTER_FALLBACK_SDK_VERSION } from "./starter_template.js";
+import { buildStarterTemplate, buildPackageStarterOverrides, STARTER_FALLBACK_SDK_VERSION, } from "./starter_template.js";
 import { generatePackageAppFields, } from "./generate_package_fields.js";
-import { appDirName, fetchLatestNpmVersion, runNpm, runTar } from "./app_commands.js";
+import { appDirName, fetchLatestNpmVersion, runNpm, runTar, writeAppDts } from "./app_commands.js";
 import { writeFileAtomic } from "./file_command_io.js";
 import { startDevServer, openBrowser } from "./dev/server.js";
 const CONTRACT_FILE = "contract.json";
@@ -361,6 +361,12 @@ export async function packageNew(args) {
         ui_version: uiLatest ? `^${uiLatest}` : undefined,
         sdk_version: packageSdkRange(sdkLatest),
     });
+    // Package-specific code surface swapped in BY PATH (same mechanism as the
+    // package.json manifest swap below): the shared app starter's App.tsx demos
+    // in-app routing over static data, wrong for a package. The package starter's
+    // App.tsx exercises the binding (F/OPT + useQuery/useConfig), its test mocks the
+    // SDK boundary, and its README carries the contract reference.
+    const overrides = new Map(buildPackageStarterOverrides({ app_name: args.name }).map((f) => [f.path, f.content]));
     for (const file of files) {
         const fullPath = path.join(targetPath, file.path);
         if (file.path === "package.json") {
@@ -378,7 +384,7 @@ export async function packageNew(args) {
             continue;
         }
         fs.mkdirSync(path.dirname(fullPath), { recursive: true });
-        fs.writeFileSync(fullPath, file.content);
+        fs.writeFileSync(fullPath, overrides.get(file.path) ?? file.content);
     }
     fs.writeFileSync(path.join(targetPath, CONTRACT_FILE), JSON.stringify(starterContract(args.name), null, 2) + "\n");
     writePackageAppFields(targetPath);
@@ -430,6 +436,7 @@ async function publishVersion(client, projectDir, opts) {
         contract,
         bundle,
         changelog: opts.changelog ?? null,
+        channel: opts.channel ?? "release",
     });
     project.manifest.version = version.version;
     writePackageManifest(projectDir, project);
@@ -487,8 +494,12 @@ async function syncToDevWorkspace(client, projectDir) {
     // Contract may have been edited since the last sync — regenerate the
     // runtime F/OPT/ROLE surface before the build that publishVersion runs.
     writePackageAppFields(projectDir);
+    // 'dev' channel: a real immutable version this dev installation pins by
+    // number, but never what "install latest" resolves to — a broken
+    // mid-iteration contract must not become the org-wide installable default.
     const { package_id, version } = await publishVersion(client, projectDir, {
         changelog: "dev sync",
+        channel: "dev",
     });
     // Re-read after publish (publishVersion may have stamped the package id).
     const project = readPackageProject(projectDir);
@@ -507,6 +518,18 @@ async function syncToDevWorkspace(client, projectDir) {
     project.manifest.dev[devWorkspaceId] = { app_id: appId, version };
     writePackageManifest(projectDir, project);
     const installed = await client.getApp(appId);
+    // Regenerate the typed `.lotics/app_{queries,workflows,agents}.d.ts` companions
+    // from the live installation — the SAME maps (`apps.queries`/`workflows`/`agents`,
+    // keyed by the contract's runtime aliases) `lotics app pull` codegens from — so
+    // `useQuery("items")` / `useWorkflow` are typed in the package dev loop, not just
+    // in pulled app projects. (`.lotics/app_fields.ts`, the runtime F/OPT surface, was
+    // already refreshed from the contract before publish.) `writeAppDts` also heals the
+    // tsconfig include/exclude so the generated `.d.ts` actually load.
+    writeAppDts(projectDir, {
+        workflows: installed.workflows ?? undefined,
+        queries: installed.queries ?? undefined,
+        agents: installed.agents ?? undefined,
+    });
     return { app_id: appId, app_name: installed.name, workspace_id: devWorkspaceId, version };
 }
 /**
@@ -730,15 +753,48 @@ export async function packageUpgrade(client, args) {
     });
     console.error(`Upgraded ${app.name} → v${app.package_version} (${app.id}).`);
 }
+/** The install-consent trust line: official > your own org > third-party. */
+function trustBadge(pkg) {
+    if (pkg.is_official)
+        return "official Lotics package";
+    if (pkg.owned_by_caller === true)
+        return "your organization's package";
+    return "third-party package (runs under your authority once installed)";
+}
+/**
+ * `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".
+ */
+export async function packageShow(client, args) {
+    const pkg = await client.getAppPackage(args.package_id);
+    const { versions } = await client.listAppPackageVersions(args.package_id);
+    console.error(`${pkg.name} (${pkg.id}) — ${trustBadge(pkg)}`);
+    if (pkg.description)
+        console.error(`  ${pkg.description}`);
+    if (pkg.retired_at)
+        console.error(`  RETIRED ${pkg.retired_at}`);
+    console.error(`  latest installable: ${pkg.latest_version > 0 ? `v${pkg.latest_version}` : "none"}`);
+    console.error("");
+    for (const v of versions) {
+        const marks = [
+            v.version === pkg.latest_version ? "*" : " ",
+            v.channel === "dev" ? "dev" : "   ",
+            v.yanked_at ? "YANKED" : "      ",
+        ].join(" ");
+        console.log(`${marks} v${v.version}  ${v.created_at}  ${v.changelog ?? ""}`.trimEnd());
+    }
+    if (versions.length === 0)
+        console.error("  (no published versions)");
+}
 export async function packageInstall(client, args) {
     // Surface the trust badge at the consent point: installing materializes the
     // package's workflows/agents under YOUR authority, so say whose package it is.
     const pkg = await client.getAppPackage(args.package_id);
-    console.error(pkg.is_official
-        ? `Installing ${pkg.name} — official Lotics package...`
-        : `Installing ${pkg.name} — third-party package (runs under your authority once installed)...`);
+    console.error(`Installing ${pkg.name} — ${trustBadge(pkg)}...`);
     const app = await client.installAppPackage(args.package_id, {
         ...(args.version !== undefined ? { version: args.version } : {}),
+        ...(args.config !== undefined ? { config: args.config } : {}),
     });
     const versionLabel = app.package_version !== null ? `v${app.package_version}` : "(unknown version)";
     console.error(`Installed ${app.name} ${versionLabel} → ${app.id} (workspace ${app.workspace_id}).`);
@@ -752,6 +808,126 @@ export async function packageEject(client, args) {
     console.error("  Its data model, queries, workflows, and templates are unchanged.");
     console.error("  Pull the pinned source for local editing:  lotics app pull " + app.id);
 }
+/**
+ * Parse one `key=value` config assignment. When the knob's type is known (from
+ * the stored value at `package config --set`) the value is parsed to that type
+ * loudly; otherwise (`package install --config`) it is inferred (true/false →
+ * boolean, numeric → number, else string) and the server validates it against
+ * the contract.
+ */
+function parseConfigAssignment(entry, flag, knownType) {
+    const eq = entry.indexOf("=");
+    if (eq <= 0 || eq === entry.length - 1) {
+        throw new Error(`Invalid ${flag} "${entry}" — expected key=value.`);
+    }
+    const key = entry.slice(0, eq);
+    const raw = entry.slice(eq + 1);
+    if (knownType === "number") {
+        const n = Number(raw);
+        if (!Number.isFinite(n))
+            throw new Error(`Config key "${key}" is a number knob — "${raw}" is not numeric.`);
+        return { key, value: n };
+    }
+    if (knownType === "boolean") {
+        if (raw !== "true" && raw !== "false") {
+            throw new Error(`Config key "${key}" is a boolean knob — expected true or false, got "${raw}".`);
+        }
+        return { key, value: raw === "true" };
+    }
+    if (knownType === "string")
+        return { key, value: raw };
+    // Inferred (install override): the server re-validates against the contract.
+    if (raw === "true" || raw === "false")
+        return { key, value: raw === "true" };
+    if (/^-?\d+(\.\d+)?$/.test(raw))
+        return { key, value: Number(raw) };
+    return { key, value: raw };
+}
+/** `--config key=value` (install): inferred types, server-validated. */
+export function parseInstallConfigFlags(config) {
+    const out = {};
+    for (const entry of config) {
+        const { key, value } = parseConfigAssignment(entry, "--config");
+        out[key] = value;
+    }
+    return out;
+}
+/**
+ * `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 async function packageConfig(client, args) {
+    const app = await client.getApp(args.app_id);
+    if (!app.package_id) {
+        throw new Error(`App ${args.app_id} is not a package installation — it has no config.`);
+    }
+    const current = app.config ?? {};
+    if (args.sets.length === 0) {
+        const keys = Object.keys(current).sort();
+        if (keys.length === 0) {
+            console.error(`${app.name} (${app.id}) — no config knobs.`);
+            return;
+        }
+        console.error(`${app.name} (${app.id}) config:`);
+        for (const key of keys)
+            console.log(`  ${key} = ${JSON.stringify(current[key])}`);
+        return;
+    }
+    const overrides = {};
+    for (const entry of args.sets) {
+        const key = entry.slice(0, Math.max(0, entry.indexOf("=")));
+        const knownType = typeof current[key];
+        const { value } = parseConfigAssignment(entry, "--set", knownType === "number" || knownType === "boolean" || knownType === "string" ? knownType : undefined);
+        overrides[key] = value;
+    }
+    const { config } = await client.updateAppPackageConfig(args.app_id, { config: overrides });
+    console.error(`Updated config for ${app.name} (${app.id}):`);
+    for (const key of Object.keys(config).sort()) {
+        const marker = key in overrides ? " *" : "";
+        console.log(`  ${key} = ${JSON.stringify(config[key])}${marker}`);
+    }
+}
+/**
+ * `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 async function packageUninstall(client, args) {
+    const app = await client.getApp(args.app_id);
+    if (!app.package_id) {
+        throw new Error(`App ${args.app_id} is not a package installation — use the app delete flow for a bespoke app.`);
+    }
+    const lifecycleCount = Object.keys(app.binding?.workflows ?? {}).length;
+    const boundCount = Object.keys(app.workflows ?? {}).length;
+    const tableCount = Object.keys(app.binding?.entities ?? {}).length;
+    console.error(`Uninstalling ${app.name} (${app.id}):`);
+    console.error(`  Archives ${boundCount + lifecycleCount} workflow(s) (${boundCount} app, ${lifecycleCount} lifecycle).`);
+    console.error(args.archive_tables
+        ? `  Archives ${tableCount} scaffolded table(s) — refused if they were adopted or are still referenced.`
+        : `  Leaves the data model (${tableCount} table(s)) intact. Pass --archive-tables to also archive them.`);
+    const result = await client.uninstallAppPackage(args.app_id, {
+        archive_tables: args.archive_tables,
+    });
+    console.error(`Uninstalled ${app.name} (${app.id}).`);
+    if (result.archived_table_ids.length > 0) {
+        console.error(`  Archived tables: ${result.archived_table_ids.join(", ")}`);
+    }
+}
+/**
+ * `lotics package retire <package_id> [--undo]` — retire (or un-retire) a
+ * registry package. Owner-org admin-only.
+ */
+export async function packageRetire(client, args) {
+    const pkg = await client.retireAppPackage(args.package_id, { undo: args.undo });
+    if (pkg.retired_at !== null) {
+        console.error(`Retired ${pkg.name} (${pkg.id}). New installs refuse it and it is hidden from other orgs; ` +
+            `existing installations keep working and may still upgrade.`);
+    }
+    else {
+        console.error(`Un-retired ${pkg.name} (${pkg.id}) — installable again.`);
+    }
+}
 /**
  * `lotics package extract <app_id> [path]` — promote a bespoke app to a DRAFT
  * package project (docs/app_packages.md § Promotion). Calls the extract read,