functionalscript 0.25.0 → 0.26.0

package/fs/cas/module.f.d.ts

@@ -6,7 +6,7 @@
 import { type Sha2 } from '../crypto/sha2/module.f.ts';
 import type { Vec } from '../types/bit_vec/module.f.ts';
 import { type Effect, type Operation } from '../effects/module.f.ts';
-import { type Fs, type NodeOp } from '../effects/node/module.f.ts';
+import { type Fs, type NodeOp, type NodeProgramOptions } from '../effects/node/module.f.ts';
 export type KvStore<O extends Operation> = {
     /** Reads a value by key; returns `undefined` when the key does not exist. */
     readonly read: (key: Vec) => Effect<O, Vec | undefined>;
@@ -33,12 +33,4 @@ export type Cas<O extends Operation> = {
  * Builds a content-addressable storage facade from a SHA-2 implementation.
  */
 export declare const cas: (sha2: Sha2) => <O extends Operation>(_: KvStore<O>) => Cas<O>;
-/**
- * Runs the CAS CLI.
- *
- * Supported subcommands:
- * - `add <path>`: stores file content and prints the hash.
- * - `get <hash> <path>`: restores content by hash into a file.
- * - `list`: prints all known hashes.
- */
-export declare const main: (args: readonly string[]) => Effect<NodeOp, number>;
+export declare const main: (options: NodeProgramOptions) => Effect<NodeOp, number>;

package/fs/cas/module.f.js

@@ -8,6 +8,7 @@ import { parse } from "../path/module.f.js";
 import { cBase32ToVec, vecToCBase32 } from "../cbase32/module.f.js";
 import { begin, forEachStep, pure } from "../effects/module.f.js";
 import { errorExit, log, mkdir, readdir, readFile, writeFile } from "../effects/node/module.f.js";
+import { dispatch } from "../cli/module.f.js";
 import { toOption } from "../types/nullable/module.f.js";
 import { unwrap } from "../types/result/module.f.js";
 const o = { withFileTypes: true };
@@ -61,59 +62,54 @@ export const cas = (sha2) => {
         list,
     });
 };
-/**
- * Runs the CAS CLI.
- *
- * Supported subcommands:
- * - `add <path>`: stores file content and prints the hash.
- * - `get <hash> <path>`: restores content by hash into a file.
- * - `list`: prints all known hashes.
- */
-export const main = (args) => {
+export const main = (options) => {
     const c = cas(sha256)(fileKvStore('.'));
-    const [cmd, ...options] = args;
-    switch (cmd) {
-        case 'add': {
-            if (options.length !== 1) {
-                return errorExit("'cas add' expects one parameter");
-            }
-            const [path] = options;
-            return begin
-                .step(() => readFile(path))
-                .step(v => c.write(unwrap(v)))
-                .step(hash => log(vecToCBase32(hash)))
-                .step(() => pure(0));
-        }
-        case 'get': {
-            if (options.length !== 2) {
-                return errorExit("'cas get' expects two parameters");
-            }
-            const [hashCBase32, path] = options;
-            const hash = cBase32ToVec(hashCBase32);
-            if (hash === null) {
-                return errorExit(`invalid hash format: ${hashCBase32}`);
-            }
-            return begin
-                .step(() => c.read(hash))
-                .step(v => {
-                const result = v === undefined
-                    ? errorExit(`no such hash: ${hashCBase32}`)
-                    : begin
-                        .step(() => writeFile(path, v))
-                        .step(() => pure(0));
-                return result;
-            });
-        }
-        case 'list': {
-            return begin
+    const commands = [
+        {
+            names: ['add'],
+            description: 'Store file content and print its hash',
+            handler: ({ args: [path, ...rest] }) => {
+                if (path === undefined || rest.length !== 0) {
+                    return errorExit("'cas add' expects one parameter");
+                }
+                return begin
+                    .step(() => readFile(path))
+                    .step(v => c.write(unwrap(v)))
+                    .step(hash => log(vecToCBase32(hash)))
+                    .step(() => pure(0));
+            },
+        },
+        {
+            names: ['get'],
+            description: 'Restore content by hash into a file',
+            handler: ({ args: [hashCBase32, path, ...rest] }) => {
+                if (hashCBase32 === undefined || path === undefined || rest.length !== 0) {
+                    return errorExit("'cas get' expects two parameters");
+                }
+                const hash = cBase32ToVec(hashCBase32);
+                if (hash === null) {
+                    return errorExit(`invalid hash format: ${hashCBase32}`);
+                }
+                return begin
+                    .step(() => c.read(hash))
+                    .step(v => {
+                    const result = v === undefined
+                        ? errorExit(`no such hash: ${hashCBase32}`)
+                        : begin
+                            .step(() => writeFile(path, v))
+                            .step(() => pure(0));
+                    return result;
+                });
+            },
+        },
+        {
+            names: ['list'],
+            description: 'List all stored content hashes',
+            handler: () => begin
                 .step(() => c.list())
                 .step(forEachStep(j => log(vecToCBase32(j))))
-                .step(() => pure(0));
-        }
-        case undefined: {
-            return errorExit('Error: CAS command requires subcommand');
-        }
-        default:
-            return errorExit(`Error: Unknown CAS subcommand "${args[0]}"`);
-    }
+                .step(() => pure(0)),
+        },
+    ];
+    return dispatch(commands)(options);
 };

package/fs/cas/proof.f.js

@@ -4,11 +4,20 @@ import { empty, length, vec8 } from "../types/bit_vec/module.f.js";
 import { pure } from "../effects/module.f.js";
 import { run } from "../effects/mock/module.f.js";
 import { emptyState, virtual } from "../effects/node/virtual/module.f.js";
+const makeOptions = (args) => ({
+    args,
+    env: {},
+    std: { stdout: { isTTY: false }, stderr: { isTTY: false } },
+    testContext: { test: async () => { } },
+    bunTestContext: { test: async () => { } },
+    playwrightTestContext: { test: async () => { } },
+    engine: 'node',
+});
 export const proof = {
     mainAdd: () => {
         const content = vec8(0x2an);
         const state = { ...emptyState, root: { myfile: content } };
-        const [finalState, exitCode] = virtual(state)(main(['add', 'myfile']));
+        const [finalState, exitCode] = virtual(state)(main(makeOptions(['add', 'myfile'])));
         if (exitCode !== 0) {
             throw ['expected exit 0', exitCode];
         }
@@ -17,7 +26,7 @@ export const proof = {
         }
     },
     mainAddWrongArgs: () => {
-        const [finalState, exitCode] = virtual(emptyState)(main(['add']));
+        const [finalState, exitCode] = virtual(emptyState)(main(makeOptions(['add'])));
         if (exitCode !== 1) {
             throw ['expected exit 1', exitCode];
         }
@@ -28,12 +37,12 @@ export const proof = {
     mainGetFound: () => {
         const content = vec8(0x2an);
         const state = { ...emptyState, root: { myfile: content } };
-        const [state1, exitCode1] = virtual(state)(main(['add', 'myfile']));
+        const [state1, exitCode1] = virtual(state)(main(makeOptions(['add', 'myfile'])));
         if (exitCode1 !== 0) {
             throw ['expected add exit 0', exitCode1];
         }
         const hashStr = state1.stdout.trim();
-        const [, exitCode2] = virtual(state1)(main(['get', hashStr, 'output']));
+        const [, exitCode2] = virtual(state1)(main(makeOptions(['get', hashStr, 'output'])));
         if (exitCode2 !== 0) {
             throw ['expected get exit 0', exitCode2];
         }
@@ -42,10 +51,10 @@ export const proof = {
         // valid cBase32 hash that has not been stored
         const content = vec8(0x2an);
         const state = { ...emptyState, root: { myfile: content } };
-        const [state1] = virtual(state)(main(['add', 'myfile']));
+        const [state1] = virtual(state)(main(makeOptions(['add', 'myfile'])));
         const hashStr = state1.stdout.trim();
         // use an empty store so the hash is not found
-        const [finalState, exitCode] = virtual(emptyState)(main(['get', hashStr, 'output']));
+        const [finalState, exitCode] = virtual(emptyState)(main(makeOptions(['get', hashStr, 'output'])));
         if (exitCode !== 1) {
             throw ['expected exit 1', exitCode];
         }
@@ -54,7 +63,7 @@ export const proof = {
         }
     },
     mainGetWrongArgs: () => {
-        const [finalState, exitCode] = virtual(emptyState)(main(['get']));
+        const [finalState, exitCode] = virtual(emptyState)(main(makeOptions(['get'])));
         if (exitCode !== 1) {
             throw ['expected exit 1', exitCode];
         }
@@ -63,7 +72,7 @@ export const proof = {
         }
     },
     mainGetInvalidHash: () => {
-        const [finalState, exitCode] = virtual(emptyState)(main(['get', 'not-a-valid-hash', 'output']));
+        const [finalState, exitCode] = virtual(emptyState)(main(makeOptions(['get', 'not-a-valid-hash', 'output'])));
         if (exitCode !== 1) {
             throw ['expected exit 1', exitCode];
         }
@@ -74,14 +83,14 @@ export const proof = {
     mainList: () => {
         const content = vec8(0x2an);
         const state = { ...emptyState, root: { myfile: content } };
-        const [state1] = virtual(state)(main(['add', 'myfile']));
-        const [, exitCode] = virtual(state1)(main(['list']));
+        const [state1] = virtual(state)(main(makeOptions(['add', 'myfile'])));
+        const [, exitCode] = virtual(state1)(main(makeOptions(['list'])));
         if (exitCode !== 0) {
             throw ['expected exit 0', exitCode];
         }
     },
     mainNoCmd: () => {
-        const [finalState, exitCode] = virtual(emptyState)(main([]));
+        const [finalState, exitCode] = virtual(emptyState)(main(makeOptions([])));
         if (exitCode !== 1) {
             throw ['expected exit 1', exitCode];
         }
@@ -90,7 +99,7 @@ export const proof = {
         }
     },
     mainUnknownCmd: () => {
-        const [finalState, exitCode] = virtual(emptyState)(main(['bogus']));
+        const [finalState, exitCode] = virtual(emptyState)(main(makeOptions(['bogus'])));
         if (exitCode !== 1) {
             throw ['expected exit 1', exitCode];
         }

package/fs/ci/module.f.d.ts

@@ -7,5 +7,4 @@ export type Setup = {
     readonly bunExtra: readonly MetaStep[];
 };
 export declare const ci: ({ nodeExtra, denoExtra, bunExtra }: Setup) => Effect<NodeOp, number>;
-declare const _default: () => Effect<NodeOp, number>;
-export default _default;
+export declare const main: () => Effect<NodeOp, number>;

package/fs/ci/module.f.js

@@ -59,4 +59,4 @@ const defaultEffect = ci({
         test({ run: 'bun ./fs/fjs/module.ts t' }),
     ]
 });
-export default () => defaultEffect;
+export const main = () => defaultEffect;

package/fs/cli/module.f.d.ts

@@ -0,0 +1,9 @@
+import { type NodeOp, type NodeProgramOptions, type Write } from '../effects/node/module.f.ts';
+import { type Effect } from '../effects/module.f.ts';
+export type Command<O extends NodeOp> = {
+    readonly names: readonly string[];
+    readonly description: string;
+    readonly handler: (options: NodeProgramOptions) => Effect<O, number>;
+};
+export type Commands<O extends NodeOp> = readonly Command<O>[];
+export declare const dispatch: <O extends NodeOp>(commands: Commands<O>) => (options: NodeProgramOptions) => Effect<O | Write, number>;

package/fs/cli/module.f.js

@@ -0,0 +1,24 @@
+import { errorExit, log } from "../effects/node/module.f.js";
+import { pure } from "../effects/module.f.js";
+const helpMeta = { names: ['help', 'h', '?'], description: 'Print this help message' };
+export const dispatch = (commands) => (options) => {
+    const [cmd, ...rest] = options.args;
+    const rows = [...commands, helpMeta];
+    const nameCol = rows.map(c => c.names.join(', '));
+    const width = Math.max(...nameCol.map(s => s.length));
+    const helpText = ['Available commands:', ...rows.map((c, i) => `  ${nameCol[i].padEnd(width)}  ${c.description}`)].join('\n');
+    const helpCommand = {
+        ...helpMeta,
+        handler: () => log(helpText).step(() => pure(0)),
+    };
+    const allCommands = [...commands, helpCommand];
+    const map = Object.fromEntries(allCommands.flatMap(c => c.names.map(n => [n, c])));
+    if (cmd === undefined) {
+        return errorExit(`Error: command is required.\n${helpText}`);
+    }
+    const found = map[cmd];
+    if (found === undefined) {
+        return errorExit(`Error: unknown command "${cmd}".\n${helpText}`);
+    }
+    return found.handler({ ...options, args: rest });
+};

package/fs/cli/proof.f.d.ts

@@ -0,0 +1,9 @@
+export declare const proof: {
+    knownCommand: () => void;
+    alias: () => void;
+    noArgs: () => void;
+    unknownCommand: () => void;
+    help: () => void;
+    errorIncludesAvailable: () => void;
+    handlerReceivesRemainingArgs: () => void;
+};

package/fs/cli/proof.f.js

@@ -0,0 +1,86 @@
+import { pure } from "../effects/module.f.js";
+import {} from "../effects/node/module.f.js";
+import { emptyState, virtual } from "../effects/node/virtual/module.f.js";
+import { dispatch } from "./module.f.js";
+const makeOptions = (args) => ({
+    args,
+    env: {},
+    std: { stdout: { isTTY: false }, stderr: { isTTY: false } },
+    testContext: { test: async () => { } },
+    bunTestContext: { test: async () => { } },
+    playwrightTestContext: { test: async () => { } },
+    engine: 'node',
+});
+const echoCommands = [
+    {
+        names: ['echo', 'e'],
+        description: 'Print the first argument',
+        handler: ({ args: [arg = ''] }) => pure(arg.length),
+    },
+];
+const run = (commands) => (args) => virtual(emptyState)(dispatch(commands)(makeOptions(args)));
+export const proof = {
+    knownCommand: () => {
+        const [, code] = run(echoCommands)(['echo', 'hello']);
+        if (code !== 5) {
+            throw ['expected length 5', code];
+        }
+    },
+    alias: () => {
+        const [, code] = run(echoCommands)(['e', 'hi']);
+        if (code !== 2) {
+            throw ['expected length 2', code];
+        }
+    },
+    noArgs: () => {
+        const [state, code] = run(echoCommands)([]);
+        if (code !== 1) {
+            throw ['expected exit 1', code];
+        }
+        if (state.stderr.length === 0) {
+            throw 'expected error in stderr';
+        }
+    },
+    unknownCommand: () => {
+        const [state, code] = run(echoCommands)(['bogus']);
+        if (code !== 1) {
+            throw ['expected exit 1', code];
+        }
+        if (state.stderr.length === 0) {
+            throw 'expected error in stderr';
+        }
+    },
+    help: () => {
+        const [state, code] = run(echoCommands)(['help']);
+        if (code !== 0) {
+            throw ['expected exit 0', code];
+        }
+        if (!state.stdout.includes('echo')) {
+            throw 'expected command name in stdout';
+        }
+        if (!state.stdout.includes('help')) {
+            throw 'expected help entry in stdout';
+        }
+    },
+    errorIncludesAvailable: () => {
+        const [state] = run(echoCommands)(['bogus']);
+        if (!state.stderr.includes('echo')) {
+            throw 'expected available commands in error';
+        }
+    },
+    handlerReceivesRemainingArgs: () => {
+        const captured = [];
+        const commands = [{
+                names: ['grab'],
+                description: 'Capture args',
+                handler: ({ args }) => {
+                    captured.push(...args);
+                    return pure(0);
+                },
+            }];
+        run(commands)(['grab', 'a', 'b', 'c']);
+        if (captured.join(',') !== 'a,b,c') {
+            throw ['unexpected args', captured];
+        }
+    },
+};

package/fs/dev/index/module.f.d.ts

@@ -1,8 +1 @@
-/**
- * Entry point for the `index` developer program: re-exports `index4` from the
- * parent `dev` module as the default `NodeProgram`.
- *
- * @module
- */
-import { index4 } from '../module.f.ts';
-export default index4;
+export declare const main: import("../../effects/node/module.f.ts").NodeProgram;

package/fs/dev/index/module.f.js

@@ -5,4 +5,4 @@
  * @module
  */
 import { index4 } from "../module.f.js";
-export default index4;
+export const main = index4;

package/fs/effects/node/module.f.d.ts

@@ -166,7 +166,7 @@ export type NodeEffect<T> = Effect<NodeOp, T>;
  * "fail with a message" program for a `NodeProgram`. For non-`1` exit codes,
  * compose `error(s).step(() => pure(n))` directly.
  */
-export declare const errorExit: (s: string) => Effect<NodeOp, number>;
+export declare const errorExit: (s: string) => Effect<Write, number>;
 export type NodeOperationMap = ToAsyncOperationMap<NodeOp>;
 /**
  * The environment variables.

package/fs/emergent_testing/module.f.d.ts

@@ -117,7 +117,7 @@ export declare const defaultTest: (file: string, path: Path, { fn, throws }: Tes
 /**
  * The terminal/GitHub reporter used by `fjs t`. Output goes through
  * `csiWrite`, so ANSI styles are stripped on non-TTY streams. When
- * `GITHUB_ACTION` is set, failures are emitted as `::error` workflow
+ * `GITHUB_ACTIONS` is set, failures are emitted as `::error` workflow
  * annotations instead of colored lines. Exported as a factory so the
  * GitHub format path can be exercised directly from tests.
  */

package/fs/emergent_testing/module.f.js

@@ -220,7 +220,7 @@ const fmtResultLine = (file, path, color, label, duration) => `${fmtImport(file,
 /**
  * The terminal/GitHub reporter used by `fjs t`. Output goes through
  * `csiWrite`, so ANSI styles are stripped on non-TTY streams. When
- * `GITHUB_ACTION` is set, failures are emitted as `::error` workflow
+ * `GITHUB_ACTIONS` is set, failures are emitted as `::error` workflow
  * annotations instead of colored lines. Exported as a factory so the
  * GitHub format path can be exercised directly from tests.
  */
@@ -232,7 +232,7 @@ export const defaultReporter = (options) => {
     };
     const csiLog = line('stdout');
     const csiError = line('stderr');
-    const isGitHub = options.env['GITHUB_ACTION'] !== undefined;
+    const isGitHub = options.env['GITHUB_ACTIONS'] !== undefined;
     return {
         // https://github.com/OndraM/ci-detector/blob/main/src/Ci/GitHubActions.php
         result: (file, path, { result: [s, v], duration }, throws) => s === 'ok'

package/fs/emergent_testing/proof.f.js

@@ -17,7 +17,7 @@ const makeReporter = () => {
 const noopTestContext = { test: todo };
 const options = (initCwd, github = false) => ({
     args: [],
-    env: { INIT_CWD: initCwd, ...(github ? { GITHUB_ACTION: 'true' } : {}) },
+    env: { INIT_CWD: initCwd, ...(github ? { GITHUB_ACTIONS: 'true' } : {}) },
     std: { stdout: { isTTY: false }, stderr: { isTTY: false } },
     testContext: noopTestContext,
     bunTestContext: noopTestContext,

package/fs/fjs/module.f.js

@@ -6,32 +6,42 @@
 import { compile } from "../djs/module.f.js";
 import { main as testMain } from "../emergent_testing/module.f.js";
 import { main as casMain } from "../cas/module.f.js";
-import { import_, errorExit } from "../effects/node/module.f.js";
-export const main = options => {
-    const [command, ...rest] = options.args;
-    switch (command) {
-        case 'test':
-        case 't':
-            return testMain({ ...options, args: rest });
-        case 'compile':
-        case 'c':
-            return compile(rest);
-        case 'cas':
-        case 's':
-            return casMain(rest);
-        case 'run':
-        case 'r': {
-            const [file, ...args] = rest;
+import { main as ciMain } from "../ci/module.f.js";
+import { import_ } from "../effects/node/module.f.js";
+import { dispatch } from "../cli/module.f.js";
+const commands = [
+    {
+        names: ['test', 't'],
+        description: 'Run the FunctionalScript test suite',
+        handler: testMain,
+    },
+    {
+        names: ['compile', 'c'],
+        description: 'Compile a FunctionalScript module to JavaScript',
+        handler: ({ args }) => compile(args),
+    },
+    {
+        names: ['cas', 's'],
+        description: 'Content-addressable storage operations',
+        handler: casMain,
+    },
+    {
+        names: ['ci', 'i'],
+        description: 'Generate the GitHub Actions CI workflow',
+        handler: ciMain,
+    },
+    {
+        names: ['run', 'r'],
+        description: 'Run a FunctionalScript module as a NodeProgram',
+        handler: options => {
+            const [file, ...args] = options.args;
             return import_(file).step(([s, v]) => {
                 if (s === 'error') {
                     throw v;
                 }
-                return v.default({ ...options, args });
+                return v.main({ ...options, args });
             });
-        }
-        case undefined:
-            return errorExit('Error: command is required');
-        default:
-            return errorExit(`Error: Unknown command "${command}"`);
-    }
-};
+        },
+    },
+];
+export const main = dispatch(commands);

package/fs/website/module.f.d.ts

@@ -1,4 +1,3 @@
 import { type WriteFile } from '../effects/node/module.f.ts';
 import { type Effect } from '../effects/module.f.ts';
-declare const _default: () => Effect<WriteFile, number>;
-export default _default;
+export declare const main: () => Effect<WriteFile, number>;

package/fs/website/module.f.js

@@ -12,4 +12,4 @@ const html = htmlUtf8()(['a',
 ]);
 const program = writeFile('index.html', html)
     .step(() => pure(0));
-export default () => program;
+export const main = () => program;

package/fs/website/proof.f.d.ts

@@ -1,3 +1,3 @@
 export declare const proof: {
-    default: () => void;
+    main: () => void;
 };

package/fs/website/proof.f.js

@@ -1,7 +1,7 @@
-import defaultExport from "./module.f.js";
+import { main } from "./module.f.js";
 export const proof = {
-    default: () => {
-        const program = defaultExport();
+    main: () => {
+        const program = main();
         if (program === undefined) {
             throw 'expected a program effect';
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "functionalscript",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "type": "module",
   "files": [
     "**/*.js",
@@ -13,7 +13,7 @@
     "cov": "node --test --experimental-test-coverage --test-coverage-include=**/module.f.ts",
     "index": "node ./fs/fjs/module.ts r ./fs/dev/index/module.f.ts",
     "start": "node ./fs/fjs/module.ts",
-    "ci-update": "node ./fs/fjs/module.ts r ./fs/ci/module.f.ts",
+    "ci-update": "node ./fs/fjs/module.ts ci",
     "update": "npm install && npm run index && npm run ci-update",
     "index-html": "node ./fs/fjs/module.ts r ./fs/website/module.f.ts",
     "website": "npm run prepack &&npm run index-html"