@mamund/grail 0.0.0-stage → 0.1.0

package/cli/grail-cli.js

@@ -0,0 +1,565 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const packageJson = JSON.parse(
+  fs.readFileSync(path.resolve(__dirname, '..', 'package.json'), 'utf8')
+);
+
+function showHelp() {
+  console.log(`GRAIL
+
+Usage:
+  grail <command> [options]
+
+Commands:
+  init       Create a runnable GRAIL world
+  run        Run a GRAIL environment
+  show       Display validated configuration
+  validate   Validate a GRAIL environment
+
+Options:
+  --config <directory>   Configuration directory (default: ./config)
+  --goal <effect>        Override the configured goal (run only)
+  --inputs <json>        Override inputs with a JSON object (run only)
+  --inputs-file <file>   Override inputs from a JSON file (run only)
+  --output <mode>        Result format: summary or json (run only)
+  --help, -h             Show help
+  --version, -v          Show version
+
+Examples:
+  grail init my-world
+  grail validate --config ./config
+  grail show registry
+  grail run --config ./config
+  grail run --config ./config --goal greetingCreated
+  grail run --config ./config --inputs '{"name":"Mike"}'
+  grail run --config ./config --inputs-file ./cases/mike.json
+  grail run --output summary
+  grail run --output json`);
+}
+
+function showCommandHelp(command) {
+
+  if (command === 'init') {
+    console.log(`GRAIL init
+
+Usage:
+  grail init <directory>
+
+Creates a complete, runnable GRAIL world.
+
+Example:
+  grail init my-world`);
+    return;
+  }
+
+  if (command === 'run') {
+    console.log(`GRAIL run
+
+Usage:
+  grail run [--config <directory>] [--goal <effect>] [--inputs <json> | --inputs-file <file>] [--output summary|json]
+
+Runs the goal declared by the GRAIL environment, with optional invocation-specific goal and input overrides.
+
+Options:
+  --config <directory>   Configuration directory (default: ./config)
+  --goal <effect>        Override the goal declared in goal.json for this run
+  --inputs <json>        Replace inputs.json for this run with an inline JSON object
+  --inputs-file <file>   Replace inputs.json for this run with a JSON file
+  --output <mode>        Print a summary or complete JSON result (default: existing trace)
+  --help, -h             Show help`);
+    return;
+  }
+
+  if (command === 'show') {
+    console.log(`GRAIL show
+
+Usage:
+  grail show [registry|worldstate|inputs|goal] [--config <directory>]
+
+Displays validated configuration as formatted JSON without executing capabilities.
+Without a target, displays all four configuration documents.
+
+Options:
+  --config <directory>   Configuration directory (default: ./config)
+  --help, -h             Show help`);
+    return;
+  }
+
+  if (command === 'validate') {
+    console.log(`GRAIL validate
+
+Usage:
+  grail validate [--config <directory>]
+
+Loads and validates the GRAIL environment without running it.
+
+Options:
+  --config <directory>   Configuration directory (default: ./config)
+  --help, -h             Show help`);
+  }
+}
+
+function parseConfig(args) {
+  let configDir = './config';
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+
+    if (arg === '--config') {
+      const value = args[i + 1];
+      if (!value || value.startsWith('-')) {
+        const error = new Error('--config requires a directory.');
+        error.hint = 'Run \"grail run --help\" or \"grail validate --help\" for usage.';
+        throw error;
+      }
+      configDir = value;
+      i += 1;
+      continue;
+    }
+
+    if (arg.startsWith('--config=')) {
+      const value = arg.slice('--config='.length);
+      if (!value) {
+        const error = new Error('--config requires a directory.');
+        error.hint = 'Run \"grail run --help\" or \"grail validate --help\" for usage.';
+        throw error;
+      }
+      configDir = value;
+      continue;
+    }
+
+    const error = new Error(`Unknown option: ${arg}`);
+    error.hint = 'Run the command with --help for supported options.';
+    throw error;
+  }
+
+  return path.resolve(configDir);
+}
+
+function parseRunOptions(args) {
+  let configDir = './config';
+  let goal;
+  let inputs;
+  let inputsFile;
+  let output;
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+
+    if (arg === '--config') {
+      const value = args[i + 1];
+      if (!value || value.startsWith('-')) {
+        const error = new Error('--config requires a directory.');
+        error.hint = 'Run "grail run --help" for usage.';
+        throw error;
+      }
+      configDir = value;
+      i += 1;
+      continue;
+    }
+
+    if (arg.startsWith('--config=')) {
+      const value = arg.slice('--config='.length);
+      if (!value) {
+        const error = new Error('--config requires a directory.');
+        error.hint = 'Run "grail run --help" for usage.';
+        throw error;
+      }
+      configDir = value;
+      continue;
+    }
+
+    if (arg === '--goal') {
+      const value = args[i + 1];
+      if (!value || value.startsWith('-')) {
+        const error = new Error('--goal requires an effect.');
+        error.hint = 'Run "grail run --help" for usage.';
+        throw error;
+      }
+      goal = value;
+      i += 1;
+      continue;
+    }
+
+    if (arg.startsWith('--goal=')) {
+      const value = arg.slice('--goal='.length);
+      if (!value) {
+        const error = new Error('--goal requires an effect.');
+        error.hint = 'Run "grail run --help" for usage.';
+        throw error;
+      }
+      goal = value;
+      continue;
+    }
+
+    if (arg === '--inputs') {
+      const value = args[i + 1];
+      if (!value || value.startsWith('-')) {
+        const error = new Error('--inputs requires a JSON object.');
+        error.hint = 'Run "grail run --help" for usage.';
+        throw error;
+      }
+      inputs = value;
+      i += 1;
+      continue;
+    }
+
+    if (arg.startsWith('--inputs=')) {
+      const value = arg.slice('--inputs='.length);
+      if (!value) {
+        const error = new Error('--inputs requires a JSON object.');
+        error.hint = 'Run "grail run --help" for usage.';
+        throw error;
+      }
+      inputs = value;
+      continue;
+    }
+
+    if (arg === '--inputs-file') {
+      const value = args[i + 1];
+      if (!value || value.startsWith('-')) {
+        const error = new Error('--inputs-file requires a file.');
+        error.hint = 'Run "grail run --help" for usage.';
+        throw error;
+      }
+      inputsFile = value;
+      i += 1;
+      continue;
+    }
+
+    if (arg.startsWith('--inputs-file=')) {
+      const value = arg.slice('--inputs-file='.length);
+      if (!value) {
+        const error = new Error('--inputs-file requires a file.');
+        error.hint = 'Run "grail run --help" for usage.';
+        throw error;
+      }
+      inputsFile = value;
+      continue;
+    }
+
+    if (arg === '--output' || arg.startsWith('--output=')) {
+      const value = arg === '--output' ? args[++i] : arg.slice('--output='.length);
+      if (!value || value.startsWith('-')) {
+        throw new Error('--output requires summary or json.');
+      }
+      if (!['summary', 'json'].includes(value)) {
+        throw new Error(`Invalid --output value: ${value}. Expected summary or json.`);
+      }
+      output = value;
+      continue;
+    }
+
+    const error = new Error(`Unknown option: ${arg}`);
+    error.hint = 'Run "grail run --help" for supported options.';
+    throw error;
+  }
+
+  if (inputs !== undefined && inputsFile !== undefined) {
+    const error = new Error('--inputs and --inputs-file cannot be used together.');
+    error.hint = 'Run "grail run --help" for usage.';
+    throw error;
+  }
+
+  return { configDir: path.resolve(configDir), goal, inputs, inputsFile, output };
+}
+
+function parseInputsJson(value, source) {
+  let parsed;
+
+  try {
+    parsed = JSON.parse(value);
+  } catch (error) {
+    throw new Error(`Invalid JSON in ${source}: ${error.message}`);
+  }
+
+  if (parsed === null || Array.isArray(parsed) || typeof parsed !== 'object') {
+    throw new Error(`${source} must contain a JSON object.`);
+  }
+
+  return parsed;
+}
+
+function loadInputsFile(file) {
+  const filePath = path.resolve(file);
+
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`Inputs file not found: ${filePath}`);
+  }
+
+  if (!fs.statSync(filePath).isFile()) {
+    throw new Error(`Inputs file is not a file: ${filePath}`);
+  }
+
+  return parseInputsJson(fs.readFileSync(filePath, 'utf8'), `inputs file ${filePath}`);
+}
+
+function writeJson(filePath, value) {
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+
+function initCommand(args) {
+  if (args.includes('--help') || args.includes('-h')) {
+    showCommandHelp('init');
+    return;
+  }
+
+  if (args.length !== 1 || args[0].startsWith('-')) {
+    throw new Error('Usage: grail init <directory>');
+  }
+
+  const targetDir = path.resolve(args[0]);
+
+  if (fs.existsSync(targetDir)) {
+    throw new Error(`Target already exists: ${targetDir}`);
+  }
+
+  const configDir = path.join(targetDir, 'config');
+  const capabilitiesDir = path.join(targetDir, 'capabilities');
+
+  fs.mkdirSync(configDir, { recursive: true });
+  fs.mkdirSync(capabilitiesDir, { recursive: true });
+
+  writeJson(path.join(configDir, 'registry.json'), {
+    createGreeting: {
+      id: 'aff-create-greeting',
+      action: 'createGreeting',
+      type: 'task',
+      preconditions: [],
+      inputs: {
+        name: '$inputs.name'
+      },
+      effects: ['greetingCreated'],
+      binding: {
+        protocol: 'node',
+        module: './capabilities/hello.mjs',
+        function: 'createGreeting',
+        outputs: {
+          message: {
+            from: 'result',
+            path: 'message'
+          }
+        }
+      }
+    }
+  });
+
+  writeJson(path.join(configDir, 'worldstate.json'), {
+    greetingCreated: false
+  });
+
+  writeJson(path.join(configDir, 'inputs.json'), {
+    name: 'World'
+  });
+
+  writeJson(path.join(configDir, 'goal.json'), {
+    goal: 'greetingCreated'
+  });
+
+  fs.writeFileSync(
+    path.join(capabilitiesDir, 'hello.mjs'),
+    `export async function createGreeting({ name }) {\n  return {\n    message: \`Hello, \${name}!\`\n  };\n}\n`,
+    'utf8'
+  );
+
+  console.log(`Created GRAIL world: ${args[0]}\n\n  config/registry.json\n  config/worldstate.json\n  config/inputs.json\n  config/goal.json\n  capabilities/hello.mjs\n\nNext:\n\n  cd ${args[0]}\n  grail validate\n  grail run`);
+}
+
+function formatSummary(result) {
+  const lines = [
+    `Goal: ${result.goal}`,
+    `Result: ${result.reached ? 'SUCCESS' : 'FAIL'}`,
+    `Capability invocations: ${result.observations.length}`
+  ];
+  for (const observation of result.observations) {
+    lines.push('', `${observation.invocation?.affordance ?? 'Unknown affordance'}: ${observation.result}`);
+    for (const [key, value] of Object.entries(observation.outputs ?? {})) {
+      lines.push(`  ${key}: ${typeof value === 'string' ? value : JSON.stringify(value)}`);
+    }
+  }
+  return lines.join('\n');
+}
+
+async function runCommand(args) {
+  if (args.includes('--help') || args.includes('-h')) {
+    showCommandHelp('run');
+    return;
+  }
+
+  const { Grail, loadEnvironment } = await import('../index.js');
+  const {
+    configDir,
+    goal: goalOverride,
+    inputs: inputsOverride,
+    inputsFile,
+    output
+  } = parseRunOptions(args);
+  const environment = loadEnvironment(configDir);
+  const goal = goalOverride ?? environment.goal;
+  const inputs = inputsOverride !== undefined
+    ? parseInputsJson(inputsOverride, '--inputs')
+    : inputsFile !== undefined
+      ? loadInputsFile(inputsFile)
+      : environment.inputs;
+
+  const grail = new Grail({
+    registry: environment.registry,
+    worldstate: environment.worldstate,
+    inputs,
+    baseDir: environment.baseDir,
+    observationPath: path.join(configDir, 'observations.json')
+  });
+
+  try {
+    // Preserve the historical trace unless an explicit result format was requested.
+    // Restore logging even when pursuit throws; structured stdout must remain clean.
+    const originalLog = console.log;
+    let result;
+    try {
+      if (output) console.log = () => {};
+      result = await grail.pursue(goal);
+    } finally {
+      console.log = originalLog;
+    }
+
+    if (output === 'json') {
+      console.log(JSON.stringify(result, null, 2));
+    } else if (output === 'summary') {
+      console.log(formatSummary(result));
+    }
+
+    if (!result.reached) {
+      const failedObservation = [...result.observations]
+        .reverse()
+        .find(observation => observation.result === 'FAIL');
+
+      if (failedObservation) {
+        const detail =
+          failedObservation.response?.error ||
+          failedObservation.response?.stderr ||
+          'a capability invocation failed';
+
+        console.error(
+          `GRAIL: Execution failed while pursuing goal \"${goal}\": ${detail}`
+        );
+      } else {
+        console.error(
+          `GRAIL: Pursuit failed: goal \"${goal}\" cannot be resolved with the available capabilities.`
+        );
+      }
+
+      process.exitCode = 1;
+    }
+  } catch (error) {
+    error.exitCode = 1;
+    throw error;
+  }
+}
+
+async function showCommand(args) {
+  if (args.includes('--help') || args.includes('-h')) {
+    showCommandHelp('show');
+    return;
+  }
+
+  const targets = new Set(['registry', 'worldstate', 'inputs', 'goal']);
+  let target;
+  const configArgs = [];
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === '--config') {
+      configArgs.push(arg);
+      if (i + 1 < args.length) configArgs.push(args[++i]);
+    } else if (arg.startsWith('--config=')) {
+      configArgs.push(arg);
+    } else if (!arg.startsWith('-') && target === undefined) {
+      target = arg;
+    } else {
+      const error = new Error(`Unknown option or extra argument: ${arg}`);
+      error.hint = 'Run "grail show --help" for usage.';
+      throw error;
+    }
+  }
+
+  if (target !== undefined && !targets.has(target)) {
+    const error = new Error(`Unknown show target: ${target}`);
+    error.hint = 'Choose registry, worldstate, inputs, or goal.';
+    throw error;
+  }
+
+  const { loadEnvironment } = await import('../index.js');
+  const environment = loadEnvironment(parseConfig(configArgs));
+  const documents = {
+    registry: environment.registry,
+    worldstate: environment.worldstate,
+    inputs: environment.inputs,
+    goal: { goal: environment.goal }
+  };
+  console.log(JSON.stringify(target ? documents[target] : documents, null, 2));
+}
+
+async function validateCommand(args) {
+  if (args.includes('--help') || args.includes('-h')) {
+    showCommandHelp('validate');
+    return;
+  }
+
+  const { loadEnvironment } = await import('../index.js');
+  const configDir = parseConfig(args);
+  loadEnvironment(configDir);
+  console.log(`VALID: ${configDir}`);
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+    showHelp();
+    return;
+  }
+
+  if (args[0] === '--version' || args[0] === '-v') {
+    console.log(packageJson.version);
+    return;
+  }
+
+  const [command, ...commandArgs] = args;
+
+  if (command === 'init') {
+    initCommand(commandArgs);
+    return;
+  }
+
+  if (command === 'run') {
+    await runCommand(commandArgs);
+    return;
+  }
+
+  if (command === 'show') {
+    await showCommand(commandArgs);
+    return;
+  }
+
+  if (command === 'validate') {
+    await validateCommand(commandArgs);
+    return;
+  }
+
+  const error = new Error(`Unknown command: ${command}`);
+  error.hint = 'Run \"grail --help\" for available commands.';
+  throw error;
+}
+
+main().catch(error => {
+  console.error(`GRAIL: ${error.message}`);
+  if (error.hint) {
+    console.error(error.hint);
+  }
+  process.exitCode = error.exitCode ?? 2;
+});

package/client.js

@@ -0,0 +1,77 @@
+// client.js
+export class Client {
+  constructor(server, inputs) {
+    this.server = server;
+    this.inputs = inputs;
+    this.stack = [];
+  }
+
+  async pursue(goal) {
+    // Each pursuit has its own traversal stack. Worldstate and observations persist.
+    this.stack = [];
+    console.log(`\n[CLIENT] Starting pursuit: ${goal}`);
+
+    while (true) {
+
+      // If there is no current work, resolve the goal.
+      if (this.stack.length === 0) {
+        const response = this.server.resolveGoal(goal);
+
+        if (response.result === "SUCCESS") {
+          console.log(`[CLIENT] Goal reached: ${goal}`);
+          break;
+        }
+
+        if (response.offeredAffordances.length > 0) {
+          const next = response.offeredAffordances[0];
+
+          console.log(
+            `[CLIENT] Pushing goal affordance: ${next.action}`
+          );
+
+          this.stack.push(next);
+          continue;
+        }
+
+        console.log(
+          `[CLIENT] Cannot proceed: goal is unresolvable - ${goal}`
+        );
+        break;
+      }
+
+      const current = this.stack[this.stack.length - 1];
+      const response = await this.server.attempt(current, this.inputs);
+
+      if (response.result === "SUCCESS") {
+        console.log(`[CLIENT] Affordance succeeded: ${current.action}`);
+        this.stack.pop();
+
+      } else if (
+        response.result === "BLOCKED" &&
+        response.offeredAffordances.length > 0
+      ) {
+        const next = response.offeredAffordances[0];
+
+        console.log(`[CLIENT] Pushing next affordance: ${next.action}`);
+        this.stack.push(next);
+
+      } else if (response.result === "FAIL") {
+        console.log(`[CLIENT] Affordance failed: ${current.action}`);
+        this.stack.pop();
+
+      } else if (
+        response.result === "BLOCKED" &&
+        response.condition
+      ) {
+        console.log(
+          `[CLIENT] Cannot proceed: condition is unresolvable - ${response.condition}`
+        );
+        break;
+
+      } else {
+        console.log(`[CLIENT] Cannot proceed: ${response.result}`);
+        break;
+      }
+    }
+  }
+}

package/config-loader/loadEnvironment.js

@@ -0,0 +1,71 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadAndValidateJSON } from '../utils/loadJSON.js';
+
+/**
+ * Load and validate a GRAIL environment from a configuration directory.
+ *
+ * Filesystem loading belongs outside the runtime itself. The returned object
+ * can be passed directly to Grail; the goal is returned alongside the runtime
+ * configuration for the caller to pursue explicitly.
+ *
+ * @param {string} configDir - Directory containing the GRAIL JSON files.
+ * @returns {{registry: object, worldstate: object, inputs: object, goal: string, baseDir: string}}
+ */
+export function loadEnvironment(configDir) {
+  if (!configDir) {
+    throw new Error('Configuration error: no configuration directory was provided.');
+  }
+
+  const resolvedConfigDir = path.resolve(configDir);
+
+  if (!fs.existsSync(resolvedConfigDir)) {
+    throw new Error(`Configuration error: directory not found: ${resolvedConfigDir}`);
+  }
+
+  if (!fs.statSync(resolvedConfigDir).isDirectory()) {
+    throw new Error(`Configuration error: not a directory: ${resolvedConfigDir}`);
+  }
+
+  const loadConfig = (filename, schemaName) => {
+    const filePath = path.join(resolvedConfigDir, filename);
+
+    if (!fs.existsSync(filePath)) {
+      throw new Error(`Configuration error: ${filename} not found in ${resolvedConfigDir}`);
+    }
+
+    try {
+      return loadAndValidateJSON(filePath, schemaName, { silent: true });
+    } catch (error) {
+      if (error instanceof SyntaxError) {
+        throw new Error(`Configuration error: invalid JSON in ${filename}: ${error.message}`);
+      }
+
+      if (error.validationErrors) {
+        const details = error.validationErrors
+          .map(validationError => {
+            const location = validationError.instancePath || '/';
+            return `${location} ${validationError.message}`;
+          })
+          .join('; ');
+
+        throw new Error(`Configuration error: ${filename} failed schema validation: ${details}`);
+      }
+
+      throw error;
+    }
+  };
+
+  const inputs = loadConfig('inputs.json', 'inputs.schema.json');
+  const registry = loadConfig('registry.json', 'registry.schema.json');
+  const worldstate = loadConfig('worldstate.json', 'worldstate.schema.json');
+  const goalObj = loadConfig('goal.json', 'goal.schema.json');
+
+  return {
+    registry,
+    worldstate,
+    inputs,
+    goal: goalObj.goal,
+    baseDir: path.dirname(resolvedConfigDir)
+  };
+}