@niscorp/cli 0.2.2 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,51 @@
1
1
  # @niscorp/cli
2
2
 
3
+ ## 0.3.0
4
+
5
+ ### Minor Changes
6
+
7
+ - f1cec45: A Prism config that validates no longer names an op Prism does not have. `validate` accepted `{ card: { $fetch: … } }` and `{ $eval: "…" }`: the plain-object branch refused only the names of ops that exist, so any other `$` key passed as a template key. Such a config could be stored — an endpoint request, a vex mapping, a strata migration — and then failed every time it was evaluated (`E_NODE_SHAPE`, "Unsupported node shape").
8
+
9
+ A key that starts with `$` is now an op's name and nothing else. The template branch refuses every `$` key — the rule the evaluator already held — so `validate` reports it with the key and where it is (`card.$fetch: Not a Prism op. A key that starts with "$" names an op; data with such a key goes in $const.`), and `evaluate` and `compile` fail with `E_SCHEMA` before anything runs. An op's name used as a template key keeps its own message. `E_NODE_SHAPE` is left for a tree that never went through the schema: an IR handed to `execute`. Adding an op no longer takes a key away from templates.
10
+ - **prism** — the change, and a grammar narrowing: `nisc.prism` 2, a marker with no document step (a key that never evaluated has nothing to be rewritten to). `$` keys that are data are untouched: a `$const` payload, `$with` names, `$renameKeys` and `$fromEntries` keys. The JSON Schema's template key pattern is `^(?!\$)` instead of a list of every op.
11
+ - **nova, vex, moss, loom, cli, nisc** — no change of their own. They depend on prism and are released with it, so the set installs together; the configs they hand to prism (endpoint `request` and `response`, `$prism` bindings, vex mappings) are held to the same rule.
12
+ - **create-nisc** — the templates' sources are recorded at `nisc.prism` 2.
13
+
14
+ **What to change:** in a config with a `$`-prefixed key that is not a Prism op, remove the key — or put the object in `$const` if it is literal data. An app that keeps a `strata.lock.json` runs `pnpm strata upgrade`, then `pnpm strata verify`; there is nothing to edit unless it has such a config. Everything else: nothing.
15
+
16
+ BREAKING — approved by moccadroid, 2026-10-04: a config with a `$`-prefixed key that is not a Prism op no longer validates, compiles or evaluates — also where evaluation never reached the key (an untaken `$case` branch, a short-circuited `$or`, a `$map` body over an empty array), which used to work. A vex seed mapping with one fails when it is seeded, at boot, instead of on each replay. Code that matched `E_NODE_SHAPE` from `evaluate` gets `E_SCHEMA`. The `@niscorp` packages that depend on prism move with it, so an app moves them together (`@niscorp/nisc` 0.3.0).
17
+
18
+ ### Patch Changes
19
+
20
+ - de6d980: A fix for the last fix: `nova:head` is the document's `<head>`, and holds what a head holds. 0.1.4 gave it five props (`title`, `description`, `image`, `kind`, `structured`) and wrote tags from them, which closed a head to whatever nova had been taught: no `og:image:alt`, no `og:type` but two, no whole address inside structured data. That was wrong, and it is replaced, not extended. The maintainer withdrew 0.1.4's props on 2026-10-04; this ships as a patch on that decision.
21
+
22
+ **What to change** (only an app that used 0.1.4's props): a `nova:head` node no longer takes props. Write its children instead — `nova:title`, `nova:meta`, `nova:link`, `nova:script` — each with the element's attributes as its props. `{ title: X }` becomes `{ component: 'nova:title', children: X }`; `description` becomes `nova:meta` with `name: 'description'`; `image` and `kind` become `nova:meta` with `property: 'og:image'` and `property: 'og:type'`; `structured` becomes `nova:script` with `type: 'application/ld+json'` and `data`. `og:title` and `og:description` are no longer written from the title and description: say them if they are wanted. An address is written as given — a picture's is not made whole from `site`. Code that called `headOf`, `placeHead` or `createTitleKeeper`, or read `head` off `renderDocument`'s result or a route report, takes the new shapes below.
23
+ - **nova** — a head's children are the elements a head holds, named as HTML names them, and **a child's props are that element's attributes, written as given**: nova keeps no list of them, so any `name`, `property` or `rel` can be said. Nothing in a head is drawn on the screen and no name has to be registered. With more than one head on a screen they are read in the order the screen is drawn, and an element that says the same thing as an earlier one (the title, a `<meta>` of that name or property, the canonical address) takes its place; anything else stands beside its like. What runs or styles is refused, left out and named: a script a browser would execute (`nova:script` is a data block — a JSON `type`, never a `src`), a stylesheet, `http-equiv`, a handler attribute. `headOf(api)` returns `{ elements, actions, refused }`. In `@niscorp/nova/document`, `placeHead(html, elements, { site, path })` writes them — an element takes the place of the tag that said the same thing, where it stood; what it wrote is marked `data-nova-head`, and a tag that gave way is kept inert in a `<template data-nova-own>` — and `createHeadKeeper(document)` replaces `createTitleKeeper`: the whole head follows the screen in the page, and the document's own tags come back when the screen stops saying them. Removed: the five props, the `Head` and `HeadProps` types, `createTitleKeeper`.
24
+ - **cli** — `build`, `export` and `start` write each path's head from those elements. A head that holds what it may not fails the path, like any other check. `site` still gives every path its own canonical address and `og:url`; it no longer touches a picture's address.
25
+ - **moss** — `renderDocument` and `exportDocuments` do the same from the snapshot (`head` on the result is `{ elements, actions, refused }`; a refusal is logged and left out), and the terminal keeps the whole head off the wire.
26
+ - **create-nisc** — the two own-shell templates write their welcome screen's head this way.
27
+
28
+ **Where a script goes:** in the app's own `index.html`, which holds anything and from which every page is written, or in the kit component that needs it. A layout is data and does not carry one.
29
+
30
+ - Updated dependencies [de6d980]
31
+ - Updated dependencies [f1cec45]
32
+ - @niscorp/nova@0.2.0
33
+ - @niscorp/moss@0.3.0
34
+
35
+ ## 0.2.3
36
+
37
+ ### Patch Changes
38
+
39
+ - af903c6: A page's head is its screen's own. `nisc export` wrote every path with the built `index.html`'s `<head>`, so a site with more than one page shipped each of them under the front page's title, description, preview card and canonical address.
40
+
41
+ What a screen says about itself is now a node in a layout: nova's `nova:head`, with `title`, `description`, `image`, `kind` and `structured` bound to the action's data like any other node's props. It draws nothing — no adapter builds an element for it, no registry has to hold it, and a component is never handed one as a child — and it rides in the render tree, so it reaches a shell in the page, a snapshot a server drew and the trees on a wire alike. `headOf(api)` reads it off any of them; with more than one on the screen the last one speaks.
42
+ - **nova** — `HEAD_NAME`, `HeadPropsSchema`, `HEAD_META`, `headOf`, `isHeadNode`; and `@niscorp/nova/document`: `placeHead` writes a head into an HTML document (the tag that said the same thing is replaced, a missing one is added before `</head>`, everything else is left as it was; values are escaped) and `createTitleKeeper` keeps a tab's title on it. The DOM, React and Vue adapters keep the title on the head as the screen moves, and give the page's own back when the screen has none.
43
+ - **cli** — `build`, `export` and `start` write each path's document with its screen's head. "Same twice" also fails a boot that says a different head the second time, and the route table says whose head each path goes out with once an app has one. New config field `site`: the address the site is served at. With it every path says its own canonical address (`<link rel="canonical">`, `og:url`) and a head's picture gets a whole address; a build with several paths, a canonical tag in `index.html` and no `site` says so.
44
+ - **moss** — `renderDocument` and `exportDocuments` do the same from the snapshot (`site` on the config, `head` on the result), and the terminal keeps the tab's title off the wire for every render target.
45
+ - **create-nisc** — the two own-shell templates say their welcome screen's head.
46
+
47
+ **What to change:** nothing. An app with no `nova:head` node and no `site` is built, served and drawn exactly as before. An app that rewrote its exported files to give each page a head can delete that step: put the node in the layout and set `site`.
48
+
3
49
  ## 0.2.2
4
50
 
5
51
  ### Patch Changes
package/README.md CHANGED
@@ -57,6 +57,7 @@ page in the manifest), and what each one needs once it has been drawn.
57
57
  | `boot` | stand the app up: `{ server, close? }` |
58
58
  | `draw` | a terminal that draws a screen to a string (moss's `terminal/react/server`, `/vue/server`, `/dom/server`) |
59
59
  | `htmlAttributes?` | what the kit would put on `<html>` from an effect (a palette, a scheme) |
60
+ | `site?` | the address the site is served at (`"https://example.com"`). With it, every path's document says its own canonical address — see "The head of each page" |
60
61
  | `paths?` | the paths to build. Default: `/` and every page whose path has no parameter. A page like `/docs/:slug` has as many paths as there are rows — list them here (`server.executeAs` runs a seeded read as a charter role) |
61
62
  | `routes?` | routes of the app's own that `nisc start` registers before the site (a sign-in handoff, a webhook) |
62
63
  | `dist?` | where the bundler writes the terminal (default `dist`) |
@@ -113,6 +114,7 @@ at all — nova's DOM adapter, `renderToString` from
113
114
  | `draw` | the shell, drawn to a string |
114
115
  | `adopt` | `(root, shell)` — the page picking the markup up |
115
116
  | `htmlAttributes?` | what the kit would put on `<html>` from an effect |
117
+ | `site?` | the address the site is served at (`"https://example.com"`) — see "The head of each page" |
116
118
  | `paths?` | the paths to build (default `/`) — an app that maps paths to actions lists its own |
117
119
  | `waitMs?` | how long a build waits for a screen to be whole (default 5000) |
118
120
  | `dist?`, `stylesheet?`, `checks?` | as above |
@@ -121,6 +123,55 @@ The built `index.html` must hold the empty root, `<div id="root"></div>` — tha
121
123
  is where a screen goes. The adoption check needs a DOM: `jsdom`, installed in
122
124
  the app.
123
125
 
126
+ ### The head of each page
127
+
128
+ Either kind. A page's `<head>` is a node in a layout — nova's `nova:head` —
129
+ and its children are the elements a head holds, bound to the action's data
130
+ like everything else on the screen:
131
+
132
+ ```typescript
133
+ { component: 'nova:head', children: [
134
+ { component: 'nova:title', children: '{{$.page.title}} · the site' },
135
+ { component: 'nova:meta', props: { name: 'description', content: '$.page.lead' } },
136
+ { component: 'nova:meta', props: { property: 'og:image', content: '$.page.card' } },
137
+ { component: 'nova:link', props: { rel: 'alternate', type: 'application/rss+xml', href: '/feed.xml' } },
138
+ { component: 'nova:script', props: { type: 'application/ld+json', data: '$.page.about' } },
139
+ ]}
140
+ ```
141
+
142
+ A child's props are that element's attributes, written as given — any `name`,
143
+ `property` or `rel`; nova keeps no list. Nothing in a head is drawn on the
144
+ screen, nothing is registered, and no code is written.
145
+
146
+ `build`, `export` and `start` read the elements off the screen they drew and
147
+ write them into the built `index.html`'s `<head>`. An element takes the place
148
+ of the tag that said the same thing — the `<title>`, a `<meta>` of that name or
149
+ property, the canonical address — where that tag stood; anything else is added
150
+ after what is there. Everything the screen does not speak of is left as
151
+ `index.html` has it. A path whose screen has no head goes out with
152
+ `index.html`'s own, and a build of an app that has one somewhere says which is
153
+ which.
154
+
155
+ Two things in a written file are for the page itself, which goes on living
156
+ after the file is read: what the screen said is marked (`data-nova-head`), and
157
+ a tag that gave up its place is kept, inert, in a `<template data-nova-own>`.
158
+ When the screen moves on to one that no longer says it, the document's own
159
+ comes back.
160
+
161
+ **What a head may not hold fails the build.** A layout is data: a script a
162
+ browser would run, a stylesheet, `http-equiv`, a handler attribute are refused,
163
+ and the path is not written. Those go in `index.html` — the app's own file,
164
+ which holds anything — or in the kit component that needs them.
165
+
166
+ **Where a page lives.** `site` in the config is the address the site is served
167
+ at. With it, every path's document says its own canonical address
168
+ (`<link rel="canonical">` and `og:url`), head or no head. Without it,
169
+ `index.html`'s canonical tag goes out in every file as it is — which, for every
170
+ path but one, names another page. A build with more than one path says so.
171
+
172
+ An app with no head node and no `site` is built exactly as it was before
173
+ either existed.
174
+
124
175
  The config is TypeScript, loaded with the app's own `tsconfig.json` — path
125
176
  aliases included. `nisc.config.mts`, `.js` and `.mjs` are found too. A config
126
177
  that hands over both `boot` and `shell` has not said which it is, and is
@@ -165,7 +216,7 @@ draws it, and checks what it drew:
165
216
  |---|---|
166
217
  | **drawn** | the boot threw, or the screen drew to nothing |
167
218
  | **whole** | something was still loading when `waitMs` ran out — a file that says "loading" is not the page |
168
- | **same twice** | a second boot drew different markup (it says where they part) — the page's boot would not match the file |
219
+ | **same twice** | a second boot drew different markup, or said a different head (it says where they part) — the page's boot would not match the file |
169
220
  | **adopted** | inside a DOM, a third boot ran the app's own `adopt` over the markup and the adapter complained: a hydration error, or a rebuilt root that is not what it was handed |
170
221
 
171
222
  And one that holds by construction: `shell` is handed a path and nothing else,
package/dist/adopt.js CHANGED
@@ -30,7 +30,7 @@ var main = async () => {
30
30
  const [root, asked, answered] = process.argv.slice(2);
31
31
  if (root === void 0 || asked === void 0 || answered === void 0) throw new Error("usage: adopt <root> <pages.json> <answer.json>");
32
32
  standDom(root);
33
- const { isShellProject, loadProject } = await import('./project-JN5KRG2G.js');
33
+ const { isShellProject, loadProject } = await import('./project-O5OEDRXN.js');
34
34
  const project = await loadProject(root);
35
35
  if (!isShellProject(project)) throw new Error("nisc: this app has no shell of its own to adopt with.");
36
36
  const pages = JSON.parse(readFileSync(asked, "utf8"));
@@ -11,6 +11,14 @@ var isProject = (value) => {
11
11
  const [moss, own] = [has(value, "boot"), has(value, "shell")];
12
12
  return moss !== own && (moss || has(value, "adopt"));
13
13
  };
14
+ var isSite = (value) => {
15
+ if (typeof value !== "string") return false;
16
+ try {
17
+ return ["http:", "https:"].includes(new URL(value).protocol);
18
+ } catch {
19
+ return false;
20
+ }
21
+ };
14
22
  var configFileOf = (root) => CONFIG_NAMES.find((name) => existsSync(join(root, name)));
15
23
  var loadProject = async (root) => {
16
24
  const name = configFileOf(root);
@@ -27,9 +35,12 @@ var loadProject = async (root) => {
27
35
  `nisc: ${file} does not export a \`project\` the command can run. It hands over EITHER \`boot\` + \`draw\` (an app behind moss) OR \`shell\` + \`draw\` + \`adopt\` (an app with its own shell).`
28
36
  );
29
37
  }
38
+ if (project.site !== void 0 && !isSite(project.site)) {
39
+ throw new Error(`nisc: ${file} gives \`site\` as ${JSON.stringify(project.site)} \u2014 it is the address the site is served at, whole: "https://example.com".`);
40
+ }
30
41
  return project;
31
42
  };
32
43
 
33
44
  export { configFileOf, isProject, isShellProject, loadProject };
34
- //# sourceMappingURL=chunk-5INZ3VGX.js.map
35
- //# sourceMappingURL=chunk-5INZ3VGX.js.map
45
+ //# sourceMappingURL=chunk-DTDMQJAO.js.map
46
+ //# sourceMappingURL=chunk-DTDMQJAO.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"sources":["../src/project.ts"],"names":[],"mappings":";;;;;AA4GA,IAAM,YAAA,GAAe,CAAC,gBAAA,EAAkB,iBAAA,EAAmB,kBAAkB,iBAAiB,CAAA;AAE9F,IAAM,GAAA,GAAM,CAAC,KAAA,EAAe,GAAA,KAAyB,OAAO,OAAA,CAAQ,GAAA,CAAI,KAAA,EAAO,GAAG,CAAA,KAAM,UAAA;AAEjF,IAAM,cAAA,GAAiB,CAAC,OAAA,KAAsD,OAAA,IAAW;AAEzF,IAAM,SAAA,GAAY,CAAC,KAAA,KAAyC;AACjE,EAAA,IAAI,KAAA,KAAU,IAAA,IAAQ,OAAO,KAAA,KAAU,QAAA,IAAY,CAAC,GAAA,CAAI,KAAA,EAAO,MAAM,CAAA,EAAG,OAAO,KAAA;AAC/E,EAAA,MAAM,CAAC,IAAA,EAAM,GAAG,CAAA,GAAI,CAAC,GAAA,CAAI,KAAA,EAAO,MAAM,CAAA,EAAG,GAAA,CAAI,KAAA,EAAO,OAAO,CAAC,CAAA;AAE5D,EAAA,OAAO,IAAA,KAAS,GAAA,KAAQ,IAAA,IAAQ,GAAA,CAAI,OAAO,OAAO,CAAA,CAAA;AACpD;AAGA,IAAM,MAAA,GAAS,CAAC,KAAA,KAA4B;AAC1C,EAAA,IAAI,OAAO,KAAA,KAAU,QAAA,EAAU,OAAO,KAAA;AACtC,EAAA,IAAI;AACF,IAAA,OAAO,CAAC,SAAS,QAAQ,CAAA,CAAE,SAAS,IAAI,GAAA,CAAI,KAAK,CAAA,CAAE,QAAQ,CAAA;AAAA,EAC7D,CAAA,CAAA,MAAQ;AACN,IAAA,OAAO,KAAA;AAAA,EACT;AACF,CAAA;AAGO,IAAM,YAAA,GAAe,CAAC,IAAA,KAAqC,YAAA,CAAa,IAAA,CAAK,CAAC,IAAA,KAAS,UAAA,CAAW,IAAA,CAAK,IAAA,EAAM,IAAI,CAAC,CAAC;AAInH,IAAM,WAAA,GAAc,OAAO,IAAA,KAAuC;AACvE,EAAA,MAAM,IAAA,GAAO,aAAa,IAAI,CAAA;AAC9B,EAAA,MAAM,OAAO,IAAA,KAAS,MAAA,GAAY,MAAA,GAAY,IAAA,CAAK,MAAM,IAAI,CAAA;AAC7D,EAAA,IAAI,SAAS,MAAA,EAAW;AACtB,IAAA,MAAM,IAAI,KAAA,CAAM,CAAA,2BAAA,EAA8B,IAAI,CAAA,iFAAA,CAAmF,CAAA;AAAA,EACvI;AACA,EAAA,MAAM,EAAE,QAAA,EAAS,GAAI,MAAM,OAAO,aAAa,CAAA;AAC/C,EAAA,MAAM,QAAA,GAAW,IAAA,CAAK,IAAA,EAAM,eAAe,CAAA;AAC3C,EAAA,MAAM,MAAA,GAAkB,MAAM,QAAA,CAAS,aAAA,CAAc,IAAI,CAAA,CAAE,IAAA,EAAM,EAAE,SAAA,EAAW,MAAA,CAAA,IAAA,CAAY,KAAK,GAAI,UAAA,CAAW,QAAQ,CAAA,GAAI,EAAE,UAAS,GAAI,IAAK,CAAA;AAC9I,EAAA,MAAM,OAAA,GAAmB,MAAA,KAAW,IAAA,IAAQ,OAAO,MAAA,KAAW,WAAW,OAAA,CAAQ,GAAA,CAAI,MAAA,EAAQ,SAAS,CAAA,GAAI,MAAA;AAC1G,EAAA,IAAI,CAAC,SAAA,CAAU,OAAO,CAAA,EAAG;AACvB,IAAA,MAAM,IAAI,KAAA;AAAA,MACR,SAAS,IAAI,CAAA,kLAAA;AAAA,KACf;AAAA,EACF;AACA,EAAA,IAAI,QAAQ,IAAA,KAAS,MAAA,IAAa,CAAC,MAAA,CAAO,OAAA,CAAQ,IAAI,CAAA,EAAG;AACvD,IAAA,MAAM,IAAI,KAAA,CAAM,CAAA,MAAA,EAAS,IAAI,CAAA,mBAAA,EAAsB,KAAK,SAAA,CAAU,OAAA,CAAQ,IAAI,CAAC,CAAA,8EAAA,CAA2E,CAAA;AAAA,EAC5J;AACA,EAAA,OAAO,OAAA;AACT","file":"chunk-DTDMQJAO.js","sourcesContent":["import { existsSync } from 'node:fs';\nimport { join } from 'node:path';\nimport { pathToFileURL } from 'node:url';\nimport type { DocumentConfig, MossServer } from '@niscorp/moss';\nimport type { Shell } from '@niscorp/nova';\n\n// ═══════════════════════════════════════════════════════════════\n// WHAT AN APP SAYS ABOUT ITSELF — `nisc.config.ts`, at the app's root, exporting\n// `project`. What only the app knows: how it stands up, and how one of its\n// screens is drawn. Everything the command does is derived from those.\n//\n// An app is one of two things, and its config says which by what it hands over.\n//\n// BEHIND MOSS — the shell lives on the server. The config hands over the\n// server; which paths exist and what each needs is read off its manifest.\n//\n// export const project: NiscProject = {\n// boot: async () => ({ server: (await boot()).server }),\n// draw: (snapshot) => renderSnapshot({ snapshot, registry, slotWrapper }),\n// };\n//\n// ITS OWN SHELL — the shell lives in the page (AGENTS.md, \"the client-degrade\n// path\"). The config hands over the app's own boot, the SAME one its browser\n// entry runs. A build runs it where there is no browser, draws the screen to\n// markup, and the page's boot picks that markup up.\n//\n// export const project: NiscShellProject = {\n// shell: async () => ({ shell: (await boot()).shell }),\n// draw: (shell) => renderToString(createElement(Screen, { shell })),\n// adopt: (root, shell) => { hydrateRoot(root, createElement(Screen, { shell })); },\n// };\n// ═══════════════════════════════════════════════════════════════\n\ntype Common = {\n // Where the bundler writes the terminal (default `dist`), relative to the root.\n dist?: string;\n // Where the built page's stylesheet goes. `page` (the default): written into\n // index.html as a <style>, so the first response paints the screen. `file`:\n // left as the bundler linked it — what a Content-Security-Policy that forbids\n // inline styles needs.\n stylesheet?: 'page' | 'file';\n // The app's check suite, for `nisc check` (default `src/dev/all-checks.ts`).\n checks?: string;\n // The address the site is served at (\"https://example.com\"). With it, every\n // path's document says its own canonical address. Without it, where a\n // document lives is left as index.html says — for every path alike.\n site?: string;\n};\n\nexport type NiscMossProject = Common & {\n // Stand the app up: the moss server, and how to let it go again. The same boot\n // the app's dev server and its checks run.\n boot: () => Promise<{ server: MossServer; close?: () => void | Promise<void> }>;\n // A terminal that draws one screen to a string — the app's kit bound to one of\n // moss's server targets (`@niscorp/moss/terminal/react/server`, …).\n draw: DocumentConfig['draw'];\n // What the kit would put on <html> from an effect (a palette, a scheme).\n htmlAttributes?: DocumentConfig['htmlAttributes'];\n // The wire's token key, when it is not `nisc.token`.\n tokenKey?: string;\n // The paths to build. Default: `/`, and every page whose path has no\n // parameter. A page with parameters (\"/docs/:slug\") has as many paths as there\n // are rows, and only the app knows them — list them here (`server.executeAs`\n // runs a seeded read as a charter role).\n paths?: (server: MossServer) => readonly string[] | Promise<readonly string[]>;\n // Routes of the app's own that a served site needs before the catch-all — a\n // sign-in handoff, a webhook. `nisc start` registers them first.\n routes?: (server: MossServer) => void | Promise<void>;\n // What only `nisc dev` uses.\n dev?: {\n // A signed-in URL in development: `/dev/as/<who>` stores the token this\n // mints and goes to `/`. `null` is nobody of that name. It exists in the\n // dev server and nowhere else.\n signIn?: (server: MossServer, who: string) => string | null | Promise<string | null>;\n };\n};\n\nexport type NiscShellProject = Common & {\n // One fresh copy of the app's shell, for one path — the boot the browser entry\n // runs. It is handed the path and NOTHING ELSE: there is no credential to pass\n // and no way to pass one, so what a build draws is the screen as nobody in\n // particular sees it. Called more than once per path (the build boots twice\n // to compare, and once more inside a DOM to adopt), so it must not memoize.\n shell: (request: { path: string }) => Promise<{ shell: Shell; close?: () => void | Promise<void> }>;\n // Draw a shell to markup where there is no browser: the app's kit through an\n // adapter's string target (`react-dom/server`, `vue/server-renderer`,\n // `@niscorp/nova/adapters/dom/server`).\n draw: (shell: Shell) => string | Promise<string>;\n // Pick the markup up: `root` already holds it, `shell` is the page's own. The\n // SAME call the browser entry makes (`hydrateRoot`, `createSSRApp().mount`,\n // nova's `mountShell`). A build runs it inside a DOM and fails on anything it\n // complains about.\n adopt: (root: HTMLElement, shell: Shell) => void | Promise<void>;\n // What the kit would put on <html> from an effect (a palette, a scheme).\n htmlAttributes?: (shell: Shell) => Record<string, string>;\n // The paths to build (default: `/`). An app that maps paths to actions lists\n // its own — only it knows them.\n paths?: () => readonly string[] | Promise<readonly string[]>;\n // How long a build waits for a screen to be whole (default 5000ms). Past it\n // the build FAILS: a file that says \"loading\" is not the page.\n waitMs?: number;\n};\n\n// What a config exports. Written against one of the two names above, a config's\n// callbacks are typed for it (`draw`'s argument is a snapshot in one and a shell\n// in the other).\nexport type NiscProject = NiscMossProject | NiscShellProject;\n\nconst CONFIG_NAMES = ['nisc.config.ts', 'nisc.config.mts', 'nisc.config.js', 'nisc.config.mjs'];\n\nconst has = (value: object, key: string): boolean => typeof Reflect.get(value, key) === 'function';\n\nexport const isShellProject = (project: NiscProject): project is NiscShellProject => 'shell' in project;\n\nexport const isProject = (value: unknown): value is NiscProject => {\n if (value === null || typeof value !== 'object' || !has(value, 'draw')) return false;\n const [moss, own] = [has(value, 'boot'), has(value, 'shell')];\n // one or the other — a config that hands over both has not said which it is\n return moss !== own && (moss || has(value, 'adopt'));\n};\n\n// An address a document can be said to live at: http or https, and whole.\nconst isSite = (value: unknown): boolean => {\n if (typeof value !== 'string') return false;\n try {\n return ['http:', 'https:'].includes(new URL(value).protocol);\n } catch {\n return false;\n }\n};\n\n// The config's file name, if the app has one.\nexport const configFileOf = (root: string): string | undefined => CONFIG_NAMES.find((name) => existsSync(join(root, name)));\n\n// Load the app's config through tsx, so it is TypeScript with the app's own\n// tsconfig (its path aliases included) — the way the app's checks already run.\nexport const loadProject = async (root: string): Promise<NiscProject> => {\n const name = configFileOf(root);\n const file = name === undefined ? undefined : join(root, name);\n if (file === undefined) {\n throw new Error(`nisc: no nisc.config.ts in ${root}. It exports \\`project\\`: how the app boots, and how one of its screens is drawn.`);\n }\n const { tsImport } = await import('tsx/esm/api');\n const tsconfig = join(root, 'tsconfig.json');\n const loaded: unknown = await tsImport(pathToFileURL(file).href, { parentURL: import.meta.url, ...(existsSync(tsconfig) ? { tsconfig } : {}) });\n const project: unknown = loaded !== null && typeof loaded === 'object' ? Reflect.get(loaded, 'project') : undefined;\n if (!isProject(project)) {\n throw new Error(\n `nisc: ${file} does not export a \\`project\\` the command can run. It hands over EITHER \\`boot\\` + \\`draw\\` (an app behind moss) OR \\`shell\\` + \\`draw\\` + \\`adopt\\` (an app with its own shell).`,\n );\n }\n if (project.site !== undefined && !isSite(project.site)) {\n throw new Error(`nisc: ${file} gives \\`site\\` as ${JSON.stringify(project.site)} — it is the address the site is served at, whole: \"https://example.com\".`);\n }\n return project;\n};\n"]}
package/dist/cli.js CHANGED
@@ -1,4 +1,4 @@
1
- import { loadProject, isShellProject, configFileOf, isProject } from './chunk-5INZ3VGX.js';
1
+ import { loadProject, isShellProject, configFileOf, isProject } from './chunk-DTDMQJAO.js';
2
2
  import { resolve, join, sep, extname, dirname } from 'path';
3
3
  import { spawn, spawnSync } from 'child_process';
4
4
  import { existsSync, statSync, readFileSync, rmSync, cpSync, mkdirSync, writeFileSync, mkdtempSync } from 'fs';
@@ -6,7 +6,8 @@ import { createRequire } from 'module';
6
6
  import { serve } from '@hono/node-server';
7
7
  import { pathToFileURL, fileURLToPath } from 'url';
8
8
  import { tmpdir } from 'os';
9
- import { shellSettled } from '@niscorp/nova';
9
+ import { shellSettled, shellView } from '@niscorp/nova';
10
+ import { placeHead, headOf } from '@niscorp/nova/document';
10
11
  import { livenessOf } from '@niscorp/nova/reflect';
11
12
  import { createBrotliCompress, constants, createGzip } from 'zlib';
12
13
 
@@ -37,6 +38,7 @@ var mossPlugin = async (configFile) => {
37
38
  ...booted.close !== void 0 ? { close: booted.close } : {},
38
39
  draw: project.draw,
39
40
  ...project.htmlAttributes !== void 0 ? { htmlAttributes: project.htmlAttributes } : {},
41
+ ...project.site !== void 0 ? { site: project.site } : {},
40
42
  ...project.tokenKey !== void 0 ? { tokenKey: project.tokenKey } : {},
41
43
  ...signIn !== void 0 ? { signIn: (who) => signIn(booted.server, who) } : {}
42
44
  };
@@ -70,6 +72,8 @@ var fileOf = (path) => {
70
72
  };
71
73
  var pad = (text, width) => text + " ".repeat(Math.max(0, width - text.length));
72
74
  var routeTable = (routes) => {
75
+ const says = (route) => (route.head?.elements.length ?? 0) > 0;
76
+ const headed = routes.some(says);
73
77
  const rows = routes.map((route) => {
74
78
  const mark = !route.drawn ? "\u2717" : route.live ? "\u25CF" : "\u25CB";
75
79
  const what = route.page === void 0 ? "the app" : `page ${route.page}`;
@@ -79,7 +83,8 @@ var routeTable = (routes) => {
79
83
  ...route.drawn && !route.settled ? ["it was still loading when the wait ran out \u2014 drawn with what it had"] : [],
80
84
  ...route.drawnWith.length > 0 ? [`drawn with ${route.drawnWith.join(", ")} \u2014 as it answered at build`] : []
81
85
  ];
82
- return { mark, path: route.path, what, served, notes };
86
+ const head = headed && route.drawn ? [says(route) ? `head: its own, said by ${route.head?.actions.join(", ") || "the shell\u2019s chrome"}` : "head: the template\u2019s own"] : [];
87
+ return { mark, path: route.path, what, served, notes, head };
83
88
  });
84
89
  const widths = {
85
90
  path: Math.max(5, ...rows.map((row) => row.path.length)),
@@ -89,7 +94,7 @@ var routeTable = (routes) => {
89
94
  const lines = [` ${pad("Route", widths.path + 2)}${pad("What", widths.what + 2)}${pad("Served as", widths.served + 2)}Because`];
90
95
  for (const row of rows) {
91
96
  const head = `${row.mark} ${pad(row.path, widths.path + 2)}${pad(row.what, widths.what + 2)}${pad(row.served, widths.served + 2)}`;
92
- const [first, ...rest] = row.notes.length > 0 ? row.notes : ["nothing on it can still happen"];
97
+ const [first, ...rest] = [...row.notes.length > 0 ? row.notes : ["nothing on it can still happen"], ...row.head];
93
98
  lines.push(`${head}${first ?? ""}`);
94
99
  for (const note of rest) lines.push(`${" ".repeat(head.length)}${note}`);
95
100
  }
@@ -124,12 +129,13 @@ var factsOf = (shell) => {
124
129
  const sorted = (set) => [...set].sort();
125
130
  return { actions: sorted(actions), opensWith: sorted(opensWith), callsLater: sorted(callsLater), listens: sorted(listens) };
126
131
  };
132
+ var documentOf = (project, template, path, drawn) => placeHead(placeScreen(template, drawn.screen, drawn.attributes), drawn.head?.elements, { ...project.site !== void 0 ? { site: project.site } : {}, path });
127
133
  var drawOnce = async (project, path) => {
128
134
  const booted = await project.shell({ path });
129
135
  try {
130
136
  const whole = await shellSettled(booted.shell, { waitMs: project.waitMs ?? DEFAULT_BUILD_WAIT_MS });
131
137
  const screen = await project.draw(booted.shell);
132
- return { screen, whole, attributes: project.htmlAttributes?.(booted.shell) ?? {}, facts: factsOf(booted.shell) };
138
+ return { screen, whole, attributes: project.htmlAttributes?.(booted.shell) ?? {}, head: headOf(shellView(booted.shell).api), facts: factsOf(booted.shell) };
133
139
  } finally {
134
140
  await booted.close?.();
135
141
  }
@@ -170,8 +176,11 @@ var surveyShell = async (root, project, template) => {
170
176
  drawn = await drawOnce(project, path);
171
177
  if (drawn.screen.trim() === "") problems.push("drawn: it drew to nothing");
172
178
  if (!drawn.whole) problems.push(`whole: it was still loading after ${project.waitMs ?? DEFAULT_BUILD_WAIT_MS}ms`);
179
+ for (const why of drawn.head?.refused ?? []) problems.push(`head: ${why}`);
173
180
  const again = await drawOnce(project, path);
174
181
  if (again.screen !== drawn.screen) problems.push(`same twice: a second boot drew different markup${differenceOf(drawn.screen, again.screen)}`);
182
+ const [head, headAgain] = [JSON.stringify(drawn.head ?? null), JSON.stringify(again.head ?? null)];
183
+ if (headAgain !== head) problems.push(`same twice: a second boot said a different head${differenceOf(head, headAgain)}`);
175
184
  } catch (error) {
176
185
  problems.push(`drawn: ${said(error)}`);
177
186
  }
@@ -185,9 +194,10 @@ var surveyShell = async (root, project, template) => {
185
194
  const problems = [...route.problems, ...complaints.map((complaint) => `adopted: ${complaint}`)];
186
195
  return {
187
196
  path: route.path,
188
- html: route.drawn === void 0 ? template : placeScreen(template, route.drawn.screen, route.drawn.attributes),
197
+ html: route.drawn === void 0 ? template : documentOf(project, template, route.path, route.drawn),
189
198
  problems,
190
- ...route.drawn?.facts ?? none
199
+ ...route.drawn?.facts ?? none,
200
+ ...route.drawn?.head !== void 0 ? { head: route.drawn.head } : {}
191
201
  };
192
202
  });
193
203
  };
@@ -202,13 +212,17 @@ var shellRouteTable = (routes) => {
202
212
  const width = Math.max(5, ...routes.map((route) => route.path.length)) + 2;
203
213
  const lines = [` ${pad2("Route", width)}First screen`];
204
214
  const indent = " ".repeat(width + 2);
215
+ const says = (route) => (route.head?.elements.length ?? 0) > 0;
216
+ const headed = routes.some(says);
217
+ const headNote = (route) => says(route) ? `head: its own, said by ${route.head?.actions.join(", ") || "the shell\u2019s chrome"}` : "head: the template\u2019s own";
205
218
  for (const route of routes) {
206
219
  const ok = route.problems.length === 0;
207
220
  const notes = ok ? [
208
221
  `drawn \xB7 whole \xB7 same twice \xB7 adopted${route.actions.length > 0 ? ` (${route.actions.join(", ")})` : ""}`,
209
222
  ...route.opensWith.length > 0 ? [`opened with ${route.opensWith.join(", ")} \u2014 in the file as answered at build`] : [],
210
223
  ...route.callsLater.length > 0 ? [`can still call ${route.callsLater.join(", ")}`] : [],
211
- ...route.listens.length > 0 ? [`waits on ${route.listens.join(", ")}`] : []
224
+ ...route.listens.length > 0 ? [`waits on ${route.listens.join(", ")}`] : [],
225
+ ...headed ? [headNote(route)] : []
212
226
  ] : route.problems;
213
227
  const [head, ...rest] = notes;
214
228
  lines.push(`${ok ? "\u25CB" : "\u2717"} ${pad2(route.path, width)}${head ?? ""}`);
@@ -255,8 +269,8 @@ var shellSite = (project, dist) => {
255
269
  const template = readFileSync(join(base, "index.html"), "utf8");
256
270
  const headers = { "content-type": "text/html; charset=utf-8", "cache-control": "no-cache" };
257
271
  try {
258
- const drawn = await drawOnce(project, path === "/index.html" ? "/" : path);
259
- return new Response(placeScreen(template, drawn.screen, drawn.attributes), { headers });
272
+ const at = path === "/index.html" ? "/" : path;
273
+ return new Response(documentOf(project, template, at, await drawOnce(project, at)), { headers });
260
274
  } catch (error) {
261
275
  console.error(`[nisc] "${path}" could not be drawn \u2014 serving it undrawn:`, error);
262
276
  return new Response(template, { headers });
@@ -464,6 +478,12 @@ var warnOfOwnAssets = (options) => {
464
478
  if (!existsSync(join(options.root, "public", "assets"))) return;
465
479
  say(options)("nisc: public/assets/ holds files of your own. `nisc start` has browsers keep everything under /assets/ for a year, so a change to one of them will not be seen under the same name \u2014 keep them elsewhere in public/.");
466
480
  };
481
+ var warnOfOneAddress = (options, project, template, paths) => {
482
+ if (project.site !== void 0 || paths < 2 || !/<link\b[^>]*\brel\s*=\s*["']?canonical\b/i.test(template)) return;
483
+ say(options)("");
484
+ say(options)(`nisc: index.html names one canonical address and this app has ${paths} paths \u2014 every file would say it lives there.`);
485
+ say(options)(' `site: "https://\u2026"` in nisc.config.ts gives each path its own.');
486
+ };
467
487
  var templateOf = (options, project) => {
468
488
  const template = join(distOf(options.root, project), "index.html");
469
489
  if (!existsSync(template)) throw new Error(`nisc: no built terminal at ${template} \u2014 run \`nisc build\`.`);
@@ -480,6 +500,7 @@ var survey = async (options, project) => {
480
500
  template,
481
501
  draw: project.draw,
482
502
  ...project.htmlAttributes !== void 0 ? { htmlAttributes: project.htmlAttributes } : {},
503
+ ...project.site !== void 0 ? { site: project.site } : {},
483
504
  ...project.tokenKey !== void 0 ? { tokenKey: project.tokenKey } : {},
484
505
  paths
485
506
  });
@@ -488,9 +509,11 @@ var survey = async (options, project) => {
488
509
  }
489
510
  };
490
511
  var buildShell = async (options, project) => {
491
- const routes = await surveyShell(options.root, project, templateOf(options, project));
512
+ const template = templateOf(options, project);
513
+ const routes = await surveyShell(options.root, project, template);
492
514
  say(options)("");
493
515
  say(options)(shellRouteTable(routes));
516
+ warnOfOneAddress(options, project, template, routes.length);
494
517
  return { kind: "shell", ok: routes.every((route) => route.problems.length === 0), routes };
495
518
  };
496
519
  var build = async (options) => {
@@ -501,6 +524,7 @@ var build = async (options) => {
501
524
  const routes = await survey(options, project);
502
525
  say(options)("");
503
526
  say(options)(routeTable(routes));
527
+ warnOfOneAddress(options, project, templateOf(options, project), routes.length);
504
528
  return { kind: "moss", ok: routes.every((route) => route.drawn), routes };
505
529
  };
506
530
  var write = (options, project, out, routes) => {
@@ -563,6 +587,7 @@ var start = async (options) => {
563
587
  dist,
564
588
  draw: project.draw,
565
589
  ...project.htmlAttributes !== void 0 ? { htmlAttributes: project.htmlAttributes } : {},
590
+ ...project.site !== void 0 ? { site: project.site } : {},
566
591
  ...project.tokenKey !== void 0 ? { tokenKey: project.tokenKey } : {}
567
592
  });
568
593
  const httpServer = serve({ fetch: siteHandler(booted.server.fetch, { except: MOSS_PATHS }), port });