@voxgig/sdkgen 1.3.7 → 1.3.8

package/src/cmp/AgentGuideContent.ts

@@ -0,0 +1,286 @@
+// Shared prose for the generated agent guides (AGENTS.md files emitted at the
+// project top level, per target language, and per feature). The workflow, the
+// two-layer template/component model, and the aontu primer are identical for
+// every generated SDK, so they live here once and the three AgentGuide
+// components (AgentGuideTop / AgentGuide / AgentGuideFeature) render them.
+//
+// IMPORTANT: these guides ship INSIDE a generated SDK project, so every path is
+// consumer-relative (`.sdk/tm/<lang>/`, `.sdk/src/cmp/<lang>/`,
+// `.sdk/model/...`) — NOT the `project/.sdk/...` form used by the sdkgen repo's
+// own developer docs.
+
+import { each } from 'jostraca'
+
+import {
+  KIT,
+  getModelPath,
+} from '../types'
+
+
+// Build/test commands for a generated target directory. Every SDK target ships
+// a Makefile (`make build` / `make test` are the source of truth), so
+// `viaMake` targets render those; only the dependency-install step is
+// ecosystem-specific. go-cli / go-mcp are non-SDK surfaces (build only).
+type LangCmd = { install?: string, build?: string, test?: string, viaMake?: boolean, note?: string }
+
+const LANG_CMD: Record<string, LangCmd> = {
+  ts:  { install: 'npm install', viaMake: true },
+  js:  { install: 'npm install', viaMake: true },
+  go:  { viaMake: true },
+  py:  { install: 'pip install -e .', viaMake: true },
+  php: { install: 'composer install', viaMake: true },
+  rb:  { install: 'bundle install', viaMake: true },
+  lua: { install: 'luarocks make', viaMake: true },
+  'go-cli': { build: 'go build ./...', note: 'A CLI surface, not an SDK client library.' },
+  'go-mcp': { build: 'go build ./...', note: 'An MCP server surface for AI agents, not an SDK client library.' },
+}
+
+
+function langCmd(name: string): LangCmd {
+  return LANG_CMD[name] || { viaMake: true }
+}
+
+
+// A fenced shell block of the per-target build/test commands, run **in the
+// target directory** (the per-language guide already lives there). Prefers the
+// target's Makefile recipes (`make build` / `make test`).
+function langCommandsBlock(name: string): string {
+  const c = langCmd(name)
+  const lines: string[] = []
+  if (c.install) lines.push(c.install)
+  if (c.viaMake) {
+    lines.push('make build')
+    lines.push('make test')
+  }
+  else {
+    if (c.build) lines.push(c.build)
+    if (c.test) lines.push(c.test)
+  }
+  if (0 === lines.length) {
+    return `Build and test with \`${name}\`'s standard toolchain.\n`
+  }
+  return '```bash\n# in this target directory (' + name + '/):\n' + lines.join('\n') + '\n```\n'
+}
+
+
+// --- feature layout helpers (targets differ) --------------------------------
+
+// Whether a target generates per-feature output at all. go-cli / go-mcp
+// disable the feature phase (`phase.feature.active: false`).
+function featuresEnabled(target: any): boolean {
+  return target?.phase?.feature?.active !== false
+}
+
+// ts/js lay each feature out as a directory `src/feature/<name>/`; the other
+// SDK targets (`srcfeature: false`) use flat files in a shared `feature/`
+// package. Drives where feature guides live / are referenced.
+function isDirLayout(target: any): boolean {
+  return target?.srcfeature !== false
+}
+
+function featureBase(target: any): string {
+  return isDirLayout(target) ? 'src/feature' : 'feature'
+}
+
+// The generated runtime file for a feature in a flat-layout target:
+// `<name>_feature.<ext>` (go/py/rb/lua) or `<Name>Feature.php` (php).
+function featureRuntimeFile(target: any, feature: any): string {
+  const ext = target?.ext || target?.name || ''
+  if ('php' === target?.name) {
+    return (feature.Name || feature.name) + 'Feature.php'
+  }
+  return feature.name + '_feature.' + ext
+}
+
+// A feature's active hook-stage names (feature.hook.<Stage>.active === true),
+// sorted (each() marks map keys as key$).
+function featureHooks(feature: any): string[] {
+  return each(feature.hook || {})
+    .filter((h: any) => h && h.active)
+    .map((h: any) => h.name || h.key$)
+    .filter(Boolean)
+}
+
+
+// --- model readers (mirror the active-item pattern in ReadmeTop.ts) ---
+
+function activeTargets(model: any): any[] {
+  const target = getModelPath(model, `main.${KIT}.target`) || {}
+  return each(target).filter((t: any) => t && t.active !== false)
+}
+
+function activeFeatures(model: any): any[] {
+  const feature = getModelPath(model, `main.${KIT}.feature`) || {}
+  return each(feature).filter((f: any) => f && f.active !== false)
+}
+
+function activeEntities(model: any): any[] {
+  const entity = getModelPath(model, `main.${KIT}.entity`) || {}
+  return each(entity).filter((e: any) => e && e.active !== false)
+}
+
+function projectName(model: any): string {
+  return model.Name || model.const?.Name || model.name || 'SDK'
+}
+
+
+// --- shared markdown sections -----------------------------------------------
+
+// (a) basic generation & updating.
+function workflowSection(): string {
+  return `## Generating and updating the SDK
+
+All generation is driven from the \`.sdk/\` directory. The generated language
+directories (\`ts/\`, \`go/\`, …) are **build output** — never edit them by
+hand; fix the model, a template, or a component and regenerate.
+
+\`\`\`bash
+cd .sdk
+npm run add-target <lang>     # scaffold a language target (ts js go py php rb lua ...)
+npm run add-feature <name>    # scaffold a feature (e.g. log, test)
+npm run build                 # compile .sdk/src/cmp -> .sdk/dist
+npm run generate              # emit/refresh the SDK into ../<lang>
+\`\`\`
+
+\`generate\` **merges** into existing files and does **not** re-apply
+placeholder substitution to merged content. If you ever see a literal
+\`ProjectName\` or \`GOMODULE\` in generated output, delete that one file and
+regenerate it fresh:
+
+\`\`\`bash
+rm <lang>/<the-file-with-the-placeholder>
+npm run generate
+\`\`\`
+
+Note: the \`voxgig-sdkgen\` CLI only *scaffolds* (\`target add\` /
+\`feature add\`). Generation itself runs via \`npm run generate\` (backed by
+\`@voxgig/model\`) — there is no \`generate\` CLI subcommand.
+`
+}
+
+
+// (b) adding a new generated feature.
+function featureSection(): string {
+  return `## Adding a feature
+
+A **feature** is a pipeline extension: an object of hooks that fire at named
+stages of every entity operation (each target's guide documents its
+features). Built-in features are \`log\` and \`test\`.
+
+\`\`\`bash
+cd .sdk
+npm run add-feature <name>    # e.g. log  (comma-separated for several)
+npm run build && npm run generate
+\`\`\`
+
+To author a **new** feature:
+
+1. Define its model at \`.sdk/model/feature/<name>.aontu\` — \`name: key()\`,
+   \`title\`, \`version\`, \`active\`, \`config.options.active\`, a \`hook\`
+   map (\`<Stage>: active: true\`), and per-language \`deps\`.
+2. Register it in \`.sdk/model/feature/feature-index.aontu\` with
+   \`@"<name>.aontu"\`.
+3. Provide the per-language runtime under that target's feature template dir
+   (\`.sdk/tm/<lang>/src/feature/<name>/\` for ts/js, \`.sdk/tm/<lang>/feature/\`
+   otherwise) — the \`FEATURE_Name\` / \`FEATURE_VERSION\` placeholders are
+   substituted on \`add-feature\`.
+4. \`npm run add-feature <name> && npm run build && npm run generate\`.
+`
+}
+
+
+// (c) customising the model and templates (the two-layer mental model).
+function customiseSection(): string {
+  return `## Customising: model, templates, components
+
+Each language target is generated from **two layers**:
+
+| Layer | Path | Nature |
+| --- | --- | --- |
+| **Templates** | \`.sdk/tm/<lang>/\` | Plain target-language source, copied verbatim with placeholder substitution. Edit when the file is the **same for every API** (transport, base classes, runtime, utilities). |
+| **Components** | \`.sdk/src/cmp/<lang>/\` | TypeScript that **generates** source by walking the model. Edit when the file's shape **depends on the API** (entity classes, the constructor, README, tests). |
+
+> Decision rule: *same for every API → template; depends on the API →
+> component.*
+
+Placeholders substituted on copy: \`ProjectName\` (Pascal-case SDK name),
+\`GOMODULE\` (Go module path), \`FEATURE_Name\` / \`FEATURE_VERSION\`, and the
+\`$$path$$\` interpolation of a model value (such as the name) in \`.aontu\`.
+
+Propagate a change: edit the template/component → \`npm run build\` (only
+needed if you touched a component) → \`npm run generate\`. Target shape and
+deps live in \`.sdk/model/target/<lang>.aontu\`; features in
+\`.sdk/model/feature/<name>.aontu\`.
+`
+}
+
+
+// (d) how the aontu model language works.
+function aontuSection(): string {
+  return `## The model language (aontu, \`.aontu\` files)
+
+The model is one structured object assembled by **aontu** (a unification
+engine) from three sources: the API model (entities/operations, from the
+OpenAPI spec via \`@voxgig/apidef\`), the base schema, and the target/feature
+definitions in \`.sdk/model/\`. An \`.aontu\` file is a relaxed JSON (jsonic
+syntax) with unification semantics:
+
+| Syntax | Meaning |
+| --- | --- |
+| \`a: b: c: 1\` | Nested-object shorthand for \`a:{b:{c:1}}\`. |
+| \`&: { ... }\` | Schema applied to **every** child of a map (one rule, many entries). |
+| \`*default \\| type\` | A default value unified against a type (e.g. \`*true \\| boolean\`). |
+| \`name: key()\` | Bind a field to its map key (so \`feature: log: {}\` gets \`name: 'log'\`). |
+| \`$$path$$\` | Interpolate a model value into a string — e.g. the SDK \`name\`. |
+| \`@"file.aontu"\` | Include another fragment (how the index files work). |
+| \`x: .y\` | Reference another path's value (e.g. \`deps: ts: .js\`). |
+
+For example, the schema for every feature entry:
+
+\`\`\`aontu
+main: kit: feature: &: {
+  name: key()
+  active: *false | boolean
+  title: string
+  version: *'0.0.1' | string
+  hook: &: { active: *false | boolean, await: *false | boolean }
+}
+\`\`\`
+
+Caveat: literal disjunctions (\`'prod' | 'peer' | 'dev'\`) are fragile in
+aontu, so the model uses \`*'prod' | string\` and enforces the enum in code —
+do not "fix" these into literal disjunctions.
+`
+}
+
+
+// A thin CLAUDE.md that points at the sibling AGENTS.md (same directory).
+function claudePointer(title: string): string {
+  return `# ${title}
+
+This project uses **AGENTS.md** as the operating guide for coding agents.
+
+See [AGENTS.md](./AGENTS.md).
+`
+}
+
+
+export {
+  LANG_CMD,
+  langCmd,
+  langCommandsBlock,
+  featuresEnabled,
+  isDirLayout,
+  featureBase,
+  featureRuntimeFile,
+  featureHooks,
+  activeTargets,
+  activeFeatures,
+  activeEntities,
+  projectName,
+  workflowSection,
+  featureSection,
+  customiseSection,
+  aontuSection,
+  claudePointer,
+}

package/src/cmp/AgentGuideFeature.ts

@@ -0,0 +1,107 @@
+
+import { cmp, each, Content, File, Folder } from 'jostraca'
+
+import { claudePointer } from './AgentGuideContent'
+
+
+function cap(s: string): string {
+  return s ? s.charAt(0).toUpperCase() + s.slice(1) : s
+}
+
+
+// Per-feature agent guide, co-located with the feature's generated runtime.
+// Invoked from AgentGuide inside the ambient target folder, so it lands at
+// `<lang>/src/feature/<name>/AGENTS.md`.
+const AgentGuideFeature = cmp(function AgentGuideFeature(props: any) {
+  const { target, feature, ctx$ } = props
+
+  const name = feature.name
+  const Name = feature.Name || cap(name)
+  const title = feature.title || `${Name} feature`
+  const version = feature.version || '0.0.1'
+  const lang = target.name
+
+  // Active hook stages (feature.hook.<Stage>.active === true).
+  const hooks = each(feature.hook || {})
+    .filter((h: any) => h && h.active)
+    .map((h: any) => h.name || h.key$)
+    .filter(Boolean)
+
+  const defaultOn = true === feature?.config?.options?.active
+
+  Folder({ name: 'src/feature/' + name }, () => {
+
+    File({ name: 'AGENTS.md' }, () => {
+      Content(`# ${Name}Feature — Agent Guide
+
+${title} (v${version}).
+
+A **feature** is a pipeline extension: an object of hooks that fire at named
+stages of every entity operation (load, list, create, update, remove) and of
+the SDK/entity lifecycle. Features are how you inspect or modify the request
+pipeline without forking the SDK. This directory holds the **generated**
+runtime for the \`${name}\` feature in the ${target.title || lang} target — do
+not edit it by hand; change its template/model in \`.sdk/\` and regenerate.
+
+Active by default: **${defaultOn ? 'yes' : 'no'}** (\`config.options.active\`
+in the model). ${defaultOn
+  ? 'It runs unless disabled.'
+  : 'It only runs when explicitly enabled (e.g. the `test` feature is switched on for test mode).'}
+
+`)
+
+      if (0 < hooks.length) {
+        Content(`## Hooks it fires
+
+${hooks.map((h: string) => `- \`${h}\``).join('\n')}
+
+Each active hook runs at its pipeline stage in feature-registration order, so a
+later feature can override an earlier one.
+
+`)
+      }
+
+      Content(`## Where it is defined
+
+| Part | Path |
+| --- | --- |
+| Model definition | \`.sdk/model/feature/${name}.aontu\` (name, title, version, \`config.options.active\`, the \`hook\` map, per-language \`deps\`) |
+| Registered in | \`.sdk/model/feature/feature-index.aontu\` (\`@"${name}.aontu"\`) |
+| Runtime template | \`.sdk/tm/${lang}/src/feature/${name}/\` (copied here on \`generate\`; \`FEATURE_Name\`/\`FEATURE_VERSION\` substituted) |
+
+(Paths are relative to the **project root** — four levels up from here.)
+
+## Customising this feature
+
+- **Turn hooks on/off**: edit the \`hook\` map in
+  \`.sdk/model/feature/${name}.aontu\` (\`<Stage>: active: true|false\`).
+- **Change default activation**: set \`config.options.active\` in the same file.
+- **Dependencies**: edit \`deps.<lang>\` in the same file.
+- **Behaviour**: edit the runtime template under
+  \`.sdk/tm/${lang}/src/feature/${name}/\`, then regenerate.
+
+After any change: \`cd ../../../../.sdk && npm run generate\` (add
+\`npm run build\` first if you changed a component). If a regenerated file
+shows a literal \`FEATURE_Name\`/\`ProjectName\`, delete it and regenerate.
+
+To author a **new** feature, copy this one's model + template shape — see the
+[project guide](../../../../AGENTS.md) and the
+[${target.title || lang} guide](../../../AGENTS.md).
+`)
+    })
+
+    File({ name: 'CLAUDE.md' }, () => {
+      Content(claudePointer(`${Name}Feature (${lang})`))
+    })
+  })
+
+  ctx$.log?.info?.({
+    point: 'generate-agentguide-feature', target, feature,
+    note: 'target:' + lang + ', feature:' + name,
+  })
+})
+
+
+export {
+  AgentGuideFeature
+}

package/src/cmp/AgentGuideTop.ts

@@ -0,0 +1,121 @@
+
+import { cmp, names, Content, File } from 'jostraca'
+
+import {
+  activeTargets,
+  activeFeatures,
+  activeEntities,
+  projectName,
+  workflowSection,
+  featureSection,
+  customiseSection,
+  aontuSection,
+  claudePointer,
+  langCmd,
+} from './AgentGuideContent'
+
+
+// Top-level agent guide for a generated SDK project. Emitted once at the
+// project root (no enclosing Folder), alongside README.md/Makefile. Teaches a
+// coding agent how to operate the whole project: regenerate, add features,
+// customise the model/templates, and read the aontu model language.
+const AgentGuideTop = cmp(function AgentGuideTop(props: any) {
+  const { ctx$ } = props
+  const { model } = ctx$
+
+  if (model.name && !model.Name) names(model, model.name)
+
+  const Name = projectName(model)
+  const targets = activeTargets(model)
+  const features = activeFeatures(model)
+  const entities = activeEntities(model)
+
+  File({ name: 'AGENTS.md' }, () => {
+    Content(`# ${Name} SDK — Agent Guide
+
+This is a **generated** multi-language SDK project. The client libraries in
+each language directory are produced by [@voxgig/sdkgen](https://github.com/voxgig/sdkgen)
+from an API model; the generator, model, templates, and components all live in
+\`.sdk/\`. Treat the language directories as build output — change the model,
+a template, or a component and regenerate.
+
+There are companion guides deeper in the tree: one per language
+(\`<lang>/AGENTS.md\`) and one per feature
+(\`<lang>/src/feature/<name>/AGENTS.md\`).
+
+## Project map
+
+`)
+
+    // Targets
+    if (0 < targets.length) {
+      Content(`**Targets** (${targets.length}):
+
+| Target | Directory | Build guide |
+| --- | --- | --- |
+`)
+      targets.forEach((t: any) => {
+        const note = langCmd(t.name).note ? ' — ' + langCmd(t.name).note : ''
+        Content(`| \`${t.name}\` | \`${t.name}/\`${note} | [\`${t.name}/AGENTS.md\`](./${t.name}/AGENTS.md) |
+`)
+      })
+      Content(`
+`)
+    }
+
+    // Features
+    if (0 < features.length) {
+      Content(`**Features** (${features.length}): `)
+      Content(features.map((f: any) => `\`${f.name}\``).join(', ') + `.
+
+Each feature is generated into every SDK target — as a directory
+\`<lang>/src/feature/<name>/\` (ts/js) or a flat file in the \`<lang>/feature/\`
+package (other languages). Each target's guide documents its features.
+
+`)
+    }
+
+    // Entities
+    if (0 < entities.length) {
+      Content(`**Entities** (${entities.length}): `)
+      Content(entities.map((e: any) => `\`${e.Name || e.name}\``).join(', ') + `.
+
+`)
+    }
+
+    Content(workflowSection())
+    Content(featureSection())
+    Content(customiseSection())
+    Content(aontuSection())
+
+    Content(`## Where things live
+
+\`\`\`
+.sdk/
+  model/          the model: target/, feature/, and index .aontu files
+  src/cmp/<lang>/  components — TypeScript that generates API-specific source
+  tm/<lang>/       templates — verbatim source copied with placeholders
+  dist/            compiled components (npm run build)
+<lang>/           generated SDK for each target (build output)
+README.md         human-facing overview
+Makefile          per-target deploy recipes
+\`\`\`
+
+---
+
+Generated by [@voxgig/sdkgen](https://github.com/voxgig/sdkgen). Regenerate
+with \`cd .sdk && npm run generate\`.
+`)
+  })
+
+  File({ name: 'CLAUDE.md' }, () => {
+    Content(claudePointer(`${Name} SDK`))
+  })
+
+  ctx$.log?.info?.({ point: 'generate-agentguide-top', note: 'name:' + Name })
+})
+
+
+export {
+  AgentGuideTop
+}

package/src/cmp/ReadmeTop.ts

@@ -215,9 +215,22 @@ ${aboutMd.trim()}
     // mental model the SDK is built around (model-driven; lists real entities).
     if (activeEntities.length > 0) {
       const entNames = activeEntities.map((e: any) => e.Name)
-      const entList = entNames.length > 1
+      const entCount = entNames.length
+      const entList = entCount > 1
         ? entNames.slice(0, -1).join(', ') + ' and ' + entNames[entNames.length - 1]
         : entNames[0]
+      // Only enumerate the entity names inline when the set is small enough that
+      // the list clarifies the mental model rather than becoming a wall of names
+      // at the top of the README. Larger APIs get a count and a pointer to the
+      // Entities table below — and we never assert a "small set" when it isn't.
+      const NAME_INLINE_MAX = 6
+      const inlineNames = entCount <= NAME_INLINE_MAX
+      const surface = inlineNames
+        ? `a small set of **semantic entities** — ${entList} —`
+        : `**${entCount} semantic entities**`
+      const seeEntities = inlineNames
+        ? ''
+        : ' See the [Entities](#entities) table below for the full list.'
       const exEnt = activeEntities[0]
       const ex = exEnt.Name
       const exLower = safeVarName(ex.toLowerCase(), 'ts')
@@ -254,8 +267,8 @@ ${aboutMd.trim()}
       const opList = (opNames.length ? opNames : ['list', 'load']).map((o) => '`' + o + '`').join(', ')
       Content(`## Entities, not endpoints
 
-This SDK exposes the API as a small set of **semantic entities** — ${entList} — that you
-call directly, instead of assembling URL paths and query strings. Entities are
+This SDK exposes the API as ${surface} that you
+call directly, instead of assembling URL paths and query strings.${seeEntities} Entities are
 **Capitalised** to mark them as the primary surface, each with the operations they
 support (${opList}):
 

package/src/sdkgen.ts

@@ -27,6 +27,9 @@ import { Entity } from './cmp/Entity'
 import { Feature } from './cmp/Feature'
 import { Readme } from './cmp/Readme'
 import { ReadmeTop } from './cmp/ReadmeTop'
+import { AgentGuideTop } from './cmp/AgentGuideTop'
+import { AgentGuide } from './cmp/AgentGuide'
+import { AgentGuideFeature } from './cmp/AgentGuideFeature'
 import { License } from './cmp/License'
 import { Security } from './cmp/Security'
 import { Changelog } from './cmp/Changelog'
@@ -415,6 +418,9 @@ export {
   Test,
   Readme,
   ReadmeTop,
+  AgentGuideTop,
+  AgentGuide,
+  AgentGuideFeature,
   ReadmeInstall,
   ReadmeQuick,
   ReadmeErrors,