@travetto/doc 8.0.0-alpha.14 → 8.0.0-alpha.16

package/README.md

@@ -57,6 +57,9 @@ As you can see, you need to export a field named `text` as the body of the help
 
    *  `Anchor` - In page anchor reference
    *  `Class` - Class reference
+   *  `CliHelpDescription` - Standardized CLI command help description
+   *  `CliHelpExecution` - Standardized CLI command help execution
+   *  `CliHelpSection` - Standardized CLI command help section
    *  `Code` - Code sample
    *  `CodeLink` - Code link with regexp for detecting line
    *  `Command` - Command invocation
@@ -87,17 +90,22 @@ Some of the more common libraries are provided as the `d.library` method.  The p
 You can also link to other [Travetto](https://travetto.dev) based modules as needed.  The `d.module` object relies on what is already imported into your project, and reference the package.json of the related module. If the module is not installed, doc generation will fail.
 
 ## CLI - doc
-The run command allows for generating documentation output.
+Generate documentation outputs from a module `DOC.tsx` entry file.
 
-**Terminal: CLI Doc Help**
+**Terminal: Help for doc**
 ```bash
 $ trv doc --help
 
 Usage: doc [options]
 
+Generate documentation outputs from a module `DOC.tsx` entry file.
+
+Supports multiple output formats/targets and optional watch mode for
+iterative documentation authoring.
+
 Options:
   -i, --input <string>    Input File (default: "DOC.tsx")
-  -o, --outputs <string>  Outputs (default: ["README.md"])
+  -o, --outputs <string>  Outputs (default: ["README.md","DOC.html"])
   -w, --watch             Watch? (default: false)
   --help                  display help for command
 ```
@@ -152,7 +160,7 @@ Sample documentation for fictional module.  This module fictitiously relies upon
 Usage:  <span class="token punctuation">[</span>options<span class="token punctuation">]</span> <span class="token punctuation">[</span>command<span class="token punctuation">]</span>
 
 Commands:
-  doc        Command line support <span class="token keyword">for</span> generating module docs.
-  <span class="token function">service</span>    Allows <span class="token keyword">for</span> running services</code></pre>
+  doc        Generate documentation outputs from a module <span class="token variable"><span class="token variable">`</span>DOC.tsx<span class="token variable">`</span></span> entry file.
+  <span class="token function">service</span>    Manage development services <span class="token punctuation">(</span>start/stop/restart/status<span class="token punctuation">)</span> across the workspace.</code></pre>
   </figure>
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@travetto/doc",
-  "version": "8.0.0-alpha.14",
+  "version": "8.0.0-alpha.16",
   "description": "Documentation support for the Travetto framework",
   "keywords": [
     "docs",
@@ -24,12 +24,14 @@
     "directory": "module/doc"
   },
   "dependencies": {
-    "@travetto/runtime": "^8.0.0-alpha.14",
+    "@travetto/runtime": "^8.0.0-alpha.16",
+    "@types/markdown-it": "^14.1.2",
     "@types/prismjs": "^1.26.6",
+    "markdown-it": "^14.2.0",
     "prismjs": "^1.30.0"
   },
   "peerDependencies": {
-    "@travetto/cli": "^8.0.0-alpha.20"
+    "@travetto/cli": "^8.0.0-alpha.22"
   },
   "peerDependenciesMeta": {
     "@travetto/cli": {

package/src/jsx.ts

@@ -1,4 +1,4 @@
-import { castTo, TypedObject } from '@travetto/runtime';
+import { castTo, type Class as ClassType, TypedObject } from '@travetto/runtime';
 
 import type { LIBRARIES } from './mapping/library.ts';
 import type { MODULES } from './mapping/module.ts';
@@ -9,6 +9,8 @@ import { PackageDocUtil } from './util/package.ts';
 
 type InstallProps = { title: string, pkg: string };
 type ExecProps = { title: string, cmd: string, args?: string[], config?: RunConfig & { formatCommand?(cmd: string, args: string[]): string } };
+type CliHelpProps = { commandClass: ClassType };
+type CliHelpExecutionProps = CliHelpProps & { config?: RunConfig };
 type StdHeaderProps = { module?: string, install?: boolean };
 type HeaderProps = { title: string, description?: string };
 type ModuleProps = { name: keyof typeof MODULES };
@@ -46,6 +48,9 @@ const Config: CompFn<CodeProps> = () => EMPTY; // Configuration block
 const StdHeader: CompFn<StdHeaderProps> = () => EMPTY; // Standard module header
 const Header: CompFn<HeaderProps> = () => EMPTY; // Basic module header
 const Execution: CompFn<ExecProps> = () => EMPTY; // Run a command, and include the output as part of the document
+const CliHelpSection: CompFn<CliHelpProps> = () => EMPTY; // Standardized CLI command help section
+const CliHelpDescription: CompFn<CliHelpProps & { short?: boolean }> = () => EMPTY; // Standardized CLI command help description
+const CliHelpExecution: CompFn<CliHelpExecutionProps> = () => EMPTY; // Standardized CLI command help execution
 
 const Module: CompFn<ModuleProps> = () => EMPTY; // Node Module Reference
 const Library: CompFn<LibraryProps> = () => EMPTY; // Library reference
@@ -55,7 +60,8 @@ export const c = {
   Anchor, Library, Ref, File, Image, CodeLink,
   Module, Note, Header, StdHeader,
   Section, SubSection, SubSubSection,
-  Code, Execution, Terminal, Install, Config
+  Code, Execution, Terminal, Install, Config,
+  CliHelpSection, CliHelpDescription, CliHelpExecution,
 } as const;
 
 type C = typeof c;

package/src/mapping/module.ts

@@ -1,7 +1,7 @@
 export const MODULES = {
   Auth: {
     name: '@travetto/auth', folder: '@travetto/auth', displayName: 'Authentication',
-    description: 'Authentication scaffolding for the Travetto framework'
+    description: 'Authentication support for the Travetto framework'
   },
   AuthModel: {
     name: '@travetto/auth-model', folder: '@travetto/auth-model', displayName: 'Authentication Model',
@@ -75,6 +75,10 @@ export const MODULES = {
     name: '@travetto/image', folder: '@travetto/image', displayName: 'Image',
     description: 'Image support, resizing, and optimization'
   },
+  LlmSupport: {
+    name: '@travetto/llm-support', folder: '@travetto/llm-support', displayName: 'LLM Support',
+    description: 'Task-oriented synthesized LLM guidance for Travetto modules.'
+  },
   Log: {
     name: '@travetto/log', folder: '@travetto/log', displayName: 'Logging',
     description: 'Logging framework that integrates at the console.log level.'
@@ -167,10 +171,6 @@ export const MODULES = {
     name: '@travetto/runtime', folder: '@travetto/runtime', displayName: 'Runtime',
     description: 'Runtime for travetto applications.'
   },
-  Scaffold: {
-    name: '@travetto/scaffold', folder: '@travetto/scaffold', displayName: 'App Scaffold',
-    description: 'App Scaffold for the Travetto framework'
-  },
   Schema: {
     name: '@travetto/schema', folder: '@travetto/schema', displayName: 'Schema',
     description: 'Data type registry for runtime validation, reflection and binding.'

package/src/render/context.ts

@@ -1,7 +1,9 @@
 import path from 'node:path';
 
 import { PackageUtil } from '@travetto/manifest';
-import { castTo, RuntimeIndex } from '@travetto/runtime';
+import { castTo, RuntimeIndex, type Class } from '@travetto/runtime';
+import { CliCommandRegistryIndex } from '@travetto/cli';
+import { SchemaRegistryIndex } from '@travetto/schema';
 
 import { type JSXElementByFn, c, d } from '../jsx.ts';
 import { DocResolveUtil, type ResolvedCode, type ResolvedRef, type ResolvedSnippetLink } from '../util/resolve.ts';
@@ -96,6 +98,15 @@ export class RenderContext {
     return this.#executeCache[key] = result;
   }
 
+  /**
+   * Resolve CLI command metadata for a class from cli:schema output.
+   */
+  resolveCliCommandFromClass(commandClass: Class): { name: string, description?: string } {
+    const { name } = CliCommandRegistryIndex.get(commandClass);
+    const { description } = SchemaRegistryIndex.getConfig(commandClass);
+    return { name, description };
+  }
+
   /**
    * Resolve a reference to a given node
    */

package/src/render/html.ts

@@ -1,7 +1,9 @@
 import fs from 'node:fs/promises';
+import markdown from 'markdown-it';
 
-import { Runtime, RuntimeIndex } from '@travetto/runtime';
+import { CodecUtil, Runtime, RuntimeError, RuntimeIndex } from '@travetto/runtime';
 import { PackageUtil } from '@travetto/manifest';
+import { HELP_FLAG } from '@travetto/cli';
 
 import { highlight } from './code-highlight.ts';
 import type { RenderProvider, RenderState } from '../types.ts';
@@ -15,6 +17,7 @@ import { PackageDocUtil } from '../util/package.ts';
 
 const ESCAPE_ENTITIES: Record<string, string> = { '<': '&lt;', '>': '&gt;', '&': '&amp;', '{': "{{'{'}}", '}': "{{'}'}}" };
 const ENTITY_REGEX = new RegExp(`[${Object.keys(ESCAPE_ENTITIES).join('')}]`, 'gm');
+const md = new markdown({ html: false });
 
 const stdInline = async ({ recurse, node }: RenderState<JSXElement, RenderContext>): Promise<string> =>
   `<${node.type}>${await recurse()}</${node.type}>`;
@@ -51,6 +54,30 @@ export const Html: RenderProvider<RenderContext> = {
     });
     return Html.Terminal(sub);
   },
+  CliHelpExecution: async ({ context, props, createState }) => {
+    const config = context.resolveCliCommandFromClass(props.commandClass);
+    const { name: command } = config;
+    return Html.Execution(createState('Execution', {
+      title: `Showing help for ${command}`,
+      cmd: 'trv',
+      args: [command, HELP_FLAG],
+      config: { ...props.config }
+    }));
+  },
+  CliHelpDescription: async ({ context, props }) => {
+    const config = context.resolveCliCommandFromClass(props.commandClass);
+    let text = config.description ?? '';
+    if (props.short) {
+      text = CodecUtil.readFirstLine(text);
+    }
+    return md.render(text);
+  },
+  CliHelpSection: async ({ context, props, recurse }) => {
+    const config = context.resolveCliCommandFromClass(props.commandClass);
+    const { name: command } = config;
+    const title = `CLI - ${command}`;
+    return `\n<h2 id="${context.getAnchorId(title)}">${title}</h2>\n\n${await recurse()}`;
+  },
   Install: async ({ context, node }) => {
     const highlighted = highlight(`
 ${PackageDocUtil.getInstallInstructions(node.props.pkg, true)}
@@ -125,7 +152,7 @@ ${PackageDocUtil.getInstallInstructions(node.props.pkg, true)}
     `<a target="_blank" class="source-link" href="${context.link(props.href, props)}">${props.title}</a>`,
   Image: async ({ context, props }) => {
     if (!/^https?:/.test(props.href) && !(await fs.stat(props.href, { throwIfNoEntry: false }))) {
-      throw new Error(`${props.href} is not a valid location`);
+      throw new RuntimeError(`${props.href} is not a valid location`);
     }
     return `<img src="${context.link(props.href, props)}" alt="${props.title}">`;
   },

package/src/render/markdown.ts

@@ -1,7 +1,8 @@
 import fs from 'node:fs/promises';
 
-import { Runtime, RuntimeIndex } from '@travetto/runtime';
+import { CodecUtil, Runtime, RuntimeError, RuntimeIndex } from '@travetto/runtime';
 import { PackageUtil } from '@travetto/manifest';
+import { HELP_FLAG } from '@travetto/cli';
 
 import type { RenderProvider } from '../types.ts';
 import { c, getComponentName } from '../jsx.ts';
@@ -53,6 +54,29 @@ export const Markdown: RenderProvider<RenderContext> = {
     });
     return Markdown.Terminal(state);
   },
+  CliHelpExecution: async ({ context, props, createState }) => {
+    const { name: command } = context.resolveCliCommandFromClass(props.commandClass);
+    return await Markdown.Execution(createState('Execution', {
+      title: `Help for ${command}`,
+      cmd: 'trv',
+      args: [command, HELP_FLAG],
+      config: { ...props.config }
+    }));
+  },
+  CliHelpDescription: async ({ context, props }) => {
+    const { description = '' } = context.resolveCliCommandFromClass(props.commandClass);
+    let text = description;
+    if (props.short) {
+      text = CodecUtil.readFirstLine(text);
+    }
+    return text;
+  },
+  CliHelpSection: async ({ context, props, recurse }) => {
+    const { name: command } = context.resolveCliCommandFromClass(props.commandClass);
+    const title = `CLI - ${command}`;
+    const body = await recurse();
+    return `\n## ${title}\n${body}`;
+  },
   Install: async ({ context, node }) =>
     `\n\n**Install: ${node.props.title}**
 \`\`\`bash
@@ -102,7 +126,7 @@ ${context.cleanText(content.text)}
 
   Image: async ({ props, context }) => {
     if (!/^https?:/.test(props.href) && !(await fs.stat(props.href, { throwIfNoEntry: false }))) {
-      throw new Error(`${props.href} is not a valid location`);
+      throw new RuntimeError(`${props.href} is not a valid location`);
     }
     return `![${props.title}](${context.link(props.href)})`;
   },

package/src/render/renderer.ts

@@ -1,7 +1,7 @@
 import path from 'node:path';
 
 import { type ManifestContext, PackageUtil } from '@travetto/manifest';
-import { castTo, type Class, Runtime } from '@travetto/runtime';
+import { castTo, type Class, Runtime, RuntimeError } from '@travetto/runtime';
 
 import { EMPTY_ELEMENT, getComponentName, type JSXElementByFn, type c } from '../jsx.ts';
 import type { DocumentShape, RenderProvider, RenderState } from '../types.ts';
@@ -106,7 +106,7 @@ export class DocRenderer {
         return renderer[name](state);
       } else {
         console.log(final);
-        throw new Error(`Unknown element: ${final.type}`);
+        throw new RuntimeError(`Unknown element: ${final.type}`);
       }
     } else {
       switch (typeof input) {
@@ -124,7 +124,7 @@ export class DocRenderer {
           return await this.#buildLink(renderer, castTo(input));
         }
       }
-      throw new Error(`Unknown object type: ${typeof input}`);
+      throw new RuntimeError(`Unknown object type: ${typeof input}`);
     }
   }
 
@@ -144,7 +144,7 @@ export class DocRenderer {
    */
   async render(format: keyof typeof providers): Promise<string> {
     if (!providers[format]) {
-      throw new Error(`Unknown renderer with format: ${format}`);
+      throw new RuntimeError(`Unknown renderer with format: ${format}`);
     }
     if (!this.#rootNode) {
       this.#rootNode = (Array.isArray(this.#root.text) || isJSXElement(this.#root.text)) ?

package/support/cli.doc.ts

@@ -7,7 +7,10 @@ import { MinLength, Validator } from '@travetto/schema';
 import { PackageUtil } from '@travetto/manifest';
 
 /**
- * Command line support for generating module docs.
+ * Generate documentation outputs from a module `DOC.tsx` entry file.
+ *
+ * Supports multiple output formats/targets and optional watch mode for
+ * iterative documentation authoring.
  */
 @CliCommand()
 @Validator(async (cmd) => {