@lotics/cli 0.71.0 → 0.74.0

package/dist/generate_package_fields.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Codegen: emit a RUNTIME `.lotics/app_fields.ts` for a PACKAGE project from
+ * its `contract.json`.
+ *
+ * The bespoke twin (`generate_app_fields.ts`) bakes this workspace's concrete
+ * `fld_…`/`opt_…` ids at authoring time — correct when source and workspace
+ * co-live, fundamentally wrong for a package (one bundle, many workspaces,
+ * different ids in each). A package project instead resolves the SAME `F` /
+ * `OPT` surface at MODULE LOAD from the installation's binding via the SDK's
+ * `getAppBinding()` (the `binding` RPC op), using top-level await — the ESM
+ * graph waits for the binding before any importer evaluates, so
+ * `F.TASKS.title` is a plain string everywhere, including module-top-level
+ * constants. Extracted bespoke sources therefore compile unchanged: same
+ * import path, same shapes, same alias naming (contract aliases derive from
+ * the same display names the bespoke codegen slugifies).
+ *
+ * A missing alias fails LOUD at boot (the binding is adopt/install-verified
+ * complete, so a miss means the generated file is stale relative to the
+ * installed contract version) — never a silent undefined key in a write.
+ *
+ * Requires the app build to target es2022+ (the starter's `build.target`) —
+ * top-level await does not exist below it.
+ */
+/** The subset of a contract this generator reads (structural, not zod-validated —
+ *  publish is the validating boundary; codegen must work on drafts too). */
+export interface PackageContractShape {
+    entities?: Array<{
+        alias: string;
+        fields?: Array<{
+            alias: string;
+            options?: Array<{
+                alias: string;
+            }>;
+        }>;
+    }>;
+    roles?: Array<{
+        alias: string;
+    }>;
+}
+/**
+ * Generate the full package `.lotics/app_fields.ts` source. Valid contract
+ * aliases are slug-grammar (`^[a-z][a-z0-9_]*$`) and emit as bare identifiers
+ * — but this also runs on unvalidated DRAFTS (dev/sync pre-publish), so every
+ * key goes through `propKey`, which quotes anything that isn't a valid
+ * identifier instead of emitting broken TypeScript into a "DO NOT EDIT" file.
+ * Pure; same contract → same bytes.
+ */
+export declare function generatePackageAppFields(contract: PackageContractShape): string;

package/dist/generate_package_fields.js

@@ -0,0 +1,104 @@
+/**
+ * Codegen: emit a RUNTIME `.lotics/app_fields.ts` for a PACKAGE project from
+ * its `contract.json`.
+ *
+ * The bespoke twin (`generate_app_fields.ts`) bakes this workspace's concrete
+ * `fld_…`/`opt_…` ids at authoring time — correct when source and workspace
+ * co-live, fundamentally wrong for a package (one bundle, many workspaces,
+ * different ids in each). A package project instead resolves the SAME `F` /
+ * `OPT` surface at MODULE LOAD from the installation's binding via the SDK's
+ * `getAppBinding()` (the `binding` RPC op), using top-level await — the ESM
+ * graph waits for the binding before any importer evaluates, so
+ * `F.TASKS.title` is a plain string everywhere, including module-top-level
+ * constants. Extracted bespoke sources therefore compile unchanged: same
+ * import path, same shapes, same alias naming (contract aliases derive from
+ * the same display names the bespoke codegen slugifies).
+ *
+ * A missing alias fails LOUD at boot (the binding is adopt/install-verified
+ * complete, so a miss means the generated file is stale relative to the
+ * installed contract version) — never a silent undefined key in a write.
+ *
+ * Requires the app build to target es2022+ (the starter's `build.target`) —
+ * top-level await does not exist below it.
+ */
+import { propKey } from "./generate_app_fields.js";
+const HEADER = `// Auto-generated by 'lotics package new/extract/dev/sync' from contract.json.
+// DO NOT EDIT — regenerated whenever the contract changes.
+//
+// Package apps resolve F/OPT/ROLE at MODULE LOAD from the installation's
+// binding (contract alias → THIS workspace's concrete id) via the SDK's
+// \`binding\` RPC. Top-level await: the module graph waits for the binding
+// before any importer evaluates, so every entry is a plain string.
+import { getAppBinding } from "@lotics/app-sdk";
+
+const binding = await getAppBinding();
+
+function bound(map: Record<string, string>, key: string, kind: string): string {
+  const id = map[key];
+  if (id === undefined) {
+    throw new Error(
+      \`app_fields: \${kind} "\${key}" is not in this installation's binding — \` +
+        \`the generated app_fields.ts is stale relative to the installed contract version.\`,
+    );
+  }
+  return id;
+}
+`;
+/**
+ * Generate the full package `.lotics/app_fields.ts` source. Valid contract
+ * aliases are slug-grammar (`^[a-z][a-z0-9_]*$`) and emit as bare identifiers
+ * — but this also runs on unvalidated DRAFTS (dev/sync pre-publish), so every
+ * key goes through `propKey`, which quotes anything that isn't a valid
+ * identifier instead of emitting broken TypeScript into a "DO NOT EDIT" file.
+ * Pure; same contract → same bytes.
+ */
+export function generatePackageAppFields(contract) {
+    const entities = contract.entities ?? [];
+    const roles = contract.roles ?? [];
+    const fieldBlocks = [];
+    for (const entity of entities) {
+        const lines = (entity.fields ?? []).map((field) => `    ${propKey(field.alias)}: bound(binding.fields, ${JSON.stringify(`${entity.alias}.${field.alias}`)}, "field"),`);
+        if (lines.length === 0)
+            continue;
+        fieldBlocks.push(`  ${propKey(entity.alias.toUpperCase())}: {\n${lines.join("\n")}\n  },`);
+    }
+    const optionBlocks = [];
+    for (const entity of entities) {
+        const perField = [];
+        for (const field of entity.fields ?? []) {
+            const options = field.options ?? [];
+            if (options.length === 0)
+                continue;
+            const lines = options.map((option) => `      ${propKey(option.alias)}: bound(binding.options, ${JSON.stringify(`${entity.alias}.${field.alias}:${option.alias}`)}, "option"),`);
+            perField.push(`    ${propKey(field.alias)}: {\n${lines.join("\n")}\n    },`);
+        }
+        if (perField.length > 0) {
+            optionBlocks.push(`  ${propKey(entity.alias.toUpperCase())}: {\n${perField.join("\n")}\n  },`);
+        }
+    }
+    const fMap = fieldBlocks.length > 0
+        ? `export const F = {\n${fieldBlocks.join("\n")}\n} as const;`
+        : `export const F = {} as const;`;
+    const optMap = optionBlocks.length > 0
+        ? `export const OPT = {\n${optionBlocks.join("\n")}\n} as const;`
+        : `export const OPT = {} as const;`;
+    const roleMap = roles.length > 0
+        ? `export const ROLE = {\n${roles
+            .map((role) => `  ${propKey(role.alias)}: bound(binding.roles, ${JSON.stringify(role.alias)}, "role"),`)
+            .join("\n")}\n} as const;`
+        : `export const ROLE = {} as const;`;
+    return `${HEADER}
+${fMap}
+
+${optMap}
+
+${roleMap}
+
+/** Field-id alias map: \`F[<ENTITY>][<field>]\` is this installation's \`fld_…\` id. */
+export type AppFields = typeof F;
+/** Select-option alias map: \`OPT[<ENTITY>][<field>][<option>]\` is this installation's \`opt_…\` id. */
+export type AppOptions = typeof OPT;
+/** Role alias map: \`ROLE[<role>]\` is this installation's \`grp_…\` id. */
+export type AppRoles = typeof ROLE;
+`;
+}

package/dist/generate_package_fields.test.d.ts

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

package/dist/generate_package_fields.test.js

@@ -0,0 +1,51 @@
+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" }],
+};
+describe("generatePackageAppFields", () => {
+    it("emits runtime-resolved F/OPT/ROLE keyed by contract aliases", () => {
+        const src = generatePackageAppFields(contract);
+        // 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();");
+        // F: uppercased entity alias, fully-qualified binding keys.
+        expect(src).toContain('title: bound(binding.fields, "tasks.title", "field")');
+        expect(src).toContain('name: bound(binding.fields, "projects.name", "field")');
+        expect(src).toMatch(/TASKS: \{/);
+        expect(src).toMatch(/PROJECTS: \{/);
+        // OPT: qualified entity.field:opt keys; option-less fields absent.
+        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.
+        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({});
+        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));
+    });
+});

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 {};