functionalscript 0.43.1 → 0.44.0

package/fjs/cas/proof.f.mjs

@@ -0,0 +1,371 @@
+/**
+ * @import { Vec } from '../types/bit_vec/types.ts'
+ * @import { FileCasOperation } from './types.ts'
+ * @import { Effect } from '../effects/types.ts'
+ * @import { ReadFile, WriteFile, Rm, Mkdir, IoResult } from '../effects/node/types.ts'
+ * @import { Ok } from '../types/result/types.ts'
+ * @import { List } from '../effects/list/types.ts'
+ */
+
+import { length, maxLength, msb, vec, vec8 } from '../types/bit_vec/module.f.mjs'
+import { cBase32ToVec, vecToCBase32 } from '../basen/cbase32/module.f.mjs'
+import { computeSync, sha256 } from '../crypto/sha2/module.f.mjs'
+import { fileCas, casAddFile, collectRead, casUpload } from './module.f.mjs'
+import { match, pure, runPure, step } from '../effects/module.f.mjs'
+import { mkdir, writeFile, rm, readFile, access } from '../effects/node/module.f.mjs'
+import { error, ok } from '../types/result/module.f.mjs'
+import { emptyState, virtual } from '../effects/node/virtual/module.f.mjs'
+import { join } from '../path/module.f.mjs'
+import { nonEmpty, empty } from '../effects/list/module.f.mjs'
+import { assert, assertEq, assertNotNullish } from '../asserts/module.f.mjs'
+
+const testDir = './test-cas-cli'
+
+/** @typedef {FileCasOperation | WriteFile | ReadFile | Rm | Mkdir} _TestOp */
+
+// Names the command a `FileCasOperation` effect stops at, so a proof can assert
+// on it and resume the continuation without reading the `Do` layout. The map
+// has to list every operation the CAS can perform — that is what makes it total,
+// and what makes a new operation a compile error here rather than a silent gap.
+const casCommand = match({
+    access: () => 'access',
+    createExclusive: () => 'createExclusive',
+    mkdir: () => 'mkdir',
+    now: () => 'now',
+    randomInt: () => 'randomInt',
+    readBytes: () => 'readBytes',
+    readdir: () => 'readdir',
+    rename: () => 'rename',
+    rm: () => 'rm',
+    stat: () => 'stat',
+    writeBytes: () => 'writeBytes',
+})
+
+// Create a 128 KiB big file content (at the max Vec size limit)
+// This tests the boundary where files are at the chunk size limit
+/** @type {() => Vec} */
+const createBigFileContent = () => {
+    const byteCount = 128n * 1024n // 128 KiB
+    // Create a repeating pattern: 0x42 repeated across the file
+    return vec(byteCount * 8n)(0x42424242n)
+}
+
+// Test adding a big file and verifying the hash
+/** @type {() => Effect<_TestOp, void>} */
+const testAddBigFile = () => {
+    const bigFilePath = `${testDir}/big-file.bin`
+    const cas = fileCas(sha256)(testDir)
+    const x0 = step(
+        mkdir(testDir, { recursive: true }),
+        () => writeFile(bigFilePath, createBigFileContent())
+    )
+    const x1 = step(
+        x0,
+        writeRes => {
+            assert(writeRes[0] === 'ok', ['failed to write test file', writeRes])
+            return casAddFile(cas)(bigFilePath)
+        }
+    )
+    const x2 = step(
+        x1,
+        addRes => {
+            assert(addRes[0] === 'ok', ['failed to add file to CAS', addRes])
+            const hash = addRes[1]
+            // Verify hash is 256 bits (SHA-256)
+            assertEq(length(hash), 256n, ['expected 256-bit hash', length(hash)])
+            // Verify hash can be encoded/decoded
+            assertNotNullish(cBase32ToVec(vecToCBase32(hash)), 'failed to decode hash from cBase32')
+            return rm(testDir)
+        })
+    return step(
+        x2,
+        () => pure(undefined)
+    )
+}
+
+// Test adding and retrieving a big file
+/** @type {() => Effect<_TestOp, void>} */
+const testAddAndGetBigFile = () => {
+    const bigContent = createBigFileContent()
+    const bigFilePath = `${testDir}/big-file.bin`
+    const cas = fileCas(sha256)(testDir)
+    const x0 = step(
+        mkdir(testDir, { recursive: true }),
+        () => writeFile(bigFilePath, bigContent)
+    )
+    const x1 = step(
+        x0,
+        writeRes => {
+            assert(writeRes[0] === 'ok', ['failed to write test file', writeRes])
+            return casAddFile(cas)(bigFilePath)
+        }
+    )
+    // Verify the file is stored at the expected location
+    const x2 = step(
+        x1,
+        addRes => {
+            assert(addRes[0] === 'ok', ['failed to add file to CAS', addRes])
+            return readFile(cas.url(addRes[1]))
+        }
+    )
+    const x3 = step(
+        x2,
+        readRes => {
+            assert(readRes[0] === 'ok', ['failed to read stored file', readRes])
+            // Verify content is the same size as original
+            assertEq(length(readRes[1]), length(bigContent), 'stored content size mismatch')
+            return rm(testDir)
+        })
+    return step(
+        x3,
+        () => pure(undefined)
+    )
+}
+
+export const proof = {
+    // Both effects must be interpreted, not merely built: an `Effect` is inert
+    // data, so returning one from a proof runs none of its continuations and
+    // asserts nothing.
+    addBigFile: () => { virtual(emptyState)(testAddBigFile()) },
+    addAndGetBigFile: () => { virtual(emptyState)(testAddAndGetBigFile()) },
+    //
+    casWriteRead: () => {
+        // Round-trip a single-chunk payload through the real streaming CAS: `write` returns
+        // the content hash, and `read` streams the same bytes back as `ok` chunk items.
+        const content = vec8(0x2An)
+        const c = fileCas(sha256)('.')
+        /** @type {List<FileCasOperation, IoResult<Vec>>} */
+        const payload = nonEmpty(ok(content), empty())
+        const [state1, writeResult] = virtual(emptyState)(c.write(payload))
+        assert(writeResult[0] === 'ok', ['expected write ok', writeResult])
+        const hash = writeResult[1]
+        assertEq(length(hash), 256n, ['expected 256-bit hash', length(hash)])
+        assertEq(msb.cmp(hash)(computeSync(sha256)([content])), 0, 'write hash mismatch')
+        /** @type {(acc: readonly Vec[]) => (stream: List<FileCasOperation, IoResult<Vec>>) => Effect<FileCasOperation, IoResult<readonly Vec[]>>} */
+        const drain = acc =>
+            stream =>
+                step(
+                    stream,
+                    (node) => {
+                        if (node === undefined) { return pure(ok(acc)) }
+                        const { first, tail } = node
+                        if (first[0] === 'error') { return pure(first) }
+                        return drain([...acc, first[1]])(tail)
+                    },
+                )
+        const [, readResult] = virtual(state1)(drain([])(c.read(hash)))
+        assert(readResult[0] === 'ok', ['expected read ok', readResult])
+        assertEq(msb.cmp(msb.listToVec(readResult[1]))(content), 0, 'read content mismatch')
+    },
+    casReadMissingShard: () => {
+        // A missing shard surfaces as an explicit error *item*, never as end-of-stream.
+        const c = fileCas(sha256)('.')
+        const hash = computeSync(sha256)([vec8(0x2An)])
+        const node = virtual(emptyState)(c.read(hash))[1]
+        assert(node !== undefined, 'missing shard must not be EOF')
+        assert(node.first[0] === 'error', ['expected error item', node.tail])
+    },
+    casWriteMultiChunk: () => {
+        // A multi-chunk payload streams through `writeBytes` chunk-by-chunk (the lease is
+        // renewed between chunks); the hash equals the SHA-256 of the concatenated bytes,
+        // and read streams the same content back.
+        const chunks = /** @type {const} */ ([vec8(0x11n), vec8(0x22n), vec8(0x33n)])
+        const c = fileCas(sha256)('.')
+        /** @type {List<FileCasOperation, IoResult<Vec>>} */
+        const payload = chunks.reduceRight(
+            (tail, chunk) => nonEmpty(ok(chunk), tail),
+            /** @type {List<FileCasOperation, IoResult<Vec>>} */ (empty()))
+        const [state1, writeResult] = virtual(emptyState)(c.write(payload))
+        assert(writeResult[0] === 'ok', ['expected write ok', writeResult])
+        const hash = writeResult[1]
+        assertEq(msb.cmp(hash)(computeSync(sha256)(chunks)), 0, 'multi-chunk write hash mismatch')
+        /** @type {(acc: readonly Vec[]) => (stream: List<FileCasOperation, IoResult<Vec>>) => Effect<FileCasOperation, IoResult<readonly Vec[]>>} */
+        const drain = acc =>
+            stream =>
+                step(
+                    stream,
+                    (node) => {
+                        if (node === undefined) { return pure(ok(acc)) }
+                        const { first, tail } = node
+                        if (first[0] === 'error') { return pure(first) }
+                        return drain([...acc, first[1]])(tail)
+                    },
+                )
+        const [, readResult] = virtual(state1)(drain([])(c.read(hash)))
+        assert(readResult[0] === 'ok', ['expected read ok', readResult])
+        const expected = msb.concat(msb.concat(chunks[0])(chunks[1]))(chunks[2])
+        assertEq(msb.cmp(msb.listToVec(readResult[1]))(expected), 0, 'multi-chunk read content mismatch')
+    },
+    casWriteDedup: () => {
+        // Same content ⇒ same hash; the second upload's replace-`rename` publishes over the
+        // first, leaving exactly one shard in the store.
+        const content = vec8(0x2An)
+        const c = fileCas(sha256)('.')
+        /** @type {() => List<FileCasOperation, IoResult<Vec>>} */
+        const payload = () => nonEmpty(ok(content), empty())
+        const [state1, w1] = virtual(emptyState)(c.write(payload()))
+        const [state2, w2] = virtual(state1)(c.write(payload()))
+        assert(!(w1[0] !== 'ok' || w2[0] !== 'ok'), ['expected both writes ok', w1, w2])
+        assertEq(msb.cmp(w1[1])(w2[1]), 0, 'dedup hash mismatch')
+        const [, hashes] = virtual(state2)(c.list())
+        assertEq(hashes.length, 1, ['expected one shard after dedup', hashes.length])
+    },
+    casWriteErrorItemAborts: () => {
+        // An error item mid-stream deletes the partial staging file and fails; nothing is
+        // published, so the store stays empty.
+        const c = fileCas(sha256)('.')
+        /** @type {IoResult<Vec>} */
+        const okItem = ok(vec8(0x11n))
+        /** @type {IoResult<Vec>} */
+        const errItem = error({ code: 'BOOM' })
+        /** @type {List<FileCasOperation, IoResult<Vec>>} */
+        const payload = nonEmpty(okItem, nonEmpty(errItem, /** @type {List<FileCasOperation, IoResult<Vec>>} */ (empty())))
+        const [state1, result] = virtual(emptyState)(c.write(payload))
+        assert(result[0] === 'error', ['expected write error', result])
+        const [, hashes] = virtual(state1)(c.list())
+        assertEq(hashes.length, 0, ['expected nothing published on abort', hashes])
+    },
+    casWriteReadExceedsMaxLength: () => {
+        // The point of streaming: a payload larger than a single `Vec`'s `maxLength`
+        // (128 KiB) must round-trip. `write` lands the chunks on disk without ever
+        // holding them as one `Vec`, and `read` streams them back the same way — so the
+        // round-trip is verified by hashing the read stream incrementally rather than
+        // concatenating it (which would itself overflow `maxLength`).
+        const big = vec(maxLength)(0xABn)   // one full-size chunk: exactly maxLength bits
+        const tail = vec8(0x2An)            // one more byte ⇒ total > maxLength
+        const chunks = /** @type {const} */ ([big, tail])
+        const c = fileCas(sha256)('.')
+        /** @type {List<FileCasOperation, IoResult<Vec>>} */
+        const payload = chunks.reduceRight(
+            (tl, chunk) => nonEmpty(ok(chunk), tl),
+            /** @type {List<FileCasOperation, IoResult<Vec>>} */ (empty()))
+        const [state1, w] = virtual(emptyState)(c.write(payload))
+        assert(w[0] === 'ok', ['expected write ok', w])
+        const hash = w[1]
+        assertEq(msb.cmp(hash)(computeSync(sha256)(chunks)), 0, 'oversized write hash mismatch')
+        // Fold the read stream straight into a fresh SHA-2 state — never one `Vec`.
+        /** @type {(state: typeof sha256.init) => (stream: List<FileCasOperation, IoResult<Vec>>) => Effect<FileCasOperation, IoResult<Vec>>} */
+        const rehash = state =>
+            stream =>
+                step(
+                    stream,
+                    (node) => {
+                        if (node === undefined) { return pure(ok(sha256.end(state))) }
+                        const { first, tail } = node
+                        if (first[0] === 'error') { return pure(first) }
+                        return rehash(sha256.append(first[1])(state))(tail)
+                    }
+                )
+        const [, readBack] = virtual(state1)(rehash(sha256.init)(c.read(hash)))
+        assert(readBack[0] === 'ok', ['expected read ok', readBack])
+        assertEq(msb.cmp(readBack[1])(hash), 0, 'oversized read-back hash mismatch')
+    },
+    casWriteGcReclaimsExpired: () => {
+        // A staging file whose deadline is in the past is reclaimed by the GC that `write`
+        // runs before staging its own file.
+        const stalePath = join('.', '.cas', '_stage', '0000000000000000000-stale')
+        const state0 = {
+            ...emptyState,
+            epochNs: 1_000_000,
+            root: { '.cas': { '_stage': { '0000000000000000000-stale': [vec8(0x99n)] } } },
+        }
+        const content = vec8(0x2An)
+        const c = fileCas(sha256)('.')
+        const x = c.write(nonEmpty(ok(content), /** @type {List<never, Ok<Vec>>} */ (empty())))
+        const [state1, w] = virtual(state0)(x)
+        assert(w[0] === 'ok', ['expected write ok', w])
+        const [, present] = virtual(state1)(access(stalePath))
+        assert(present[0] === 'error', 'expected GC to reclaim the expired staging file')
+    },
+    casWriteGcSkipsLiveLease: () => {
+        // A staging file whose deadline is still in the future is left alone by the GC
+        // that `write` runs before staging its own file.
+        const livePath = join('.', '.cas', '_stage', '0000000000002000000-live')
+        const state0 = {
+            ...emptyState,
+            epochNs: 1_000_000,
+            root: { '.cas': { '_stage': { '0000000000002000000-live': [vec8(0x99n)] } } },
+        }
+        const content = vec8(0x2An)
+        const c = fileCas(sha256)('.')
+        const x = c.write(nonEmpty(ok(content), /** @type {List<never, Ok<Vec>>} */ (empty())))
+        const [state1, w] = virtual(state0)(x)
+        assert(w[0] === 'ok', ['expected write ok', w])
+        const [, present] = virtual(state1)(access(livePath))
+        assert(present[0] === 'ok', 'expected GC to leave the live staging file alone')
+    },
+    casUploadSuccess: () => {
+        // A successful upload returns the hash and deletes the source file from cas_upload/.
+        const content = vec8(0x2An)
+        const state0 = { ...emptyState, root: { 'cas_upload': { 'myfile': [content] } } }
+        const [state1, result] = virtual(state0)(casUpload('.')('myfile'))
+        assert(result[0] === 'ok', ['expected casUpload ok', result])
+        assertEq(length(result[1]), 256n, ['expected 256-bit hash', length(result[1])])
+        // Source must be deleted after successful publish.
+        const srcPath = join('.', 'cas_upload', 'myfile')
+        const [, srcAccess] = virtual(state1)(access(srcPath))
+        assert(srcAccess[0] === 'error', 'expected source to be deleted after successful upload')
+    },
+    casUploadFailureKeepsSource: () => {
+        // A missing source file causes write to fail; casUpload returns error and the
+        // source is left in place (trivially: it was never there, but the upload is not published).
+        const state0 = { ...emptyState, root: {} }
+        const [state1, result] = virtual(state0)(casUpload('.')('nonexistent'))
+        assert(result[0] === 'error', ['expected casUpload to fail on missing source', result])
+        // Nothing published to the store.
+        const c = fileCas(sha256)('.')
+        const [, hashes] = virtual(state1)(c.list())
+        assertEq(hashes.length, 0, ['expected nothing published on failed upload', hashes])
+    },
+    collectReadDrainsChunks: () => {
+        // The common path: every chunk is `ok`, so collectRead concatenates them all
+        // and returns the whole blob as one `Vec`.
+        /** @type {List<never, IoResult<Vec>>} */
+        const stream = nonEmpty(ok(vec8(0x11n)), nonEmpty(ok(vec8(0x22n)), empty()))
+        const o = runPure(collectRead(stream))
+        assert(o.length === 1, 'expected collectRead to finish without issuing a command')
+        assertEq(o[0][0], 'ok')
+    },
+    collectReadPropagatesErrorItem: () => {
+        // An error item mid-stream short-circuits collectRead with that same error.
+        /** @type {IoResult<Vec>} */
+        const boom = error('boom')
+        /** @type {List<never, IoResult<Vec>>} */
+        const stream = nonEmpty(ok(vec8(0x11n)), nonEmpty(boom, /** @type {List<never, IoResult<Vec>>} */ (empty())))
+        const o = runPure(collectRead(stream))
+        assert(o.length === 1, 'expected collectRead to finish without issuing a command')
+        const [r] = o
+        assertEq(r[0], 'error')
+        assertEq(r[1], 'boom')
+    },
+    // A single `Vec` cannot exceed `maxLength` bits — feed a pure stream whose second
+    // chunk pushes the running total just over the limit so the overflow guard fires
+    // without any real I/O.
+    collectReadOverflow: () => {
+        const half = maxLength / 2n
+        const v1 = vec(half)(0n)
+        const v2 = vec(half + 1n)(0n)
+        /** @type {List<never, IoResult<Vec>>} */
+        const stream = nonEmpty(ok(v1), nonEmpty(ok(v2), empty()))
+        const o = runPure(collectRead(stream))
+        assert(o.length === 1, 'expected collectRead to finish without issuing a command')
+        assertEq(o[0][0], 'error')
+    },
+    casListPropagatesNonNotFoundAccessError: () => {
+        // A non-ENOENT `access` failure (permissions, corruption) is a genuine storage
+        // error and must propagate out of `list`, not be swallowed as an empty store.
+        const c = fileCas(sha256)('.')
+        const boom = { code: 'EACCES' }
+        const r = casCommand(c.list())
+        assert(r[0] === 'cont', 'expected list() to issue an access command first')
+        assertEq(r[1], 'access')
+        /** @type {unknown} */
+        let threw
+        try {
+            r[2](error(boom))
+        } catch (e) {
+            threw = e
+        }
+        assertEq(threw, boom)
+    },
+}

package/fjs/cas/types.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Types for content-addressable storage utilities.
+ *
+ * @module
+ */
+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';
+/**
+ * The filesystem effects the streaming CAS performs: `read` pulls shards
+ * (`ReadBytes`); `list` walks the store (`Access`/`Readdir`); `write` runs the
+ * lock-free staging upload (`Mkdir`/`CreateExclusive`/`WriteBytes`/`Rename`/`Rm`/
+ * `Stat`, lease deadlines from `Now`, staging names from `RandomInt`) and GC's
+ * expired staging files (`Readdir`/`Rm`).
+ */
+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`).
+     */
+    readonly read: (hash: Vec) => List<O, IoResult<Vec>>;
+    /**
+     * Consumes a chunk stream — each item `ok(chunk)` or `error` — hashing incrementally,
+     * and returns the content address. An error item aborts the upload.
+     */
+    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[]>;
+};
+export type FileCas = Cas<FileCasOperation> & {
+    url: (v: Vec) => string;
+};

package/fjs/cas/types.js

@@ -0,0 +1,6 @@
+/**
+ * Types for content-addressable storage utilities.
+ *
+ * @module
+ */
+export {};

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

@@ -0,0 +1,11 @@
+/**
+ * CI step builder for Bun: installs the pinned Bun version and runs the
+ * FunctionalScript package smoke test plus Bun coverage in one canonical job.
+ *
+ * @module
+ *
+ * @import { MetaStep } from '../common/types.ts'
+ */
+import type { MetaStep } from '../common/types.ts';
+/** @type {(version: string) => readonly MetaStep[]} */
+export declare const bunSteps: (version: string) => readonly MetaStep[];

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

@@ -0,0 +1,20 @@
+/**
+ * CI step builder for Bun: installs the pinned Bun version and runs the
+ * FunctionalScript package smoke test plus Bun coverage in one canonical job.
+ *
+ * @module
+ *
+ * @import { MetaStep } from '../common/types.ts'
+ */
+
+import { bun } from '../config/module.f.mjs'
+import { install, test, uses } from '../common/module.f.mjs'
+
+/** @type {(version: string) => readonly MetaStep[]} */
+export const bunSteps = version => [
+    install(uses('oven-sh/setup-bun', { 'bun-version': bun })),
+    install({ run: `bun install -g functionalscript@${version}` }),
+    test({ run: 'bun install --frozen-lockfile' }),
+    test({ run: `bunx functionalscript@${version} test` }),
+    test({ run: 'bun test --coverage' }),
+]

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

@@ -0,0 +1,80 @@
+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
+ * `install`, `test`, `ubuntu`, and `toSteps`. See `./types.ts` for the
+ * `Os`/`Architecture`/`Image`/`Step`/`Job`/`Jobs`/`GitHubAction`/`StepType`/
+ * `MetaStep` type-level API.
+ *
+ * @module
+ *
+ * @import { Step, Job, MetaStep, StepType } 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'];
+export declare const stepSchema: {
+    readonly run: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts")._Type0<"string">, undefined]>;
+    readonly uses: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts")._Type0<"string">, undefined]>;
+    readonly with: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts").Type1<"record", import("../../types/rtti/types.ts")._Type0<"string">>, undefined]>;
+};
+export declare const jobSchema: {
+    readonly 'runs-on': import("../../types/rtti/types.ts")._Type0<"string">;
+    readonly steps: import("../../types/rtti/types.ts").Type1<"array", {
+        readonly run: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts")._Type0<"string">, undefined]>;
+        readonly uses: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts")._Type0<"string">, undefined]>;
+        readonly with: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts").Type1<"record", import("../../types/rtti/types.ts")._Type0<"string">>, undefined]>;
+    }>;
+};
+export declare const jobsSchema: import("../../types/rtti/types.ts").Type1<"record", {
+    readonly 'runs-on': import("../../types/rtti/types.ts")._Type0<"string">;
+    readonly steps: import("../../types/rtti/types.ts").Type1<"array", {
+        readonly run: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts")._Type0<"string">, undefined]>;
+        readonly uses: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts")._Type0<"string">, undefined]>;
+        readonly with: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts").Type1<"record", import("../../types/rtti/types.ts")._Type0<"string">>, undefined]>;
+    }>;
+}>;
+export declare const gitHubActionSchema: {
+    readonly name: import("../../types/rtti/types.ts")._Type0<"string">;
+    readonly on: {
+        readonly pull_request: import("../../types/rtti/types.ts").Or<readonly [{}, undefined]>;
+        readonly merge_group: import("../../types/rtti/types.ts").Or<readonly [{}, undefined]>;
+    };
+    readonly permissions: import("../../types/rtti/types.ts").Type1<"record", import("../../types/rtti/types.ts")._Type0<"string">>;
+    readonly jobs: import("../../types/rtti/types.ts").Type1<"record", {
+        readonly 'runs-on': import("../../types/rtti/types.ts")._Type0<"string">;
+        readonly steps: import("../../types/rtti/types.ts").Type1<"array", {
+            readonly run: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts")._Type0<"string">, undefined]>;
+            readonly uses: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts")._Type0<"string">, undefined]>;
+            readonly with: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts").Type1<"record", import("../../types/rtti/types.ts")._Type0<"string">>, undefined]>;
+        }>;
+    }>;
+};
+export declare const parseGitHubAction: import("../../types/rtti/parse/types.ts").Parse<{
+    readonly name: import("../../types/rtti/types.ts")._Type0<"string">;
+    readonly on: {
+        readonly pull_request: import("../../types/rtti/types.ts").Or<readonly [{}, undefined]>;
+        readonly merge_group: import("../../types/rtti/types.ts").Or<readonly [{}, undefined]>;
+    };
+    readonly permissions: import("../../types/rtti/types.ts").Type1<"record", import("../../types/rtti/types.ts")._Type0<"string">>;
+    readonly jobs: import("../../types/rtti/types.ts").Type1<"record", {
+        readonly 'runs-on': import("../../types/rtti/types.ts")._Type0<"string">;
+        readonly steps: import("../../types/rtti/types.ts").Type1<"array", {
+            readonly run: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts")._Type0<"string">, undefined]>;
+            readonly uses: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts")._Type0<"string">, undefined]>;
+            readonly with: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts").Type1<"record", import("../../types/rtti/types.ts")._Type0<"string">>, undefined]>;
+        }>;
+    }>;
+}>;
+/** @type {(name: keyof typeof actions, w?: Record<string, string>) => Step} */
+export declare const uses: (name: keyof typeof actions, w?: Record<string, string>) => Step;
+/** @type {(step: Step) => MetaStep} */
+export declare const install: (step: Step) => MetaStep;
+/** @type {(step: Step) => MetaStep} */
+export declare const test: (step: Step) => MetaStep;
+/** @type {(m: readonly MetaStep[]) => readonly Step[]} */
+export declare const toSteps: (m: readonly MetaStep[]) => readonly Step[];
+/** @type {(ms: readonly MetaStep[]) => Job} */
+export declare const ubuntu: (ms: readonly MetaStep[]) => Job;
+/** @type {(ms: readonly MetaStep[]) => Job} */
+export declare const ubuntuArm: (ms: readonly MetaStep[]) => Job;

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

@@ -0,0 +1,87 @@
+/**
+ * Shared CI types and helpers: GitHub Actions step/job RTTI schemas, the
+ * `MetaStep` representation used by tool-specific modules, and assemblers like
+ * `install`, `test`, `ubuntu`, and `toSteps`. See `./types.ts` for the
+ * `Os`/`Architecture`/`Image`/`Step`/`Job`/`Jobs`/`GitHubAction`/`StepType`/
+ * `MetaStep` type-level API.
+ *
+ * @module
+ *
+ * @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'
+
+export const os = /** @type {const} */ (['ubuntu', 'macos', 'windows'])
+
+export const architecture = /** @type {const} */ (['intel', 'arm'])
+
+export const stepSchema = /** @type {const} */ ({
+    run: option(string),
+    uses: option(string),
+    with: option(record(string))
+})
+
+export const jobSchema = /** @type {const} */ ({
+    'runs-on': string,
+    steps: array(stepSchema)
+})
+
+export const jobsSchema = record(jobSchema)
+
+export const gitHubActionSchema = /** @type {const} */ ({
+    name: string,
+    on: {
+        pull_request: option({}),
+        merge_group: option({})
+    },
+    permissions: record(string),
+    jobs: jobsSchema
+})
+
+export const parseGitHubAction = rttiParse(gitHubActionSchema)
+
+/** @type {(name: keyof typeof actions, w?: Record<string, string>) => Step} */
+export const uses = (name, w) => ({
+    uses: `${name}@${actions[name]}`,
+    ...(w === undefined ? {} : { with: w })
+})
+
+/** @type {(step: Step) => MetaStep} */
+export const install = step => ({ type: 'install', step })
+
+/** @type {(step: Step) => MetaStep} */
+export const test = step => ({ type: 'test', step })
+
+/** @type {(m: readonly MetaStep[]) => readonly Step[]} */
+export const toSteps = m => {
+    /** @type {(st: StepType) => Step[]} */
+    const filter = st => m.flatMap(mt => mt.type === st ? [mt.step] : [])
+    const aptGet = m.flatMap(v => v.type === 'apt-get' ? [v.package] : []).join(' ')
+
+    const needRust = m.find(v => v.type === 'rust') !== undefined
+    const targets = m.flatMap(v => v.type === 'rust' && v.target !== undefined ? [v.target] : []).join(',')
+    return [
+        ...(aptGet !== '' ? [{ run: `sudo apt-get update && sudo apt-get install -y ${aptGet}` }] : []),
+        ...(needRust ? [uses('dtolnay/rust-toolchain', {
+            components: 'rustfmt,clippy',
+            ...(targets === '' ? {} : { targets }),
+        })] : []),
+        ...filter('install'),
+        uses('actions/checkout'),
+        ...filter('test'),
+    ]
+}
+
+/** @type {(ms: readonly MetaStep[]) => Job} */
+export const ubuntu = ms => ({
+    'runs-on': images.ubuntu.intel,
+    steps: toSteps(ms)
+})
+
+/** @type {(ms: readonly MetaStep[]) => Job} */
+export const ubuntuArm = ms => ({
+    'runs-on': images.ubuntu.arm,
+    steps: toSteps(ms)
+})

package/fjs/ci/common/types.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Type-level API for shared CI types: GitHub Actions step/job RTTI schemas,
+ * the `MetaStep` representation used by tool-specific modules.
+ *
+ * @module
+ */
+import type { Ts } from '../../types/rtti/ts/types.ts';
+import type { images } from '../config/module.f.mjs';
+import type { os, architecture, stepSchema, jobSchema, jobsSchema, gitHubActionSchema } from './module.f.mjs';
+export type Os = typeof os[number];
+export type Architecture = typeof architecture[number];
+export type Image = typeof images[Os][Architecture];
+export type Step = Ts<typeof stepSchema>;
+export type Job = Ts<typeof jobSchema>;
+export type Jobs = Ts<typeof jobsSchema>;
+export type GitHubAction = Ts<typeof gitHubActionSchema>;
+export type StepType = 'install' | 'test';
+export type MetaStep = {
+    readonly type: StepType;
+    readonly step: Step;
+} | {
+    readonly type: 'rust';
+    readonly target?: string;
+} | {
+    readonly type: 'apt-get';
+    readonly package: string;
+};