functionalscript 0.44.0 → 0.46.0

package/fjs/cas/types.d.ts

@@ -6,7 +6,7 @@
 import type { Vec } from '../types/bit_vec/types.ts';
 import type { Effect, Operation } from '../effects/types.ts';
 import type { List } from '../effects/list/types.ts';
-import type { IoResult, Mkdir, Now, RandomInt, ReadBytes, Readdir, Rename, Rm, CreateExclusive, WriteBytes, Access, Stat } from '../effects/node/types.ts';
+import type { Access, CreateExclusive, IoChannel, Mkdir, Now, RandomInt, ReadBytes, Readdir, Rename, Rm, Stat, WriteBytes } from '../effects/node/types.ts';
 /**
  * The filesystem effects the streaming CAS performs: `read` pulls shards
  * (`ReadBytes`); `list` walks the store (`Access`/`Readdir`); `write` runs the
@@ -17,18 +17,32 @@ import type { IoResult, Mkdir, Now, RandomInt, ReadBytes, Readdir, Rename, Rm, C
 export type FileCasOperation = ReadBytes | Mkdir | Readdir | Access | Rename | Rm | RandomInt | Now | CreateExclusive | WriteBytes | Stat | Now | Readdir | Rm;
 export type Cas<O extends Operation> = {
     /**
-     * Streams the content for `hash` out in `<=128 KiB` chunks. Every pull yields an
-     * explicit `ok(chunk)` or `error` item, so a missing shard or I/O error is a distinct
-     * error *item* in the stream, never collapsed into end-of-stream (`undefined`).
+     * Streams the content for `hash` out in `<=128 KiB` chunks.
+     *
+     * A missing shard or an I/O error **fails the stream** rather than ending
+     * it, so it can never be mistaken for end-of-stream. That distinction used
+     * to be a rule this comment had to state, with an `ok(chunk)`/`error` item
+     * union that every consumer kept apart by hand; it is now the difference
+     * between an `error` cell and an `ok(undefined)` one, which nothing can
+     * confuse.
      */
-    readonly read: (hash: Vec) => List<O, IoResult<Vec>>;
+    readonly read: (hash: Vec) => List<O, Vec, IoChannel>;
     /**
-     * Consumes a chunk stream — each item `ok(chunk)` or `error` — hashing incrementally,
-     * and returns the content address. An error item aborts the upload.
+     * Consumes a chunk stream, hashing incrementally, and returns the content
+     * address. A stream that fails aborts the upload with that failure.
      */
-    readonly write: <O1 extends Operation>(payload: List<O1, IoResult<Vec>>) => Effect<O | O1, IoResult<Vec>>;
-    /** Lists all stored content hashes. */
-    readonly list: () => Effect<O, readonly Vec[]>;
+    readonly write: <O1 extends Operation>(payload: List<O1, Vec, IoChannel>) => Effect<O | O1, Vec, IoChannel>;
+    /**
+     * Lists all stored content hashes.
+     *
+     * Fallible like its siblings: walking the store is IO, and a store that
+     * cannot be walked must be distinguishable from one that is empty. An
+     * absent store *is* empty and answers `ok([])` — that is the fresh-store
+     * case, not a failure — but a directory that exists and cannot be read is
+     * an error, and returning it is what lets a caller say so instead of
+     * reporting no content.
+     */
+    readonly list: () => Effect<O, readonly Vec[], IoChannel>;
 };
 export type FileCas = Cas<FileCasOperation> & {
     url: (v: Vec) => string;

package/fjs/ci/common/module.f.d.mts

@@ -1,4 +1,3 @@
-import type { Step, Job, MetaStep } from './types.ts';
 /**
  * Shared CI types and helpers: GitHub Actions step/job RTTI schemas, the
  * `MetaStep` representation used by tool-specific modules, and assemblers like
@@ -10,6 +9,7 @@ import type { Step, Job, MetaStep } from './types.ts';
  *
  * @import { Step, Job, MetaStep, StepType } from './types.ts'
  */
+import type { Step, Job, MetaStep } from './types.ts';
 import { actions } from '../config/module.f.mjs';
 export declare const os: readonly ['ubuntu', 'macos', 'windows'];
 export declare const architecture: readonly ['intel', 'arm'];

package/fjs/ci/common/module.f.mjs

@@ -9,6 +9,7 @@
  *
  * @import { Step, Job, MetaStep, StepType } from './types.ts'
  */
+
 import { actions, images } from '../config/module.f.mjs'
 import { option, array, record, string } from '../../types/rtti/module.f.mjs'
 import { parse as rttiParse } from '../../types/rtti/parse/module.f.mjs'

package/fjs/ci/config/module.f.d.mts

@@ -18,7 +18,7 @@ export declare const images: {
         readonly arm: 'windows-11-arm';
     };
 };
-export declare const functionalscript = /** @type {const} */ "0.43.1";
+export declare const functionalscript = /** @type {const} */ "0.45.0";
 export declare const bun = "1.3.14";
 export declare const deno = "2.9.5";
 export declare const node: {
@@ -28,7 +28,7 @@ export declare const node: {
 };
 export declare const nixpkgs: {
     readonly ref: 'nixos-26.05';
-    readonly commit: '9f78f44a87948854445dae0b6bf82b2e87e4efb5';
+    readonly commit: '02e08985a27c65ffd33d434eeb2e660a2e4dc84d';
 };
 export declare const wasmtime = "47.0.3";
 export declare const wasmer = "7.2.1";
@@ -40,6 +40,6 @@ export declare const actions: {
     readonly 'oven-sh/setup-bun': 'v2.2.0';
     readonly 'bytecodealliance/actions/wasmtime/setup': 'v1.1.3';
     readonly 'wasmerio/setup-wasmer': 'v3.1';
-    readonly 'cachix/install-nix-action': 'v31.11.0';
+    readonly 'cachix/install-nix-action': 'v31.11.1';
     readonly 'dtolnay/rust-toolchain': '1.97.1';
 };

package/fjs/ci/config/module.f.mjs

@@ -25,7 +25,7 @@ export const images = /** @type {const} */({
 // published FunctionalScript release; do not tie it to package.json's current
 // in-repo version.
 // https://www.npmjs.com/package/functionalscript
-export const functionalscript = /** @type {const} */ '0.43.1'
+export const functionalscript = /** @type {const} */ '0.45.0'
 
 // https://bun.sh/
 export const bun = '1.3.14'
@@ -53,7 +53,7 @@ export const node = /** @type {const} */({
 // https://channels.nixos.org/nixos-26.05/git-revision
 export const nixpkgs = /** @type {const} */({
     ref: 'nixos-26.05',
-    commit: '9f78f44a87948854445dae0b6bf82b2e87e4efb5',
+    commit: '02e08985a27c65ffd33d434eeb2e660a2e4dc84d',
 })
 
 // https://github.com/bytecodealliance/wasmtime/releases
@@ -83,7 +83,7 @@ export const actions = /** @type {const} */({
     'wasmerio/setup-wasmer': 'v3.1',
     // https://github.com/marketplace/actions/install-nix
     // Enables the `nix-command` and `flakes` experimental features by default.
-    'cachix/install-nix-action': 'v31.11.0',
+    'cachix/install-nix-action': 'v31.11.1',
     // https://rust-lang.org/ - value is Rust version, not action version
     'dtolnay/rust-toolchain': '1.97.1',
 })

package/fjs/ci/module.f.d.mts

@@ -5,15 +5,15 @@
  *
  * @module
  *
- * @import { Effect } from '../effects/types.ts'
  * @import { NodeOp } from '../effects/node/types.ts'
  * @import { Architecture, GitHubAction, Job, Jobs, MetaStep, Os } from './common/types.ts'
  * @import { NixJob } from './nix/types.ts'
  * @import { Setup } from './types.ts'
+ * @import { Effect } from '../effects/types.ts'
  */
-import type { Effect } from '../effects/types.ts';
 import type { NodeOp } from '../effects/node/types.ts';
 import type { Setup } from './types.ts';
-/** @type {(setup: Setup) => Effect<NodeOp, number>} */
-export declare const ci: (setup: Setup) => Effect<NodeOp, number>;
-export declare const main: () => Effect<NodeOp, number>;
+import type { Effect } from '../effects/types.ts';
+/** @type {(setup: Setup) => Effect<NodeOp, 0, number>} */
+export declare const ci: (setup: Setup) => Effect<NodeOp, 0, number>;
+export declare const main: () => Effect<NodeOp, 0, number>;

package/fjs/ci/module.f.mjs

@@ -5,15 +5,16 @@
  *
  * @module
  *
- * @import { Effect } from '../effects/types.ts'
  * @import { NodeOp } from '../effects/node/types.ts'
  * @import { Architecture, GitHubAction, Job, Jobs, MetaStep, Os } from './common/types.ts'
  * @import { NixJob } from './nix/types.ts'
  * @import { Setup } from './types.ts'
+ * @import { Effect } from '../effects/types.ts'
  */
 
-import { mapStep, step } from '../effects/module.f.mjs'
-import { access, writeUtf8File } from '../effects/node/module.f.mjs'
+import { resultStep } from '../effects/module.f.mjs'
+import { access, exitStep, writeUtf8File } from '../effects/node/module.f.mjs'
+import { step as ioStep } from '../effects/module.f.mjs'
 import { functionalscript, images } from './config/module.f.mjs'
 import {
     architecture,
@@ -57,8 +58,8 @@ const canonicalJobs = rust => ({
     'nix-flakes': nixFlakeJob,
 })
 
-/** @type {(setup: Setup) => Effect<NodeOp, number>} */
-export const ci = ({ nodeExtra }) => step(
+/** @type {(setup: Setup) => Effect<NodeOp, 0, number>} */
+export const ci = ({ nodeExtra }) => resultStep(
     access('Cargo.toml'),
     result => {
         const rust = result[0] === 'ok'
@@ -82,8 +83,8 @@ export const ci = ({ nodeExtra }) => step(
         const workflowWritten = writeUtf8File(
             '.github/workflows/ci.yml',
             JSON.stringify(gha, null, '  '))
-        const flakesWritten = step(workflowWritten, () => nixFlakes(nixJobs))
-        return mapStep(flakesWritten, () => 0)
+        const flakesWritten = ioStep(workflowWritten, () => nixFlakes(nixJobs))
+        return exitStep(flakesWritten)
     })
 
 export const main = () => ci({ nodeExtra: () => [] })

package/fjs/ci/nix/module.f.d.mts

@@ -11,14 +11,14 @@
  *
  * @module
  *
+ * @import { IoChannel, Mkdir, WriteFile } from '../../effects/node/types.ts'
  * @import { Effect } from '../../effects/types.ts'
- * @import { Mkdir, WriteFile } from '../../effects/node/types.ts'
  * @import { Expression } from '../../media/nix/types.ts'
  * @import { MetaStep } from '../common/types.ts'
  * @import { NixJob } from './types.ts'
  */
+import type { IoChannel, Mkdir, WriteFile } from '../../effects/node/types.ts';
 import type { Effect } from '../../effects/types.ts';
-import type { Mkdir, WriteFile } from '../../effects/node/types.ts';
 import type { MetaStep } from '../common/types.ts';
 import type { NixJob } from './types.ts';
 /** Directory owned by this generator. */
@@ -35,16 +35,18 @@ export declare const generatedDirectory: 'nix/generated';
  */
 export declare const flakeText: (job: NixJob) => string;
 /**
- * Writes one generated flake per job.
+ * Writes one generated flake per job, stopping at the first failure.
  *
- * @type {(jobs: readonly NixJob[]) => Effect<Mkdir | WriteFile, void>}
+ * @type {(jobs: readonly NixJob[]) => Effect<Mkdir | WriteFile, void, IoChannel>}
  */
-export declare const nixFlakes: (jobs: readonly NixJob[]) => Effect<Mkdir | WriteFile, void>;
+export declare const nixFlakes: (jobs: readonly NixJob[]) => Effect<Mkdir | WriteFile, void, IoChannel>;
 /** Path a workflow passes to `nix develop`, for the job of the given id. */
+/** @type {(id: string) => string} */
 export declare const flakePath: (id: string) => string;
 /** Installs Nix, with `nix-command` and `flakes` enabled by the action's defaults. */
 export declare const nixInstall: MetaStep;
 /** Runs one command inside a job's generated development shell. */
+/** @type {(id: string, command: string) => string} */
 export declare const nixDevelop: (id: string, command: string) => string;
 /**
  * Runs a migrated job's whole command sequence in one development shell, so the

package/fjs/ci/nix/module.f.mjs

@@ -11,15 +11,16 @@
  *
  * @module
  *
+ * @import { IoChannel, Mkdir, WriteFile } from '../../effects/node/types.ts'
  * @import { Effect } from '../../effects/types.ts'
- * @import { Mkdir, WriteFile } from '../../effects/node/types.ts'
  * @import { Expression } from '../../media/nix/types.ts'
  * @import { MetaStep } from '../common/types.ts'
  * @import { NixJob } from './types.ts'
  */
 
-import { forEachStep, mapStep, pure, step } from '../../effects/module.f.mjs'
+import { pureOk } from '../../effects/module.f.mjs'
 import { mkdir, writeUtf8File } from '../../effects/node/module.f.mjs'
+import { forEachStep, step } from '../../effects/module.f.mjs'
 import { nixToString } from '../../media/nix/module.f.mjs'
 import { fromUndefined, unwrap as unwrapNullable } from '../../types/nullable/module.f.mjs'
 import { unwrap } from '../../types/result/module.f.mjs'
@@ -72,33 +73,33 @@ const flake = ({ system, packages, shellHook }) => ['set',
 export const flakeText = job =>
     unwrapNullable(fromUndefined(nixToString(flake(job))))
 
-/** @type {(job: NixJob) => Effect<Mkdir | WriteFile, void>} */
+/** @type {(job: NixJob) => Effect<Mkdir | WriteFile, void, IoChannel>} */
 const writeFlake = job => {
     const directory = `${generatedDirectory}/${job.id}`
-    const created = mapStep(mkdir(directory, { recursive: true }), unwrap)
-    const written = step(
+    const created = mkdir(directory, { recursive: true })
+    return step(
         created,
         () => writeUtf8File(`${directory}/flake.nix`, flakeText(job)))
-    return mapStep(written, unwrap)
 }
 
 /**
- * Writes one generated flake per job.
+ * Writes one generated flake per job, stopping at the first failure.
  *
- * @type {(jobs: readonly NixJob[]) => Effect<Mkdir | WriteFile, void>}
+ * @type {(jobs: readonly NixJob[]) => Effect<Mkdir | WriteFile, void, IoChannel>}
  */
 export const nixFlakes = jobs =>
-    forEachStep(pure(jobs), writeFlake)
+    forEachStep(pureOk(jobs), writeFlake)
 
 /** Path a workflow passes to `nix develop`, for the job of the given id. */
-export const flakePath = /** @type {(id: string) => string} */ (id => `./${generatedDirectory}/${id}`)
+/** @type {(id: string) => string} */
+export const flakePath = id => `./${generatedDirectory}/${id}`
 
 /** Installs Nix, with `nix-command` and `flakes` enabled by the action's defaults. */
 export const nixInstall = install(uses('cachix/install-nix-action'))
 
 /** Runs one command inside a job's generated development shell. */
-export const nixDevelop = /** @type {(id: string, command: string) => string} */
-    ((id, command) => `nix develop ${flakePath(id)} --command ${command}`)
+/** @type {(id: string, command: string) => string} */
+export const nixDevelop = (id, command) => `nix develop ${flakePath(id)} --command ${command}`
 
 /**
  * Wraps a string so a POSIX shell reproduces it exactly. Single quotes protect

package/fjs/ci/nix/proof.f.d.mts

@@ -2,6 +2,8 @@
  * Proofs for generated CI flakes.
  *
  * @module
+ *
+ * @import { NixJob } from './types.ts'
  */
 export declare const proof: {
     flakeText: {

package/fjs/ci/nix/proof.f.mjs

@@ -2,12 +2,12 @@
  * Proofs for generated CI flakes.
  *
  * @module
+ *
+ * @import { NixJob } from './types.ts'
  */
 
-/** @import { NixJob } from './types.ts' */
-
 import { assert, assertEq } from '../../asserts/module.f.mjs'
-import { step } from '../../effects/module.f.mjs'
+import { step as ioStep } from '../../effects/module.f.mjs'
 import { readUtf8File } from '../../effects/node/module.f.mjs'
 import { emptyState, virtual } from '../../effects/node/virtual/module.f.mjs'
 import { nixpkgs } from '../config/module.f.mjs'
@@ -74,7 +74,7 @@ const shellHookFlake = `{
 
 /** @type {(jobs: readonly NixJob[], id: string) => string} */
 const generated = (jobs, id) => {
-    const written = step(
+    const written = ioStep(
         nixFlakes(jobs),
         () => readUtf8File(`${generatedDirectory}/${id}/flake.nix`))
     const [, [tag, result]] = virtual(emptyState)(written)

package/fjs/ci/proof.f.d.mts

@@ -1,5 +1,7 @@
-/** @import { MetaStep, Os, GitHubAction } from './common/types.ts' */
-/** @import { Dir, State } from '../effects/node/virtual/types.ts' */
+/**
+ * @import { MetaStep, Os, GitHubAction } from './common/types.ts'
+ * @import { Dir, State } from '../effects/node/virtual/types.ts'
+ */
 export declare const proof: {
     matrixShape: () => void;
     rust: () => void;

package/fjs/ci/proof.f.mjs

@@ -1,6 +1,9 @@
-/** @import { MetaStep, Os, GitHubAction } from './common/types.ts' */
-/** @import { Dir, State } from '../effects/node/virtual/types.ts' */
+/**
+ * @import { MetaStep, Os, GitHubAction } from './common/types.ts'
+ * @import { Dir, State } from '../effects/node/virtual/types.ts'
+ */
 
+import { exitCode } from '../effects/node/module.f.mjs'
 import { ci, main } from './module.f.mjs'
 import { functionalscript, node } from './config/module.f.mjs'
 import { nodeNixJobs } from './node/module.f.mjs'
@@ -11,7 +14,6 @@ import { assert, assertEq } from '../asserts/module.f.mjs'
 import { emptyState, virtual } from '../effects/node/virtual/module.f.mjs'
 import { unwrap } from '../types/result/module.f.mjs'
 import { definedValues } from '../types/object/module.f.mjs'
-
 import { parse as jsonParse } from '../media/json/module.f.mjs'
 
 /** @type {(cmd: string) => (gha: GitHubAction) => boolean} */
@@ -38,8 +40,11 @@ const makeState = (/** @type {boolean} */ rust, /** @type {string | undefined} *
 /** @type {(dir: Dir, name: string) => Dir} */
 const subDir = (dir, name) => {
     const entity = dir[name]
-    assert(typeof entity === 'object' && !Array.isArray(entity), entity)
-    return /** @type {Dir} */ (entity)
+    // `Array.isArray` narrows to `any[]`, which `readonly Vec[]` is not assignable
+    // to, so its negative branch never removes a `readonly` array from a union.
+    // `instanceof Array` does, so this `assert` narrows `entity` to `Dir`.
+    assert(typeof entity === 'object' && !(entity instanceof Array), entity)
+    return entity
 }
 
 /** @type {(dir: Dir, name: string) => string} */
@@ -65,14 +70,14 @@ const flake = (state, id) =>
 /** @type {(rust: boolean, nodeExtra?: (o: Os) => readonly MetaStep[]) => GitHubAction} */
 const run = (rust, nodeExtra = () => []) => {
     const [state, result] = virtual(makeState(rust, undefined))(ci({ nodeExtra }))
-    assertEq(result, 0)
+    assertEq(exitCode(result), 0)
     return workflow(state)
 }
 
 /** @type {(packageJson?: string) => GitHubAction} */
 const runDefault = packageJson => {
     const [state, result] = virtual(makeState(false, packageJson))(main())
-    assertEq(result, 0)
+    assertEq(exitCode(result), 0)
     return workflow(state)
 }
 
@@ -174,7 +179,7 @@ export const proof = {
     },
     nixFlakes: () => {
         const [state, result] = virtual(makeState(false, undefined))(main())
-        assertEq(result, 0)
+        assertEq(exitCode(result), 0)
         for (const { id, packages } of nodeNixJobs) {
             const [nodePackage] = packages
             assert(

package/fjs/cli/module.f.d.mts

@@ -5,12 +5,10 @@
  *
  * @module
  *
- * @import { NodeOp, NodeProgramOptions, Write } from '../effects/node/types.ts'
- * @import { Effect } from '../effects/types.ts'
+ * @import { NodeOp, Program, Write } from '../effects/node/types.ts'
  * @import { Commands } from './types.ts'
  */
-import type { NodeOp, NodeProgramOptions, Write } from '../effects/node/types.ts';
-import type { Effect } from '../effects/types.ts';
+import type { NodeOp, Program, Write } from '../effects/node/types.ts';
 import type { Commands } from './types.ts';
-/** @type {<O extends NodeOp>(commands: Commands<O>) => (options: NodeProgramOptions) => Effect<O | Write, number>} */
-export declare const dispatch: <O extends NodeOp>(commands: Commands<O>) => (options: NodeProgramOptions) => Effect<O | Write, number>;
+/** @type {<O extends NodeOp>(commands: Commands<O>) => Program<O | Write>} */
+export declare const dispatch: <O extends NodeOp>(commands: Commands<O>) => Program<O | Write>;

package/fjs/cli/module.f.mjs

@@ -5,18 +5,16 @@
  *
  * @module
  *
- * @import { NodeOp, NodeProgramOptions, Write } from '../effects/node/types.ts'
- * @import { Effect } from '../effects/types.ts'
+ * @import { NodeOp, Program, Write } from '../effects/node/types.ts'
  * @import { Commands } from './types.ts'
  */
 
-import { errorExit, log } from '../effects/node/module.f.mjs'
-import { pure, step } from '../effects/module.f.mjs'
+import { errorExit, exitStep, log } from '../effects/node/module.f.mjs'
 import { at, fromEntries } from '../types/object/module.f.mjs'
 
 const helpMeta = { names: ['help', 'h', '?'], description: 'Print this help message' }
 
-/** @type {<O extends NodeOp>(commands: Commands<O>) => (options: NodeProgramOptions) => Effect<O | Write, number>} */
+/** @type {<O extends NodeOp>(commands: Commands<O>) => Program<O | Write>} */
 export const dispatch = commands => options => {
     const [cmd, ...rest] = options.args
     const rows = [...commands, helpMeta]
@@ -38,9 +36,7 @@ export const dispatch = commands => options => {
                 return dispatch(targetCmd.handler)({ ...options, args: ['help'] })
             }
         }
-        return step(
-            log(helpText),
-            () => pure(0))
+        return exitStep(log(helpText))
     }
     const found = at(cmd)(map)
     if (found === null) {

package/fjs/cli/proof.f.d.mts

@@ -1,5 +1,7 @@
-/** @import { NodeOp, NodeProgramOptions } from '../effects/node/types.ts' */
-/** @import { Commands } from './types.ts' */
+/**
+ * @import { NodeOp, NodeProgramOptions } from '../effects/node/types.ts'
+ * @import { Commands } from './types.ts'
+ */
 export declare const proof: {
     knownCommand: () => void;
     alias: () => void;

package/fjs/cli/proof.f.mjs

@@ -1,7 +1,10 @@
-/** @import { NodeOp, NodeProgramOptions } from '../effects/node/types.ts' */
-/** @import { Commands } from './types.ts' */
+/**
+ * @import { NodeOp, NodeProgramOptions } from '../effects/node/types.ts'
+ * @import { Commands } from './types.ts'
+ */
 
-import { pure } from '../effects/module.f.mjs'
+import { exitCode } from '../effects/node/module.f.mjs'
+import { pureError, pureOk } from '../effects/module.f.mjs'
 import { defaultNodeProgramOptions, emptyState, virtual } from '../effects/node/virtual/module.f.mjs'
 import { dispatch } from './module.f.mjs'
 import { assert, assertEq } from '../asserts/module.f.mjs'
@@ -15,7 +18,7 @@ const echoCommands = [
     {
         names: ['echo', 'e'],
         description: 'Print the first argument',
-        handler: ({ args: [arg = ''] }) => pure(arg.length),
+        handler: ({ args: [arg = ''] }) => arg.length === 0 ? pureOk(0) : pureError(arg.length),
     },
 ]
 
@@ -25,25 +28,25 @@ const run = (/** @type {Commands<NodeOp>} */ commands) => (/** @type {readonly s
 export const proof = {
     knownCommand: () => {
         const [, code] = run(echoCommands)(['echo', 'hello'])
-        assertEq(code, 5, ['expected length 5', code])
+        assertEq(exitCode(code), 5, ['expected length 5', code])
     },
     alias: () => {
         const [, code] = run(echoCommands)(['e', 'hi'])
-        assertEq(code, 2, ['expected length 2', code])
+        assertEq(exitCode(code), 2, ['expected length 2', code])
     },
     noArgs: () => {
         const [state, code] = run(echoCommands)([])
-        assertEq(code, 1, ['expected exit 1', code])
+        assertEq(exitCode(code), 1, ['expected exit 1', code])
         assert(state.stderr.length !== 0, 'expected error in stderr')
     },
     unknownCommand: () => {
         const [state, code] = run(echoCommands)(['bogus'])
-        assertEq(code, 1, ['expected exit 1', code])
+        assertEq(exitCode(code), 1, ['expected exit 1', code])
         assert(state.stderr.length !== 0, 'expected error in stderr')
     },
     help: () => {
         const [state, code] = run(echoCommands)(['help'])
-        assertEq(code, 0, ['expected exit 0', code])
+        assertEq(exitCode(code), 0, ['expected exit 0', code])
         assert(state.stdout.includes('echo'), 'expected command name in stdout')
         assert(state.stdout.includes('help'), 'expected help entry in stdout')
     },
@@ -60,7 +63,7 @@ export const proof = {
             description: 'Capture args',
             handler: (/** @type {{ args: readonly string[] }} */ { args }) => {
                 captured.push(...args)
-                return pure(0)
+                return pureOk(0)
             },
         }]
         run(commands)(['grab', 'a', 'b', 'c'])
@@ -71,7 +74,7 @@ export const proof = {
         const inner = [{
             names: ['ping'],
             description: 'Inner ping',
-            handler: () => pure(42),
+            handler: () => pureError(42),
         }]
         /** @type {Commands<NodeOp>} */
         const outer = [{
@@ -80,14 +83,14 @@ export const proof = {
             handler: inner,
         }]
         const [, code] = run(outer)(['sub', 'ping'])
-        assertEq(code, 42, ['expected 42', code])
+        assertEq(exitCode(code), 42, ['expected 42', code])
     },
     nestedHelp: () => {
         /** @type {Commands<NodeOp>} */
         const inner = [{
             names: ['ping'],
             description: 'Inner ping',
-            handler: () => pure(0),
+            handler: () => pureOk(0),
         }]
         /** @type {Commands<NodeOp>} */
         const outer = [{
@@ -96,17 +99,17 @@ export const proof = {
             handler: inner,
         }]
         const [state, code] = run(outer)(['sub', 'help'])
-        assertEq(code, 0, ['expected exit 0', code])
+        assertEq(exitCode(code), 0, ['expected exit 0', code])
         assert(state.stdout.includes('ping'), 'expected inner command in help')
     },
     prototypeNameIsUnknownCommand: () => {
         const [state, code] = run(echoCommands)(['toString'])
-        assertEq(code, 1, ['expected exit 1 for prototype-name command', code])
+        assertEq(exitCode(code), 1, ['expected exit 1 for prototype-name command', code])
         assert(state.stderr.includes('unknown command'), 'expected unknown-command error in stderr')
     },
     helpPrototypeSafe: () => {
         const [state, code] = run(echoCommands)(['help', 'toString'])
-        assertEq(code, 0, ['expected exit 0, not a throw', code])
+        assertEq(exitCode(code), 0, ['expected exit 0, not a throw', code])
         assert(state.stdout.includes('echo'), 'expected top-level help for unknown target')
     },
     helpWithTarget: () => {
@@ -114,7 +117,7 @@ export const proof = {
         const inner = [{
             names: ['ping'],
             description: 'Inner ping',
-            handler: () => pure(0),
+            handler: () => pureOk(0),
         }]
         /** @type {Commands<NodeOp>} */
         const outer = [{
@@ -123,7 +126,7 @@ export const proof = {
             handler: inner,
         }]
         const [state, code] = run(outer)(['help', 'sub'])
-        assertEq(code, 0, ['expected exit 0', code])
+        assertEq(exitCode(code), 0, ['expected exit 0', code])
         assert(state.stdout.includes('ping'), 'expected inner command in help')
         assert(!(state.stdout.includes('Subcommand group')), 'expected inner help, not outer')
     },

package/fjs/cli/types.d.ts

@@ -3,9 +3,8 @@
  *
  * @module
  */
-import type { NodeOp, NodeProgramOptions } from '../effects/node/types.ts';
-import type { Effect } from '../effects/types.ts';
-type Handler<O extends NodeOp> = (options: NodeProgramOptions) => Effect<O, number>;
+import type { NodeOp, Program } from '../effects/node/types.ts';
+type Handler<O extends NodeOp> = Program<O>;
 export type Command<O extends NodeOp> = {
     readonly names: readonly string[];
     readonly description: string;