functionalscript 0.39.0 → 0.40.0

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

@@ -0,0 +1,61 @@
+/**
+ * Generates one self-contained Nix flake per declared CI job.
+ *
+ * Each job gets its own `nix/generated/<id>/flake.nix` pinning the exact
+ * Nixpkgs commit from `../config/module.f.ts` and exposing a single
+ * `devShells.<system>.default` development shell. The files are static and
+ * readable on purpose: no job selection, no shared Nix modules, no helper
+ * libraries.
+ *
+ * @module
+ */
+import { type Effect } from '../../effects/module.f.ts';
+import { type Mkdir, type WriteFile } from '../../effects/node/module.f.ts';
+import { type MetaStep } from '../common/module.f.ts';
+/** A CI job's development environment, one generated flake each. */
+export type NixJob = {
+    /** Generated directory name under `nix/generated`, matching the CI job id. */
+    readonly id: string;
+    /** Nix system of the job's runner, e.g. `aarch64-linux`. */
+    readonly system: string;
+    /** Nixpkgs attribute names made available in the job's shell. */
+    readonly packages: readonly string[];
+    /** Job-local shell initialization, when the job needs one. */
+    readonly shellHook?: string;
+};
+/** Directory owned by this generator. */
+export declare const generatedDirectory: 'nix/generated';
+/**
+ * Serializes a job's flake.
+ *
+ * The serializer rejects invalid *identifiers*, and every identifier in a flake
+ * is written here — a job only contributes attribute names and strings, which
+ * are quoted when they are not identifiers. The unwrap is therefore a totality
+ * assertion, not an input check.
+ */
+export declare const flakeText: (job: NixJob) => string;
+/** Writes one generated flake per job. */
+export declare const nixFlakes: (jobs: readonly NixJob[]) => Effect<Mkdir | WriteFile, void>;
+/** Path a workflow passes to `nix develop`, for the job of the given id. */
+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. */
+export declare const nixDevelop: (id: string, command: string) => string;
+/**
+ * Runs a migrated job's whole command sequence in one development shell, so the
+ * shell's packages and environment reach every command without exporting a
+ * profile across GitHub Actions steps.
+ *
+ * The commands are a shell script, joined so a failure stops the rest, and are
+ * quoted as one argument — a command may contain quotes of its own.
+ */
+export declare const nixDevelopAll: (id: string, commands: readonly string[]) => string;
+/**
+ * Checks a job's generated flake end to end: the shell builds, and the Node it
+ * puts on `PATH` is exactly the pinned version. The pinned Nixpkgs commit
+ * already determines the version, so this is the only place the expectation
+ * is stated — the generated flakes stay declarative instead of carrying an
+ * `assert` that restates the commit they pin.
+ */
+export declare const nixVersionCheckStep: (id: string, version: string) => MetaStep;

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

@@ -0,0 +1,92 @@
+/**
+ * Generates one self-contained Nix flake per declared CI job.
+ *
+ * Each job gets its own `nix/generated/<id>/flake.nix` pinning the exact
+ * Nixpkgs commit from `../config/module.f.ts` and exposing a single
+ * `devShells.<system>.default` development shell. The files are static and
+ * readable on purpose: no job selection, no shared Nix modules, no helper
+ * libraries.
+ *
+ * @module
+ */
+import { forEachStep, mapStep, pure, step } from '../../effects/module.f.js';
+import { mkdir, writeUtf8File } from '../../effects/node/module.f.js';
+import { nixToString } from '../../media/nix/module.f.js';
+import { fromUndefined, unwrap as unwrapNullable } from '../../types/nullable/module.f.js';
+import { unwrap } from '../../types/result/module.f.js';
+import { install, test, uses } from '../common/module.f.js';
+import { nixpkgs } from '../config/module.f.js';
+/** Directory owned by this generator. */
+export const generatedDirectory = 'nix/generated';
+const { commit } = nixpkgs;
+const url = `github:NixOS/nixpkgs/${commit}`;
+const flake = ({ system, packages, shellHook }) => ['set',
+    ['=', ['inputs', 'nixpkgs', 'url'], url],
+    ['=', ['outputs'], ['lambda',
+            ['open-set-pattern', 'nixpkgs'],
+            ['set',
+                ['=', ['devShells', system, 'default'], ['let',
+                        [['=', ['pkgs'], ['apply',
+                                    ['ref', 'import'],
+                                    ['ref', 'nixpkgs'],
+                                    ['set', ['=', ['system'], system]]
+                                ]]],
+                        ['apply',
+                            ['ref', 'pkgs', 'mkShell'],
+                            ['set',
+                                ['=', ['packages'], ['list', ...packages.map(p => ['ref', 'pkgs', p])]],
+                                ...(shellHook === undefined
+                                    ? []
+                                    : [['=', ['shellHook'], ['indented-string', shellHook]]])
+                            ]
+                        ]
+                    ]]
+            ]
+        ]]
+];
+/**
+ * Serializes a job's flake.
+ *
+ * The serializer rejects invalid *identifiers*, and every identifier in a flake
+ * is written here — a job only contributes attribute names and strings, which
+ * are quoted when they are not identifiers. The unwrap is therefore a totality
+ * assertion, not an input check.
+ */
+export const flakeText = (job) => unwrapNullable(fromUndefined(nixToString(flake(job))));
+const writeFlake = (job) => {
+    const directory = `${generatedDirectory}/${job.id}`;
+    const created = mapStep(mkdir(directory, { recursive: true }), unwrap);
+    const written = step(created, () => writeUtf8File(`${directory}/flake.nix`, flakeText(job)));
+    return mapStep(written, unwrap);
+};
+/** Writes one generated flake per job. */
+export const nixFlakes = (jobs) => forEachStep(pure(jobs), writeFlake);
+/** Path a workflow passes to `nix develop`, for the job of the given id. */
+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 = (id, command) => `nix develop ${flakePath(id)} --command ${command}`;
+/**
+ * Wraps a string so a POSIX shell reproduces it exactly. Single quotes protect
+ * every other character, so only the quote itself needs handling: leave the
+ * literal, reopen it, and escape the quote outside (`'` becomes `'\''`).
+ */
+const singleQuoted = (value) => `'${value.replaceAll("'", "'\\''")}'`;
+/**
+ * Runs a migrated job's whole command sequence in one development shell, so the
+ * shell's packages and environment reach every command without exporting a
+ * profile across GitHub Actions steps.
+ *
+ * The commands are a shell script, joined so a failure stops the rest, and are
+ * quoted as one argument — a command may contain quotes of its own.
+ */
+export const nixDevelopAll = (id, commands) => nixDevelop(id, `bash -euo pipefail -c ${singleQuoted(commands.join(' && '))}`);
+/**
+ * Checks a job's generated flake end to end: the shell builds, and the Node it
+ * puts on `PATH` is exactly the pinned version. The pinned Nixpkgs commit
+ * already determines the version, so this is the only place the expectation
+ * is stated — the generated flakes stay declarative instead of carrying an
+ * `assert` that restates the commit they pin.
+ */
+export const nixVersionCheckStep = (id, version) => test({ run: `test "$(${nixDevelop(id, 'node --version')})" = v${version}` });

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

@@ -0,0 +1,23 @@
+export declare const proof: {
+    flakeText: {
+        plain: () => void;
+        shellHook: () => void;
+    };
+    nixFlakes: {
+        write: () => void;
+        every: () => void;
+        nodeShellHook: () => void;
+        packages: () => void;
+        quotedPackage: () => void;
+        multiplePackages: () => void;
+    };
+    workflow: {
+        flakePath: () => void;
+        nixDevelop: () => void;
+        nixDevelopAll: {
+            sequence: () => void;
+            quote: () => void;
+        };
+        nixInstall: () => void;
+    };
+};

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

@@ -0,0 +1,109 @@
+/**
+ * Proofs for generated CI flakes.
+ *
+ * @module
+ */
+import { assert, assertEq } from '../../asserts/module.f.js';
+import { step } from '../../effects/module.f.js';
+import { readUtf8File } from '../../effects/node/module.f.js';
+import { emptyState, virtual } from '../../effects/node/virtual/module.f.js';
+import { nixpkgs } from '../config/module.f.js';
+import { nodeNixJobs } from '../node/module.f.js';
+import { flakePath, flakeText, generatedDirectory, nixDevelop, nixDevelopAll, nixFlakes, nixInstall, } from './module.f.js';
+const { commit } = nixpkgs;
+const plain = {
+    id: 'node24',
+    system: 'aarch64-linux',
+    packages: ['nodejs_24'],
+};
+const withShellHook = {
+    ...plain,
+    id: 'node22',
+    packages: ['nodejs_22'],
+    shellHook: `export NPM_CONFIG_PREFIX="$HOME/.npm-global"`,
+};
+const plainFlake = `{
+    inputs.nixpkgs.url = "github:NixOS/nixpkgs/${commit}";
+    outputs = { nixpkgs, ... }: {
+        devShells.aarch64-linux.default = let
+            pkgs = import nixpkgs {
+                system = "aarch64-linux";
+            };
+        in
+        pkgs.mkShell {
+            packages = [ pkgs.nodejs_24 ];
+        };
+    };
+}
+`;
+const shellHookFlake = `{
+    inputs.nixpkgs.url = "github:NixOS/nixpkgs/${commit}";
+    outputs = { nixpkgs, ... }: {
+        devShells.aarch64-linux.default = let
+            pkgs = import nixpkgs {
+                system = "aarch64-linux";
+            };
+        in
+        pkgs.mkShell {
+            packages = [ pkgs.nodejs_22 ];
+            shellHook = ''
+                export NPM_CONFIG_PREFIX="$HOME/.npm-global"
+            '';
+        };
+    };
+}
+`;
+const generated = (jobs, id) => {
+    const written = step(nixFlakes(jobs), () => readUtf8File(`${generatedDirectory}/${id}/flake.nix`));
+    const [, [tag, result]] = virtual(emptyState)(written);
+    assert(tag === 'ok', result);
+    return result;
+};
+export const proof = {
+    flakeText: {
+        plain: () => assertEq(flakeText(plain), plainFlake),
+        shellHook: () => assertEq(flakeText(withShellHook), shellHookFlake),
+    },
+    nixFlakes: {
+        write: () => assertEq(generated([plain], plain.id), plainFlake),
+        every: () => {
+            for (const job of nodeNixJobs) {
+                assertEq(generated(nodeNixJobs, job.id), flakeText(job));
+            }
+        },
+        nodeShellHook: () => {
+            const [node22] = nodeNixJobs;
+            assert(node22.shellHook !== undefined, 'expected a Node 22 shell hook');
+            assert(generated(nodeNixJobs, node22.id).includes('$HOME/.npm-global'), 'expected the Node 22 global installation prefix');
+        },
+        packages: () => {
+            for (const { id, packages } of nodeNixJobs) {
+                assertEq(packages.length, 1);
+                assertEq(packages[0], `nodejs_${id.slice('node'.length)}`);
+            }
+        },
+        // Job data only ever reaches quotable positions, so an unusual package
+        // name is escaped rather than rejected.
+        quotedPackage: () => assert(flakeText({ ...plain, packages: ['not an identifier'] })
+            .includes('pkgs."not an identifier"'), 'expected a quoted attribute name'),
+        multiplePackages: () => assert(flakeText({ ...plain, packages: ['nodejs_24', 'git'] })
+            .includes('[ pkgs.nodejs_24 pkgs.git ]'), 'expected both packages in the shell'),
+    },
+    workflow: {
+        // The path a workflow passes to `nix develop` must be the directory the
+        // generator wrote the flake into.
+        flakePath: () => assertEq(flakePath(plain.id), `./${generatedDirectory}/node24`),
+        nixDevelop: () => assertEq(nixDevelop(plain.id, 'node --version'), 'nix develop ./nix/generated/node24 --command node --version'),
+        nixDevelopAll: {
+            sequence: () => assertEq(nixDevelopAll(plain.id, ['npm ci', 'node --test']), `nix develop ./nix/generated/node24 --command bash -euo pipefail -c 'npm ci && node --test'`),
+            // A command carrying its own quote must not end the outer one: the
+            // shell has to see the script back exactly as it was written.
+            quote: () => assertEq(nixDevelopAll(plain.id, [`printf '%s' 'a b'`]), `nix develop ./nix/generated/node24 --command bash -euo pipefail -c 'printf '\\''%s'\\'' '\\''a b'\\'''`),
+        },
+        nixInstall: () => {
+            assertEq(nixInstall.type, 'install');
+            assert(nixInstall.type === 'install'
+                && nixInstall.step.uses?.startsWith('cachix/install-nix-action@') === true, 'expected the pinned Nix installer action');
+        },
+    },
+};

package/fjs/ci/node/module.f.d.ts

@@ -1,6 +1,28 @@
-import { type Jobs, type MetaStep } from '../common/module.f.ts';
+import { type Job, type Jobs, type MetaStep } from '../common/module.f.ts';
+import { type NixJob } from '../nix/module.f.ts';
 export declare const major: (v: string) => string;
 export declare const basicNode: (version: string) => (extra: readonly MetaStep[]) => readonly MetaStep[];
 export declare const platformNodeSteps: (version: string) => readonly MetaStep[];
 export declare const nodeVersionJobs: (version: string) => Jobs;
+export declare const nixSystem: 'aarch64-linux';
+/** Generated development environments for the canonical Node jobs. */
+export declare const nodeNixJobs: readonly NixJob[];
+/**
+ * Version-check steps for the canonical Node jobs' generated flakes, one per
+ * job. Collected into the shared temporary `nix-flakes` job in
+ * `fjs/ci/module.f.ts`.
+ */
+export declare const nodeNixVersionSteps: readonly MetaStep[];
+/**
+ * Temporary job that instantiates every generated flake.
+ *
+ * Nothing else in CI evaluates the generated files, so a broken flake — or one
+ * whose snapshot moved to a different Node — would only surface once a real job
+ * started using it. It deliberately stays separate from the canonical Node jobs:
+ * those keep their current `setup-node` runtime until they are migrated one at a
+ * time. When the last one migrates and this job goes away, each migrated job
+ * must check its own Node version inside the `nix develop` invocation, or the
+ * guarantee is lost.
+ */
+export declare const nodeNixFlakeJob: Job;
 export declare const nodeMainSteps: typeof platformNodeSteps;

package/fjs/ci/node/module.f.js

@@ -6,7 +6,9 @@
  */
 import { node } from '../config/module.f.js';
 import { install, test, ubuntuArm, uses } from '../common/module.f.js';
+import { nixInstall, nixVersionCheckStep } from '../nix/module.f.js';
 export const major = (v) => v.split('.')[0];
+const jobId = (version) => `node${major(version)}`;
 const installNode = (version) => uses('actions/setup-node', { 'node-version': version });
 const nodeInstall = (v) => [
     install(installNode(v)),
@@ -26,6 +28,7 @@ const node22Steps = (version) => [
     ...nodeInstall(node.node22),
     fjsGlobalInstall(version),
     test({ run: 'fjs t' }),
+    test({ run: 'node --test' }),
 ];
 const node24Steps = [
     ...nodeInstall(node.node24),
@@ -41,8 +44,49 @@ const node26Steps = [
 ];
 const nodeJob = (steps) => ubuntuArm(steps);
 export const nodeVersionJobs = (version) => ({
-    [`node${major(node.node22)}`]: nodeJob(node22Steps(version)),
-    [`node${major(node.node24)}`]: nodeJob(node24Steps),
-    [`node${major(node.default)}`]: nodeJob(node26Steps),
+    [jobId(node.node22)]: nodeJob(node22Steps(version)),
+    [jobId(node.node24)]: nodeJob(node24Steps),
+    [jobId(node.default)]: nodeJob(node26Steps),
+});
+// The canonical Node jobs run on the Ubuntu ARM runner.
+export const nixSystem = 'aarch64-linux';
+// Keeps `npm install -g functionalscript` writable and puts the installed `fjs`
+// on `PATH` for the rest of the same `nix develop` invocation.
+const npmGlobalShellHook = `export NPM_CONFIG_PREFIX="$HOME/.npm-global"
+export PATH="$NPM_CONFIG_PREFIX/bin:$PATH"
+mkdir -p "$NPM_CONFIG_PREFIX"`;
+// Versions of the canonical Node jobs, in job order.
+const nixVersions = [node.node22, node.node24, node.default];
+const nixJob = (version) => ({
+    id: jobId(version),
+    system: nixSystem,
+    packages: [`nodejs_${major(version)}`],
 });
+/** Generated development environments for the canonical Node jobs. */
+export const nodeNixJobs = [
+    { ...nixJob(node.node22), shellHook: npmGlobalShellHook },
+    nixJob(node.node24),
+    nixJob(node.default),
+];
+/**
+ * Version-check steps for the canonical Node jobs' generated flakes, one per
+ * job. Collected into the shared temporary `nix-flakes` job in
+ * `fjs/ci/module.f.ts`.
+ */
+export const nodeNixVersionSteps = nixVersions.map(version => nixVersionCheckStep(jobId(version), version));
+/**
+ * Temporary job that instantiates every generated flake.
+ *
+ * Nothing else in CI evaluates the generated files, so a broken flake — or one
+ * whose snapshot moved to a different Node — would only surface once a real job
+ * started using it. It deliberately stays separate from the canonical Node jobs:
+ * those keep their current `setup-node` runtime until they are migrated one at a
+ * time. When the last one migrates and this job goes away, each migrated job
+ * must check its own Node version inside the `nix develop` invocation, or the
+ * guarantee is lost.
+ */
+export const nodeNixFlakeJob = ubuntuArm([
+    nixInstall,
+    ...nodeNixVersionSteps,
+]);
 export const nodeMainSteps = platformNodeSteps;

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

@@ -12,5 +12,7 @@ export declare const proof: {
         configuredPackageVersion: () => void;
         missingPackageJson: () => void;
     };
+    nixFlakes: () => void;
+    nixFlakeJob: () => void;
     ubuntu: () => void;
 };

package/fjs/ci/proof.f.js

@@ -1,5 +1,6 @@
 import { ci, main } from './module.f.js';
-import { functionalscript } from './config/module.f.js';
+import { functionalscript, node } from './config/module.f.js';
+import { nodeNixJobs } from './node/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, ubuntu, parseGitHubAction } from './common/module.f.js';
@@ -19,15 +20,22 @@ const makeState = (rust, packageJson) => ({
         ...(rust ? { 'Cargo.toml': [emptyVec] } : {}),
     },
 });
-const workflow = (state) => {
-    const dotGithub = state.root['.github'];
-    assert(typeof dotGithub === 'object' && !Array.isArray(dotGithub), dotGithub);
-    const workflows = dotGithub['workflows'];
-    assert(typeof workflows === 'object' && !Array.isArray(workflows), workflows);
-    const file = workflows['ci.yml'];
+const subDir = (dir, name) => {
+    const entity = dir[name];
+    assert(typeof entity === 'object' && !Array.isArray(entity), entity);
+    return entity;
+};
+const text = (dir, name) => {
+    const file = dir[name];
     assert(!(!Array.isArray(file) || file.length === 0), file);
-    return unwrap(parseGitHubAction(jsonParse(utf8ToString(file[0]))));
+    return utf8ToString(file[0]);
 };
+const path = (dir, names) => names.reduce(subDir, dir);
+const workflow = (state) => {
+    const workflows = path(state.root, ['.github', 'workflows']);
+    return unwrap(parseGitHubAction(jsonParse(text(workflows, 'ci.yml'))));
+};
+const flake = (state, id) => text(path(state.root, ['nix', 'generated', id]), 'flake.nix');
 const run = (rust, nodeExtra = () => []) => {
     const [state, result] = virtual(makeState(rust))(ci({ nodeExtra }));
     assertEq(result, 0);
@@ -75,7 +83,6 @@ export const proof = {
             'node22',
             'node24',
             'node26',
-            'playwright',
         ]) {
             assert(hasRunInJob(id, 'npm ci')(gha), `expected npm ci in ${id}`);
         }
@@ -135,6 +142,37 @@ export const proof = {
             assert(hasRun(`npm install -g functionalscript@${functionalscript}`)(gha), 'expected configured-version install');
         },
     },
+    nixFlakes: () => {
+        const [state, result] = virtual(makeState(false))(main());
+        assertEq(result, 0);
+        for (const { id, packages } of nodeNixJobs) {
+            const [nodePackage] = packages;
+            assert(flake(state, id).includes(`pkgs.${nodePackage}`), `expected ${nodePackage} in the ${id} flake`);
+        }
+    },
+    nixFlakeJob: () => {
+        const gha = run(false);
+        const job = gha.jobs['nix-flakes'];
+        assert(job !== undefined, 'expected the temporary flake job');
+        assert(job.steps.some(step => step.uses?.startsWith('cachix/install-nix-action@') === true), 'expected a pinned Nix installer');
+        // Exactly one check per unmigrated flake: none goes unchecked, and no
+        // check outlives the flake it was written for. A migrated job checks its
+        // own flake by running through it, so it is not covered here.
+        assertEq(job.steps.filter(step => step.run !== undefined).length, nodeNixJobs.length);
+        for (const { id } of nodeNixJobs) {
+            assert(hasRunInJob('nix-flakes', `nix develop ./nix/generated/${id} --command node --version`)(gha), `expected the ${id} flake to be instantiated`);
+        }
+        // Since the flakes no longer assert their own version, this job is the
+        // only place the Nix runtime is tied to the version `setup-node` installs.
+        for (const version of [node.node22, node.node24, node.default]) {
+            assert(hasRunInJob('nix-flakes', `= v${version}`)(gha), `expected the flake job to check Node ${version}`);
+        }
+        // The canonical Node jobs keep their current runtime setup until they
+        // are migrated one at a time.
+        for (const { id } of nodeNixJobs) {
+            assert(!hasRunInJob(id, 'nix develop')(gha), `unexpected nix develop in ${id}`);
+        }
+    },
     ubuntu: () => {
         const job = ubuntu([test({ run: 'echo hi' })]);
         assert(job['runs-on'] !== undefined, 'expected runs-on');

package/fjs/dev/module.f.d.ts

@@ -42,4 +42,5 @@ export type LoadModuleOperations = Access | Import | All | Readdir;
 export declare const loadModuleMap: (env: Env) => Effect<LoadModuleOperations, ModuleMap>;
 export declare const proof: {
     isSourceFile: () => void;
+    allFilesSkipsNodeModules: () => void;
 };

package/fjs/dev/module.f.js

@@ -8,7 +8,8 @@ import { cmp as strCmp } from '../types/string/module.f.js';
 import { unwrap } from '../types/result/module.f.js';
 import { pure, step } from '../effects/module.f.js';
 import { join, relativize, toPosix } from '../path/module.f.js';
-import { assert } from '../asserts/module.f.js';
+import { assert, assertEq } from '../asserts/module.f.js';
+import { emptyState, virtual } from '../effects/node/virtual/module.f.js';
 /**
  * Returns `true` if the file should be loaded for proof discovery.
  *
@@ -72,7 +73,7 @@ export const loadModuleMap = (env) => {
     const s = initCwd === undefined ? '.' : toPosix(initCwd);
     const prefix = s === '.' ? '' : s;
     // TODO: there are multiple `all` effects here,
-    //       we should consider optimize them by ALIQ technique or something similar.
+    //       we should consider optimizing them by ALIQ technique or something similar.
     //       For example, we should be able to write it like `allFiles(s).flatMap(loadFile)`,
     //       then an effect runner can batch all file loading operations together.
     const x0 = step(allFiles(s, shouldLoad), files => all(...files.map(loadFile)));
@@ -90,4 +91,14 @@ export const proof = {
         assert(!isSourceFile('readme.md'));
         assert(!isSourceFile('module.json'));
     },
+    allFilesSkipsNodeModules: () => {
+        // `node_modules` is skipped without descending into it, even though
+        // it contains a file that would otherwise match the predicate.
+        const root = {
+            'node_modules': { 'pkg.f.ts': [] },
+            'a.f.ts': [],
+        };
+        const [, result] = virtual({ ...emptyState, root })(allFiles('.', shouldLoad));
+        assertEq(result.join(','), './a.f.ts');
+    },
 };

package/fjs/dev/update/module.f.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Synchronizes local development configuration generated from canonical repository files.
+ *
+ * @module
+ */
+import { type Effect } from '../../effects/module.f.ts';
+import { type Mkdir, type NodeProgram, type ReadFile, type WriteFile } from '../../effects/node/module.f.ts';
+/** Regenerates VS Code's local MCP configuration from the canonical Copilot configuration. */
+export declare const syncMcp: () => Effect<Mkdir | ReadFile | WriteFile, void>;
+/** Runs all local development configuration generators. */
+export declare const main: NodeProgram;

package/fjs/dev/update/module.f.js

@@ -0,0 +1,20 @@
+/**
+ * Synchronizes local development configuration generated from canonical repository files.
+ *
+ * @module
+ */
+import { history, historyStep, mapStep, step } from '../../effects/module.f.js';
+import { mkdir, readUtf8File, writeUtf8File } from '../../effects/node/module.f.js';
+import { unwrap } from '../../types/result/module.f.js';
+const source = '.copilot/mcp.json';
+const targetDirectory = '.vscode';
+const target = '.vscode/mcp.json';
+/** Regenerates VS Code's local MCP configuration from the canonical Copilot configuration. */
+export const syncMcp = () => {
+    const sourceText = history(mapStep(readUtf8File(source), unwrap));
+    const targetDirectoryReady = historyStep(sourceText, () => mapStep(mkdir(targetDirectory, { recursive: true }), unwrap));
+    const targetWritten = step(targetDirectoryReady, ([, text]) => writeUtf8File(target, text));
+    return mapStep(targetWritten, unwrap);
+};
+/** Runs all local development configuration generators. */
+export const main = () => mapStep(syncMcp(), () => 0);

package/fjs/dev/update/proof.f.d.ts

@@ -0,0 +1,7 @@
+export declare const proof: {
+    syncMcp: () => void;
+    main: () => void;
+    throw: {
+        missingSource: () => readonly [import("../../effects/node/virtual/module.f.ts").State, void];
+    };
+};

package/fjs/dev/update/proof.f.js

@@ -0,0 +1,35 @@
+/**
+ * Proofs for local development configuration generation.
+ *
+ * @module
+ */
+import { assert, assertEq } from '../../asserts/module.f.js';
+import { utf8 } from '../../text/module.f.js';
+import { readUtf8File } from '../../effects/node/module.f.js';
+import { defaultNodeProgramOptions, emptyState, virtual } from '../../effects/node/virtual/module.f.js';
+import { main, syncMcp } from './module.f.js';
+import { step } from '../../effects/module.f.js';
+const mcp = '{"servers":{}}';
+const initial = {
+    ...emptyState,
+    root: {
+        '.copilot': {
+            'mcp.json': [utf8(mcp)],
+        },
+    },
+};
+export const proof = {
+    syncMcp: () => {
+        const generatedMcp = step(syncMcp(), () => readUtf8File('.vscode/mcp.json'));
+        const [, [tag, result]] = virtual(initial)(generatedMcp);
+        assert(tag === 'ok', result);
+        assertEq(result, mcp);
+    },
+    main: () => {
+        const [, result] = virtual(initial)(main(defaultNodeProgramOptions));
+        assertEq(result, 0);
+    },
+    throw: {
+        missingSource: () => virtual(emptyState)(syncMcp()),
+    },
+};

package/fjs/djs/ast/module.f.d.ts

@@ -4,12 +4,59 @@
  * @module
  */
 import type { Primitive, Array, Unknown } from '../module.f.ts';
+/**
+ * A parsed DJS module: its imported module specifiers, in source order, and
+ * its body.
+ *
+ * The specifier list indexes `['aref', i]`.
+ */
 export type AstModule = [readonly string[], AstBody];
+/** A value in a module body: a primitive, a reference, an array, or an object. */
 export type AstConst = Primitive | AstModuleRef | AstArray | AstObject;
+/**
+ * A reference to a value defined outside this `AstConst`.
+ *
+ * - `['aref', i]` — the `i`-th argument of the body, i.e. the `i`-th imported
+ *   module of the enclosing `AstModule`.
+ * - `['cref', i]` — the `i`-th entry of the enclosing `AstBody`.
+ *
+ * Both indices are absolute and zero-based, **not** offsets from the
+ * referencing entry: in the body `[a, b, ['cref', 0]]` the reference resolves
+ * to `a`, not to the nearest preceding entry `b`.
+ *
+ * A `cref` index must be smaller than the index of the entry holding it —
+ * `run` evaluates a body left to right, so a reference to the current or a
+ * later entry is unsatisfiable. It is not rejected: it resolves to the most
+ * recently evaluated entry instead.
+ */
 export type AstModuleRef = ['aref' | 'cref', number];
+/** An array value; its elements are evaluated in order. */
 export type AstArray = ['array', readonly AstConst[]];
+/** An object value, keyed by property name. */
 export type AstObject = {
     readonly [k in string]?: AstConst;
 };
+/**
+ * The constants of a module body, in declaration order. The **last** entry is
+ * the value the module yields; the preceding entries exist to be named by
+ * `['cref', i]`.
+ *
+ * A body describes the function
+ *
+ * ```js
+ * (...args) => { const c0 = ...; const c1 = ...; return <last> }
+ * ```
+ *
+ * where `args` are the imported modules.
+ */
 export type AstBody = readonly AstConst[];
+/**
+ * Evaluates a module body against its imported modules and returns the value
+ * the module yields — the last entry of the body.
+ *
+ * Entries are evaluated left to right, so a `cref` resolves to an already
+ * evaluated entry. A reference is shared, not copied: two properties holding
+ * the same `['cref', i]` deserialize to the same object, which is what lets a
+ * DJS module denote a graph rather than a tree.
+ */
 export declare const run: (body: AstBody) => (args: Array) => Unknown;