@kadi.build/core 0.8.0 → 0.11.0

package/dist/utils.js

@@ -0,0 +1,212 @@
+/**
+ * Dot-path utility functions for kadi-core
+ *
+ * Provides get/set/delete operations on nested objects using dot-notation paths.
+ * Used by AgentJsonManager for field-level reads and writes.
+ *
+ * @example
+ * ```typescript
+ * const obj = { deploy: { local: { target: 'docker' } } };
+ *
+ * getByPath(obj, 'deploy.local.target');
+ * // → 'docker'
+ *
+ * setByPath(obj, 'deploy.staging.target', 'akash');
+ * // obj is now: { deploy: { local: { target: 'docker' }, staging: { target: 'akash' } } }
+ *
+ * deleteByPath(obj, 'deploy.staging');
+ * // obj is now: { deploy: { local: { target: 'docker' } } }
+ * ```
+ */
+// ═══════════════════════════════════════════════════════════════════════
+// PATH PARSING
+// ═══════════════════════════════════════════════════════════════════════
+/**
+ * Split a dot-notation path into segments.
+ *
+ * If the full path exists as a literal key in the object, it takes precedence
+ * over dot-splitting. This handles the (rare) case where a key literally
+ * contains a dot.
+ *
+ * @param path - Dot-notation path (e.g., 'deploy.local.services')
+ * @returns Array of path segments
+ */
+export function splitPath(path) {
+    if (!path)
+        return [];
+    return path.split('.');
+}
+// ═══════════════════════════════════════════════════════════════════════
+// GET
+// ═══════════════════════════════════════════════════════════════════════
+/**
+ * Get a value from a nested object by dot-notation path.
+ *
+ * @param obj - The object to read from
+ * @param path - Dot-notation path (e.g., 'deploy.local.target')
+ * @returns The value at the path, or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * const config = { deploy: { local: { target: 'docker' } } };
+ *
+ * getByPath(config, 'deploy.local.target');  // 'docker'
+ * getByPath(config, 'deploy.local');          // { target: 'docker' }
+ * getByPath(config, 'missing');               // undefined
+ * getByPath(config, 'deploy.missing.deep');   // undefined
+ * ```
+ */
+export function getByPath(obj, path) {
+    // Check if the full path exists as a literal key first
+    if (path in obj) {
+        return obj[path];
+    }
+    const segments = splitPath(path);
+    let current = obj;
+    for (const segment of segments) {
+        if (current === null || current === undefined || typeof current !== 'object') {
+            return undefined;
+        }
+        current = current[segment];
+    }
+    return current;
+}
+// ═══════════════════════════════════════════════════════════════════════
+// SET
+// ═══════════════════════════════════════════════════════════════════════
+/**
+ * Deep merge two objects. Arrays and scalars are replaced, not merged.
+ *
+ * @param target - The object to merge into
+ * @param source - The object to merge from
+ * @returns The merged target object
+ */
+export function deepMerge(target, source) {
+    for (const key of Object.keys(source)) {
+        const sourceVal = source[key];
+        const targetVal = target[key];
+        if (sourceVal !== null &&
+            typeof sourceVal === 'object' &&
+            !Array.isArray(sourceVal) &&
+            targetVal !== null &&
+            typeof targetVal === 'object' &&
+            !Array.isArray(targetVal)) {
+            // Both are plain objects — recurse
+            target[key] = deepMerge(targetVal, sourceVal);
+        }
+        else {
+            // Scalar, array, or type mismatch — replace
+            target[key] = sourceVal;
+        }
+    }
+    return target;
+}
+/**
+ * Set a value in a nested object by dot-notation path.
+ *
+ * Creates intermediate objects as needed. For object values, performs
+ * a deep merge with existing values (preserving sibling keys).
+ * For scalars and arrays, replaces the value.
+ *
+ * @param obj - The object to modify (mutated in place)
+ * @param path - Dot-notation path (e.g., 'deploy.staging.target')
+ * @param value - The value to set
+ *
+ * @example
+ * ```typescript
+ * const config = { deploy: { local: { target: 'docker', engine: 'docker' } } };
+ *
+ * // Set a scalar — replaces
+ * setByPath(config, 'deploy.local.target', 'akash');
+ * // { deploy: { local: { target: 'akash', engine: 'docker' } } }
+ *
+ * // Set an object — deep merges
+ * setByPath(config, 'deploy.local', { network: 'mainnet' });
+ * // { deploy: { local: { target: 'akash', engine: 'docker', network: 'mainnet' } } }
+ *
+ * // Set on non-existent path — creates intermediates
+ * setByPath(config, 'build.arm64.from', 'node:22-slim');
+ * // { deploy: {...}, build: { arm64: { from: 'node:22-slim' } } }
+ * ```
+ */
+export function setByPath(obj, path, value) {
+    const segments = splitPath(path);
+    if (segments.length === 0)
+        return;
+    // Walk to the parent of the target key, creating intermediates
+    let current = obj;
+    for (let i = 0; i < segments.length - 1; i++) {
+        const segment = segments[i];
+        const next = current[segment];
+        if (next === null || next === undefined || typeof next !== 'object' || Array.isArray(next)) {
+            // Create intermediate object
+            const newObj = {};
+            current[segment] = newObj;
+            current = newObj;
+        }
+        else {
+            current = next;
+        }
+    }
+    const lastSegment = segments[segments.length - 1];
+    const existing = current[lastSegment];
+    // Deep merge if both existing and new are plain objects
+    if (value !== null &&
+        typeof value === 'object' &&
+        !Array.isArray(value) &&
+        existing !== null &&
+        typeof existing === 'object' &&
+        !Array.isArray(existing)) {
+        current[lastSegment] = deepMerge(existing, value);
+    }
+    else {
+        current[lastSegment] = value;
+    }
+}
+// ═══════════════════════════════════════════════════════════════════════
+// DELETE
+// ═══════════════════════════════════════════════════════════════════════
+/**
+ * Delete a key from a nested object by dot-notation path.
+ *
+ * @param obj - The object to modify (mutated in place)
+ * @param path - Dot-notation path to the key to delete
+ * @returns true if the key was found and deleted, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const config = { deploy: { local: { target: 'docker' }, staging: { target: 'akash' } } };
+ *
+ * deleteByPath(config, 'deploy.staging');
+ * // config is now: { deploy: { local: { target: 'docker' } } }
+ * // returns true
+ *
+ * deleteByPath(config, 'missing.key');
+ * // returns false
+ * ```
+ */
+export function deleteByPath(obj, path) {
+    const segments = splitPath(path);
+    if (segments.length === 0)
+        return false;
+    // Walk to the parent of the target key
+    let current = obj;
+    for (let i = 0; i < segments.length - 1; i++) {
+        const segment = segments[i];
+        if (current === null || current === undefined || typeof current !== 'object') {
+            return false;
+        }
+        current = current[segment];
+    }
+    if (current === null || current === undefined || typeof current !== 'object') {
+        return false;
+    }
+    const lastSegment = segments[segments.length - 1];
+    const parent = current;
+    if (!(lastSegment in parent)) {
+        return false;
+    }
+    delete parent[lastSegment];
+    return true;
+}
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kadi.build/core",
-  "version": "0.8.0",
+  "version": "0.11.0",
   "description": "A lean, readable SDK for building KADI agents.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -14,6 +14,8 @@
   "files": [
     "dist",
     "src",
+    "scripts",
+    "agent.json",
     "tsconfig.json",
     "README.md",
     "LICENSE"

package/scripts/symlink.mjs

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+
+/**
+ * kadi-core postinstall symlink script
+ *
+ * When kadi-core is installed as an ability (via `kadi install`), it ends up in:
+ *   <project>/abilities/kadi-core@x.y.z/
+ *
+ * This script creates a symlink so that regular Node.js imports work seamlessly:
+ *   <project>/node_modules/@kadi.build/core → <project>/abilities/kadi-core@x.y.z/
+ *
+ * This means users can do:
+ *   import { KadiClient } from '@kadi.build/core';
+ *
+ * without needing to know the ability install path or version number.
+ *
+ * The script is idempotent — safe to run multiple times.
+ */
+
+import { existsSync, mkdirSync, symlinkSync, lstatSync, readlinkSync, unlinkSync } from 'fs';
+import { join, dirname, resolve, relative } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// This script lives at <ability>/scripts/symlink.mjs
+// The ability root is one level up
+const abilityRoot = resolve(__dirname, '..');
+
+/**
+ * Walk up from the ability directory to find the project root.
+ * The project root is the parent of the "abilities" directory.
+ *
+ * Expected structure:
+ *   <project>/abilities/kadi-core@0.10.0/scripts/symlink.mjs
+ *   <project>/node_modules/@kadi.build/core  ← symlink target
+ */
+function findProjectRoot() {
+  let current = abilityRoot;
+
+  // Walk up looking for the abilities/ parent
+  for (let i = 0; i < 5; i++) {
+    const parent = dirname(current);
+    const dirName = current.split('/').pop() || current.split('\\').pop();
+
+    // Check if we're inside an "abilities" directory
+    if (parent && dirname(current).endsWith('abilities')) {
+      // Parent of abilities/ is the project root
+      return dirname(dirname(current));
+    }
+
+    // Also check if the parent directory name starts with "abilities"
+    const parentDirName = dirname(current).split('/').pop() || dirname(current).split('\\').pop();
+    if (parentDirName === 'abilities') {
+      return dirname(dirname(current));
+    }
+
+    current = parent;
+  }
+
+  // Fallback: if abilities/ directory exists as a sibling pattern,
+  // the project root is likely 2 levels up from where the ability is installed
+  // e.g., <project>/abilities/kadi-core@x.y.z → <project>
+  const twoUp = resolve(abilityRoot, '..', '..');
+  if (existsSync(join(twoUp, 'agent.json'))) {
+    return twoUp;
+  }
+
+  return null;
+}
+
+function main() {
+  const projectRoot = findProjectRoot();
+
+  if (!projectRoot) {
+    // Not installed as an ability (maybe running from source) — skip silently
+    console.log('[kadi-core] Not installed as an ability, skipping symlink creation.');
+    return;
+  }
+
+  const symlinkDir = join(projectRoot, 'node_modules', '@kadi.build');
+  const symlinkPath = join(symlinkDir, 'core');
+
+  // Compute relative path from symlink location to ability root
+  const relativeTarget = relative(symlinkDir, abilityRoot);
+
+  // Create the @kadi.build/ directory in node_modules
+  if (!existsSync(symlinkDir)) {
+    mkdirSync(symlinkDir, { recursive: true });
+    console.log(`[kadi-core] Created ${symlinkDir}`);
+  }
+
+  // Check if symlink already exists and points to the right place
+  if (existsSync(symlinkPath)) {
+    try {
+      const stats = lstatSync(symlinkPath);
+      if (stats.isSymbolicLink()) {
+        const currentTarget = readlinkSync(symlinkPath);
+        if (resolve(symlinkDir, currentTarget) === abilityRoot) {
+          console.log(`[kadi-core] Symlink already exists and is correct: ${symlinkPath}`);
+          return;
+        }
+        // Wrong target — remove and recreate
+        console.log(`[kadi-core] Updating symlink (was pointing to ${currentTarget})`);
+        unlinkSync(symlinkPath);
+      } else {
+        // It's a real directory/file — don't touch it
+        console.log(`[kadi-core] ${symlinkPath} exists and is not a symlink — skipping.`);
+        console.log('[kadi-core] If you want the symlink, remove the existing directory first.');
+        return;
+      }
+    } catch {
+      // Can't read — try to remove
+      try { unlinkSync(symlinkPath); } catch { /* ignore */ }
+    }
+  }
+
+  // Create the symlink
+  try {
+    symlinkSync(relativeTarget, symlinkPath, 'dir');
+    console.log(`[kadi-core] Created symlink: ${symlinkPath} → ${relativeTarget}`);
+    console.log('[kadi-core] You can now: import { KadiClient } from \'@kadi.build/core\'');
+  } catch (error) {
+    console.error(`[kadi-core] Failed to create symlink: ${error.message}`);
+    console.error(`[kadi-core] You can create it manually:`);
+    console.error(`  ln -s ${relativeTarget} ${symlinkPath}`);
+  }
+}
+
+main();