@kinotic-ai/spawn 0.1.0

package/README.md

@@ -0,0 +1,14 @@
+# @kinotic-ai/spawn
+
+Host-agnostic engine for rendering Spawns: file trees containing liquid
+templates, liquid expressions in file paths, and an optional `spawn.json`
+declaring globals, a property schema, and inheritance.
+
+The engine performs no IO — it takes an in-memory tree of `path -> content`
+and returns the rendered tree. Hosts supply the adapters:
+
+- the Kinotic CLI loads spawns from disk and prompts for missing properties
+  via a `PropertyResolver`
+- the Kinotic server runs the same engine embedded in the JVM (GraalJS) to
+  render project baselines into freshly provisioned repositories, with the
+  context derived entirely from the `Project`

package/dist/index.cjs

@@ -0,0 +1,167 @@
+var import_node_module = require("node:module");
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+function __accessProp(key) {
+  return this[key];
+}
+var __toCommonJS = (from) => {
+  var entry = (__moduleCache ??= new WeakMap).get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (var key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(entry, key))
+        __defProp(entry, key, {
+          get: __accessProp.bind(from, key),
+          enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+        });
+  }
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __moduleCache;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+
+// packages/spawn/src/index.ts
+var exports_src = {};
+__export(exports_src, {
+  SpawnEngine: () => SpawnEngine
+});
+module.exports = __toCommonJS(exports_src);
+
+// packages/spawn/src/api/SpawnEngine.ts
+var import_liquidjs = require("liquidjs");
+var import_zod = require("zod");
+var PropertySchemaSchema = import_zod.z.object({
+  type: import_zod.z.enum(["string", "number", "integer", "boolean"]).optional(),
+  description: import_zod.z.string().optional(),
+  default: import_zod.z.union([import_zod.z.string(), import_zod.z.number(), import_zod.z.boolean()]).optional(),
+  enum: import_zod.z.array(import_zod.z.string()).optional()
+});
+var SpawnConfigSchema = import_zod.z.object({
+  inherits: import_zod.z.string().optional(),
+  globals: import_zod.z.record(import_zod.z.string(), import_zod.z.unknown()).optional(),
+  propertySchema: import_zod.z.record(import_zod.z.string(), PropertySchemaSchema).optional()
+});
+var IGNORED_FILE_NAMES = ["spawn.json", ".DS_Store"];
+function upperFirst(s) {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+function camelCase(s) {
+  return s.replace(/[-_\s]+(.)/g, (_, c) => c.toUpperCase()).replace(/^(.)/, (_, c) => c.toLowerCase());
+}
+
+class SpawnEngine {
+  engine;
+  constructor() {
+    this.engine = new import_liquidjs.Liquid({ cache: true });
+    this.engine.registerFilter("packageToPath", (v) => v.replaceAll(".", "/"));
+    this.engine.registerFilter("encodePackage", (v) => {
+      v = v.replaceAll("-", "_");
+      v = v.replace(/\.(\d+)/g, "._$1");
+      return v;
+    });
+    this.engine.registerFilter("camelCase", (v) => camelCase(v));
+    this.engine.registerFilter("upperFirst", (v) => upperFirst(v));
+  }
+  async renderSpawn(spawn, options) {
+    const trees = [spawn];
+    const configs = [];
+    let currentConfig = this.parseConfig(spawn);
+    if (currentConfig) {
+      configs.push(currentConfig);
+    }
+    while (currentConfig?.inherits) {
+      if (!options?.loadInherited) {
+        throw new Error(`Spawn inherits '${currentConfig.inherits}' but no loadInherited callback was provided`);
+      }
+      const inherited = await options.loadInherited(currentConfig.inherits);
+      trees.push(inherited);
+      currentConfig = this.parseConfig(inherited);
+      if (currentConfig) {
+        configs.push(currentConfig);
+      }
+    }
+    let globals = {};
+    let propertySchemas = {};
+    for (const config of [...configs].reverse()) {
+      if (config.globals) {
+        globals = { ...globals, ...config.globals };
+      }
+      if (config.propertySchema) {
+        propertySchemas = { ...propertySchemas, ...config.propertySchema };
+      }
+    }
+    let context = { ...globals, ...options?.context };
+    context = await this.resolveMissingProperties(propertySchemas, context, options?.propertyResolver);
+    const files = {};
+    for (const tree of [...trees].reverse()) {
+      for (const source of Object.keys(tree).sort()) {
+        const fileName = source.substring(source.lastIndexOf("/") + 1);
+        if (IGNORED_FILE_NAMES.includes(fileName)) {
+          continue;
+        }
+        let destination = source;
+        if (destination.includes("{{")) {
+          destination = await this.engine.parseAndRender(destination, context);
+        }
+        let content = tree[source];
+        if (destination.endsWith(".liquid")) {
+          destination = destination.substring(0, destination.length - 7);
+          if (typeof content !== "string") {
+            throw new Error(`Template ${source} must contain text content`);
+          }
+          content = await this.engine.parseAndRender(content, context);
+        }
+        files[destination] = content;
+      }
+    }
+    return { files, context };
+  }
+  parseConfig(tree) {
+    const raw = tree["spawn.json"];
+    if (raw === undefined) {
+      return;
+    }
+    const text = typeof raw === "string" ? raw : new TextDecoder().decode(raw);
+    return SpawnConfigSchema.parse(JSON.parse(text));
+  }
+  async resolveMissingProperties(propertySchemas, context, resolver) {
+    const ret = { ...context };
+    for (const key in propertySchemas) {
+      if (!Object.prototype.hasOwnProperty.call(ret, key)) {
+        if (!resolver) {
+          throw new Error(`No value provided for required property '${key}'`);
+        }
+        const schema = propertySchemas[key];
+        let message;
+        if (schema.description?.includes("{{")) {
+          message = this.engine.parseAndRenderSync(schema.description, ret);
+        } else {
+          message = schema.description ?? key;
+        }
+        let defaultValue = schema.default;
+        if (typeof schema.default === "string" && schema.default.includes("{{")) {
+          defaultValue = this.engine.parseAndRenderSync(schema.default, ret);
+        }
+        ret[key] = await resolver.resolve(key, schema, message, defaultValue);
+      }
+    }
+    return ret;
+  }
+}

package/dist/index.d.cts

@@ -0,0 +1,110 @@
+/**
+* Declares a single property a spawn needs to render, as found in a
+* spawn.json propertySchema. Descriptions and defaults may contain liquid
+* expressions, which are rendered against the context resolved so far before
+* the property is requested from a {@link PropertyResolver}.
+*/
+interface PropertySchema {
+	type?: "string" | "number" | "integer" | "boolean";
+	description?: string;
+	default?: string | number | boolean;
+	enum?: string[];
+}
+/**
+* Supplies values for properties declared in a spawn's propertySchema that are
+* absent from the render context. An interactive host can prompt the user; a
+* non-interactive host can omit the resolver entirely, in which case rendering
+* fails on the first missing property.
+*/
+interface PropertyResolver {
+	/**
+	* Returns the value to use for {@code key}.
+	*
+	* @param key the property name as declared in the propertySchema
+	* @param schema the declaration for the property (type, enum, etc.)
+	* @param message the property description with any liquid expressions already
+	*        rendered against the context resolved so far, or the key when the
+	*        schema has no description
+	* @param defaultValue the schema default with any liquid expressions already
+	*        rendered, or undefined when the schema has no default
+	*/
+	resolve(key: string, schema: PropertySchema, message: string, defaultValue?: unknown): Promise<unknown>;
+}
+/**
+* The files of a spawn or of a rendered result, keyed by POSIX-style relative
+* path (no leading slash). Text files are strings; binary files are
+* {@link Uint8Array} and are copied verbatim, never rendered.
+*/
+type SpawnTree = Record<string, string | Uint8Array>;
+/**
+* Options for {@link SpawnEngine#renderSpawn}.
+*/
+interface RenderSpawnOptions {
+	/**
+	* Values made available to the templates. Entries here override globals
+	* declared in spawn.json and are never re-requested from the
+	* {@link PropertyResolver}.
+	*/
+	context?: Record<string, unknown>;
+	/**
+	* Supplies values for propertySchema entries missing from the context.
+	* When omitted, a missing property fails the render.
+	*/
+	propertyResolver?: PropertyResolver;
+	/**
+	* Loads the spawn referenced by a spawn.json {@code inherits} value. The ref
+	* is passed verbatim; resolving it (e.g. against the location of the spawn
+	* that declared it) is the host's responsibility. Inheritance chains are
+	* linear, so refs are requested in declaration order: each call refers to the
+	* spawn loaded by the previous one. Required when the spawn uses inheritance.
+	*/
+	loadInherited?: (ref: string) => Promise<SpawnTree>;
+}
+/**
+* The outcome of rendering a spawn.
+*/
+interface SpawnRenderResult {
+	/**
+	* The rendered files keyed by destination path: liquid expressions in paths
+	* are rendered, {@code .liquid} suffixes are stripped, and files from derived
+	* spawns overwrite same-destination files from inherited spawns.
+	*/
+	files: SpawnTree;
+	/**
+	* The full context the templates were rendered with: merged globals,
+	* caller-provided values, and any values supplied by the property resolver.
+	*/
+	context: Record<string, unknown>;
+}
+/**
+* Renders a Spawn: a file tree containing liquid templates, an optional
+* spawn.json, and liquid expressions in file paths. The engine is
+* host-agnostic — it operates on in-memory {@link SpawnTree}s and performs no
+* IO, so the same implementation runs in Node and embedded in the JVM.
+*
+* Rendering applies the following rules:
+*
+* - spawn.json declares globals, a propertySchema, and an optional inherited
+*   spawn; inheritance chains are followed via
+*   {@link RenderSpawnOptions#loadInherited}
+* - globals and propertySchema entries from derived spawns override inherited
+*   ones; values supplied in the context override globals
+* - propertySchema entries missing from the context are obtained from the
+*   {@link PropertyResolver}, or fail the render when no resolver is given
+* - paths containing liquid expressions are rendered; files ending in
+*   {@code .liquid} have their content rendered and the suffix stripped
+* - files from derived spawns overwrite same-destination files from inherited
+*   spawns
+*/
+declare class SpawnEngine {
+	private engine;
+	constructor();
+	/**
+	* Renders the given spawn and returns the rendered files along with the full
+	* context used, including values added by the property resolver.
+	*/
+	renderSpawn(spawn: SpawnTree, options?: RenderSpawnOptions): Promise<SpawnRenderResult>;
+	private parseConfig;
+	private resolveMissingProperties;
+}
+export { SpawnTree, SpawnRenderResult, SpawnEngine, RenderSpawnOptions, PropertySchema, PropertyResolver };

package/dist/index.d.ts

@@ -0,0 +1,110 @@
+/**
+* Declares a single property a spawn needs to render, as found in a
+* spawn.json propertySchema. Descriptions and defaults may contain liquid
+* expressions, which are rendered against the context resolved so far before
+* the property is requested from a {@link PropertyResolver}.
+*/
+interface PropertySchema {
+	type?: "string" | "number" | "integer" | "boolean";
+	description?: string;
+	default?: string | number | boolean;
+	enum?: string[];
+}
+/**
+* Supplies values for properties declared in a spawn's propertySchema that are
+* absent from the render context. An interactive host can prompt the user; a
+* non-interactive host can omit the resolver entirely, in which case rendering
+* fails on the first missing property.
+*/
+interface PropertyResolver {
+	/**
+	* Returns the value to use for {@code key}.
+	*
+	* @param key the property name as declared in the propertySchema
+	* @param schema the declaration for the property (type, enum, etc.)
+	* @param message the property description with any liquid expressions already
+	*        rendered against the context resolved so far, or the key when the
+	*        schema has no description
+	* @param defaultValue the schema default with any liquid expressions already
+	*        rendered, or undefined when the schema has no default
+	*/
+	resolve(key: string, schema: PropertySchema, message: string, defaultValue?: unknown): Promise<unknown>;
+}
+/**
+* The files of a spawn or of a rendered result, keyed by POSIX-style relative
+* path (no leading slash). Text files are strings; binary files are
+* {@link Uint8Array} and are copied verbatim, never rendered.
+*/
+type SpawnTree = Record<string, string | Uint8Array>;
+/**
+* Options for {@link SpawnEngine#renderSpawn}.
+*/
+interface RenderSpawnOptions {
+	/**
+	* Values made available to the templates. Entries here override globals
+	* declared in spawn.json and are never re-requested from the
+	* {@link PropertyResolver}.
+	*/
+	context?: Record<string, unknown>;
+	/**
+	* Supplies values for propertySchema entries missing from the context.
+	* When omitted, a missing property fails the render.
+	*/
+	propertyResolver?: PropertyResolver;
+	/**
+	* Loads the spawn referenced by a spawn.json {@code inherits} value. The ref
+	* is passed verbatim; resolving it (e.g. against the location of the spawn
+	* that declared it) is the host's responsibility. Inheritance chains are
+	* linear, so refs are requested in declaration order: each call refers to the
+	* spawn loaded by the previous one. Required when the spawn uses inheritance.
+	*/
+	loadInherited?: (ref: string) => Promise<SpawnTree>;
+}
+/**
+* The outcome of rendering a spawn.
+*/
+interface SpawnRenderResult {
+	/**
+	* The rendered files keyed by destination path: liquid expressions in paths
+	* are rendered, {@code .liquid} suffixes are stripped, and files from derived
+	* spawns overwrite same-destination files from inherited spawns.
+	*/
+	files: SpawnTree;
+	/**
+	* The full context the templates were rendered with: merged globals,
+	* caller-provided values, and any values supplied by the property resolver.
+	*/
+	context: Record<string, unknown>;
+}
+/**
+* Renders a Spawn: a file tree containing liquid templates, an optional
+* spawn.json, and liquid expressions in file paths. The engine is
+* host-agnostic — it operates on in-memory {@link SpawnTree}s and performs no
+* IO, so the same implementation runs in Node and embedded in the JVM.
+*
+* Rendering applies the following rules:
+*
+* - spawn.json declares globals, a propertySchema, and an optional inherited
+*   spawn; inheritance chains are followed via
+*   {@link RenderSpawnOptions#loadInherited}
+* - globals and propertySchema entries from derived spawns override inherited
+*   ones; values supplied in the context override globals
+* - propertySchema entries missing from the context are obtained from the
+*   {@link PropertyResolver}, or fail the render when no resolver is given
+* - paths containing liquid expressions are rendered; files ending in
+*   {@code .liquid} have their content rendered and the suffix stripped
+* - files from derived spawns overwrite same-destination files from inherited
+*   spawns
+*/
+declare class SpawnEngine {
+	private engine;
+	constructor();
+	/**
+	* Renders the given spawn and returns the rendered files along with the full
+	* context used, including values added by the property resolver.
+	*/
+	renderSpawn(spawn: SpawnTree, options?: RenderSpawnOptions): Promise<SpawnRenderResult>;
+	private parseConfig;
+	private resolveMissingProperties;
+}
+export { SpawnTree, SpawnRenderResult, SpawnEngine, RenderSpawnOptions, PropertySchema, PropertyResolver };

package/dist/index.js

@@ -0,0 +1,124 @@
+// packages/spawn/src/api/SpawnEngine.ts
+import { Liquid } from "liquidjs";
+import { z } from "zod";
+var PropertySchemaSchema = z.object({
+  type: z.enum(["string", "number", "integer", "boolean"]).optional(),
+  description: z.string().optional(),
+  default: z.union([z.string(), z.number(), z.boolean()]).optional(),
+  enum: z.array(z.string()).optional()
+});
+var SpawnConfigSchema = z.object({
+  inherits: z.string().optional(),
+  globals: z.record(z.string(), z.unknown()).optional(),
+  propertySchema: z.record(z.string(), PropertySchemaSchema).optional()
+});
+var IGNORED_FILE_NAMES = ["spawn.json", ".DS_Store"];
+function upperFirst(s) {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+function camelCase(s) {
+  return s.replace(/[-_\s]+(.)/g, (_, c) => c.toUpperCase()).replace(/^(.)/, (_, c) => c.toLowerCase());
+}
+
+class SpawnEngine {
+  engine;
+  constructor() {
+    this.engine = new Liquid({ cache: true });
+    this.engine.registerFilter("packageToPath", (v) => v.replaceAll(".", "/"));
+    this.engine.registerFilter("encodePackage", (v) => {
+      v = v.replaceAll("-", "_");
+      v = v.replace(/\.(\d+)/g, "._$1");
+      return v;
+    });
+    this.engine.registerFilter("camelCase", (v) => camelCase(v));
+    this.engine.registerFilter("upperFirst", (v) => upperFirst(v));
+  }
+  async renderSpawn(spawn, options) {
+    const trees = [spawn];
+    const configs = [];
+    let currentConfig = this.parseConfig(spawn);
+    if (currentConfig) {
+      configs.push(currentConfig);
+    }
+    while (currentConfig?.inherits) {
+      if (!options?.loadInherited) {
+        throw new Error(`Spawn inherits '${currentConfig.inherits}' but no loadInherited callback was provided`);
+      }
+      const inherited = await options.loadInherited(currentConfig.inherits);
+      trees.push(inherited);
+      currentConfig = this.parseConfig(inherited);
+      if (currentConfig) {
+        configs.push(currentConfig);
+      }
+    }
+    let globals = {};
+    let propertySchemas = {};
+    for (const config of [...configs].reverse()) {
+      if (config.globals) {
+        globals = { ...globals, ...config.globals };
+      }
+      if (config.propertySchema) {
+        propertySchemas = { ...propertySchemas, ...config.propertySchema };
+      }
+    }
+    let context = { ...globals, ...options?.context };
+    context = await this.resolveMissingProperties(propertySchemas, context, options?.propertyResolver);
+    const files = {};
+    for (const tree of [...trees].reverse()) {
+      for (const source of Object.keys(tree).sort()) {
+        const fileName = source.substring(source.lastIndexOf("/") + 1);
+        if (IGNORED_FILE_NAMES.includes(fileName)) {
+          continue;
+        }
+        let destination = source;
+        if (destination.includes("{{")) {
+          destination = await this.engine.parseAndRender(destination, context);
+        }
+        let content = tree[source];
+        if (destination.endsWith(".liquid")) {
+          destination = destination.substring(0, destination.length - 7);
+          if (typeof content !== "string") {
+            throw new Error(`Template ${source} must contain text content`);
+          }
+          content = await this.engine.parseAndRender(content, context);
+        }
+        files[destination] = content;
+      }
+    }
+    return { files, context };
+  }
+  parseConfig(tree) {
+    const raw = tree["spawn.json"];
+    if (raw === undefined) {
+      return;
+    }
+    const text = typeof raw === "string" ? raw : new TextDecoder().decode(raw);
+    return SpawnConfigSchema.parse(JSON.parse(text));
+  }
+  async resolveMissingProperties(propertySchemas, context, resolver) {
+    const ret = { ...context };
+    for (const key in propertySchemas) {
+      if (!Object.prototype.hasOwnProperty.call(ret, key)) {
+        if (!resolver) {
+          throw new Error(`No value provided for required property '${key}'`);
+        }
+        const schema = propertySchemas[key];
+        let message;
+        if (schema.description?.includes("{{")) {
+          message = this.engine.parseAndRenderSync(schema.description, ret);
+        } else {
+          message = schema.description ?? key;
+        }
+        let defaultValue = schema.default;
+        if (typeof schema.default === "string" && schema.default.includes("{{")) {
+          defaultValue = this.engine.parseAndRenderSync(schema.default, ret);
+        }
+        ret[key] = await resolver.resolve(key, schema, message, defaultValue);
+      }
+    }
+    return ret;
+  }
+}
+export {
+  SpawnEngine
+};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@kinotic-ai/spawn",
+  "version": "0.1.0",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "module": "./dist/index.js",
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "homepage": "https://github.com/kinotic-ai/kinotic",
+  "license": "Elastic License 2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "liquidjs": "10.25.7",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.2",
+    "@vitest/coverage-v8": "^4.0.18",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
+  }
+}