@fraczak/k 6.0.4 → 6.1.0

package/codecs/ieee.mjs

@@ -6,6 +6,13 @@ import { decodeWire, encodeToWire } from "./runtime/prefix-codec.mjs";
 import { FLOAT64_PATTERN } from "./runtime/ieee-pattern.mjs";
 const UNIT = new Product({});
 
+function usage(stream = console.error) {
+  stream(`Usage: ${argv[1]} --parse | --print`);
+  stream("  --parse      Read a float literal from stdin, write binary pattern+value stream.");
+  stream("  --print      Read binary pattern+value stream from stdin, write a float literal.");
+  stream("  -h, --help   Show this help.");
+}
+
 function bitValue(bit) {
   return new Variant(bit === 0 ? "0" : "1", UNIT);
 }
@@ -116,10 +123,13 @@ function readAll(stream) {
 
 async function main() {
   const args = argv.slice(2);
+  if (args.includes("-h") || args.includes("--help")) {
+    usage(console.log);
+    exit(0);
+  }
+
   if (args.length !== 1 || (args[0] !== "--parse" && args[0] !== "--print")) {
-    console.error("Usage: ieee.mjs --parse | --print");
-    console.error("  --parse  read a float literal from stdin, write binary pattern+value stream");
-    console.error("  --print  read binary pattern+value stream from stdin, write a float literal");
+    usage();
     exit(1);
   }
 

package/codecs/int.mjs

@@ -17,6 +17,13 @@ import { stdin, stdout, argv, exit } from "node:process";
 import { Product, Variant } from "../Value.mjs";
 import { decodeWire, encodeToWire } from "./runtime/prefix-codec.mjs";
 
+function usage(stream = console.error) {
+  stream(`Usage: ${argv[1]} --parse | --print`);
+  stream("  --parse      Read a decimal integer from stdin, write binary pattern+value stream.");
+  stream("  --print      Read binary pattern+value stream from stdin, write decimal integer.");
+  stream("  -h, --help   Show this help.");
+}
+
 // Closed pattern for $ int = < bits '+', bits '-' >
 // with $ bits = < {} _, bits 0, bits 1 >
 const INT_PATTERN = [
@@ -79,10 +86,13 @@ function printIntValue(value) {
 
 async function main() {
   const args = argv.slice(2);
+  if (args.includes("-h") || args.includes("--help")) {
+    usage(console.log);
+    exit(0);
+  }
+
   if (args.length !== 1 || (args[0] !== "--parse" && args[0] !== "--print")) {
-    console.error("Usage: int.mjs --parse | --print");
-    console.error("  --parse  read a decimal integer from stdin, write binary pattern+value stream");
-    console.error("  --print  read binary pattern+value stream from stdin, write decimal integer");
+    usage();
     exit(1);
   }
 

package/codecs/json.mjs

@@ -4,6 +4,13 @@ import { stdin, stdout, argv, exit } from "node:process";
 import { decodeWire, encodeToWire } from "./runtime/prefix-codec.mjs";
 import { fromJsonValue, toJsonValue, patternFromJsonValue } from "./json-codec.mjs";
 
+function usage(stream = console.error) {
+  stream(`Usage: ${argv[1]} --parse | --print`);
+  stream("  --parse      Read JSON from stdin, write binary pattern+value stream.");
+  stream("  --print      Read binary pattern+value stream from stdin, write JSON.");
+  stream("  -h, --help   Show this help.");
+}
+
 function readAll(stream) {
   return new Promise((resolve, reject) => {
     const chunks = [];
@@ -15,10 +22,13 @@ function readAll(stream) {
 
 async function main() {
   const args = argv.slice(2);
+  if (args.includes("-h") || args.includes("--help")) {
+    usage(console.log);
+    exit(0);
+  }
+
   if (args.length !== 1 || (args[0] !== "--parse" && args[0] !== "--print")) {
-    console.error("Usage: json.mjs --parse | --print");
-    console.error("  --parse  read JSON from stdin, write binary pattern+value stream");
-    console.error("  --print  read binary pattern+value stream from stdin, write JSON");
+    usage();
     exit(1);
   }
 

package/codecs/k-parse.mjs

@@ -49,6 +49,11 @@ async function main() {
   const prog = argv[1];
   const args = argv.slice(2);
 
+  if (args.includes("-h") || args.includes("--help")) {
+    usage(prog);
+    return exit(0);
+  }
+
   let inputTypeArg = null;
   let inputPatternArg = null;
   let valueFile = null;

package/codecs/k-print.mjs

@@ -4,6 +4,15 @@ import fs from "node:fs";
 import { argv, stdin, stdout } from "node:process";
 import { decodeWire } from "./runtime/prefix-codec.mjs";
 
+function usage(stream = console.error) {
+  stream(`Usage: ${argv[1]} [--debug] [file]`);
+  stream("  Read a binary pattern+value stream and print the decoded textual value.");
+  stream("");
+  stream("Options:");
+  stream("  --debug      Print decoded pattern and value as JSON.");
+  stream("  -h, --help   Show this help.");
+}
+
 function readAll(stream) {
   return new Promise((resolve, reject) => {
     const chunks = [];
@@ -15,6 +24,11 @@ function readAll(stream) {
 
 async function main() {
   const args = argv.slice(2);
+  if (args.includes("-h") || args.includes("--help")) {
+    usage(console.log);
+    return;
+  }
+
   let debug = false;
   let fileArg = null;
 
@@ -24,7 +38,8 @@ async function main() {
     } else if (fileArg == null) {
       fileArg = arg;
     } else {
-      throw new Error("Usage: k-print [--debug] [file]");
+      usage();
+      process.exit(1);
     }
   }
 

package/codecs/show.mjs

@@ -5,6 +5,15 @@ import { argv, stdin, stdout, stderr } from "node:process";
 import { decodeWire } from "./runtime/prefix-codec.mjs";
 import { propertyListToFilter, valueToK } from "./runtime/show-value.mjs";
 
+function usage(stream = console.error) {
+  stream(`Usage: ${argv[1]} [wire-file]`);
+  stream("  Pass the wire stream through unchanged on stdout.");
+  stream("  Print the decoded value and filter to stderr.");
+  stream("");
+  stream("Options:");
+  stream("  -h, --help   Show this help.");
+}
+
 function readAll(stream) {
   return new Promise((resolve, reject) => {
     const chunks = [];
@@ -16,10 +25,15 @@ function readAll(stream) {
 
 async function main() {
   const args = argv.slice(2);
+  if (args.includes("-h") || args.includes("--help")) {
+    usage(console.log);
+    return;
+  }
+
   let fileArg = null;
   for (const arg of args) {
     if (fileArg == null) fileArg = arg;
-    else { console.error("Usage: show.mjs [wire-file]"); process.exit(1); }
+    else { usage(); process.exit(1); }
   }
 
   const buffer = fileArg ? fs.readFileSync(fileArg) : await readAll(stdin);

package/codecs/unit.mjs

@@ -4,6 +4,13 @@ import { stdin, stdout, argv, exit } from "node:process";
 import { Product } from "../Value.mjs";
 import { decodeWire, encodeToWire } from "./runtime/prefix-codec.mjs";
 
+function usage(stream = console.error) {
+  stream(`Usage: ${argv[1]} --parse | --print`);
+  stream("  --parse      Ignore stdin and write the unit binary pattern+value stream.");
+  stream("  --print      Validate the unit binary pattern+value stream and write {}.");
+  stream("  -h, --help   Show this help.");
+}
+
 const UNIT_PATTERN = [
   ["closed-product", []]
 ];
@@ -23,10 +30,13 @@ function unitEncoding() {
 
 async function main() {
   const args = argv.slice(2);
+  if (args.includes("-h") || args.includes("--help")) {
+    usage(console.log);
+    exit(0);
+  }
+
   if (args.length !== 1 || (args[0] !== "--parse" && args[0] !== "--print")) {
-    console.error("Usage: unit.mjs --parse | --print");
-    console.error("  --parse  ignore stdin and write the unit binary pattern+value stream");
-    console.error("  --print  validate the unit binary pattern+value stream and write {}");
+    usage();
     exit(1);
   }
 

package/codecs/utf16.mjs

@@ -3,6 +3,13 @@
 import { stdin, stdout, argv, exit } from "node:process";
 import { encodeText, decodeText } from "./string-codec.mjs";
 
+function usage(stream = console.error) {
+  stream(`Usage: ${argv[1]} --parse | --print`);
+  stream("  --parse      Read UTF-16 text from stdin (BOM-aware), write binary pattern+value stream of k string.");
+  stream("  --print      Read binary pattern+value stream of k string, write UTF-16LE text with BOM.");
+  stream("  -h, --help   Show this help.");
+}
+
 function readAll(stream) {
   return new Promise((resolve, reject) => {
     const chunks = [];
@@ -43,10 +50,13 @@ function encodeUtf16Output(text) {
 
 async function main() {
   const args = argv.slice(2);
+  if (args.includes("-h") || args.includes("--help")) {
+    usage(console.log);
+    exit(0);
+  }
+
   if (args.length !== 1 || (args[0] !== "--parse" && args[0] !== "--print")) {
-    console.error("Usage: utf16.mjs --parse | --print");
-    console.error("  --parse  read UTF-16 text from stdin (BOM-aware), write binary pattern+value stream of k string");
-    console.error("  --print  read binary pattern+value stream of k string, write UTF-16LE text with BOM");
+    usage();
     exit(1);
   }
 

package/codecs/utf8.mjs

@@ -3,6 +3,13 @@
 import { stdin, stdout, argv, exit } from "node:process";
 import { encodeText, decodeText } from "./string-codec.mjs";
 
+function usage(stream = console.error) {
+  stream(`Usage: ${argv[1]} --parse | --print`);
+  stream("  --parse      Read UTF-8 text from stdin, write binary pattern+value stream of k string.");
+  stream("  --print      Read binary pattern+value stream of k string, write UTF-8 text.");
+  stream("  -h, --help   Show this help.");
+}
+
 function readAll(stream) {
   return new Promise((resolve, reject) => {
     const chunks = [];
@@ -14,10 +21,13 @@ function readAll(stream) {
 
 async function main() {
   const args = argv.slice(2);
+  if (args.includes("-h") || args.includes("--help")) {
+    usage(console.log);
+    exit(0);
+  }
+
   if (args.length !== 1 || (args[0] !== "--parse" && args[0] !== "--print")) {
-    console.error("Usage: utf8.mjs --parse | --print");
-    console.error("  --parse  read UTF-8 text from stdin, write binary pattern+value stream of k string");
-    console.error("  --print  read binary pattern+value stream of k string, write UTF-8 text");
+    usage();
     exit(1);
   }
 

package/k-vscode/README.md

@@ -1,7 +1,8 @@
 # k language — VS Code extension
 
-Syntax highlighting and snippets for the **k language**: a language for composing
-first-order partial functions over algebraic data types (products and tagged unions).
+Syntax highlighting and snippets for the **k language**: a small language for
+typed data transformations over algebraic data types (products and tagged
+unions).
 
 ## Features
 

package/k.mjs

@@ -13,7 +13,10 @@ let kScript, inputStream;
 
 function usage() {
   console.error(`Usage: ${prog} [ --lib lib-file ]... ( k-expr | -k file ) [ input-file ]`);
-  console.error(`       E.g.,  echo '["zebara","ela"]' | ./codecs/k-parse.mjs --input-type '$x=<{} zebara, {} ela>; $v={x 0, x 1}; $v' | ${prog} '{.1 0}'`);
+  console.error(`       E.g.,  echo '["zebara","ela"]' | k-parse --input-type '$x=<{} zebara, {} ela>; $v={x 0, x 1}; $v' | ${prog} '{.1 0}'`);
+  console.error("Options:");
+  console.error("  --lib file   Load a .klib dependency before compiling. May be repeated.");
+  console.error("  -h, --help   Show this help.");
 }
 
 function compileFile(path, libraries) {
@@ -27,6 +30,11 @@ function compileFile(path, libraries) {
 
 ({ kScript, inputStream } = ((args) => {
   try {
+    if (args.includes("-h") || args.includes("--help")) {
+      usage();
+      return exit(0);
+    }
+
     const libraries = [];
     // Parse --lib flags
     while (args.length > 0 && args[0] === "--lib") {

package/objects/README.md

@@ -4,17 +4,17 @@ CLI tools for compiling and inspecting k object files (`.ko`) and library files
 
 ## Tools
 
-### compile.mjs
+### `k-compile`
 
 Compiles a `.k` source file into an executable object file (`.ko`).
 The output contains only the codes and relations reachable from `main`.
 Each stored relation includes `typeDerivation.status` for backend eligibility.
 
 ```bash
-./objects/compile.mjs [--lib lib-file]... [k-file [object-file]]
+k-compile [--lib lib-file]... [k-file [object-file]]
 ```
 
-### compile-lib.mjs
+### `k-compile-lib`
 
 Compiles a `.k` source file into a library file (`.klib`).
 The output is plain JSON with no binary header. It contains the library closure
@@ -25,27 +25,30 @@ Each stored relation includes `typeDerivation.status`; libraries may contain a
 mix of converged and non-converged relations.
 
 ```bash
-./objects/compile-lib.mjs [--lib lib-file]... [k-file [lib-file]]
+k-compile-lib [--lib lib-file]... [k-file [lib-file]]
 ```
 
-### decompile.mjs
+### `k-decompile`
 
 Decompiles a `.ko` or `.klib` back into human-readable k source.
 
 ```bash
-./objects/decompile.mjs [object-file [k-file]]
+k-decompile [object-file [k-file]]
 ```
 
-### extract-aliases.mjs
+### `k-extract-aliases`
 
 Extracts metadata aliases from a `.ko` or `.klib` as a valid k definition
 snippet. Output is grouped by metadata type (`code`, then `rel`), then sorted by
 alias name and `compiledAt`.
 
 ```bash
-./objects/extract-aliases.mjs [object-file [k-file]]
+k-extract-aliases [object-file [k-file]]
 ```
 
+The installed names are `k-` plus the source basename without `.mjs`. Every
+installed object binary supports `-h` and `--help`.
+
 ## Current Format Notes
 
 - `.klib` files are plain UTF-8 JSON, not binary containers.

package/package.json

@@ -1,11 +1,11 @@
 {
     "name": "@fraczak/k",
-    "version": "6.0.4",
+    "version": "6.1.0",
     "description": "k — a language for composing first-order partial functions over algebraic data types (products and tagged unions); includes runtime, type derivation, REPL, and codec toolchain",
     "main": "index.mjs",
     "scripts": {
         "prepare": "jiwson -m es6 parser.jison -o parser.mjs; jiwson -m es6 valueParser.jison -o valueParser.mjs; ",
-        "test": "node test.mjs; for f in Code-derivation-tests/*.mjs; do echo $f; node $f; done; node test-fingerprint.mjs; node test-hash-fuzz.mjs; node test-hash-normalization.mjs; node test-k-object.mjs; node test-repl2.mjs; ./tests.sh",
+        "test": "node test.mjs; for f in Code-derivation-tests/*.mjs; do echo $f; node $f; done; node test-fingerprint.mjs; node test-hash-fuzz.mjs; node test-hash-normalization.mjs; node test-k-object.mjs; node test-repl.mjs; ./tests.sh",
         "deps:graph": "node scripts/generate-dependency-graph.mjs"
     },
     "repository": {
@@ -16,14 +16,20 @@
     "license": "ISC",
     "bin": {
         "k": "./k.mjs",
-        "k-compile-object": "./objects/compile.mjs",
-        "k-decompile-object": "./objects/decompile.mjs",
+        "k-compile": "./objects/compile.mjs",
+        "k-compile-lib": "./objects/compile-lib.mjs",
+        "k-decompile": "./objects/decompile.mjs",
         "k-extract-aliases": "./objects/extract-aliases.mjs",
+        "k-ieee": "./codecs/ieee.mjs",
+        "k-int": "./codecs/int.mjs",
+        "k-json": "./codecs/json.mjs",
         "k-parse": "./codecs/k-parse.mjs",
-        "k-pattern": "./patterns/from-k.mjs",
         "k-print": "./codecs/k-print.mjs",
-        "k-repl": "./repl2.mjs",
-        "k-repl2": "./repl2.mjs"
+        "k-repl": "./repl.mjs",
+        "k-show": "./codecs/show.mjs",
+        "k-unit": "./codecs/unit.mjs",
+        "k-utf16": "./codecs/utf16.mjs",
+        "k-utf8": "./codecs/utf8.mjs"
     },
     "devDependencies": {
         "jiwson": "^0.1.2"

package/{repl2.mjs → repl.mjs}

@@ -840,6 +840,16 @@ function helpText() {
   ].join("\n");
 }
 
+function cliUsage() {
+  console.log("Usage: k-repl");
+  console.log("       k-repl -h");
+  console.log("");
+  console.log("Start the interactive k interpreter. Type :help inside the REPL for commands.");
+  console.log("");
+  console.log("Options:");
+  console.log("  -h, --help   Show this help.");
+}
+
 function startRepl() {
   const state = createState();
   const rl = readline.createInterface({
@@ -916,6 +926,15 @@ function startRepl() {
 }
 
 if (isMainEntrypoint()) {
+  const args = argv.slice(2);
+  if (args.includes("-h") || args.includes("--help")) {
+    cliUsage();
+    exit(0);
+  }
+  if (args.length > 0) {
+    cliUsage();
+    exit(1);
+  }
   startRepl();
 }
 

package/{test-repl2.mjs → test-repl.mjs}

@@ -15,7 +15,7 @@ import {
   isMainEntrypoint,
   lineHasExplicitContinuation,
   lineTerminatesSnippet
-} from "./repl2.mjs";
+} from "./repl.mjs";
 import { decodeObject, objectToFunction } from "./object.mjs";
 import { Product } from "./Value.mjs";
 
@@ -78,11 +78,11 @@ await assert.rejects(
   /Type Error in 'filter' \(lines 1:1\.\.\.1:4\)/
 );
 
-const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "k-repl2-"));
+const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "k-repl-"));
 const libPath = path.join(tmpDir, "session.klib");
 const koPath = path.join(tmpDir, "succ.ko");
 const sourcePath = path.join(tmpDir, "session.k");
-const symlinkPath = path.resolve(".test-k-repl2-link");
+const symlinkPath = path.resolve(".test-k-repl-link");
 output = await evaluateInput(`:klib ${libPath}`, state);
 assert.equal(output[0], `saved ${libPath}`);
 
@@ -106,7 +106,7 @@ assert.match(output[0], /^nat = @/m);
 output = await evaluateInput(":rels", loadedSource);
 assert.match(output[0], /^succ = @/m);
 
-const replPath = fileURLToPath(new URL("./repl2.mjs", import.meta.url));
+const replPath = fileURLToPath(new URL("./repl.mjs", import.meta.url));
 try {
   fs.rmSync(symlinkPath, { force: true });
 } catch {}