@kinotic-ai/spawn 0.3.0 → 0.5.0

package/dist/node/index.js

@@ -0,0 +1,77 @@
+import {
+  SpawnEngine
+} from "../shared/spawn-1h1k8w8r.js";
+
+// packages/spawn/src/node/index.ts
+import fs from "node:fs";
+import fsP from "node:fs/promises";
+import path from "node:path";
+function assertContained(root, resolved) {
+  const rel = path.relative(root, resolved);
+  if (rel.startsWith("..") || path.isAbsolute(rel)) {
+    throw new Error(`Path escapes ${root}: ${resolved}`);
+  }
+  return resolved;
+}
+function assertPathWithin(root, target) {
+  return assertContained(root, path.resolve(root, target));
+}
+async function loadSpawnTree(dir) {
+  const tree = {};
+  const entries = await fsP.readdir(dir, { recursive: true, withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isFile()) {
+      continue;
+    }
+    const filePath = path.join(entry.parentPath, entry.name);
+    const treePath = path.relative(dir, filePath).split(path.sep).join("/");
+    if (treePath.endsWith(".liquid")) {
+      tree[treePath] = await fsP.readFile(filePath, { encoding: "utf8" });
+    } else {
+      tree[treePath] = await fsP.readFile(filePath);
+    }
+  }
+  return tree;
+}
+function diskInheritanceLoader(spawnRoot) {
+  let currentDir = spawnRoot;
+  return async (ref) => {
+    currentDir = assertContained(spawnRoot, path.resolve(currentDir, ref));
+    if (!fs.existsSync(path.resolve(currentDir, "spawn.json"))) {
+      throw new Error(`Inherited spawn ${path.resolve(currentDir, "spawn.json")} does not exist`);
+    }
+    return loadSpawnTree(currentDir);
+  };
+}
+async function lintSpawnDir(dir) {
+  return new SpawnEngine().lint(await loadSpawnTree(dir), { loadInherited: diskInheritanceLoader(dir) });
+}
+
+class NodeSpawnRenderer {
+  engine = new SpawnEngine;
+  async render(spawnDir, destination, options) {
+    if (fs.existsSync(destination)) {
+      throw new Error(`The target directory ${destination} already exists`);
+    }
+    const result = await this.engine.renderSpawn(await loadSpawnTree(spawnDir), {
+      context: options?.context,
+      propertyResolver: options?.propertyResolver,
+      loadInherited: diskInheritanceLoader(spawnDir)
+    });
+    await this.writeSpawnTree(result.files, destination);
+    return result.context;
+  }
+  async writeSpawnTree(tree, destination) {
+    await fsP.mkdir(destination, { recursive: true });
+    for (const [treePath, content] of Object.entries(tree)) {
+      const filePath = assertPathWithin(destination, treePath);
+      await fsP.mkdir(path.dirname(filePath), { recursive: true });
+      await fsP.writeFile(filePath, content);
+    }
+  }
+}
+export {
+  lintSpawnDir,
+  assertPathWithin,
+  NodeSpawnRenderer
+};

package/dist/shared/spawn-1h1k8w8r.js

@@ -0,0 +1,172 @@
+// 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, strictVariables: 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, configs } = await this.walkInheritance(spawn, options?.loadInherited);
+    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 = {};
+    const sources = {};
+    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;
+        sources[destination] = source;
+      }
+    }
+    return { files, sources, context };
+  }
+  async lint(spawn, options) {
+    const { trees, configs } = await this.walkInheritance(spawn, options?.loadInherited);
+    const declared = new Set;
+    for (const config of configs) {
+      if (config.globals) {
+        Object.keys(config.globals).forEach((key) => declared.add(key));
+      }
+      if (config.propertySchema) {
+        Object.keys(config.propertySchema).forEach((key) => declared.add(key));
+      }
+    }
+    const usedIn = new Map;
+    const record = (name, file) => {
+      let files = usedIn.get(name);
+      if (!files) {
+        files = new Set;
+        usedIn.set(name, files);
+      }
+      files.add(file);
+    };
+    const externalVars = (template) => Object.keys(this.engine.parseAndAnalyzeSync(template, undefined, { partials: false }).globals);
+    for (const tree of trees) {
+      for (const source of Object.keys(tree)) {
+        const fileName = source.substring(source.lastIndexOf("/") + 1);
+        if (IGNORED_FILE_NAMES.includes(fileName)) {
+          continue;
+        }
+        externalVars(source).forEach((name) => record(name, source));
+        const content = tree[source];
+        if (source.endsWith(".liquid") && typeof content === "string") {
+          externalVars(content).forEach((name) => record(name, source));
+        }
+      }
+    }
+    const undeclared = [];
+    for (const [name, files] of usedIn) {
+      if (!declared.has(name)) {
+        undeclared.push({ name, files: [...files].sort() });
+      }
+    }
+    undeclared.sort((a, b) => a.name.localeCompare(b.name));
+    return { undeclared };
+  }
+  async walkInheritance(spawn, loadInherited) {
+    const trees = [spawn];
+    const configs = [];
+    let currentConfig = this.parseConfig(spawn);
+    if (currentConfig) {
+      configs.push(currentConfig);
+    }
+    while (currentConfig?.inherits) {
+      if (!loadInherited) {
+        throw new Error(`Spawn inherits '${currentConfig.inherits}' but no loadInherited callback was provided`);
+      }
+      const inherited = await loadInherited(currentConfig.inherits);
+      trees.push(inherited);
+      currentConfig = this.parseConfig(inherited);
+      if (currentConfig) {
+        configs.push(currentConfig);
+      }
+    }
+    return { trees, configs };
+  }
+  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

@@ -1,6 +1,6 @@
 {
   "name": "@kinotic-ai/spawn",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "type": "module",
   "files": [
     "dist"
@@ -19,6 +19,16 @@
         "default": "./dist/index.cjs"
       }
     },
+    "./node": {
+      "import": {
+        "types": "./dist/node/index.d.ts",
+        "default": "./dist/node/index.js"
+      },
+      "require": {
+        "types": "./dist/node/index.d.cts",
+        "default": "./dist/node/index.cjs"
+      }
+    },
     "./package.json": "./package.json"
   },
   "homepage": "https://github.com/kinotic-ai/kinotic",
@@ -30,11 +40,11 @@
     "type-check": "tsc --noEmit",
     "test": "vitest run",
     "coverage": "vitest run --coverage",
-    "build:renderer": "bun build ./src/spawnRendererMain.ts --outfile ./dist/spawn-renderer.global.js --format=iife --target=browser"
+    "build:graal-spawn-renderer": "bun build ./src/graalSpawnRendererMain.ts --outfile ./dist/graal-spawn-renderer.js --format=iife --target=browser"
   },
   "dependencies": {
-    "liquidjs": "10.25.7",
-    "zod": "^4.3.6"
+    "liquidjs": "10.27.0",
+    "zod": "4.4.3"
   },
   "devDependencies": {
     "@types/node": "^25.3.2",