functionalscript 0.25.0 → 0.27.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/config/module.f.d.ts

@@ -28,7 +28,7 @@ export declare const node: {
 };
 export declare const wasmtime = "45.0.0";
 export declare const wasmer = "7.1.0";
-export declare const tsgo = "7.0.0-dev.20260605.1";
+export declare const tsgo = "7.0.0-dev.20260606.1";
 export declare const actions: {
     readonly 'actions/checkout': "v6";
     readonly 'actions/setup-node': "v6";

package/fs/ci/config/module.f.js

@@ -36,7 +36,7 @@ export const wasmtime = '45.0.0';
 // https://github.com/wasmerio/wasmer/releases
 export const wasmer = '7.1.0';
 // https://www.npmjs.com/package/@typescript/native-preview?activeTab=versions
-export const tsgo = '7.0.0-dev.20260605.1';
+export const tsgo = '7.0.0-dev.20260606.1';
 // GitHub Action versions used by CI step builders. The key is the action
 // `owner/name`; call sites compose the full ref as
 // `` `${name}@${actions[name]}` ``.

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

@@ -3,9 +3,10 @@
  *
  * @module
  */
-import { utf8 } from "../text/module.f.js";
+import { utf8, utf8ToString } from "../text/module.f.js";
+import { validatePackageJsonText } from "../dev/package_json/module.f.js";
 import { pure } from "../effects/module.f.js";
-import { access, writeFile } from "../effects/node/module.f.js";
+import { access, readFile, writeFile } from "../effects/node/module.f.js";
 import { images } from "./config/module.f.js";
 import { architecture, findTgz, os, test, toSteps } from "./common/module.f.js";
 import { rustSteps } from "./rust/module.f.js";
@@ -24,6 +25,20 @@ const job = (rust, nodeExtra, denoExtra, bunExtra) => (o) => (a) => {
     ];
     return [id, { 'runs-on': image, steps: toSteps(result) }];
 };
+const functionalscriptPackageName = 'functionalscript';
+const fallbackPackageInfo = {
+    name: functionalscriptPackageName,
+    functionalscript: false,
+};
+const packageInfoFromPackageJson = ({ name }) => name !== undefined
+    ? { name, functionalscript: name === functionalscriptPackageName }
+    : fallbackPackageInfo;
+const packageInfoFromText = (text) => {
+    const result = validatePackageJsonText(text);
+    return result[0] === 'ok' ? packageInfoFromPackageJson(result[1]) : fallbackPackageInfo;
+};
+const readPackageInfo = readFile('package.json')
+    .step(result => pure(result[0] === 'ok' ? packageInfoFromText(utf8ToString(result[1])) : fallbackPackageInfo));
 export const ci = ({ nodeExtra, denoExtra, bunExtra }) => access('Cargo.toml').step(result => {
     const rust = result[0] === 'ok';
     const jobs = {
@@ -42,21 +57,29 @@ export const ci = ({ nodeExtra, denoExtra, bunExtra }) => access('Cargo.toml').s
     return writeFile('.github/workflows/ci.yml', utf8(JSON.stringify(gha, null, '  ')))
         .step(() => pure(0));
 });
-const defaultEffect = ci({
-    nodeExtra: o => [
-        test({ run: 'npm pack' }),
-        test({ run: `npm install -g ${findTgz(o)}` }),
-        test({ run: 'fjs compile issues/demo/data/tree.json _tree.f.js' }),
-        test({ run: 'fjs t' }),
-        test({ run: 'npm uninstall functionalscript -g' }),
-    ],
+const demoCompile = [
+    test({ run: 'fjs compile issues/demo/data/tree.json _tree.f.js' }),
+    test({ run: 'fjs t' }),
+];
+const denoDemoCompile = [
+    test({ run: 'deno task fjs compile issues/demo/data/tree.json _tree.f.js' }),
+    test({ run: 'deno task fjs t' }),
+];
+const bunDemoCompile = [
+    test({ run: 'bun ./fs/fjs/module.ts t' }),
+];
+const defaultNodeExtra = ({ name, functionalscript }) => (o) => [
+    test({ run: 'npm pack' }),
+    test({ run: `npm install -g ${findTgz(o)}` }),
+    ...(functionalscript ? demoCompile : []),
+    test({ run: `npm uninstall ${name} -g` }),
+];
+const defaultEffect = (info) => ci({
+    nodeExtra: defaultNodeExtra(info),
     denoExtra: [
-        test({ run: 'deno task fjs compile issues/demo/data/tree.json _tree.f.js' }),
-        test({ run: 'deno task fjs t' }),
+        ...(info.functionalscript ? denoDemoCompile : []),
         test({ run: 'deno publish --dry-run --allow-slow-types' }),
     ],
-    bunExtra: [
-        test({ run: 'bun ./fs/fjs/module.ts t' }),
-    ]
+    bunExtra: info.functionalscript ? bunDemoCompile : [],
 });
-export default () => defaultEffect;
+export const main = () => readPackageInfo.step(defaultEffect);

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

@@ -5,4 +5,13 @@ export declare const proof: {
         allOs: () => void;
         osSpecific: () => void;
     };
+    defaultSetup: {
+        functionalscriptDemo: () => void;
+        otherPackageNoDemo: () => void;
+        uninstallPackageName: () => void;
+        malformedPackageJsonFallback: () => void;
+        missingPackageJsonFallback: () => void;
+        missingNameFallback: () => void;
+        nonObjectFallback: () => void;
+    };
 };

package/fs/ci/proof.f.js

@@ -1,5 +1,5 @@
-import { ci } from "./module.f.js";
-import { utf8ToString } from "../text/module.f.js";
+import { ci, main } from "./module.f.js";
+import { utf8, utf8ToString } from "../text/module.f.js";
 import { empty as emptyVec, isVec } from "../types/bit_vec/module.f.js";
 import { test, parseGitHubAction } from "./common/module.f.js";
 import { assert } from "../asserts/module.f.js";
@@ -8,16 +8,15 @@ import { parse as jsonParse } from "../json/module.f.js";
 import { unwrap } from "../types/result/module.f.js";
 const hasRun = (cmd) => (gha) => Object.values(gha.jobs).some(job => job.steps.some(step => step.run?.includes(cmd)));
 const hasRunInJob = (jobId, cmd) => (gha) => gha.jobs[jobId]?.steps.some(step => step.run?.includes(cmd)) ?? false;
-const makeState = (rust) => ({
+const makeState = (rust, packageJson) => ({
     ...emptyState,
     root: {
         '.github': { workflows: {} },
+        ...(packageJson !== undefined ? { 'package.json': utf8(packageJson) } : {}),
         ...(rust ? { 'Cargo.toml': emptyVec } : {}),
     },
 });
-const run = (rust, nodeExtra = () => []) => {
-    const [state, result] = virtual(makeState(rust))(ci({ nodeExtra, denoExtra: [], bunExtra: [] }));
-    assert(result === 0, result);
+const workflow = (state) => {
     const dotGithub = state.root['.github'];
     assert(typeof dotGithub === 'object', dotGithub);
     const workflows = dotGithub['workflows'];
@@ -26,6 +25,16 @@ const run = (rust, nodeExtra = () => []) => {
     assert(isVec(file), file);
     return unwrap(parseGitHubAction(jsonParse(utf8ToString(file))));
 };
+const run = (rust, nodeExtra = () => []) => {
+    const [state, result] = virtual(makeState(rust))(ci({ nodeExtra, denoExtra: [], bunExtra: [] }));
+    assert(result === 0, result);
+    return workflow(state);
+};
+const runDefault = (packageJson) => {
+    const [state, result] = virtual(makeState(false, packageJson))(main());
+    assert(result === 0, result);
+    return workflow(state);
+};
 export const proof = {
     rust: () => {
         assert(hasRun('cargo')(run(true)), 'expected Rust steps');
@@ -52,4 +61,47 @@ export const proof = {
             }
         },
     },
+    defaultSetup: {
+        functionalscriptDemo: () => {
+            const gha = runDefault('{"name":"functionalscript"}');
+            assert(hasRun('fjs compile issues/demo/data/tree.json _tree.f.js')(gha), 'expected fjs demo compile');
+            assert(hasRun('fjs t')(gha), 'expected fjs self-test');
+            assert(hasRun('deno task fjs compile issues/demo/data/tree.json _tree.f.js')(gha), 'expected deno demo compile');
+            assert(hasRun('deno task fjs t')(gha), 'expected deno self-test');
+            assert(hasRun('bun ./fs/fjs/module.ts t')(gha), 'expected bun self-test');
+        },
+        otherPackageNoDemo: () => {
+            const gha = runDefault('{"name":"other-package"}');
+            assert(!hasRun('fjs compile issues/demo/data/tree.json _tree.f.js')(gha), 'unexpected fjs demo compile');
+            assert(!hasRun('fjs t')(gha), 'unexpected fjs self-test');
+            assert(!hasRun('deno task fjs compile issues/demo/data/tree.json _tree.f.js')(gha), 'unexpected deno demo compile');
+            assert(!hasRun('deno task fjs t')(gha), 'unexpected deno self-test');
+            assert(!hasRun('bun ./fs/fjs/module.ts t')(gha), 'unexpected bun self-test');
+        },
+        uninstallPackageName: () => {
+            const gha = runDefault('{"name":"other-package"}');
+            assert(hasRun('npm uninstall other-package -g')(gha), 'expected package-specific uninstall');
+            assert(!hasRun('npm uninstall functionalscript -g')(gha), 'unexpected functionalscript uninstall');
+        },
+        malformedPackageJsonFallback: () => {
+            const gha = runDefault('{');
+            assert(!hasRun('fjs compile issues/demo/data/tree.json _tree.f.js')(gha), 'unexpected fjs demo compile');
+            assert(hasRun('npm uninstall functionalscript -g')(gha), 'expected fallback uninstall');
+        },
+        missingPackageJsonFallback: () => {
+            const gha = runDefault();
+            assert(!hasRun('fjs compile issues/demo/data/tree.json _tree.f.js')(gha), 'unexpected fjs demo compile');
+            assert(hasRun('npm uninstall functionalscript -g')(gha), 'expected fallback uninstall');
+        },
+        missingNameFallback: () => {
+            const gha = runDefault('{"version":"1.0.0"}');
+            assert(!hasRun('fjs compile issues/demo/data/tree.json _tree.f.js')(gha), 'unexpected fjs demo compile');
+            assert(hasRun('npm uninstall functionalscript -g')(gha), 'expected fallback uninstall');
+        },
+        nonObjectFallback: () => {
+            const gha = runDefault('[]');
+            assert(!hasRun('fjs compile issues/demo/data/tree.json _tree.f.js')(gha), 'unexpected fjs demo compile');
+            assert(hasRun('npm uninstall functionalscript -g')(gha), 'expected fallback uninstall');
+        },
+    },
 };

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/dev/package_json/module.f.d.ts

@@ -0,0 +1,16 @@
+import type { ValidationError } from '../../types/rtti/validate/module.f.ts';
+import type { Ts } from '../../types/rtti/ts/module.f.ts';
+import { type Result } from '../../types/result/module.f.ts';
+export declare const packageJsonSchema: {
+    readonly name: import("../../types/rtti/module.f.ts").Or<readonly [import("../../types/rtti/module.f.ts").String, undefined]>;
+    readonly version: import("../../types/rtti/module.f.ts").Or<readonly [import("../../types/rtti/module.f.ts").String, undefined]>;
+    readonly scripts: import("../../types/rtti/module.f.ts").Or<readonly [import("../../types/rtti/module.f.ts").Type1<"record", import("../../types/rtti/module.f.ts").String>, undefined]>;
+};
+export type PackageJson = Ts<typeof packageJsonSchema>;
+export type JsonTextError = string | ValidationError;
+export declare const validatePackageJson: import("../../types/rtti/common/module.f.ts").Validate<{
+    readonly name: import("../../types/rtti/module.f.ts").Or<readonly [import("../../types/rtti/module.f.ts").String, undefined]>;
+    readonly version: import("../../types/rtti/module.f.ts").Or<readonly [import("../../types/rtti/module.f.ts").String, undefined]>;
+    readonly scripts: import("../../types/rtti/module.f.ts").Or<readonly [import("../../types/rtti/module.f.ts").Type1<"record", import("../../types/rtti/module.f.ts").String>, undefined]>;
+}>;
+export declare const validatePackageJsonText: (text: string) => Result<PackageJson, JsonTextError>;

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

@@ -0,0 +1,21 @@
+import { parse as jsonParse } from "../../json/parser/module.f.js";
+import { tokenize as jsonTokenize } from "../../json/tokenizer/module.f.js";
+import { stringToList } from "../../text/utf16/module.f.js";
+import { option, record, string } from "../../types/rtti/module.f.js";
+import { validate as rttiValidate } from "../../types/rtti/validate/module.f.js";
+import { error, ok } from "../../types/result/module.f.js";
+export const packageJsonSchema = {
+    name: option(string),
+    version: option(string),
+    scripts: option(record(string)),
+};
+export const validatePackageJson = rttiValidate(packageJsonSchema);
+const parseJsonText = (text) => jsonParse(jsonTokenize(stringToList(text)));
+export const validatePackageJsonText = (text) => {
+    const [t, v] = parseJsonText(text);
+    if (t === 'error') {
+        return error(v);
+    }
+    const [t2, v2] = validatePackageJson(v);
+    return t2 === 'ok' ? ok(v2) : error(v2);
+};

package/fs/dev/package_json/proof.f.d.ts

@@ -0,0 +1,5 @@
+export declare const proof: {
+    parseMetadata: () => void;
+    malformedJson: () => void;
+    validatePreservesOriginalObject: () => void;
+};

package/fs/dev/package_json/proof.f.js

@@ -0,0 +1,23 @@
+import { assert } from "../../asserts/module.f.js";
+import { unwrap } from "../../types/result/module.f.js";
+import { validatePackageJson, validatePackageJsonText, } from "./module.f.js";
+export const proof = {
+    parseMetadata: () => {
+        const result = unwrap(validatePackageJsonText('{"name":"x","version":"1.0.0","scripts":{"test":"node test.js"}}'));
+        assert(result.name === 'x', result);
+        assert(result.version === '1.0.0', result);
+        assert(result.scripts?.test === 'node test.js', result);
+    },
+    malformedJson: () => {
+        const result = validatePackageJsonText('{');
+        assert(result[0] === 'error', result);
+    },
+    validatePreservesOriginalObject: () => {
+        const object = { name: 'x', version: '1.0.0', private: true };
+        const metadata = unwrap(validatePackageJson(object));
+        assert(metadata.name === 'x', metadata);
+        assert(metadata.version === '1.0.0', metadata);
+        assert(Object.is(metadata, object), metadata);
+        assert(object.private === true, object);
+    },
+};

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

@@ -7,21 +7,27 @@ import { utf8, utf8ToString } from "../../text/module.f.js";
 import { begin, pure } from "../../effects/module.f.js";
 import { all, readFile, writeFile } from "../../effects/node/module.f.js";
 import { unwrap } from "../../types/result/module.f.js";
-const { stringify, parse } = JSON;
+import { validatePackageJson } from "../package_json/module.f.js";
+import { assert } from "../../asserts/module.f.js";
+const { parse, stringify } = JSON;
 const jsonFile = (jsonFile) => `${jsonFile}.json`;
 const readJson = (name) => begin
     .step(() => readFile(jsonFile(name)))
-    .step(v => pure(parse(utf8ToString(unwrap(v)))));
+    .step(v => pure(unwrap(validatePackageJson(parse(utf8ToString(unwrap(v)))))));
 const writeVersion = (version) => (name) => begin
     .step(() => readJson(name))
-    .step(json => writeFile(jsonFile(name), utf8(stringify({
+    .step((json) => writeFile(jsonFile(name), utf8(stringify({
     ...json,
     version,
 }, null, 2))));
+const version = (p) => {
+    assert(p.version !== undefined, 'package.json version is missing');
+    return p.version;
+};
 export const updateVersion = begin
     .step(() => readJson('package'))
     .step(p => {
-    const w = writeVersion(p.version);
+    const w = writeVersion(version(p));
     return all(w('package'), w('deno'));
 })
     .step(() => pure(0));

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.27.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"