@hesed/recipe 0.1.0

package/dist/commands/recipe/import.d.ts

@@ -0,0 +1,18 @@
+import { Command } from '@oclif/core';
+export default class RecipeImport extends Command {
+    static args: {
+        path: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    static flags: {
+        force: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        name: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    static summary: string;
+    run(): Promise<{
+        name: string;
+        path: string;
+    }>;
+}

package/dist/commands/recipe/import.js

@@ -0,0 +1,33 @@
+import { Args, Command, Flags } from '@oclif/core';
+import { cyan } from 'ansis';
+import { loadRecipeFile, recipeExists, saveRecipe } from '../../recipe/store.js';
+export default class RecipeImport extends Command {
+    static args = {
+        path: Args.string({ description: 'Path to a recipe JSON file to import.', required: true }),
+    };
+    static description = 'Import a recipe from a JSON file into the recipe store so it can be run by name.';
+    static enableJsonFlag = true;
+    static examples = [
+        '<%= config.bin %> <%= command.id %> ./close-user-tickets.json',
+        '<%= config.bin %> <%= command.id %> ./shared-recipe.json --name my-copy',
+    ];
+    static flags = {
+        force: Flags.boolean({ char: 'f', description: 'Overwrite an existing recipe with the same name.' }),
+        name: Flags.string({ description: 'Save the imported recipe under a different name.' }),
+    };
+    static summary = 'Import a recipe from a file.';
+    async run() {
+        const { args, flags } = await this.parse(RecipeImport);
+        const recipe = await loadRecipeFile(args.path);
+        if (flags.name)
+            recipe.name = flags.name;
+        if (!flags.force && (await recipeExists(this.config, recipe.name))) {
+            this.error(`Recipe "${recipe.name}" already exists. Use --force to overwrite or --name to rename.`);
+        }
+        const path = await saveRecipe(this.config, recipe);
+        if (!this.jsonEnabled()) {
+            this.log(`Imported recipe ${cyan(recipe.name)} to ${path}`);
+        }
+        return { name: recipe.name, path };
+    }
+}

package/dist/commands/recipe/index.d.ts

@@ -0,0 +1,9 @@
+import { Command } from '@oclif/core';
+import { Recipe } from '../../recipe/types.js';
+export default class RecipeIndex extends Command {
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    static summary: string;
+    run(): Promise<Recipe[]>;
+}

package/dist/commands/recipe/index.js

@@ -0,0 +1,27 @@
+import { Command } from '@oclif/core';
+import { dim } from 'ansis';
+import { listRecipes, recipesDir } from '../../recipe/store.js';
+export default class RecipeIndex extends Command {
+    static description = 'List saved recipes.';
+    static enableJsonFlag = true;
+    static examples = ['<%= config.bin %> <%= command.id %>'];
+    static summary = 'List saved recipes.';
+    async run() {
+        const recipes = await listRecipes(this.config);
+        if (!this.jsonEnabled()) {
+            if (recipes.length === 0) {
+                this.log(`No recipes saved. Create one with "${this.config.bin} recipe create <name>".`);
+                this.log(dim(`Recipes are stored in ${recipesDir(this.config)}`));
+            }
+            else {
+                for (const recipe of recipes) {
+                    const steps = `${recipe.steps.length} step${recipe.steps.length === 1 ? '' : 's'}`;
+                    this.log(`${recipe.name} ${dim(steps)}`);
+                    if (recipe.description)
+                        this.log(dim(`  ${recipe.description}`));
+                }
+            }
+        }
+        return recipes;
+    }
+}

package/dist/commands/recipe/remove.d.ts

@@ -0,0 +1,15 @@
+import { Command } from '@oclif/core';
+export default class RecipeRemove extends Command {
+    static aliases: string[];
+    static args: {
+        recipe: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    static summary: string;
+    run(): Promise<{
+        name: string;
+        removed: boolean;
+    }>;
+}

package/dist/commands/recipe/remove.js

@@ -0,0 +1,23 @@
+import { Args, Command } from '@oclif/core';
+import { recipeExists, removeRecipe } from '../../recipe/store.js';
+export default class RecipeRemove extends Command {
+    static aliases = ['recipe:delete'];
+    static args = {
+        recipe: Args.string({ description: 'Name of the saved recipe to remove.', required: true }),
+    };
+    static description = 'Delete a recipe from the recipe store.';
+    static enableJsonFlag = true;
+    static examples = ['<%= config.bin %> <%= command.id %> close-user-tickets'];
+    static summary = 'Remove a saved recipe.';
+    async run() {
+        const { args } = await this.parse(RecipeRemove);
+        if (!(await recipeExists(this.config, args.recipe))) {
+            this.error(`Recipe "${args.recipe}" not found.`);
+        }
+        await removeRecipe(this.config, args.recipe);
+        if (!this.jsonEnabled()) {
+            this.log(`Removed recipe ${args.recipe}.`);
+        }
+        return { name: args.recipe, removed: true };
+    }
+}

package/dist/commands/recipe/run.d.ts

@@ -0,0 +1,16 @@
+import { Command } from '@oclif/core';
+import { Context } from '../../recipe/types.js';
+export default class RecipeRun extends Command {
+    static args: {
+        recipe: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    static flags: {
+        'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        var: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    static summary: string;
+    run(): Promise<Context>;
+}

package/dist/commands/recipe/run.js

@@ -0,0 +1,64 @@
+import { Args, Command, Flags } from '@oclif/core';
+import { bold, cyan, dim } from 'ansis';
+import { executeRecipe } from '../../recipe/engine.js';
+import { execShell } from '../../recipe/exec.js';
+import { resolveRecipe } from '../../recipe/store.js';
+/** Parses a `--var key=value` flag, JSON-decoding the value when possible. */
+function parseVar(input) {
+    const eq = input.indexOf('=');
+    if (eq === -1)
+        throw new Error(`Invalid --var "${input}". Expected key=value.`);
+    const key = input.slice(0, eq);
+    const raw = input.slice(eq + 1);
+    try {
+        return [key, JSON.parse(raw)];
+    }
+    catch {
+        return [key, raw];
+    }
+}
+export default class RecipeRun extends Command {
+    static args = {
+        recipe: Args.string({ description: 'Name of a saved recipe, or a path to a recipe file.', required: true }),
+    };
+    static description = `Each step runs a command, with optional conditions, loops and JSON operations between them.
+
+Use --var to override the recipe's default variables, and --dry-run to preview the commands without running them.`;
+    static enableJsonFlag = true;
+    static examples = [
+        '<%= config.bin %> <%= command.id %> close-user-tickets',
+        '<%= config.bin %> <%= command.id %> close-user-tickets --var assignee=jdoe',
+        '<%= config.bin %> <%= command.id %> ./my-recipe.json --dry-run',
+    ];
+    static flags = {
+        'dry-run': Flags.boolean({ description: 'Print the commands that would run without executing them.' }),
+        var: Flags.string({
+            description: 'Override a recipe variable (key=value). Repeatable. Values are parsed as JSON when possible.',
+            multiple: true,
+        }),
+    };
+    static summary = 'Run a recipe: a sequence of commands chained with conditions, loops and JSON operations.';
+    async run() {
+        const { args, flags } = await this.parse(RecipeRun);
+        const recipe = await resolveRecipe(this.config, args.recipe);
+        const overrides = Object.fromEntries((flags.var ?? []).map((entry) => parseVar(entry)));
+        if (!this.jsonEnabled()) {
+            this.log(bold(`Running recipe ${cyan(recipe.name)}`));
+            if (recipe.description)
+                this.log(dim(recipe.description));
+            if (flags['dry-run'])
+                this.log(dim('Dry run — no commands will be executed.\n'));
+        }
+        const runner = {
+            dryRun: flags['dry-run'],
+            exec: (command) => execShell(command),
+            log: (message) => this.log(message),
+            runCommand: (id, argv) => this.config.runCommand(id, argv),
+        };
+        const result = await executeRecipe(recipe, runner, overrides);
+        if (!this.jsonEnabled()) {
+            this.log(dim(`\n✅ Recipe ${recipe.name} finished (${result.steps} step${result.steps === 1 ? '' : 's'}).`));
+        }
+        return result.vars;
+    }
+}

package/dist/commands/recipe/show.d.ts

@@ -0,0 +1,12 @@
+import { Command } from '@oclif/core';
+import { Recipe } from '../../recipe/types.js';
+export default class RecipeShow extends Command {
+    static args: {
+        recipe: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    static summary: string;
+    run(): Promise<Recipe>;
+}

package/dist/commands/recipe/show.js

@@ -0,0 +1,19 @@
+import { Args, Command } from '@oclif/core';
+import { resolveRecipe } from '../../recipe/store.js';
+export default class RecipeShow extends Command {
+    static args = {
+        recipe: Args.string({ description: 'Name of a saved recipe, or a path to a recipe file.', required: true }),
+    };
+    static description = 'Print the full definition of a recipe.';
+    static enableJsonFlag = true;
+    static examples = ['<%= config.bin %> <%= command.id %> close-user-tickets'];
+    static summary = 'Print a recipe definition.';
+    async run() {
+        const { args } = await this.parse(RecipeShow);
+        const recipe = await resolveRecipe(this.config, args.recipe);
+        if (!this.jsonEnabled()) {
+            this.log(JSON.stringify(recipe, null, 2));
+        }
+        return recipe;
+    }
+}

package/dist/commands/recipe/validate.d.ts

@@ -0,0 +1,14 @@
+import { Command } from '@oclif/core';
+export default class RecipeValidate extends Command {
+    static args: {
+        recipe: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    static summary: string;
+    run(): Promise<{
+        name: string;
+        valid: boolean;
+    }>;
+}

package/dist/commands/recipe/validate.js

@@ -0,0 +1,21 @@
+import { Args, Command } from '@oclif/core';
+import { green } from 'ansis';
+import { resolveRecipe } from '../../recipe/store.js';
+export default class RecipeValidate extends Command {
+    static args = {
+        recipe: Args.string({ description: 'Name of a saved recipe, or a path to a recipe file.', required: true }),
+    };
+    static description = 'Check that a recipe is well-formed without running it.';
+    static enableJsonFlag = true;
+    static examples = ['<%= config.bin %> <%= command.id %> ./my-recipe.json'];
+    static summary = 'Validate a recipe.';
+    async run() {
+        const { args } = await this.parse(RecipeValidate);
+        // resolveRecipe validates the recipe as it loads it, throwing on any problem.
+        const recipe = await resolveRecipe(this.config, args.recipe);
+        if (!this.jsonEnabled()) {
+            this.log(`${green('✓')} Recipe ${recipe.name} is valid (${recipe.steps.length} steps).`);
+        }
+        return { name: recipe.name, valid: true };
+    }
+}

package/dist/recipe/condition.d.ts

@@ -0,0 +1,2 @@
+import { Context } from './types.js';
+export declare function evaluateCondition(expr: string, context: Context): boolean;

package/dist/recipe/condition.js

@@ -0,0 +1,78 @@
+import { resolvePath } from './interpolate.js';
+function splitOutsideTemplates(expr, separator) {
+    const parts = [];
+    let depth = 0;
+    let current = '';
+    let i = 0;
+    while (i < expr.length) {
+        if (expr[i] === '$' && expr[i + 1] === '{') {
+            depth++;
+            current += expr[i++];
+        }
+        else if (expr[i] === '}' && depth > 0) {
+            depth--;
+            current += expr[i++];
+        }
+        else if (depth === 0 && expr.startsWith(separator, i)) {
+            parts.push(current);
+            current = '';
+            i += separator.length;
+        }
+        else {
+            current += expr[i++];
+        }
+    }
+    parts.push(current);
+    return parts.length > 1 ? parts : [expr];
+}
+function applyOp(value, op, right) {
+    switch (op) {
+        case '!=': {
+            return String(value) !== right;
+        }
+        case '<': {
+            return Number(value) < Number(right);
+        }
+        case '<=': {
+            return Number(value) <= Number(right);
+        }
+        case '==': {
+            return String(value) === right;
+        }
+        case '>': {
+            return Number(value) > Number(right);
+        }
+        case '>=': {
+            return Number(value) >= Number(right);
+        }
+        case 'contains': {
+            return Array.isArray(value) ? value.includes(right) : String(value).includes(right);
+        }
+        case 'matches': {
+            return new RegExp(right).test(String(value));
+        }
+        default: {
+            return false;
+        }
+    }
+}
+export function evaluateCondition(expr, context) {
+    expr = expr.trim();
+    const orParts = splitOutsideTemplates(expr, '||');
+    if (orParts.length > 1)
+        return orParts.some((part) => evaluateCondition(part.trim(), context));
+    const andParts = splitOutsideTemplates(expr, '&&');
+    if (andParts.length > 1)
+        return andParts.every((part) => evaluateCondition(part.trim(), context));
+    if (expr.startsWith('!'))
+        return !evaluateCondition(expr.slice(1).trim(), context);
+    const binaryMatch = /^\$\{([^}]+)\}\s*(==|!=|>=|<=|>|<|contains|matches)\s*(.+)$/.exec(expr);
+    if (binaryMatch) {
+        const [, path, op, right] = binaryMatch;
+        return applyOp(resolvePath(context, path), op, right.trim());
+    }
+    const simpleMatch = /^\$\{([^}]+)\}$/.exec(expr);
+    if (simpleMatch)
+        return Boolean(resolvePath(context, simpleMatch[1]));
+    return Boolean(expr);
+}

package/dist/recipe/engine.d.ts

@@ -0,0 +1,14 @@
+import { Context, Recipe } from './types.js';
+export interface RecipeRunner {
+    dryRun?: boolean;
+    exec(command: string): Promise<{
+        stderr: string;
+        stdout: string;
+    }>;
+    log(message: string): void;
+    runCommand(id: string, argv: string[]): Promise<unknown>;
+}
+export declare function executeRecipe(recipe: Recipe, runner: RecipeRunner, overrides?: Context): Promise<{
+    steps: number;
+    vars: Context;
+}>;

package/dist/recipe/engine.js

@@ -0,0 +1,80 @@
+/* eslint-disable no-await-in-loop */
+// Recipe steps execute sequentially by design: each step may read variables
+// captured by the previous step, so parallel execution is not an option.
+import { evaluateCondition } from './condition.js';
+import { interpolate, interpolateDeep, toArg } from './interpolate.js';
+export async function executeRecipe(recipe, runner, overrides = {}) {
+    const vars = { ...recipe.vars, ...overrides };
+    let stepCount = 0;
+    async function runSteps(steps, ctx) {
+        for (const step of steps) {
+            if ('then' in step || ('else' in step && !('run' in step) && !('exec' in step))) {
+                const cond = evaluateCondition(step.if, ctx);
+                if (cond) {
+                    if (step.then)
+                        await runSteps(step.then, ctx);
+                }
+                else if (step.else)
+                    await runSteps(step.else, ctx);
+                stepCount++;
+                continue;
+            }
+            if ('if' in step && step.if && !evaluateCondition(step.if, ctx))
+                continue;
+            if ('log' in step) {
+                runner.log(String(interpolate(step.log, ctx)));
+                stepCount++;
+            }
+            else if ('set' in step) {
+                ctx[step.set] = interpolateDeep(step.value, ctx);
+                stepCount++;
+            }
+            else if ('run' in step) {
+                const argv = (step.args ?? []).map((a) => toArg(String(a), ctx));
+                if (runner.dryRun) {
+                    runner.log(`[dry-run] ${step.run}${argv.length > 0 ? ' ' + argv.join(' ') : ''}`);
+                }
+                else {
+                    const result = await runner.runCommand(step.run, argv);
+                    if (step.capture)
+                        ctx[step.capture] = result;
+                }
+                stepCount++;
+            }
+            else if ('exec' in step) {
+                const command = String(interpolate(step.exec, ctx));
+                if (runner.dryRun) {
+                    runner.log(`[dry-run] ${command}`);
+                }
+                else {
+                    const { stdout } = await runner.exec(command);
+                    if (step.capture)
+                        ctx[step.capture] = step.json ? JSON.parse(stdout) : stdout;
+                }
+                stepCount++;
+            }
+            else if ('repeat' in step) {
+                const raw = step.repeat;
+                const count = typeof raw === 'number' ? raw : Number(interpolate(String(raw), ctx));
+                for (let i = 0; i < count; i++) {
+                    if (step.as)
+                        ctx[step.as] = i;
+                    await runSteps(step.steps, ctx);
+                }
+                stepCount++;
+            }
+            else if ('forEach' in step) {
+                const collection = interpolate(step.forEach, ctx);
+                if (Array.isArray(collection)) {
+                    for (const item of collection) {
+                        ctx[step.as] = item;
+                        await runSteps(step.steps, ctx);
+                    }
+                }
+                stepCount++;
+            }
+        }
+    }
+    await runSteps(recipe.steps, vars);
+    return { steps: stepCount, vars };
+}

package/dist/recipe/exec.d.ts

@@ -0,0 +1,4 @@
+export declare function execShell(command: string): Promise<{
+    stderr: string;
+    stdout: string;
+}>;

package/dist/recipe/exec.js

@@ -0,0 +1,9 @@
+import { exec } from 'node:child_process';
+import { promisify } from 'node:util';
+const execAsync = promisify(exec);
+// exec() is intentional: recipe exec steps are full shell commands that may use pipes,
+// redirects, and other shell features. Commands come from user-authored recipe files.
+export async function execShell(command) {
+    const { stderr, stdout } = await execAsync(command);
+    return { stderr, stdout };
+}

package/dist/recipe/interpolate.d.ts

@@ -0,0 +1,5 @@
+import { Context } from './types.js';
+export declare function resolvePath(context: Context, path: string): unknown;
+export declare function interpolate(template: string, context: Context): unknown;
+export declare function interpolateDeep(value: unknown, context: Context): unknown;
+export declare function toArg(template: string, context: Context): string;

package/dist/recipe/interpolate.js

@@ -0,0 +1,85 @@
+function parsePath(path) {
+    const parts = [];
+    let i = 0;
+    while (i < path.length) {
+        if (path[i] === '.') {
+            i++;
+        }
+        else if (path[i] === '[') {
+            i++;
+            if (path[i] === '*') {
+                parts.push('*');
+                i += 2; // skip * and ]
+            }
+            else if (path[i] === '"' || path[i] === "'") {
+                const quote = path[i];
+                i++;
+                const end = path.indexOf(quote, i);
+                parts.push(path.slice(i, end));
+                i = end + 2; // skip closing quote and ]
+            }
+            else {
+                const end = path.indexOf(']', i);
+                const n = Number(path.slice(i, end));
+                parts.push(Number.isNaN(n) ? path.slice(i, end) : n);
+                i = end + 1;
+            }
+        }
+        else {
+            let end = i;
+            while (end < path.length && path[end] !== '.' && path[end] !== '[')
+                end++;
+            parts.push(path.slice(i, end));
+            i = end;
+        }
+    }
+    return parts;
+}
+function resolveWithParts(obj, parts) {
+    if (parts.length === 0)
+        return obj;
+    const [head, ...tail] = parts;
+    if (head === '*') {
+        if (!Array.isArray(obj))
+            return undefined;
+        return obj.map((item) => resolveWithParts(item, tail));
+    }
+    // typeof null === 'object', so we need the explicit null check first
+    if (obj === null || typeof obj !== 'object')
+        return undefined;
+    const next = obj[String(head)];
+    return resolveWithParts(next, tail);
+}
+export function resolvePath(context, path) {
+    return resolveWithParts(context, parsePath(path));
+}
+export function interpolate(template, context) {
+    const fullMatch = /^\$\{([^}]+)\}$/.exec(template);
+    if (fullMatch)
+        return resolvePath(context, fullMatch[1]);
+    return template.replaceAll(/\$\{([^}]+)\}/g, (_, path) => {
+        const value = resolvePath(context, path);
+        return value === null || value === undefined ? '' : String(value);
+    });
+}
+export function interpolateDeep(value, context) {
+    if (typeof value === 'string')
+        return interpolate(value, context);
+    if (Array.isArray(value))
+        return value.map((item) => interpolateDeep(item, context));
+    // typeof null === 'object', so the null check is required here
+    if (value !== null && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, interpolateDeep(v, context)]));
+    }
+    return value;
+}
+export function toArg(template, context) {
+    const value = interpolate(template, context);
+    if (typeof value === 'string')
+        return value;
+    if (value === null || value === undefined)
+        return '';
+    if (typeof value === 'object')
+        return JSON.stringify(value);
+    return String(value);
+}

package/dist/recipe/store.d.ts

@@ -0,0 +1,23 @@
+import { Recipe } from './types.js';
+export declare function recipesDir(config: {
+    dataDir: string;
+}): string;
+export declare function recipeExists(config: {
+    dataDir: string;
+}, name: string): Promise<boolean>;
+export declare function saveRecipe(config: {
+    dataDir: string;
+}, recipe: Recipe): Promise<string>;
+export declare function readRecipe(config: {
+    dataDir: string;
+}, name: string): Promise<Recipe>;
+export declare function listRecipes(config: {
+    dataDir: string;
+}): Promise<Recipe[]>;
+export declare function removeRecipe(config: {
+    dataDir: string;
+}, name: string): Promise<void>;
+export declare function loadRecipeFile(filePath: string): Promise<Recipe>;
+export declare function resolveRecipe(config: {
+    dataDir: string;
+}, nameOrPath: string): Promise<Recipe>;

package/dist/recipe/store.js

@@ -0,0 +1,46 @@
+import { mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+export function recipesDir(config) {
+    return join(config.dataDir, 'recipes');
+}
+export async function recipeExists(config, name) {
+    try {
+        await readFile(join(recipesDir(config), `${name}.json`));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function saveRecipe(config, recipe) {
+    const dir = recipesDir(config);
+    await mkdir(dir, { recursive: true });
+    const path = join(dir, `${recipe.name}.json`);
+    await writeFile(path, JSON.stringify(recipe, null, 2) + '\n');
+    return path;
+}
+export async function readRecipe(config, name) {
+    const content = await readFile(join(recipesDir(config), `${name}.json`), 'utf8');
+    return JSON.parse(content);
+}
+export async function listRecipes(config) {
+    try {
+        const files = await readdir(recipesDir(config));
+        return Promise.all(files.filter((f) => f.endsWith('.json')).map((f) => readRecipe(config, f.slice(0, -5))));
+    }
+    catch {
+        return [];
+    }
+}
+export async function removeRecipe(config, name) {
+    await rm(join(recipesDir(config), `${name}.json`));
+}
+export async function loadRecipeFile(filePath) {
+    const content = await readFile(filePath, 'utf8');
+    return JSON.parse(content);
+}
+export async function resolveRecipe(config, nameOrPath) {
+    if (nameOrPath.includes('/') || nameOrPath.endsWith('.json'))
+        return loadRecipeFile(nameOrPath);
+    return readRecipe(config, nameOrPath);
+}