@decocms/eitri 7.20.0

package/README.md

@@ -0,0 +1,123 @@
+# `@decocms/eitri`
+
+Deco binding for the **Eitri** mobile stack. Unlike `@decocms/nextjs` /
+`@decocms/tanstack`, this package does **not** render anything — Eitri renders
+sections natively on its own mobile runtime. `@decocms/eitri` only *produces a
+well-filled `.deco`* so Studio can author content against your Eitri sections:
+
+- a **self-contained** `.deco/meta.gen.json` (section schemas **plus** the
+  framework block types — Page, matchers, `Resolvable`, the section picker —
+  baked in, so an FS-based Studio reads it verbatim with no runtime), and
+- the bundled `.deco/blocks.gen.json` decofile snapshot the Eitri runtime
+  consumes.
+
+It is a thin, Eitri-flavored wrapper over `@decocms/blocks-cli`'s `generate`
+orchestrator (`--platform eitri`). See
+[`docs/eitri-stack-design.md`](../../docs/eitri-stack-design.md) for the full
+design.
+
+## What Eitri owns vs. what deco owns
+
+| | Owner |
+|---|---|
+| Section `Props` → JSON Schema, decofile snapshot (`.deco`) | **`@decocms/eitri`** (this package) |
+| Authoring content (forms, page composition) | Studio (reads `.deco`) |
+| Fetching the decofile on-device + rendering sections | **Eitri platform / your app** |
+
+There is intentionally **no runtime SDK** here.
+
+## Sections
+
+An Eitri section is exactly a deco section: a default-exported component in
+`src/sections/**` with an exported `Props` interface documented with JSDoc.
+
+```tsx
+// src/sections/Banners/Hero.tsx
+import { Image, View } from "eitri-luminus";
+
+export interface Props {
+  /** @title Hero image. */
+  image: string;
+  /** @title Alt text. */
+  alt?: string;
+  /** @title Publish date. @format datetime */
+  datetime?: string;
+}
+
+export default function HeroBanner({ image, alt }: Props) {
+  return <View><Image src={image} alt={alt} /></View>;
+}
+```
+
+`@title`, `@format` (e.g. `textarea`, `datetime` → normalized to `date-time`),
+and the other JSDoc widget tags drive the Studio form. Sections may be `.tsx`,
+`.ts`, `.jsx`, or `.js`.
+
+## Install
+
+```bash
+# in your Eitri app (as a dev tool)
+npm i -D @decocms/eitri
+```
+
+## Setup
+
+```bash
+npx deco-eitri init
+```
+
+This scaffolds (never overwriting existing files):
+
+- `tsconfig.json` extending `@decocms/eitri/tsconfig` — **required**;
+  `generate-schema` needs a tsconfig to parse your `Props` types.
+- `src/eitri-env.d.ts` — ambient shims for `eitri-luminus` / `eitri-bifrost` so
+  your editor and `tsc` don't flag those imports. Purely ergonomic; generation
+  works without it. Delete it if you install the real `eitri-luminus` types.
+
+If you prefer to wire it by hand, your `tsconfig.json` need only be:
+
+```json
+{ "extends": "@decocms/eitri/tsconfig", "include": ["src"] }
+```
+
+## Generate
+
+```bash
+# from the app root
+npx deco-eitri generate
+
+# or, targeting a sub-app in a monorepo without cd:
+npx deco-eitri generate --root eitri-shopping-monte-carlo-shared
+```
+
+Add it as a script:
+
+```json
+{ "scripts": { "deco:generate": "deco-eitri generate" } }
+```
+
+Output under `.deco/`:
+
+- `meta.gen.json` — self-contained schema (`framework: "eitri"`).
+- `blocks.gen.json` — decofile snapshot (starts as `{}` for a fresh app; Studio
+  fills it as content is authored).
+- `generate.digests.json` — the incremental-generation cache (commit it).
+
+The React-runtime artifacts (`sections.gen.ts`, `blocksManifest.gen.ts`,
+`loaders.gen.ts`, `invoke.gen.ts`) are intentionally **not** produced — Eitri
+doesn't use them.
+
+## Programmatic API
+
+```ts
+import { generateEitri } from "@decocms/eitri";
+
+const code = await generateEitri({ root: "path/to/app", force: true });
+```
+
+## Flags
+
+`deco-eitri generate` forwards every `@decocms/blocks-cli` `generate` flag
+(`--root`, `--force`, `--dry-run`, `--sections-dir`, `--namespace`, `--site`,
+…). Run `npx deco-eitri generate --help` for the full list. `--platform eitri`
+is always applied.

package/configs/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "//": "Base tsconfig for Eitri apps that generate a .deco with @decocms/eitri. Extend it from your app root: { \"extends\": \"@decocms/eitri/tsconfig\", \"include\": [\"src\"] }. generate-schema (ts-morph) reads this to parse section Props interfaces. allowJs + checkJs:false because Eitri apps are mostly plain JS with .tsx sections; skipLibCheck because eitri-luminus/eitri-bifrost types are shimmed, not installed.",
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "react-jsx",
+    "allowJs": true,
+    "checkJs": false,
+    "strict": false,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "isolatedModules": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true
+  }
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@decocms/eitri",
+  "version": "7.20.0",
+  "type": "module",
+  "description": "Deco binding for the Eitri mobile stack: produces a well-filled .deco (self-contained schema + decofile snapshot) so Studio can author content. No rendering — Eitri renders natively.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/decocms/blocks.git",
+    "directory": "packages/eitri"
+  },
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./tsconfig": "./configs/tsconfig.json",
+    "./types": "./types/eitri-luminus.d.ts"
+  },
+  "bin": {
+    "deco-eitri": "./src/cli.ts"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run --root ../.. packages/eitri/",
+    "typecheck": "tsc --noEmit",
+    "lint:unused": "knip"
+  },
+  "dependencies": {
+    "@decocms/blocks-cli": "7.20.0",
+    "tsx": "^4.22.5"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.0",
+    "knip": "^5.86.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,77 @@
+#!/usr/bin/env tsx
+/**
+ * `deco-eitri` — CLI for producing a Studio-ready `.deco` from an Eitri app.
+ *
+ *   deco-eitri init [--root <dir>]
+ *       Scaffold tsconfig.json (+ src/eitri-env.d.ts shim). Idempotent.
+ *
+ *   deco-eitri generate [--root <dir>] [--force] [any generate flags]
+ *       Run the blocks-cli orchestrator with --platform eitri: emits a
+ *       self-contained .deco/meta.gen.json + the .deco/blocks.gen.json
+ *       snapshot, skipping the React-runtime generators.
+ *
+ * `generate` forwards every flag through to @decocms/blocks-cli's `generate`
+ * (see `deco-eitri generate --help`), only ensuring --platform eitri is set.
+ */
+import { runGenerate } from "@decocms/blocks-cli/generate";
+import { runEitriInit } from "./init";
+
+const USAGE = `\
+deco-eitri — produce a Studio-ready .deco for an Eitri app
+
+Usage:
+  deco-eitri init [--root <dir>]
+      Scaffold tsconfig.json (extends @decocms/eitri/tsconfig) and a
+      src/eitri-env.d.ts shim. Never overwrites existing files.
+
+  deco-eitri generate [--root <dir>] [--force] [...generate flags]
+      Generate .deco (self-contained meta.gen.json + blocks.gen.json snapshot)
+      with --platform eitri. All @decocms/blocks-cli generate flags are
+      forwarded; run \`deco-eitri generate --help\` for the full list.
+`;
+
+/** Pull `--root <dir>` out of an argv slice (used by init). */
+function valueFlag(argv: string[], flag: string): string | undefined {
+  const i = argv.indexOf(flag);
+  return i !== -1 ? argv[i + 1] : undefined;
+}
+
+async function main(): Promise<number> {
+  const [command, ...rest] = process.argv.slice(2);
+
+  if (!command || command === "--help" || command === "-h") {
+    console.log(USAGE);
+    return command ? 0 : 1;
+  }
+
+  if (command === "init") {
+    const { created, skipped } = runEitriInit({ root: valueFlag(rest, "--root") });
+    for (const f of created) console.log(`[deco-eitri] created ${f}`);
+    for (const f of skipped) console.log(`[deco-eitri] skipped ${f} (already exists)`);
+    console.log(
+      created.length
+        ? "[deco-eitri] init done — run `deco-eitri generate` to produce .deco"
+        : "[deco-eitri] init: nothing to do (already set up)",
+    );
+    return 0;
+  }
+
+  if (command === "generate") {
+    // Forward everything to the orchestrator, guaranteeing --platform eitri.
+    const args = rest.includes("--platform") ? rest : ["--platform", "eitri", ...rest];
+    return runGenerate(args);
+  }
+
+  console.error(`[deco-eitri] unknown command "${command}"\n`);
+  console.error(USAGE);
+  return 1;
+}
+
+main()
+  .then((code) => {
+    process.exitCode = code;
+  })
+  .catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });

package/src/index.ts

@@ -0,0 +1,49 @@
+/**
+ * @decocms/eitri — programmatic entry.
+ *
+ * Deco does not render Eitri apps (Eitri renders natively on its mobile
+ * runtime); this package only *produces* a well-filled `.deco` so Studio can
+ * author content. It is a thin, Eitri-flavored wrapper over
+ * `@decocms/blocks-cli`'s `generate` orchestrator: `--platform eitri` selects
+ * the schema + blocks generators only and emits a SELF-CONTAINED
+ * `meta.gen.json` (Page, matchers, Resolvable baked in via composeMeta), plus
+ * the bundled `blocks.gen.json` snapshot the Eitri runtime consumes.
+ *
+ * The CLI (`deco-eitri`) is the usual entry; this function is for scripting.
+ */
+import { runGenerate } from "@decocms/blocks-cli/generate";
+
+export interface GenerateEitriOptions {
+  /** App folder to generate for (input dirs + `.deco/` resolve against it). */
+  root?: string;
+  /** Site name written into the schema (default: blocks-cli's default). */
+  site?: string;
+  /** Section namespace (default: "site"). */
+  namespace?: string;
+  /** Ignore the incremental cache and regenerate. */
+  force?: boolean;
+  /** Extra raw flags forwarded verbatim to the orchestrator. */
+  extraArgs?: string[];
+}
+
+/** Build the orchestrator argv for an Eitri generation run. */
+export function eitriGenerateArgs(opts: GenerateEitriOptions = {}): string[] {
+  const args = ["--platform", "eitri"];
+  if (opts.root) args.push("--root", opts.root);
+  if (opts.site) args.push("--site", opts.site);
+  if (opts.namespace) args.push("--namespace", opts.namespace);
+  if (opts.force) args.push("--force");
+  if (opts.extraArgs?.length) args.push(...opts.extraArgs);
+  return args;
+}
+
+/**
+ * Generate the `.deco` for an Eitri app. Resolves to the process exit code
+ * (0 = success), mirroring the CLI.
+ */
+export function generateEitri(opts: GenerateEitriOptions = {}): Promise<number> {
+  return runGenerate(eitriGenerateArgs(opts));
+}
+
+export { runEitriInit } from "./init";
+export type { EitriInitOptions, EitriInitResult } from "./init";

package/src/init.test.ts

@@ -0,0 +1,71 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { eitriGenerateArgs } from "./index";
+import { runEitriInit } from "./init";
+
+describe("eitriGenerateArgs", () => {
+  it("always applies --platform eitri", () => {
+    expect(eitriGenerateArgs()).toEqual(["--platform", "eitri"]);
+  });
+
+  it("maps options onto orchestrator flags", () => {
+    expect(
+      eitriGenerateArgs({ root: "apps/foo", site: "monte", namespace: "site", force: true }),
+    ).toEqual([
+      "--platform",
+      "eitri",
+      "--root",
+      "apps/foo",
+      "--site",
+      "monte",
+      "--namespace",
+      "site",
+      "--force",
+    ]);
+  });
+
+  it("appends extra raw flags verbatim", () => {
+    expect(eitriGenerateArgs({ extraArgs: ["--dry-run"] })).toEqual([
+      "--platform",
+      "eitri",
+      "--dry-run",
+    ]);
+  });
+});
+
+describe("runEitriInit", () => {
+  let dir: string;
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), "eitri-init-"));
+  });
+  afterEach(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("scaffolds tsconfig.json + src/eitri-env.d.ts on a fresh app", () => {
+    const res = runEitriInit({ root: dir });
+    expect(res.created).toEqual(["tsconfig.json", path.join("src", "eitri-env.d.ts")]);
+    expect(res.skipped).toEqual([]);
+
+    const tsconfig = JSON.parse(fs.readFileSync(path.join(dir, "tsconfig.json"), "utf-8"));
+    expect(tsconfig.extends).toBe("@decocms/eitri/tsconfig");
+    expect(tsconfig.include).toEqual(["src"]);
+
+    const shim = fs.readFileSync(path.join(dir, "src", "eitri-env.d.ts"), "utf-8");
+    expect(shim).toContain('declare module "eitri-luminus"');
+    expect(shim).toContain('declare module "eitri-bifrost"');
+  });
+
+  it("is idempotent — never overwrites existing files", () => {
+    fs.writeFileSync(path.join(dir, "tsconfig.json"), '{"custom":true}\n');
+    const res = runEitriInit({ root: dir });
+    expect(res.skipped).toContain("tsconfig.json");
+    expect(res.created).toEqual([path.join("src", "eitri-env.d.ts")]);
+    // The pre-existing tsconfig is left untouched.
+    expect(JSON.parse(fs.readFileSync(path.join(dir, "tsconfig.json"), "utf-8"))).toEqual({
+      custom: true,
+    });
+  });
+});

package/src/init.ts

@@ -0,0 +1,69 @@
+/**
+ * `deco-eitri init` — scaffold the two files an Eitri app needs to generate a
+ * `.deco`, without touching anything that already exists (idempotent):
+ *
+ *   1. `tsconfig.json` extending `@decocms/eitri/tsconfig` — required by
+ *      generate-schema (ts-morph needs a tsconfig to build the program).
+ *   2. `src/eitri-env.d.ts` — a copy of the eitri-luminus/bifrost ambient
+ *      shims, dropped inside `src/` so the app's `include: ["src"]` picks it up
+ *      with no node_modules path gymnastics. Purely editor/tsc ergonomics —
+ *      generation works without it.
+ *
+ * Never overwrites an existing file, so it's safe to re-run.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export interface EitriInitOptions {
+  /** App root to scaffold into. Defaults to process.cwd(). */
+  root?: string;
+}
+
+export interface EitriInitResult {
+  /** Files created this run (relative to root). */
+  created: string[];
+  /** Files that already existed and were left untouched (relative to root). */
+  skipped: string[];
+}
+
+const APP_TSCONFIG = `${JSON.stringify(
+  {
+    extends: "@decocms/eitri/tsconfig",
+    include: ["src"],
+  },
+  null,
+  2,
+)}\n`;
+
+/** Absolute path to the packaged ambient shim (../types/eitri-luminus.d.ts). */
+function packagedShimPath(): string {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(here, "..", "types", "eitri-luminus.d.ts");
+}
+
+export function runEitriInit(opts: EitriInitOptions = {}): EitriInitResult {
+  const root = path.resolve(opts.root ?? process.cwd());
+  const created: string[] = [];
+  const skipped: string[] = [];
+
+  const write = (rel: string, contents: string) => {
+    const abs = path.join(root, rel);
+    if (fs.existsSync(abs)) {
+      skipped.push(rel);
+      return;
+    }
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, contents);
+    created.push(rel);
+  };
+
+  write("tsconfig.json", APP_TSCONFIG);
+
+  // Copy the shim content (not a reference) so the app file is self-contained
+  // and immune to node_modules path resolution quirks.
+  const shim = fs.readFileSync(packagedShimPath(), "utf-8");
+  write(path.join("src", "eitri-env.d.ts"), shim);
+
+  return { created, skipped };
+}

package/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist"
+  },
+  "include": ["src/**/*"]
+}

package/types/eitri-luminus.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Ambient shims for the Eitri runtime libraries.
+ *
+ * Eitri apps import UI primitives from `eitri-luminus` and the native SDK from
+ * `eitri-bifrost`/`eitri-commons`, but those packages are resolved by the
+ * external `eitri-cli` toolchain, not installed in the app's node_modules. When
+ * generating a `.deco` we only need the section `Props` interfaces (which use
+ * plain primitives), so these shims exist purely to keep an author's editor and
+ * `tsc` from erroring on the imports — they are intentionally loose (`any`).
+ *
+ * `deco-eitri init` copies this file into your app's `src/` (as
+ * `eitri-env.d.ts`) so it is picked up by `include: ["src"]` with no path
+ * gymnastics. If you install the real `eitri-luminus` types, delete the copy.
+ */
+declare module "eitri-luminus" {
+  // Every luminus component (View, Text, Image, Page, Button, ...) is exposed
+  // as a permissive component type. Named + default imports both resolve.
+  const luminus: Record<string, any>;
+  export = luminus;
+}
+
+declare module "eitri-bifrost" {
+  const Eitri: any;
+  export default Eitri;
+  export = Eitri;
+}
+
+declare module "eitri-commons" {
+  const commons: any;
+  export = commons;
+}