@voxgig/sdkgen 4.16.0 → 4.17.1

package/src/action/{docs.ts → edition.ts}

@@ -1,4 +1,5 @@
-// `docs add <ref>` — the third kind. See docs/design/sdkgen-packages.md §20.
+import { kindCollection } from '../helpers/kindCollection'
+// `edition add <ref>` — the third kind. See edition/design/sdkgen-packages.md §20.
 //
 // WHAT A DOCS ITEM IS
 //
@@ -12,11 +13,11 @@
 //
 // Three reasons, argued in §20.2 and worth restating where the code is:
 //
-//   - a docs item's INPUT is the target collection — a page per SDK, the
-//     package table, per-language tabs — so a docs item inside
+//   - a edition item's INPUT is the target collection — a page per SDK, the
+//     package table, per-language tabs — so a edition item inside
 //     `main.kit.target` would enumerate itself;
 //   - `action/feature.ts` fans out with `each(target, …)` and warns
-//     `feature-source-missing` per target with no source, so a docs item in
+//     `feature-source-missing` per target with no source, so a edition item in
 //     that collection would collect one warning per feature, forever
 //     (`srcfeature: false` does not help — that flag is read at generate time
 //     and never by the add-time fan-out);
@@ -30,7 +31,7 @@
 // aliasing and the index come along unchanged — and the kind's trees, whose
 // paths come from the registry rather than being spelled here.
 //
-// It does NOT fan out over targets, trim, or prune. A docs item reads the
+// It does NOT fan out over targets, trim, or prune. A edition item reads the
 // target collection at GENERATE time, not at add time: the opposite direction
 // and the opposite moment from a feature's fan-out, so sharing that machinery
 // would have been a false economy.
@@ -58,26 +59,26 @@ import { aliasCmpTree, pruneStaleTemplates } from './target'
 import { parseAddNames, loadContent, ensureModelInclude } from './action'
 
 
-// The PREFIX of a docs item's component tree (`src/cmp/docs/`), for the
+// The PREFIX of a edition item's component tree (`src/cmp/edition/`), for the
 // alias rewrite. Derived from the registry's declaration rather than written
-// out a second time, so the two cannot disagree about where docs components
+// out a second time, so the two cannot disagree about where edition components
 // live.
 const NAME_MARK = '\u0001name\u0001'
 
 function cmpBase(): string {
-  const cmp = kindTrees('docs', NAME_MARK)
+  const cmp = kindTrees('edition', NAME_MARK)
     .find((t: TreeDef) => 'none' === t.replace)
 
-  return null == cmp ? 'src/cmp/docs/' : cmp.path.split(NAME_MARK)[0]
+  return null == cmp ? 'src/cmp/edition/' : cmp.path.split(NAME_MARK)[0]
 }
 
 
 const CMD_MAP: any = Object.assign(Object.create(null), {
-  add: cmd_docs_add,
+  add: cmd_edition_add,
 })
 
 
-async function action_docs(
+async function action_edition(
   args: string[], actx: ActionContext,
 ): Promise<ActionResult> {
   const cmdname = args[1]
@@ -85,7 +86,7 @@ async function action_docs(
 
   if (null == cmd) {
     throw new SdkGenError(
-      'Unknown docs cmd: ' + cmdname + ' (expected: ' +
+      'Unknown edition cmd: ' + cmdname + ' (expected: ' +
       Object.keys(CMD_MAP).sort().join(', ') + ')')
   }
 
@@ -93,17 +94,19 @@ async function action_docs(
 }
 
 
-async function cmd_docs_add(
+async function cmd_edition_add(
   args: string[], actx: ActionContext,
 ): Promise<ActionResult> {
-  return docs_add(parseAddNames(args), actx)
+  return edition_add(parseAddNames(args), actx)
 }
 
 
 // Code API.
-async function docs_add(
-  docs: string[], actx: ActionContext,
+async function edition_add(
+  edition: string[], actx: ActionContext,
 ): Promise<ActionResult> {
+  edition = edition.map(ref => !ref.includes('/') && !ref.includes('\\') &&
+    !kindCollection(actx.model, 'edition')[ref.split('~')[0]] ? '@voxgig/docgen/project/' + ref : ref)
   const jostraca = actx.jostraca
 
   const opts = {
@@ -112,9 +115,9 @@ async function docs_add(
     log: actx.log.child({ cmp: 'jostraca' }),
     meta: {
       url: actx.url,
-      // Seeded: no project scaffolded before the docs kind existed has a
-      // docs index, and every project alive today is in that position.
-      content: loadContent(actx, 'docs', { docs: '# Docs\n' }),
+      // Seeded: no project scaffolded before the edition kind existed has a
+      // edition index, and every project alive today is in that position.
+      content: loadContent(actx, 'edition', { edition: '# Docs\n' }),
     },
     model: actx.model,
     // Per-call, never left to the Jostraca instance: `generate` runs its own
@@ -130,7 +133,7 @@ async function docs_add(
   }
 
   opts.log.info({
-    point: 'docs-start',
+    point: 'edition-start',
     note: (actx.opts.dryrun ? '** DRY RUN **' : '')
   })
 
@@ -138,26 +141,26 @@ async function docs_add(
   //
   // The write pass emits the definition and its index entry before it copies
   // the trees, so a ref whose definition exists but whose required components
-  // do not left the command failed AND the project carrying a docs item with
+  // do not left the command failed AND the project carrying a edition item with
   // no implementation — which the next model compile then reads as real.
   // `package add` already validates a whole package up front for exactly this
-  // reason; a direct `docs add` needs the same guarantee.
-  preflight(docs, actx)
+  // reason; a direct `edition add` needs the same guarantee.
+  preflight(edition, actx)
 
-  // The project's own model must INCLUDE the docs index, or everything below
+  // The project's own model must INCLUDE the edition index, or everything below
   // is invisible: no project scaffolded before this kind existed includes it,
-  // and `main.kit.docs` would simply be absent from the next compile.
-  ensureModelInclude(actx, 'docs')
+  // and `main.kit.edition` would simply be absent from the next compile.
+  ensureModelInclude(actx, 'edition')
 
   // Into the IN-MEMORY model before anything reads it. Nothing recompiles
-  // `model/sdk.aontu` mid-process, so without this a second docs item in the
+  // `model/sdk.aontu` mid-process, so without this a second edition item in the
   // same command — and anything else later in it — behaves as if the first
   // was never installed. One definition of what gets recorded, shared with
   // `target add` and `package add`.
-  registerInstalled('docs', docs, actx)
+  registerInstalled('edition', edition, actx)
 
   const jres = await jostraca.generate(opts, () =>
-    DocsRoot({ docs, actx }))
+    EditionRoot({ edition, actx }))
 
   return { jres }
 }
@@ -166,13 +169,13 @@ async function docs_add(
 // Resolve every ref and check every REQUIRED tree, throwing before anything
 // is written. Resolution itself is the other half: a ref that names no
 // definition fails here rather than partway through the pass.
-function preflight(docs: string[], actx: ActionContext) {
+function preflight(edition: string[], actx: ActionContext) {
   const fs = actx.fs()
 
-  for (const ref of docs) {
-    const source = resolveKind(ref, 'docs', actx as any)
+  for (const ref of edition) {
+    const source = resolveKind(ref, 'edition', actx as any)
 
-    for (const tree of kindTrees('docs', source.origname)) {
+    for (const tree of kindTrees('edition', source.origname)) {
       if (!tree.required) {
         continue
       }
@@ -182,7 +185,7 @@ function preflight(docs: string[], actx: ActionContext) {
       if (!fs.existsSync(from)) {
         throw new SdkGenError(
           'Docs ' + source.name + ': required tree not found: ' + from +
-          '\n  a docs item needs its components (' + tree.path +
+          '\n  a edition item needs its components (' + tree.path +
           '); nothing has been written')
       }
     }
@@ -190,8 +193,8 @@ function preflight(docs: string[], actx: ActionContext) {
 }
 
 
-const DocsRoot = cmp(function DocsRoot(props: any) {
-  const { ctx$, docs } = props
+const EditionRoot = cmp(function EditionRoot(props: any) {
+  const { ctx$, edition } = props
   const { log } = ctx$
 
   Project({}, () => {
@@ -200,29 +203,29 @@ const DocsRoot = cmp(function DocsRoot(props: any) {
     // carry all of them.
     const dnames: string[] = []
 
-    each(docs, (n: any) => {
+    each(edition, (n: any) => {
       const dref = n.val$
 
-      log.info({ point: 'docs-build', docs: dref, note: dref })
+      log.info({ point: 'edition-build', edition: dref, note: dref })
 
       // The shared spine: a BARE name resolves against what the model
-      // RECORDS, so a docs item installed from a package resolves back to
+      // RECORDS, so a edition item installed from a package resolves back to
       // that package on its next add rather than to the bundled scaffold.
-      const source = resolveKind(dref, 'docs', ctx$)
+      const source = resolveKind(dref, 'edition', ctx$)
 
       dnames.push(source.name)
 
       log.info({
-        point: 'docs-name', docs: source.name, folder: source.folder, ref: dref,
+        point: 'edition-name', edition: source.name, folder: source.folder, ref: dref,
         note: source.name +
           (source.name !== source.origname ?
             ' (from ' + source.origname + ')' : '') +
           ' from:' + source.folder
       })
 
-      Folder({ name: 'model/docs' }, () => kindModel({
-        ctx$, kind: 'docs', source, names: dnames,
-        content: ctx$.meta.content.docs_index,
+      Folder({ name: 'model/edition' }, () => kindModel({
+        ctx$, kind: 'edition', source, names: dnames,
+        content: ctx$.meta.content.edition_index,
       }))
 
       // Both ends of every tree come from the registry's ONE declaration,
@@ -230,8 +233,8 @@ const DocsRoot = cmp(function DocsRoot(props: any) {
       // the installed one. Deriving the source path by substituting inside
       // the destination path would corrupt any item whose name also appears
       // in the fixed part of the path.
-      const dest = kindTrees('docs', source.name)
-      const from = kindTrees('docs', source.origname)
+      const dest = kindTrees('edition', source.name)
+      const from = kindTrees('edition', source.origname)
 
       dest.forEach((tree: TreeDef, i: number) => {
         // Copy only ADDS and overwrites. A newer version of the package that
@@ -252,7 +255,7 @@ const DocsRoot = cmp(function DocsRoot(props: any) {
         copyTree(ctx$, source, tree, from[i].path)
       })
 
-      log.info({ point: 'docs-done', docs: source.name, note: source.name })
+      log.info({ point: 'edition-done', edition: source.name, note: source.name })
     })
   })
 })
@@ -261,7 +264,7 @@ const DocsRoot = cmp(function DocsRoot(props: any) {
 // One tree, copied from the origin path to the installed one.
 //
 // An optional tree the source does not ship is simply not copied — that is
-// what `required: false` means, and a docs item whose every byte is generated
+// what `required: false` means, and a edition item whose every byte is generated
 // legitimately has no template tree.
 function copyTree(ctx$: any, source: any, tree: TreeDef, frompath: string) {
   const fs = ctx$.fs()
@@ -274,7 +277,7 @@ function copyTree(ctx$: any, source: any, tree: TreeDef, frompath: string) {
     }
 
     ctx$.log.info({
-      point: 'docs-tree-absent', docs: source.name, tree: tree.path, from,
+      point: 'edition-tree-absent', edition: source.name, tree: tree.path, from,
       note: source.name + ': the source ships no ' + frompath +
         ', nothing to copy'
     })
@@ -282,8 +285,8 @@ function copyTree(ctx$: any, source: any, tree: TreeDef, frompath: string) {
   }
 
   // An ALIASED component tree cannot be copied verbatim: components are
-  // dispatched by the convention `cmp/docs/<n>/Main_<n>`, so files keeping
-  // the origin suffix resolve nothing — `Main_apidocs.ts` is invisible to a
+  // dispatched by the convention `cmp/edition/<n>/Main_<n>`, so files keeping
+  // the origin suffix resolve nothing — `Main_summary.ts` is invisible to a
   // lookup for `Main_portal`. Same rule as a target's, so the same function
   // does it; jostraca's tree Copy has no per-entry rename hook, which is why
   // an aliased tree is emitted file by file.
@@ -305,6 +308,6 @@ function copyTree(ctx$: any, source: any, tree: TreeDef, frompath: string) {
 
 
 export {
-  action_docs,
-  docs_add,
+  action_edition,
+  edition_add,
 }

package/src/action/kind.ts

@@ -1,3 +1,4 @@
+import { kindCollection } from '../helpers/kindCollection'
 // KINDS: the things an `add` can install.
 //
 // `target` and `feature` are two of them, `docs` and others are meant to
@@ -20,6 +21,7 @@
 // are genuinely different work, not the same work with different strings, and
 // pretending otherwise would buy generality nobody can use.
 
+
 import Path from 'node:path'
 
 import { File, Copy, Content, template } from 'jostraca'
@@ -30,7 +32,7 @@ import { SdkGenError } from '../utility'
 
 import { provenanceReplace } from '../helpers/stdrep'
 
-import { resolveSource } from './resolve'
+import { resolveSource, recordedRef, isBare } from './resolve'
 import type { Source } from './resolve'
 
 import { UpdateIndex } from './action'
@@ -92,7 +94,7 @@ type TreeDef = {
 
 // Rewrite the ITEM KEY in a copied model file, for an aliased install.
 //
-// Parameterised by kind because `main: kit: docs: <n>:` is the same rewrite
+// Parameterised by kind because `main: kit: doc: edition: <n>:` is the same rewrite
 // with a different word, and a second copy of this regex is exactly the
 // same-rule-written-twice defect the registry exists to prevent.
 //
@@ -156,21 +158,21 @@ const KINDS: Record<string, KindDef> = Object.assign(Object.create(null), {
 
   // DOCS — the third kind. See docs/design/sdkgen-packages.md §20.
   //
-  // Its trees are NESTED under the kind name (`src/cmp/docs/<n>`, not
+  // Its trees are NESTED under the kind name (`src/cmp/edition/<n>`, not
   // `src/cmp/<n>`) so a docs item and a target may share a name without
   // sharing a directory. Everything that composes those paths takes them
   // from here.
   //
-  // `tm/docs/{name}` is NOT required: a docs item whose every emitted byte
+  // `tm/edition/{name}` is NOT required: a docs item whose every emitted byte
   // depends on the API — a catalogue entry, a config file — legitimately
   // ships no template tree, while a static site needs one. So it is
   // copy-if-present, and `package check` does not demand it.
-  docs: {
-    name: 'docs', alias: true, ownedWhenAliased: true,
-    rename: aliasModelKey('docs'),
+  edition: {
+    name: 'edition', alias: true, ownedWhenAliased: true,
+    rename: aliasModelKey('edition'),
     trees: [
-      { path: 'src/cmp/docs/{name}', replace: 'none', required: true },
-      { path: 'tm/docs/{name}', replace: 'template', required: false },
+      { path: 'src/cmp/edition/{name}', replace: 'none', required: true },
+      { path: 'tm/edition/{name}', replace: 'template', required: false },
     ],
   },
 })
@@ -208,12 +210,7 @@ function kindDef(kind: string): KindDef {
 // source.
 function resolveKind(ref: string, kind: string, ctx$: any): Source {
   const def = kindDef(kind)
-  const model = ctx$.model
-
-  const declared: any = model?.main?.[KIT]?.[kind]?.[ref]
-  const recorded = (isBare(ref) && recordedRef(declared, ref)) || ref
-
-  const source = resolveSource(recorded, kind, ctx$)
+  const source = resolveSource(ref, kind, ctx$)
 
   // Asked of the RESOLVER rather than by re-reading the ref. `~` separates an
   // alias only in the last segment, and a check that looked for one anywhere
@@ -334,24 +331,6 @@ function kindModel(props: {
 // ONE definition, used by the add actions and by doctor. This reconstruction
 // was written twice and the two copies had already diverged on exactly this
 // point, which is the drift the kind spine exists to end.
-function recordedRef(declared: any, name: string): string | undefined {
-  if (null == declared?.base || '' === declared.base) {
-    return undefined
-  }
-
-  const origname = declared.origname || name
-
-  return Path.join(declared.base, '..', origname) +
-    (origname === name ? '' : '~' + name)
-}
-
-
-// A bare NAME, as opposed to a ref that locates a source.
-function isBare(ref: string): boolean {
-  return !ref.includes('/') && !ref.includes(Path.sep)
-}
-
-
 function capitalise(s: string): string {
   return s.charAt(0).toUpperCase() + s.slice(1)
 }

package/src/action/package.ts

@@ -1,3 +1,4 @@
+import { kindCollection } from '../helpers/kindCollection'
 // `package add` / `package list` — the whole-package verbs.
 //
 // See docs/design/sdkgen-packages.md §9.
@@ -78,7 +79,7 @@ const CMD_MAP: any = Object.assign(Object.create(null), {
 // reads them at generate time rather than at add time, installing it last
 // keeps the add log in the order a reader would expect and leaves the model
 // complete before anything reads it.
-const ADD_ORDER = ['target', 'feature', 'docs']
+const ADD_ORDER = ['target', 'feature', 'edition']
 
 
 async function action_package(
@@ -663,7 +664,7 @@ function installedFrom(pkgname: string, actx: ActionContext): Installed[] {
   const found: Installed[] = []
 
   for (const kind of Object.keys(KINDS).sort()) {
-    const items = kit[kind] ?? {}
+    const items = kindCollection({ main: { [KIT]: kit } }, kind)
 
     for (const name of Object.keys(items).sort()) {
       const item = items[name]
@@ -1078,7 +1079,7 @@ async function cmd_package_list(
   const groups: Record<string, any[]> = Object.create(null)
 
   for (const kind of Object.keys(KINDS).sort()) {
-    const items = kit[kind] ?? {}
+    const items = kindCollection({ main: { [KIT]: kit } }, kind)
 
     for (const name of Object.keys(items).sort()) {
       const item = items[name]

package/src/action/resolve.ts

@@ -1,3 +1,4 @@
+import { kindCollection } from '../helpers/kindCollection'
 // Where a `<kind> add <ref>` gets its definition from.
 //
 // One resolver for every KIND of thing an add can install — targets today,
@@ -59,6 +60,9 @@ function lastSegment(ref: string): string {
 
 
 function resolveSource(ref: string, kind: string, ctx$: any): Source {
+  // Registration and copying must resolve a bare resync name identically.
+  const declared = kindCollection(ctx$.model, kind)?.[ref]
+  ref = (isBare(ref) && recordedRef(declared, ref)) || ref
   const root = ctx$.folder
   const fs = ctx$.fs()
 
@@ -275,7 +279,7 @@ function registerInstalled(kind: string, refs: string[], ctx$: any) {
     return
   }
 
-  const items = kit[kind] = kit[kind] ?? {}
+  const items = kindCollection(ctx$.model, kind, true)
 
   for (const ref of refs) {
     let source: Source
@@ -317,7 +321,7 @@ function registerInstalled(kind: string, refs: string[], ctx$: any) {
 function nameConflict(
   kind: string, source: Source, ctx$: any,
 ): { package?: string, base?: string } | undefined {
-  const declared: any = ctx$.model?.main?.[KIT]?.[kind]?.[source.name]
+  const declared: any = kindCollection(ctx$.model, kind)?.[source.name]
 
   if (null == declared || 'object' !== typeof declared) {
     return undefined
@@ -423,6 +427,24 @@ function providesStill(
 }
 
 
+function recordedRef(declared: any, name: string): string | undefined {
+  if (null == declared?.base || '' === declared.base) {
+    return undefined
+  }
+
+  const origname = declared.origname || name
+
+  return Path.join(declared.base, '..', origname) +
+    (origname === name ? '' : '~' + name)
+}
+
+
+// A bare NAME, as opposed to a ref that locates a source.
+function isBare(ref: string): boolean {
+  return !ref.includes('/') && !ref.includes(Path.sep)
+}
+
+
 function normaliseBase(base: string): string {
   return Path.normalize(String(base ?? '')).split(Path.sep).join('/')
 }
@@ -439,6 +461,8 @@ export type {
 
 export {
   resolveSource,
+  recordedRef,
+  isBare,
   registerInstalled,
   nameConflict,
   lastSegment,

package/src/admin/status.ts

@@ -0,0 +1,124 @@
+import Fs from 'node:fs'
+import Path from 'node:path'
+import { spawnSync } from 'node:child_process'
+
+function command(cwd: string, bin: string, args: string[]) {
+  return spawnSync(bin, args, { cwd, encoding: 'utf8', timeout: 15000, windowsHide: true, env: { ...process.env, GIT_OPTIONAL_LOCKS: '0' } })
+}
+function git(cwd: string, args: string[]): string | null {
+  const result = command(cwd, 'git', args)
+  return result.status === 0 ? result.stdout.trim() : null
+}
+function directory(path: string): boolean {
+  return Fs.existsSync(path) && Fs.statSync(path).isDirectory()
+}
+function entries(value: any): [string, any][] {
+  return Object.entries(value || {}).filter(([name]) => !name.includes('$')).sort(([a], [b]) => a.localeCompare(b))
+}
+function workingTree(folder: string) {
+  if (!directory(folder)) return 'missing'
+  const state = git(folder, ['status', '--porcelain=v1', '--untracked-files=normal', '--', '.'])
+  return state === null ? 'not a git repository' : state ? 'modified' : 'clean'
+}
+
+// Read the compiled model and working trees. Never fetch, build, test, or publish.
+export function repositoryStatus(root: string) {
+  root = Path.resolve(root)
+  const sdk = Path.join(root, '.sdk')
+  if (!directory(sdk)) throw new Error('Expected an SDK repository containing .sdk: ' + root)
+  const file = Path.join(sdk, 'model/sdk.json')
+  let model: any, modelError: string | undefined
+  if (Fs.existsSync(file)) {
+    try {
+      model = JSON.parse(Fs.readFileSync(file, 'utf8'))
+      if (!model?.main?.kit) throw new Error('missing main.kit')
+    } catch (err: any) { modelError = 'Invalid compiled model: ' + err.message }
+  }
+  const kit = model?.main?.kit || {}
+  const upstream = git(root, ['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{upstream}'])
+  const counts = upstream && git(root, ['rev-list', '--left-right', '--count', 'HEAD...@{upstream}'])
+  const [ahead, behind] = counts ? counts.split(/\s+/).map(Number) : [null, null]
+  const packages = ['sdkgen', 'apidef', 'model', 'docgen'].map(name => {
+    const file = Path.join(sdk, 'node_modules/@voxgig', name, 'package.json')
+    try { return { name: '@voxgig/' + name, version: JSON.parse(Fs.readFileSync(file, 'utf8')).version } }
+    catch { return { name: '@voxgig/' + name, version: 'not installed' } }
+  })
+  return {
+    root, name: model?.name || Path.basename(root),
+    repository: {
+      branch: git(root, ['branch', '--show-current']) || 'detached or not initialised',
+      commit: git(root, ['rev-parse', '--short', 'HEAD']), state: workingTree(root), upstream, ahead, behind,
+    },
+    model: { path: file, compiled: !!model && !modelError, error: modelError,
+      generatedAt: Fs.existsSync(file) ? Fs.statSync(file).mtime.toISOString() : null },
+    toolchain: { node: process.version, packages },
+    targets: entries(kit.target).map(([name, target]) => {
+      const folder = Path.resolve(root, target.output?.path || name)
+      const present = directory(folder)
+      return { name, active: target.active !== false, path: folder, present,
+        state: workingTree(folder), readme: Fs.existsSync(Path.join(folder, 'README.md')),
+        version: target.publish?.version || null,
+        publication: target.publish?.registry?.state || 'not recorded',
+      }
+    }),
+    editions: entries(kit.doc?.edition).map(([name, edition]) => ({ name,
+      active: kit.doc?.active !== false && edition.active !== false, kind: edition.kind,
+      path: edition.output?.path || null,
+      present: !!edition.output?.path && Fs.existsSync(Path.resolve(root, edition.output.path)),
+    })),
+  }
+}
+
+function githubStatus(root: string) {
+  const run = (args: string[]) => {
+    const result = command(root, 'gh', args)
+    if (result.status !== 0) throw new Error(result.error?.message || result.stderr.trim() || 'GitHub query failed')
+    return JSON.parse(result.stdout)
+  }
+  const repository = run(['repo', 'view', '--json', 'nameWithOwner,url'])
+  const host = new URL(repository.url).hostname
+  const pages = command(root, 'gh', ['api', '--hostname', host, 'repos/' + repository.nameWithOwner + '/pages'])
+  let site: any
+  try { site = JSON.parse(pages.stdout || '{}') } catch { site = {} }
+  if (pages.status !== 0 && String(site.status) !== '404') throw new Error(pages.error?.message || pages.stderr.trim() || 'Pages query failed')
+  return { repository: repository.nameWithOwner,
+    pages: pages.status === 0 ? { url: site.html_url, status: site.status, buildType: site.build_type } : { status: 'not configured' },
+    runs: run(['run', 'list', '--limit', '5', '--json', 'workflowName,status,conclusion,headBranch,url']),
+  }
+}
+
+export function main(args = process.argv.slice(2)): number {
+  const root = args.shift()
+  if (args.includes('--help') || root === '--help') {
+    console.log('Usage: .sdk/admin/status.sh [--json] [--github]\nRead local repository, SDK, and documentation status. --github also reads Pages and recent CI runs.\nBuild and test results are not inferred from generated files. No commands that change the repository are run.')
+    return 0
+  }
+  if (!root || args.some(arg => !['--json', '--github'].includes(arg))) throw new Error('Usage: status.sh [--json] [--github]')
+  const report: any = repositoryStatus(root)
+  let failed = !!report.model.error
+  if (args.includes('--github')) {
+    try { report.github = githubStatus(report.root) }
+    catch (err: any) { report.github = { error: err.message }; failed = true }
+  }
+  if (args.includes('--json')) console.log(JSON.stringify(report, null, 2))
+  else {
+    console.log('Repository: ' + report.root)
+    console.log('Git: ' + report.repository.branch + ' | ' + report.repository.state + ' | ' + (report.repository.commit || 'no commits'))
+    console.log('Upstream: ' + (report.repository.upstream ? report.repository.upstream + ' | ahead ' + report.repository.ahead + ', behind ' + report.repository.behind + ' (local tracking refs)' : 'not configured'))
+    console.log('Model: ' + (report.model.error || (report.model.compiled ? 'compiled ' + report.model.generatedAt : 'not generated; run npm run generate from .sdk')))
+    console.log('Toolchain: Node ' + report.toolchain.node + '; ' + report.toolchain.packages.map((p: any) => p.name + ' ' + p.version).join('; '))
+    console.log('\nSDKs and tools (publication state comes from the model):')
+    for (const t of report.targets) console.log('  ' + t.name + ' | ' + (t.active ? 'active' : 'inactive') + ' | ' + t.state + ' | version ' + (t.version || 'not recorded') + ' | ' + t.publication + ' | ' + t.path)
+    if (!report.targets.length) console.log('  No targets in the compiled model.')
+    console.log('\nDocumentation:')
+    for (const e of report.editions) console.log('  ' + e.name + ' | ' + (e.active ? 'active' : 'inactive') + ' | ' + (e.present ? 'present' : 'missing') + ' | ' + (e.path || 'no output path'))
+    if (!report.editions.length) console.log('  No editions in the compiled model.')
+    console.log('\nLocal status does not run builds/tests or check registries. Use --github for remote CI and Pages status.')
+    if (report.github) console.log('\nGitHub:\n' + JSON.stringify(report.github, null, 2))
+  }
+  return failed ? 1 : 0
+}
+
+if (require.main === module) {
+  try { process.exitCode = main() } catch (err: any) { console.error(err.message); process.exitCode = 1 }
+}

package/src/cmp/Test.ts

@@ -1,6 +1,6 @@
 
 import {
-  cmp,
+  cmp, File, Content,
 } from 'jostraca'
 
 import { requirePath } from '../utility'
@@ -19,6 +19,18 @@ const Test = cmp(function Test(props: any) {
   const { model, log } = ctx$
   const stdrep = ensureStdrep(ctx$)
 
+  const points = Object.values(model.main.kit.entity || {}).flatMap((entity: any) =>
+    Object.values(entity.op || {}).flatMap((op: any) => op.points || [])) as any[]
+  if (points.some(point => point.contract && JSON.parse(point.contract.json).live)) {
+    const supported = ['ts', 'js'].includes(target.name)
+    File({ name: 'live-coverage.json' }, () => Content(JSON.stringify({
+      version: 1, target: target.name, scenarios: supported ? 'supported' : 'unsupported',
+      points: points.map(point => point.contract?.id || point.method + ' ' + point.orig),
+      ...(!supported ? { reason: 'This target does not yet execute declarative live recipes. Its existing tests do not establish full operation coverage.' } : {}),
+    }, null, 2)))
+    if (!supported) log.warn({ point: 'live-scenarios-unsupported', note: 'Declarative live recipes are not executed by target ' + target.name })
+  }
+
   const Test_sdk = requirePath(ctx$, `./cmp/${target.name}/Test_${target.name}`)
   Test_sdk['Test']({ model, target, stdrep })
 

package/src/helpers/kindCollection.ts

@@ -0,0 +1,11 @@
+import { KIT } from '../types'
+
+// Physical kind names and model namespaces are independent.
+export function kindCollection(model: any, kind: string, create = false): any {
+  const kit = create ? (model.main ??= {})[KIT] ??= {} : model?.main?.[KIT]
+  if (kind === 'edition') {
+    const doc = create ? kit.doc ??= {} : kit?.doc
+    return create ? doc.edition ??= {} : doc?.edition ?? {}
+  }
+  return create ? kit[kind] ??= {} : kit?.[kind] ?? {}
+}