@voxgig/sdkgen 3.4.6 → 3.5.0

package/project/.sdk/tm/ocaml/test/struct_corpus.ml

@@ -8,92 +8,10 @@ let nullmark = "__NULL__"
 let undefmark = "__UNDEF__"
 let existsmark = "__EXISTS__"
 
-(* ---------------- JSON reader -> value ---------------- *)
-
-let json_read (s : string) : value =
-  let n = String.length s in
-  let pos = ref 0 in
-  let peek () = if !pos < n then Some s.[!pos] else None in
-  let adv () = incr pos in
-  let skip_ws () =
-    while !pos < n && (match s.[!pos] with ' ' | '\t' | '\n' | '\r' -> true | _ -> false) do incr pos done
-  in
-  let rec pval () =
-    skip_ws ();
-    match peek () with
-    | Some '{' -> pobj ()
-    | Some '[' -> parr ()
-    | Some '"' -> Str (pstr ())
-    | Some 't' -> pos := !pos + 4; Bool true
-    | Some 'f' -> pos := !pos + 5; Bool false
-    | Some 'n' -> pos := !pos + 4; Null
-    | _ -> pnum ()
-  and pobj () =
-    adv (); skip_ws ();
-    if peek () = Some '}' then (adv (); empty_map ())
-    else begin
-      let m = empty_map () in
-      let rec loop () =
-        skip_ws ();
-        let k = pstr () in
-        skip_ws (); adv (); (* : *)
-        let v = pval () in
-        ignore (setprop m (Str k) v);
-        skip_ws ();
-        let c = (match peek () with Some c -> adv (); c | None -> '}') in
-        if c = ',' then loop () else m
-      in loop ()
-    end
-  and parr () =
-    adv (); skip_ws ();
-    if peek () = Some ']' then (adv (); empty_list ())
-    else begin
-      let acc = ref [] in
-      let rec loop () =
-        let v = pval () in
-        acc := v :: !acc;
-        skip_ws ();
-        let c = (match peek () with Some c -> adv (); c | None -> ']') in
-        if c = ',' then loop () else lst (List.rev !acc)
-      in loop ()
-    end
-  and pstr () =
-    adv ();
-    let b = Buffer.create 16 in
-    let rec loop () =
-      let c = s.[!pos] in adv ();
-      if c = '"' then Buffer.contents b
-      else if c = '\\' then begin
-        let e = s.[!pos] in adv ();
-        (match e with
-         | '"' -> Buffer.add_char b '"' | '\\' -> Buffer.add_char b '\\'
-         | '/' -> Buffer.add_char b '/' | 'n' -> Buffer.add_char b '\n'
-         | 't' -> Buffer.add_char b '\t' | 'r' -> Buffer.add_char b '\r'
-         | 'b' -> Buffer.add_char b '\b' | 'f' -> Buffer.add_char b '\012'
-         | 'u' ->
-           let hex = String.sub s !pos 4 in pos := !pos + 4;
-           let code = int_of_string ("0x" ^ hex) in
-           if code < 128 then Buffer.add_char b (Char.chr code)
-           else if code < 2048 then begin
-             Buffer.add_char b (Char.chr (0xC0 lor (code lsr 6)));
-             Buffer.add_char b (Char.chr (0x80 lor (code land 0x3F)))
-           end else begin
-             Buffer.add_char b (Char.chr (0xE0 lor (code lsr 12)));
-             Buffer.add_char b (Char.chr (0x80 lor ((code lsr 6) land 0x3F)));
-             Buffer.add_char b (Char.chr (0x80 lor (code land 0x3F)))
-           end
-         | c -> Buffer.add_char b c);
-        loop ()
-      end else (Buffer.add_char b c; loop ())
-    in loop ()
-  and pnum () =
-    let start = !pos in
-    while !pos < n && (match s.[!pos] with
-        | '0'..'9' | '-' | '+' | '.' | 'e' | 'E' -> true | _ -> false) do incr pos done;
-    let tok = String.sub s start (!pos - start) in
-    Num (float_of_string tok)
-  in
-  pval ()
+(* The JSON reader now lives in the runtime (sdk_json.ml) so the SDK's
+ * generated config can use it; the corpus runs against that same function
+ * rather than a second copy that could drift from it. *)
+let json_read = Sdk_json.json_read
 
 (* ---------------- fixJSON / equality ---------------- *)
 

package/project/.sdk/tm/perl/utility/make_options.pm

@@ -82,7 +82,11 @@ $REGISTRY{make_options} = sub {
 
   my $sys_fetch = ProjectNameHelpers::gpath($opts, 'system.fetch');
 
-  my $merged = Voxgig::Struct::merge([{}, $cfgopts, $opts]);
+  # CLONE the config side: `config` is a process-wide singleton
+  # (ProjectNameConfig::shared_config) and merge uses its nested hashes as merge
+  # TARGETS, so without this one client's options (headers, server, ...) are
+  # written into the shared config and inherited by every client after it.
+  my $merged = Voxgig::Struct::merge([{}, Voxgig::Struct::clone($cfgopts), $opts]);
   my $validated = Voxgig::Struct::validate($merged, $optspec);
   $opts = Voxgig::Struct::ismap($validated) ? $validated : {};
 

package/project/.sdk/tm/rust/utility/make_options.rs

@@ -98,18 +98,96 @@ pub fn make_options_util(ctx: &Rc<Context>) -> Value {
             ]),
         ),
         ("clean", jo(vec![("keys", Value::str("key,token,id"))])),
+        // Server-variable values for a templated base URL (OpenAPI server
+        // variables): {name} placeholders in "base" are substituted from this
+        // map at construction. Spec defaults arrive via the generated config;
+        // user values override them. Mirrors go's make_options optspec.
+        ("server", jo(vec![("`$CHILD`", Value::str(""))])),
     ]);
 
     // Preserve system.fetch before merge/validate (validation strips it).
     let sys_fetch = getpath(&["system", "fetch"], &opts);
 
-    let merged = vs::merge(&ja(vec![Value::empty_map(), cfgopts, opts.clone()]), None);
+    // CLONE the config side: `config` is a per-thread singleton
+    // (core::config::shared_config) and merge uses its nested maps as merge
+    // TARGETS, so without this one client's options (headers, server, ...) are
+    // written into the shared config and inherited by every client after it.
+    let merged = vs::merge(
+        &ja(vec![Value::empty_map(), vs::clone(&cfgopts), opts.clone()]), None);
     if let Ok(validated) = vs::validate(&merged, &optspec, None) {
         if let Value::Map(_) = validated {
             opts = validated;
         }
     }
 
+    // Resolve a templated base URL (e.g. https://{tenant_id}.hanko.io).
+    // Every placeholder must resolve to a non-empty value: from options.server
+    // (user), else the Config default. A placeholder that resolves to "" is a
+    // construction ERROR in live mode - the URL cannot work - but in test mode
+    // substitutes the deterministic value "test-<name>" so offline tests need
+    // no configuration. The SDK constructor has no error return, so a missing
+    // required variable PANICS: construction-time misconfiguration.
+    //
+    // Scanned by hand rather than with vs::re_replace, whose replacement is a
+    // fixed string and cannot vary per placeholder.
+    if let Value::Str(base) = getp(&opts, "base") {
+        if base.contains('{') {
+            let testmode = matches!(getpath(&["test", "active"], &opts), Value::Bool(true))
+                || matches!(
+                    getpath(&["feature", "test", "active"], &opts),
+                    Value::Bool(true)
+                );
+            let server = getp(&opts, "server");
+            let sdkname = match getpath(&["main", "name"], &config) {
+                Value::Str(s) if !s.is_empty() => s,
+                _ => "SDK".to_string(),
+            };
+
+            let mut resolved = String::with_capacity(base.len());
+            let bytes: Vec<char> = base.chars().collect();
+            let mut i = 0usize;
+            while i < bytes.len() {
+                if '{' != bytes[i] {
+                    resolved.push(bytes[i]);
+                    i += 1;
+                    continue;
+                }
+                // A placeholder only when it closes and the name is
+                // [A-Za-z0-9_]+; anything else is literal text.
+                let mut j = i + 1;
+                while j < bytes.len() && (bytes[j].is_ascii_alphanumeric() || '_' == bytes[j]) {
+                    j += 1;
+                }
+                if j >= bytes.len() || '}' != bytes[j] || j == i + 1 {
+                    resolved.push(bytes[i]);
+                    i += 1;
+                    continue;
+                }
+                let name: String = bytes[i + 1..j].iter().collect();
+                let val = match getp(&server, &name) {
+                    Value::Str(s) => s,
+                    _ => String::new(),
+                };
+                if val.is_empty() {
+                    if testmode {
+                        resolved.push_str(&format!("test-{}", name));
+                    } else {
+                        panic!(
+                            "{}: the server variable '{}' is required: the API base \
+                             URL is '{}' - pass server: {{ \"{}\": \"...\" }} in the \
+                             SDK options",
+                            sdkname, name, base, name
+                        );
+                    }
+                } else {
+                    resolved.push_str(&val);
+                }
+                i = j + 1;
+            }
+            setp(&opts, "base", Value::str(&resolved));
+        }
+    }
+
     // Restore system.fetch.
     if !sys_fetch.is_noval() {
         let sys = getp(&opts, "system");

package/project/.sdk/tm/scala/core/SdkClient.scala

@@ -16,7 +16,9 @@ abstract class SdkClient(options0: JMap[String, Object]) {
   protected var rootctx: Context = null
 
   locally {
-    val config = Config.makeConfig()
+    // The process-wide config (sdkgen rung L2): read-only on the request path,
+    // so every client shares one rather than rebuilding it.
+    val config = Config.sharedConfig()
 
     val ctxmap = new LinkedHashMap[String, Object]()
     ctxmap.put("client", this)

package/project/.sdk/tm/scala/utility/Make.scala

@@ -216,7 +216,11 @@ object MakeOptions {
 
     val mergeList = new ArrayList[Object]()
     mergeList.add(new LinkedHashMap[String, Object]())
-    mergeList.add(cfgopts)
+    // CLONE the config side: `config` is a process-wide singleton
+    // (Config.sharedConfig) and merge uses its nested maps as merge TARGETS, so
+    // without this one client's options (headers, server, ...) are written into
+    // the shared config and inherited by every client constructed afterwards.
+    mergeList.add(Struct.clone(cfgopts))
     mergeList.add(opts)
     val merged = Struct.merge(mergeList)
 

package/project/.sdk/tm/swift/Sources/ProjectNameSDK/utility/MakeOptions.swift

@@ -98,7 +98,11 @@ func makeOptionsUtil(_ ctx: Context) -> VMap {
   // validation reshapes the system block).
   let sysFetch = gpath(opts, "system", "fetch")
 
-  let merged = merge(.list([.map(VMap()), .map(cfgopts), .map(opts)]))
+  // CLONE the config side: `config` is a process-wide singleton
+  // (SdkConfig.sharedConfig) and merge uses its nested maps as merge TARGETS,
+  // so without this one client's options (headers, server, ...) are written
+  // into the shared config and inherited by every client built afterwards.
+  let merged = merge(.list([.map(VMap()), clone(.map(cfgopts)), .map(opts)]))
   let validated = validate(merged, optspec)
   let result = validated.asMap ?? VMap()
 

package/project/.sdk/tm/zig/core/utility.zig

@@ -35,6 +35,14 @@ fn fmt(comptime f: []const u8, args: anytype) []const u8 {
     return std.fmt.allocPrint(h.A(), f, args) catch "";
 }
 
+// Boolean-or-absent: an option that is unset, null or a non-boolean is false.
+fn is_true(v: Value) bool {
+    return switch (v) {
+        .bool => |b| b,
+        else => false,
+    };
+}
+
 // ============================================================================
 // Utility bundle
 // ============================================================================
@@ -368,17 +376,93 @@ pub fn make_options_util(ctx: *Context) Value {
             .{ "entity", h.jo(&.{.{ "`$OPEN`", h.vbool(true) }}) },
         }) },
         .{ "clean", h.jo(&.{.{ "keys", h.vstr("key,token,id") }}) },
+        // Server-variable values for a templated base URL (OpenAPI server
+        // variables): {name} placeholders in "base" are substituted from this
+        // map at construction. Spec defaults arrive via the generated config;
+        // user values override them. Mirrors go's make_options optspec.
+        .{ "server", h.jo(&.{.{ "`$CHILD`", h.vstr("") }}) },
     });
 
     // Preserve system.fetch before merge/validate (validation strips it).
     const sys_fetch = h.getpath(&.{ "system", "fetch" }, opts);
 
-    const merged = vs.merge(h.A(), h.ja(&.{ h.omap(), cfgopts, opts }), vs.MAXDEPTH) catch opts;
+    // CLONE the config side: `config` is a process-wide singleton
+    // (config.shared_config) and merge uses its nested maps as merge TARGETS,
+    // so without this one client's options (headers, server, ...) are written
+    // into the shared config and inherited by every client built after it.
+    const merged = vs.merge(h.A(), h.ja(&.{ h.omap(), h.clone(cfgopts), opts }), vs.MAXDEPTH) catch opts;
     const vres = vs.validate(h.A(), merged, optspec) catch null;
     if (vres) |vr| {
         if (vr.err == null and vr.out == .object) opts = vr.out;
     }
 
+    // Resolve a templated base URL (e.g. https://{tenant_id}.hanko.io).
+    // Every placeholder must resolve to a non-empty value: from options.server
+    // (user), else the Config default. A placeholder that resolves to "" is a
+    // construction ERROR in live mode - the URL cannot work - but in test mode
+    // substitutes the deterministic value "test-<name>" so offline tests need
+    // no configuration. The SDK constructor has no error return, so a missing
+    // required variable PANICS: construction-time misconfiguration.
+    //
+    // Scanned by hand: a placeholder is `{` followed by [A-Za-z0-9_]+ and `}`;
+    // anything else is literal text, so a stray brace in a URL is left alone.
+    switch (h.getp(opts, "base")) {
+        .string => |base| {
+            if (null != std.mem.indexOfScalar(u8, base, '{')) {
+                const testmode =
+                    is_true(h.getpath(&.{ "test", "active" }, opts)) or
+                    is_true(h.getpath(&.{ "feature", "test", "active" }, opts));
+                const server = h.getp(opts, "server");
+                const sdkname: []const u8 = switch (h.getpath(&.{ "main", "name" }, config)) {
+                    .string => |s| if (0 < s.len) s else "SDK",
+                    else => "SDK",
+                };
+
+                var out = std.ArrayList(u8).init(h.A());
+                var i: usize = 0;
+                while (i < base.len) {
+                    if ('{' != base[i]) {
+                        out.append(base[i]) catch {};
+                        i += 1;
+                        continue;
+                    }
+                    var j = i + 1;
+                    while (j < base.len and (std.ascii.isAlphanumeric(base[j]) or '_' == base[j])) {
+                        j += 1;
+                    }
+                    if (j >= base.len or '}' != base[j] or j == i + 1) {
+                        out.append(base[i]) catch {};
+                        i += 1;
+                        continue;
+                    }
+                    const name = base[i + 1 .. j];
+                    const val: []const u8 = switch (h.getp(server, name)) {
+                        .string => |s| s,
+                        else => "",
+                    };
+                    if (0 == val.len) {
+                        if (testmode) {
+                            out.appendSlice("test-") catch {};
+                            out.appendSlice(name) catch {};
+                        } else {
+                            std.debug.panic(
+                                "{s}: the server variable '{s}' is required: the API " ++
+                                    "base URL is '{s}' - pass .server = .{{ .{s} = \"...\" }} " ++
+                                    "in the SDK options",
+                                .{ sdkname, name, base, name },
+                            );
+                        }
+                    } else {
+                        out.appendSlice(val) catch {};
+                    }
+                    i = j + 1;
+                }
+                h.setp(opts, "base", h.vstr(out.toOwnedSlice() catch base));
+            }
+        },
+        else => {},
+    }
+
     // Restore system.fetch.
     if (!h.is_noval(sys_fetch)) {
         const sysv = h.getp(opts, "system");

package/project/.sdk/tm/zig/test/gotcha_test.zig

@@ -100,7 +100,7 @@ test "gotcha8: custom utility callable survives" {
     const fn_val = h.callable(@ptrCast(&probe_dummy), probeCall);
     const opts = h.jo(&.{.{ "utility", h.jo(&.{.{ "probe", fn_val }}) }});
     const client = sdk.SDK.new(opts);
-    const stored = h.getp(client.utility.custom, "probe");
+    const stored = h.getp(client.sdkUtility.custom, "probe");
     try testing.expect(stored == .function);
     const r = h.call_vfn(stored, h.vstr("x"));
     try testing.expect(r == .string and std.mem.eql(u8, r.string, "x"));
@@ -139,10 +139,10 @@ test "gotcha3: many features" {
 
 test "gotcha2: make_point surfaces out.point error" {
     const client = sdk.new();
-    const ctx = client.utility.make_context(.{ .opname = "list" }, client.get_root_ctx());
+    const ctx = client.sdkUtility.make_context(.{ .opname = "list" }, client.get_root_ctx());
     const e = ctx.make_error("rbac_denied", "denied");
     ctx.out_set("point", sdk.OutVal{ .err = e });
-    try testing.expectError(error.Sdk, client.utility.make_point(ctx));
+    try testing.expectError(error.Sdk, client.sdkUtility.make_point(ctx));
     try testing.expect(ctx.pending_err != null);
     try testing.expect(std.mem.eql(u8, ctx.pending_err.?.code, "rbac_denied"));
 }
@@ -152,8 +152,8 @@ test "gotcha2: make_point surfaces out.point error" {
 test "gotcha4: featureAdd before ordering" {
     const client = sdk.new();
     const ctx = client.get_root_ctx();
-    client.utility.feature_add(ctx, OrderFeat.make("aaa", vnull()));
-    client.utility.feature_add(ctx, OrderFeat.make("bbb", h.jo(&.{.{ "__before__", h.vstr("aaa") }})));
+    client.sdkUtility.feature_add(ctx, OrderFeat.make("aaa", vnull()));
+    client.sdkUtility.feature_add(ctx, OrderFeat.make("bbb", h.jo(&.{.{ "__before__", h.vstr("aaa") }})));
     var ai: usize = 999;
     var bi: usize = 999;
     for (client.features.items, 0..) |f, i| {
@@ -176,7 +176,7 @@ test "gotcha6: netsim offline error code" {
     });
     const client = sdk.SDK.new(opts);
     const ctx = client.get_root_ctx();
-    const r = client.utility.fetch(ctx, "http://x", h.jo(&.{.{ "url", h.vstr("http://x") }}));
+    const r = client.sdkUtility.fetch(ctx, "http://x", h.jo(&.{.{ "url", h.vstr("http://x") }}));
     try testing.expectError(error.Sdk, r);
     try testing.expect(std.mem.eql(u8, ctx.pending_err.?.code, "netsim_offline"));
 }
@@ -192,7 +192,7 @@ test "gotcha6: netsim conn error code" {
     });
     const client = sdk.SDK.new(opts);
     const ctx = client.get_root_ctx();
-    const r = client.utility.fetch(ctx, "http://x", h.jo(&.{.{ "url", h.vstr("http://x") }}));
+    const r = client.sdkUtility.fetch(ctx, "http://x", h.jo(&.{.{ "url", h.vstr("http://x") }}));
     try testing.expectError(error.Sdk, r);
     try testing.expect(std.mem.eql(u8, ctx.pending_err.?.code, "netsim_conn"));
 }
@@ -215,7 +215,7 @@ test "gotcha6: netsim seeded latency is deterministic" {
             const ctx = client.get_root_ctx();
             var i: usize = 0;
             while (i < 4) : (i += 1) {
-                _ = client.utility.fetch(ctx, "http://x", h.jo(&.{.{ "url", h.vstr("http://x") }})) catch {};
+                _ = client.sdkUtility.fetch(ctx, "http://x", h.jo(&.{.{ "url", h.vstr("http://x") }})) catch {};
             }
             return sleep_log.toOwnedSlice() catch &.{};
         }

package/project/sdkgen-package.json

@@ -0,0 +1,57 @@
+{
+  "sdkgen": {
+    "package": 1
+  },
+  "name": "@voxgig/sdkgen",
+  "version": "3.5.0",
+  "provides": {
+    "target": [
+      "c",
+      "clojure",
+      "cpp",
+      "csharp",
+      "dart",
+      "elixir",
+      "go",
+      "go-cli",
+      "go-mcp",
+      "haskell",
+      "java",
+      "js",
+      "kotlin",
+      "lean",
+      "lua",
+      "ocaml",
+      "perl",
+      "php",
+      "py",
+      "py-data",
+      "rb",
+      "rust",
+      "scala",
+      "seneca-provider",
+      "swift",
+      "ts",
+      "zig"
+    ],
+    "feature": [
+      "audit",
+      "cache",
+      "clienttrack",
+      "debug",
+      "idempotency",
+      "log",
+      "metrics",
+      "netsim",
+      "paging",
+      "proxy",
+      "ratelimit",
+      "rbac",
+      "retry",
+      "streaming",
+      "telemetry",
+      "test",
+      "timeout"
+    ]
+  }
+}

package/src/action/action.ts

@@ -12,6 +12,40 @@ import type {
 } from '../types'
 
 
+const indexEntry = (name: string) => `@"${name}.aontu"`
+
+
+// An index line that is an ACTIVE include, and the name it includes — or
+// undefined for a blank line, a comment, or anything else.
+//
+// Parsed rather than compared as a string, because both spellings around an
+// include are legal aontu and mean opposite things:
+//
+//   @"go.aontu"                 -> active, name 'go'
+//   @"go.aontu"  # pinned       -> active, name 'go'  (trailing comment)
+//     @"go.aontu"               -> active, name 'go'  (indented)
+//   # @"go.aontu"               -> NOT active
+//
+// A substring test (what this used to be) reads the commented-out form as
+// present, so `target add go` on a project that had switched the target off
+// by hand appended nothing and reported success while the target stayed
+// absent from the model. A whole-line equality test fixes that but then
+// misses the trailing-comment form, and appends a SECOND active include.
+const INDEX_ENTRY_RE = /^\s*@"([^"]+)\.aontu"\s*(?:#.*)?$/
+
+function indexEntryName(line: string): string | undefined {
+  const m = line.match(INDEX_ENTRY_RE)
+  return null == m ? undefined : m[1]
+}
+
+
+// Is this name already included by the index?
+function hasIndexEntry(content: string, name: string): boolean {
+  return content.split('\n')
+    .some((line: string) => indexEntryName(line) === name)
+}
+
+
 // Append `@"<name>.aontu"` import lines for each name not already present in
 // the index content. Checking against the accumulating result (not the
 // original) means duplicate names in the same call are added at most once.
@@ -19,9 +53,8 @@ function appendIndexEntries(content: string, names: string[]): string {
   let out = content
 
   for (const n of names) {
-    const entry = `@"${n}.aontu"`
-    if (!out.includes(entry)) {
-      out += '\n' + entry
+    if (!hasIndexEntry(out, n)) {
+      out += '\n' + indexEntry(n)
     }
   }
 
@@ -29,6 +62,25 @@ function appendIndexEntries(content: string, names: string[]): string {
 }
 
 
+// Drop the `@"<name>.aontu"` line for each name — the inverse of
+// appendIndexEntries, matching line-exact for the same reasons.
+//
+// Nothing calls this yet: a `remove` action is the fast-follow this exists
+// for (see docs/design/sdkgen-packages.md), and it is written here beside its
+// inverse so the two cannot drift on how an entry is recognised.
+function removeIndexEntries(content: string, names: string[]): string {
+  const drop = new Set(names)
+
+  return content
+    .split('\n')
+    .filter((line: string) => {
+      const name = indexEntryName(line)
+      return undefined === name || !drop.has(name)
+    })
+    .join('\n')
+}
+
+
 const UpdateIndex = cmp(function UpdateIndex(props: any) {
   Content(appendIndexEntries(props.content, props.names))
 })
@@ -45,7 +97,20 @@ function parseAddNames(args: any[]): string[] {
 }
 
 
-function loadContent(actx: ActionContext, which: string | string[]) {
+// The current index file for each kind, which `UpdateIndex` appends to.
+//
+// `seed` IS THE UPGRADE PATH. A project scaffolded before a kind existed has
+// no `model/<kind>/<kind>-index.aontu` — every project alive today is in
+// exactly that position for `docs` — and reading it unguarded made the FIRST
+// `docs add` in any existing project fail on ENOENT before it wrote anything.
+//
+// Seeded per call rather than defaulted for every kind: a missing
+// `target-index.aontu` in a scaffolded project is a broken project, and
+// quietly recreating it would hide that. A kind the project has never used is
+// a different thing, and only its own action knows which case it is in.
+function loadContent(
+  actx: ActionContext, which: string | string[], seed?: Record<string, string>,
+) {
   which = Array.isArray(which) ? which : [which]
 
   const content: any = {}
@@ -55,8 +120,9 @@ function loadContent(actx: ActionContext, which: string | string[]) {
 
   which.map((w: string) => {
     const indexfile = Path.join(modelfolder, w, w + '-index.aontu')
-    const indexcontent = fs.readFileSync(indexfile, 'utf8')
-    content[`${w}_index`] = indexcontent
+
+    content[`${w}_index`] = (null != seed?.[w] && !fs.existsSync(indexfile)) ?
+      seed[w] : fs.readFileSync(indexfile, 'utf8')
   })
 
   return content
@@ -64,9 +130,73 @@ function loadContent(actx: ActionContext, which: string | string[]) {
 
 
 
+// ENSURE THE PROJECT'S OWN MODEL INCLUDES A KIND'S INDEX.
+//
+// `model/sdk.aontu` is written once, by create-sdkgen, and includes the
+// indexes of the kinds that existed then. So a project scaffolded before a
+// kind existed — which is every project alive today, for `docs` — never
+// includes its index, and the item's model file is an orphan: it is on disk,
+// `<kind>-index.aontu` includes it, and NOTHING includes that. `main.kit.docs`
+// is then absent from the compiled model, so `package list`, `package update`
+// and `doctor` cannot see the item at all.
+//
+// Appending one include line is additive and idempotent, and it is the only
+// way an existing project can adopt a new kind without hand-editing. The
+// entry is parsed, not substring-matched, for the reason `hasIndexEntry`
+// documents: a commented-out include means the project switched it OFF, and
+// re-adding it would override that.
+function ensureModelInclude(actx: ActionContext, kind: string): boolean {
+  const fs = actx.fs()
+  const url = actx.url
+
+  if (!fs.existsSync(url)) {
+    // Said out loud rather than skipped silently: without the include the
+    // item is invisible to the next model compile, and a quiet no-op here
+    // would look exactly like success.
+    actx.log.warn({
+      point: 'model-include-absent', kind, file: url,
+      note: url + ' not found, so ' + indexEntry(kind + '/' + kind + '-index') +
+        ' could not be added — add it by hand, or nothing will see any ' +
+        kind + ' item'
+    })
+    return false
+  }
+
+  const name = kind + '/' + kind + '-index'
+  const content = String(fs.readFileSync(url, 'utf8'))
+
+  if (hasIndexEntry(content, name)) {
+    return false
+  }
+
+  if (actx.opts?.dryrun) {
+    actx.log.info({
+      point: 'model-include-dryrun', kind, file: url, entry: indexEntry(name),
+      note: '** DRY RUN ** would add ' + indexEntry(name) + ' to ' + url
+    })
+    return false
+  }
+
+  fs.writeFileSync(url,
+    content + (content.endsWith('\n') ? '' : '\n') +
+    indexEntry(name) + '\n')
+
+  actx.log.info({
+    point: 'model-include-added', kind, file: url, entry: indexEntry(name),
+    note: url + ': added ' + indexEntry(name) +
+      ' — without it the project model never sees any ' + kind + ' item'
+  })
+
+  return true
+}
+
+
 export {
   UpdateIndex,
+  ensureModelInclude,
   appendIndexEntries,
+  removeIndexEntries,
+  hasIndexEntry,
   parseAddNames,
   loadContent
 }