@sectui/operations 0.0.0-stage → 0.1.0

package/dist/template.js

@@ -0,0 +1,198 @@
+import { coerceArg, findArg, kebab } from "./args.js";
+import { getOperation, isOperationId, run } from "./registry.js";
+export class TemplateError extends Error {
+    name = "TemplateError";
+    /** 1-based line and column of `position`. */
+    line;
+    column;
+    /** Offset in the source. */
+    position;
+    constructor(message, source, position) {
+        const before = source.slice(0, position);
+        const line = before.split("\n").length;
+        const column = position - before.lastIndexOf("\n");
+        super(`${message} (line ${line}, column ${column})`);
+        this.position = position;
+        this.line = line;
+        this.column = column;
+    }
+}
+const OP_START = /([a-z0-9]+(?:-[a-z0-9]+)*)([{(])/y;
+const IDENT_CHAR = /[a-z0-9-]/;
+const ARG_NAME = /[a-z0-9]+(?:-[a-z0-9]+)*/y;
+const BARE_VALUE = /[A-Za-z0-9\-_.+/=]+/y;
+const SPACE = /\s/;
+/** Index of the `)` closing an argument list opened before `from`, ignoring quoted parts; -1 if none. */
+function findArgsEnd(source, from) {
+    let quote = null;
+    for (let j = from; j < source.length; j++) {
+        const c = source[j];
+        if (quote) {
+            if (c === "\\")
+                j++;
+            else if (c === quote)
+                quote = null;
+        }
+        else if (c === '"' || c === "'") {
+            quote = c;
+        }
+        else if (c === ")") {
+            return j;
+        }
+    }
+    return -1;
+}
+function parseArgList(id, source, from, end) {
+    const op = getOperation(id);
+    const args = {};
+    let j = from;
+    const skipSpaces = () => {
+        while (j < end && SPACE.test(source[j]))
+            j++;
+    };
+    const fail = (message, at = j) => {
+        throw new TemplateError(message, source, at);
+    };
+    const parseValue = () => {
+        const quote = source[j];
+        if (quote === '"' || quote === "'") {
+            let value = "";
+            for (j++; source[j] !== quote; j++) {
+                if (j >= end)
+                    fail("Unterminated quote");
+                if (source[j] === "\\" && (source[j + 1] === quote || source[j + 1] === "\\"))
+                    j++;
+                value += source[j];
+            }
+            j++;
+            return value;
+        }
+        BARE_VALUE.lastIndex = j;
+        const match = BARE_VALUE.exec(source);
+        if (!match || BARE_VALUE.lastIndex > end)
+            return fail("Expected a value (use quotes for special characters)");
+        j = BARE_VALUE.lastIndex;
+        return match[0];
+    };
+    skipSpaces();
+    while (j < end) {
+        const nameStart = j;
+        ARG_NAME.lastIndex = j;
+        const name = ARG_NAME.exec(source)?.[0];
+        if (!name || ARG_NAME.lastIndex > end)
+            fail("Expected an argument name");
+        j = ARG_NAME.lastIndex;
+        const arg = findArg(op, name);
+        if (!arg) {
+            const expected = Object.keys(op.args).map(kebab).join(", ") || "none";
+            fail(`Unknown argument "${name}" for "${id}" (expected: ${expected})`, nameStart);
+        }
+        const [key, def] = arg;
+        if (Object.hasOwn(args, key))
+            fail(`Duplicate argument "${name}"`, nameStart);
+        skipSpaces();
+        let raw = true;
+        if (source[j] === "=") {
+            j++;
+            skipSpaces();
+            raw = parseValue();
+        }
+        skipSpaces();
+        if (j < end && source[j] !== ",")
+            fail(`Unexpected "${source[j]}" (use quotes for special characters)`);
+        try {
+            args[key] = coerceArg(def, name, raw);
+        }
+        catch (error) {
+            fail(error.message, nameStart);
+        }
+        if (j < end) {
+            j++;
+            skipSpaces();
+            if (j >= end)
+                fail("Expected an argument name");
+        }
+    }
+    return args;
+}
+export function parse(source) {
+    let i = 0;
+    function parseNodes(open) {
+        const nodes = [];
+        let text = "";
+        const flush = () => {
+            if (text)
+                nodes.push({ type: "text", value: text });
+            text = "";
+        };
+        while (i < source.length) {
+            const ch = source[i];
+            if (ch === "\\" && i + 1 < source.length && "{}\\".includes(source[i + 1])) {
+                text += source[i + 1];
+                i += 2;
+                continue;
+            }
+            if (ch === "}" && open) {
+                i++;
+                flush();
+                return nodes;
+            }
+            if (i === 0 || !IDENT_CHAR.test(source[i - 1])) {
+                OP_START.lastIndex = i;
+                const match = OP_START.exec(source);
+                const id = match?.[1];
+                if (id && isOperationId(id)) {
+                    let args = {};
+                    let contentStart = OP_START.lastIndex;
+                    const argsEnd = match[2] === "(" ? findArgsEnd(source, contentStart) : -1;
+                    const isBlock = match[2] === "{" || (argsEnd >= 0 && source[argsEnd + 1] === "{");
+                    if (isBlock) {
+                        if (argsEnd >= 0) {
+                            args = parseArgList(id, source, contentStart, argsEnd);
+                            contentStart = argsEnd + 2;
+                        }
+                        flush();
+                        const start = i;
+                        i = contentStart;
+                        nodes.push({ type: "op", id, args, children: parseNodes({ start }), start });
+                        continue;
+                    }
+                }
+            }
+            text += ch;
+            i++;
+        }
+        if (open)
+            throw new TemplateError("Missing closing brace", source, open.start);
+        flush();
+        return nodes;
+    }
+    return parseNodes(null);
+}
+function evaluate(nodes, source) {
+    const parts = nodes.map((node) => {
+        if (node.type === "text")
+            return new TextEncoder().encode(node.value);
+        const input = evaluate(node.children, source);
+        try {
+            return run(node.id, input, node.args);
+        }
+        catch (error) {
+            throw new TemplateError(`${node.id}: ${error.message}`, source, node.start);
+        }
+    });
+    const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+    let offset = 0;
+    for (const part of parts) {
+        out.set(part, offset);
+        offset += part.length;
+    }
+    return out;
+}
+export function renderBytes(source) {
+    return evaluate(parse(source), source);
+}
+export function render(source) {
+    return new TextDecoder().decode(renderBytes(source));
+}
+//# sourceMappingURL=template.js.map

package/dist/template.js.map

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

package/package.json

@@ -1,6 +1,69 @@
 {
   "name": "@sectui/operations",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "CyberChef-like data transformation operations: a TypeScript library and the ops CLI",
+  "license": "MIT",
+  "author": "Hadi",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sectui/operations.git"
+  },
+  "homepage": "https://github.com/sectui/operations#readme",
+  "bugs": {
+    "url": "https://github.com/sectui/operations/issues"
+  },
+  "keywords": [
+    "cyberchef",
+    "encoding",
+    "base64",
+    "security",
+    "cli"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./template": {
+      "source": "./src/template.ts",
+      "types": "./dist/template.d.ts",
+      "default": "./dist/template.js"
+    }
+  },
+  "bin": {
+    "ops": "./dist/cli.js"
+  },
+  "engines": {
+    "node": ">=26"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "bundle": "node scripts/bundle.ts",
+    "test": "node --conditions=source --test 'src/**/*.test.ts'",
+    "typecheck": "tsc",
+    "docs": "node scripts/gen-docs.ts",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "esbuild": "^0.28.2",
+    "prettier": "3.8.3",
+    "typescript": "^7"
+  },
+  "files": [
+    "dist",
+    "!dist/ops.mjs",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/test",
+    "!dist/**/*.test.*"
+  ],
+  "dependencies": {
+    "bcryptjs": "^3.0.3",
+    "yaml": "^2.9.1"
+  }
+}

package/src/args.ts

@@ -0,0 +1,47 @@
+import type { ArgDef, Operation } from "./operation.ts";
+
+export const kebab = (key: string) => key.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);
+
+/** Finds an argument by its kebab-case name, as used by the CLI and templates. */
+export function findArg(op: Operation, name: string): [key: string, def: ArgDef] | undefined {
+  return Object.entries(op.args).find(([key]) => kebab(key) === name);
+}
+
+/** Throws a readable error if `value` does not fit the argument definition. */
+export function checkArg(def: ArgDef, name: string, value: unknown): void {
+  switch (def.type) {
+    case "boolean":
+      if (typeof value !== "boolean") throw new Error(`"${name}" expects true or false, got ${JSON.stringify(value)}`);
+      return;
+    case "string":
+      if (typeof value !== "string") throw new Error(`"${name}" expects a string, got ${JSON.stringify(value)}`);
+      return;
+    case "number":
+      if (typeof value !== "number" || Number.isNaN(value)) {
+        throw new Error(`"${name}" expects a number, got ${JSON.stringify(value)}`);
+      }
+      if ((def.min !== undefined && value < def.min) || (def.max !== undefined && value > def.max)) {
+        throw new Error(`"${name}" must be between ${def.min ?? "-∞"} and ${def.max ?? "∞"}, got ${value}`);
+      }
+      return;
+    case "select":
+      if (!def.options.some((o) => o.value === value)) {
+        const expected = def.options.map((o) => o.value).join(", ");
+        throw new Error(`Invalid value ${JSON.stringify(value)} for "${name}" (expected: ${expected})`);
+      }
+  }
+}
+
+/** Converts a raw CLI or template value to the argument's type, then checks it. */
+export function coerceArg(def: ArgDef, name: string, raw: string | boolean): unknown {
+  let value: unknown = raw;
+  if (typeof raw === "string") {
+    if (def.type === "boolean" && (raw === "true" || raw === "false")) value = raw === "true";
+    if (def.type === "number" && raw.trim() !== "") value = Number(raw);
+  }
+  if (def.type === "number" && typeof value !== "number") {
+    throw new Error(`"${name}" expects a number, got ${JSON.stringify(raw)}`);
+  }
+  checkArg(def, name, value);
+  return value;
+}

package/src/cli-flags.ts

@@ -0,0 +1,29 @@
+import { kebab } from "./args.ts";
+import type { ArgDef, Example, Operation } from "./operation.ts";
+
+/** The flag users type: booleans that default to true are toggled with `--no-*`. */
+export function cliFlag(key: string, def: ArgDef): string {
+  return def.type === "boolean" && def.default ? `--no-${kebab(key)}` : `--${kebab(key)}`;
+}
+
+/** Quotes a value for a POSIX shell, using $'...' when it contains control characters. */
+export function shellQuote(value: string): string {
+  if (/^[\w\-.,/=+:@%]+$/.test(value)) return value;
+  if (!/[\x00-\x1f\x7f]/.test(value)) return `'${value.replaceAll("'", `'\\''`)}'`;
+  const escaped = value.replace(/[\\'\x00-\x1f\x7f]/g, (c) =>
+    c === "\n" ? "\\n" : c === "\t" ? "\\t" : c === "\\" || c === "'" ? `\\${c}` : `\\x${c.charCodeAt(0).toString(16).padStart(2, "0")}`,
+  );
+  return `$'${escaped}'`;
+}
+
+/** The CLI invocation of an example, e.g. `ops to-base64 --no-padding hi`. */
+export function cliExample(op: Operation, example: Example): string {
+  const parts = ["ops", op.id];
+  for (const [key, value] of Object.entries(example.args ?? {})) {
+    const def = op.args[key]!;
+    if (def.type !== "boolean") parts.push(`--${kebab(key)}`, shellQuote(String(value)));
+    else if (value !== def.default) parts.push(cliFlag(key, def));
+  }
+  parts.push(shellQuote(example.input));
+  return parts.join(" ");
+}

package/src/cli.ts

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { buffer } from "node:stream/consumers";
+import { parseArgs, type ParseArgsOptionsConfig } from "node:util";
+import { coerceArg, kebab } from "./args.ts";
+import { cliExample, cliFlag } from "./cli-flags.ts";
+import { completions, SHELLS, type Shell } from "./completions.ts";
+import { hexdump, isPrintable } from "./display.ts";
+import { OperationError } from "./errors.ts";
+import type { ArgDef, Operation } from "./operation.ts";
+import { getOperation, isOperationId, operations, run } from "./registry.ts";
+import { renderBytes } from "./template.ts";
+
+type Package = { version: string; description: string };
+/** Inlined by scripts/bundle.ts, undefined everywhere else. */
+declare const BUNDLED_PACKAGE: Package | undefined;
+
+// Read at run time: the same relative path works from src/ and from the built dist/.
+const pkg: Package =
+  typeof BUNDLED_PACKAGE !== "undefined"
+    ? BUNDLED_PACKAGE
+    : (JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as Package);
+
+class UsageError extends Error {}
+
+const USAGE = `ops ${pkg.version} - ${pkg.description}
+
+Usage:
+  ops <operation> [options] [input]   Apply an operation (input from stdin if omitted)
+  ops render [text]                   Replace operation{...} blocks in text
+  ops list                            List available operations
+  ops help [operation]                Show help
+  ops completions <${SHELLS.join("|")}>       Print a shell completion script
+
+Global options:
+  --raw    Write binary output to the terminal as is (by default it is shown as a hexdump)
+  --help   Show help
+
+Examples:
+  ops to-base64 hello
+  echo -n aGVsbG8= | ops from-base64
+  cat token.txt | ops from-base64 | ops url-encode --encode-all
+  ops render "hello my name is to-base64{hadi}"`;
+
+const RENDER_HELP = `ops render [--raw] [text]
+
+Replaces every operation{...} block in the text (or stdin) with the result of the operation.
+Arguments go between parentheses: to-hex(delimiter=colon){hadi}
+
+Example:
+  ops render "hello my name is to-base64{hadi}"`;
+
+function describeArg(key: string, def: ArgDef): string {
+  const value = def.type === "select" ? ` <${def.options.map((o) => o.value).join("|")}>` : def.type === "boolean" ? "" : ` <${def.type}>`;
+  const details = [def.name, def.description, def.type === "boolean" ? undefined : `default: ${def.default}`].filter(Boolean).join(". ");
+  return `  ${cliFlag(key, def)}${value}\n      ${details}`;
+}
+
+function operationHelp(op: Operation): string {
+  const lines = [`${op.id} - ${op.name}`, "", op.description];
+  if (op.aliases?.length) lines.push("", `Aliases: ${op.aliases.join(", ")}`);
+  if (op.inverse) lines.push(`Inverse: ${op.inverse}`);
+  const args = Object.entries(op.args);
+  if (args.length) lines.push("", "Options:", ...args.map(([key, def]) => describeArg(key, def)));
+  lines.push("", "Examples:", ...op.examples.map((ex) => `  ${cliExample(op, ex)}\n      -> ${JSON.stringify(ex.output)}`));
+  return lines.join("\n");
+}
+
+function list(): string {
+  const byCategory = Map.groupBy(operations, (op) => op.category);
+  const width = Math.max(...operations.map((op) => op.id.length));
+  return [...byCategory]
+    .map(([category, ops]) => [category, ...ops.map((op) => `  ${op.id.padEnd(width)}  ${op.name}`)].join("\n"))
+    .join("\n\n");
+}
+
+/** Extracts the global flags, which are only recognized before a `--` separator. */
+function splitGlobalFlags(argv: string[]) {
+  const end = argv.includes("--") ? argv.indexOf("--") : argv.length;
+  const isGlobal = (arg: string, i: number) => i < end && ["--raw", "--help", "-h"].includes(arg);
+  return {
+    raw: argv.some((arg, i) => isGlobal(arg, i) && arg === "--raw"),
+    help: argv.some((arg, i) => isGlobal(arg, i) && arg !== "--raw"),
+    rest: argv.filter((arg, i) => !isGlobal(arg, i)),
+  };
+}
+
+function parse(argv: string[], options: ParseArgsOptionsConfig, helpHint: string) {
+  try {
+    return parseArgs({ args: argv, options, allowPositionals: true, allowNegative: true, strict: true });
+  } catch (error) {
+    throw new UsageError(`${(error as Error).message} (see: ${helpHint})`);
+  }
+}
+
+function parseOperationArgs(op: Operation, argv: string[]) {
+  const options: ParseArgsOptionsConfig = {};
+  for (const [key, def] of Object.entries(op.args)) {
+    options[kebab(key)] = { type: def.type === "boolean" ? "boolean" : "string" };
+  }
+  const parsed = parse(argv, options, `ops help ${op.id}`);
+
+  const args: Record<string, unknown> = {};
+  for (const [key, def] of Object.entries(op.args)) {
+    const raw = parsed.values[kebab(key)];
+    if (raw === undefined || Array.isArray(raw)) continue;
+    try {
+      args[key] = coerceArg(def, `--${kebab(key)}`, raw);
+    } catch (error) {
+      throw new UsageError((error as Error).message);
+    }
+  }
+  return { args, positionals: parsed.positionals };
+}
+
+async function readInput(positionals: string[]): Promise<Uint8Array> {
+  if (positionals.length) return new TextEncoder().encode(positionals.join(" "));
+  if (process.stdin.isTTY) throw new UsageError("No input: pass it as an argument or pipe it through stdin");
+  return new Uint8Array(await buffer(process.stdin));
+}
+
+async function write(output: Uint8Array | string, { raw = false } = {}) {
+  let bytes = typeof output === "string" ? new TextEncoder().encode(output) : output;
+  if (process.stdout.isTTY) {
+    // Decoded data may hold escape sequences that would drive the terminal.
+    if (!raw && !isPrintable(bytes)) {
+      console.error("ops: output contains binary data or control characters, shown as a hexdump (use --raw to print it as is)");
+      bytes = new TextEncoder().encode(hexdump(bytes));
+    }
+    // Keep the shell prompt off the output line, without altering piped bytes.
+    bytes = new Uint8Array([...bytes, 0x0a]);
+  }
+  await new Promise<void>((resolve, reject) => process.stdout.write(bytes, (error) => (error ? reject(error) : resolve())));
+}
+
+async function main(argv: string[]): Promise<void> {
+  const [command, ...args] = argv;
+  const { raw, help, rest } = splitGlobalFlags(args);
+
+  if (command === undefined || command === "--help" || command === "-h") return write(USAGE);
+  if (command === "--version" || command === "-v") return write(pkg.version);
+  if (command === "list") return write(list());
+
+  if (command === "help") {
+    const id = rest[0];
+    if (id === undefined) return write(USAGE);
+    if (id === "render") return write(RENDER_HELP);
+    if (!isOperationId(id)) throw new UsageError(`Unknown operation "${id}" (see: ops list)`);
+    return write(operationHelp(getOperation(id)));
+  }
+
+  if (command === "completions") {
+    const shell = rest[0];
+    if (!SHELLS.includes(shell as Shell)) throw new UsageError(`Expected a shell: ${SHELLS.join(", ")}`);
+    return write(completions(shell as Shell));
+  }
+
+  if (command === "render") {
+    if (help) return write(RENDER_HELP);
+    const { positionals } = parse(rest, {}, "ops help render");
+    const input = await readInput(positionals);
+    return write(renderBytes(new TextDecoder().decode(input)), { raw });
+  }
+
+  if (!isOperationId(command)) throw new UsageError(`Unknown operation "${command}" (see: ops list)`);
+  const op = getOperation(command);
+  if (help) return write(operationHelp(op));
+
+  const { args: opArgs, positionals } = parseOperationArgs(op, rest);
+  return write(run(command, await readInput(positionals), opArgs as never), { raw });
+}
+
+if (import.meta.main) {
+  // The reader went away (e.g. `ops ... | head`): stop quietly like other Unix tools.
+  process.stdout.on("error", (error: NodeJS.ErrnoException) => {
+    if (error.code === "EPIPE") process.exit(0);
+    throw error;
+  });
+  try {
+    await main(process.argv.slice(2));
+  } catch (error) {
+    // The reader went away (e.g. `ops ... | head`): stop quietly like other Unix tools.
+    if ((error as { code?: string }).code === "EPIPE") process.exit(0);
+    const message = error instanceof Error ? error.message : String(error);
+    const prefix = error instanceof OperationError && error.operation ? `${error.operation}: ` : "";
+    console.error(`ops: ${prefix}${message}`);
+    process.exit(error instanceof UsageError ? 2 : 1);
+  }
+}