@seamlet/astro 0.10.0 → 0.11.0

package/README.md

@@ -4,6 +4,15 @@ Connects an [Astro](https://astro.build) site to the Seamlet CMS ([source](https
 
 ## How a site connects
 
+The quick way, in an Astro project:
+
+```bash
+npx @seamlet/astro init --title "Кофейня «Зерно»"   # seamlet.json, src/schema.ts, src/seamlet.ts, a first page component
+npx astro add @seamlet/astro node                   # the integration, and an adapter for the preview
+```
+
+`init` takes the id from the name in `package.json` unless `--id` gives it, and the CMS `https://cms.seamlet.ru` unless `--cms` names another; it never overwrites a file the site has, and says what to render in a page. The steps below are what it starts, one by one.
+
 1. Install the package. The site needs an adapter, because the preview is rendered on request; its own pages may stay static.
 
    ```bash
@@ -89,7 +98,7 @@ Connects an [Astro](https://astro.build) site to the Seamlet CMS ([source](https
    });
    ```
 
-The site's pages take their published content with `site.loadPublishedContent()`: at build time for a static site, on request otherwise. A module that needs the content without importing every page takes it with `loadPublishedContent(schema)` of `@seamlet/astro/site`.
+The site's pages take their published content with `site.loadPublishedContent()`: at build time for a static site, on request otherwise. Until the first publication, and while the CMS does not know the site yet (a site connected from its repository is built before that), it is the site's initial content; any other refusal of the CMS stops the build. A module that needs the content without importing every page takes it with `loadPublishedContent(schema)` of `@seamlet/astro/site`.
 
 ## Fields
 

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.js

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+import {
+  SITE_CONFIG_FILE,
+  isSiteId,
+  readSiteConfig
+} from "./chunk-DRDPKFHZ.js";
+
+// src/cli.ts
+import process from "process";
+
+// src/init/init-command.ts
+import { readFile } from "fs/promises";
+import { join as join2 } from "path";
+import { parseArgs } from "util";
+
+// src/init/site-files.ts
+var SITE_MODULE_PATH = "src/seamlet.ts";
+var SCHEMA_PATH = "src/schema.ts";
+var HOME_PAGE_PATH = "src/components/HomePage.astro";
+var JSON_INDENT = 2;
+function siteFilesOf(config) {
+  return [
+    {
+      path: SITE_CONFIG_FILE,
+      text: `${JSON.stringify(config, null, JSON_INDENT)}
+`
+    },
+    { path: SCHEMA_PATH, text: schemaModuleOf(config.title) },
+    { path: SITE_MODULE_PATH, text: SITE_MODULE },
+    { path: HOME_PAGE_PATH, text: HOME_PAGE }
+  ];
+}
+function siteIdOf(packageName) {
+  const unscoped = packageName.replace(/^@[^/]+\//u, "");
+  const id = unscoped.toLowerCase().replace(/[^a-z0-9]+/gu, "-").replace(/^-+|-+$/gu, "");
+  return isSiteId(id) ? id : void 0;
+}
+function schemaModuleOf(title) {
+  return `import { defineSchema, text, type ContentOf } from "@seamlet/astro/schema";
+
+// What the site's owner edits in the CMS. Add a field here, show it on a page and mark its element
+// with edit(...): the CMS builds its form from this schema alone.
+export const schema = defineSchema({
+  title: text({ label: "\u0417\u0430\u0433\u043E\u043B\u043E\u0432\u043E\u043A", maxLength: 80 }),
+});
+
+export type Content = ContentOf<typeof schema>;
+
+/** What the site shows, and the CMS edits, until the first publication. */
+export const initialContent: Content = {
+  title: ${JSON.stringify(title)},
+};
+`;
+}
+var SITE_MODULE = `import { defineSeamletSite } from "@seamlet/astro/site";
+import HomePage from "./components/HomePage.astro";
+import { initialContent, schema } from "./schema";
+
+// The site as the CMS knows it: its schema, the content it starts with and its pages (its id and
+// title are in seamlet.json). Every page is a component that takes the content as its prop.
+export default defineSeamletSite({
+  schema,
+  initialContent,
+  pages: {
+    "/": { title: "\u0413\u043B\u0430\u0432\u043D\u0430\u044F", component: HomePage },
+  },
+});
+`;
+var HOME_PAGE = `---
+import { editable } from "@seamlet/astro/schema";
+import type { Content } from "../schema";
+
+interface Props {
+  content: Content;
+}
+
+const { content } = Astro.props;
+// The CMS's editor lets the owner click the marked elements; a path the content lacks does not compile.
+const edit = editable<Content>();
+---
+
+<h1 {...edit("title")}>{content.title}</h1>
+`;
+
+// src/init/write-site-files.ts
+import { mkdir, writeFile } from "fs/promises";
+import { dirname, join } from "path";
+var ALREADY_EXISTS = "EEXIST";
+async function writeSiteFiles(root, files) {
+  const written = [];
+  const kept = [];
+  for (const file of files) {
+    const isWritten = await writeNewFile(join(root, file.path), file.text);
+    (isWritten ? written : kept).push(file.path);
+  }
+  return { written, kept };
+}
+async function writeNewFile(path, text) {
+  await mkdir(dirname(path), { recursive: true });
+  try {
+    await writeFile(path, text, { flag: "wx" });
+    return true;
+  } catch (error) {
+    if (isAlreadyThere(error)) return false;
+    throw new Error(`@seamlet/astro: cannot write ${path}`, { cause: error });
+  }
+}
+function isAlreadyThere(error) {
+  return error instanceof Error && "code" in error && error.code === ALREADY_EXISTS;
+}
+
+// src/init/init-command.ts
+var DEFAULT_CMS = "https://cms.seamlet.ru";
+var SUCCESS = 0;
+var FAILURE = 1;
+var MISUSE = 2;
+var USAGE = `Usage: npx @seamlet/astro init [--id <id>] [--title <title>] [--cms <address>]
+
+Writes ${SITE_CONFIG_FILE} and a first module of the site in the Astro project here. The id is the
+site's name in the CMS (lower-case letters, digits and hyphens); by default it comes from the
+name in package.json, the title from the id, the CMS is ${DEFAULT_CMS}.`;
+var NEXT_STEPS = `
+Next:
+  npx astro add @seamlet/astro node    the integration, and an adapter for the preview
+  render a page with its content, such as src/pages/index.astro:
+    ---
+    import site from "../seamlet";
+    import HomePage from "../components/HomePage.astro";
+    const content = await site.loadPublishedContent();
+    ---
+    <HomePage content={content} />`;
+async function runInit(run) {
+  const options = optionsOf(run.argv);
+  if (options === void 0) {
+    run.log(USAGE);
+    return MISUSE;
+  }
+  const packageName = await packageNameOf(run.root);
+  const id = options.id ?? siteIdOf(packageName ?? "");
+  const reading = readSiteConfig({
+    id,
+    title: options.title ?? id,
+    cms: options.cms ?? DEFAULT_CMS
+  });
+  if (reading.status === "invalid") {
+    const fields = reading.invalidFields.map((field) => `--${field}`).join(", ");
+    run.log(`Give the site ${fields}.
+
+${USAGE}`);
+    return FAILURE;
+  }
+  const files = await writeSiteFiles(run.root, siteFilesOf(reading.config));
+  for (const path of files.written) run.log(`wrote ${path}`);
+  for (const path of files.kept)
+    run.log(`kept ${path}: the site has it already`);
+  run.log(NEXT_STEPS);
+  return SUCCESS;
+}
+function optionsOf(argv) {
+  try {
+    const { positionals, values } = parseArgs({
+      args: [...argv],
+      allowPositionals: true,
+      options: {
+        id: { type: "string" },
+        title: { type: "string" },
+        cms: { type: "string" }
+      }
+    });
+    const isInit = positionals.length === 1 && positionals[0] === "init";
+    return isInit ? { id: values.id, title: values.title, cms: values.cms } : void 0;
+  } catch {
+    return void 0;
+  }
+}
+async function packageNameOf(root) {
+  try {
+    const manifest = JSON.parse(
+      await readFile(join2(root, "package.json"), "utf8")
+    );
+    const name = manifest?.name;
+    return typeof name === "string" ? name : void 0;
+  } catch {
+    return void 0;
+  }
+}
+
+// src/cli.ts
+var code = await runInit({
+  root: process.cwd(),
+  argv: process.argv.slice(2),
+  log: (line) => {
+    console.log(line);
+  }
+});
+process.exitCode = code;

package/dist/site.d.ts

@@ -40,7 +40,8 @@ interface SeamletSite<F extends Fields = Fields> {
 declare function defineSeamletSite<F extends Fields>(definition: SeamletSiteDefinition<F>): SeamletSite<F>;
 /**
  * What the CMS published for the site, in the shape of its schema: the site's initial content until
- * the first publication. For a module that needs the content without the pages.
+ * the first publication, and while the CMS does not know the site yet. For a module that needs the
+ * content without the pages.
  */
 declare function loadPublishedContent<F extends Fields>(schema: F): Promise<ContentOf<F>>;
 

package/dist/site.js

@@ -5,6 +5,27 @@ import {
 // src/site.ts
 import { cmsOrigin, siteId, siteTitle } from "virtual:seamlet/config";
 
+// src/published-answers.ts
+var NOT_FOUND = 404;
+var UNKNOWN_SITE = "unknown-site";
+async function readPublishedAnswer(response, url) {
+  if (response.ok)
+    return { status: "published", content: await response.json() };
+  const isUnknownSite = response.status === NOT_FOUND && await errorOf(response) === UNKNOWN_SITE;
+  if (isUnknownSite) return { status: "unknown-site" };
+  throw new Error(
+    `Loading the published content from ${url.href} failed with status ${String(response.status)}`
+  );
+}
+async function errorOf(response) {
+  try {
+    const body = await response.json();
+    return typeof body === "object" && body !== null ? body.error : void 0;
+  } catch {
+    return void 0;
+  }
+}
+
 // src/site-descriptions.ts
 function describeSite(identity, definition) {
   const pages = Object.entries(definition.pages).map(
@@ -41,18 +62,17 @@ function defineSeamletSite(definition) {
   };
 }
 async function loadPublishedContent(schema) {
-  const published = await fetchPublished(siteId);
-  return parseContent(schema, published).content;
+  const url = new URL(`/api/sites/${siteId}/published`, cmsOrigin);
+  const answer = await readPublishedAnswer(await fetch(url), url);
+  const content = answer.status === "published" ? answer.content : await initialContentOfSite();
+  return parseContent(schema, content).content;
 }
-async function fetchPublished(id) {
-  const url = new URL(`/api/sites/${id}/published`, cmsOrigin);
-  const response = await fetch(url);
-  if (!response.ok) {
-    throw new Error(
-      `Loading the published content from ${url.href} failed with status ${String(response.status)}`
-    );
-  }
-  return response.json();
+async function initialContentOfSite() {
+  console.warn(
+    `@seamlet/astro: the CMS at ${cmsOrigin} does not know the site "${siteId}" yet; its initial content is shown`
+  );
+  const { default: site } = await import("virtual:seamlet/site");
+  return site.description.initialContent;
 }
 export {
   defineSeamletSite,

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "@seamlet/astro",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Connects an Astro site to the Seamlet CMS: the schema of its content, the preview the editor frames, and its published content.",
   "license": "MIT",
   "type": "module",
+  "bin": {
+    "seamlet-astro": "./dist/cli.js"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/seamlet/sdk.git",