docs: update architecture and matrix status; improve clarity and accuracy

refactor: streamline imports and enhance file handling in core modules
test: enhance unit tests with additional fs utilities and assertions

Author: robertsLando

docs/architecture.md

@@ -4,8 +4,8 @@ Living reference for how `pkg-action` is put together. Updated whenever
 structure changes; pipeline intent lives here so `packages/build/src/main.ts`
 can stay focused on wiring.
 
-> Status: authoritative for v1.0 candidate (2026-04-23). If this file and the
-> code disagree, the code wins and this file is a bug.
+> Reflects the v1.0 candidate (as of 2026-04-23). Code is the source of
+> truth — if this file and the code disagree, the file is stale, file a fix.
 
 ---
 

docs/matrix.md

@@ -8,9 +8,9 @@ hardware that matches the target — so you never rely on cross-compilation.
 
 ## Status
 
-> **M2 — under construction.** See [`STATUS.yaml`](../STATUS.yaml) for the
-> current milestone state. Pin a commit SHA if you depend on this before
-> `v1.0.0`.
+> **ALPHA — ready for early adopters.** Surface is stable for M2; see
+> [`STATUS.yaml`](../STATUS.yaml) for full milestone state. Pin a commit
+> SHA if you depend on this before `v1.0.0`.
 
 ## Inputs
 

packages/build/dist/index.mjs

@@ -14498,7 +14498,8 @@ function getState(name) {
 
 // packages/build/src/main.ts
 import { mkdir as mkdir3, rename as rename3, stat as stat4 } from "node:fs/promises";
-import { basename as pathBasename, dirname as dirname4, join as join7, resolve as pathResolve } from "node:path";
+import { tmpdir as tmpdir2 } from "node:os";
+import { basename as pathBasename, dirname as dirname5, join as join7, resolve as pathResolve } from "node:path";
 
 // packages/core/src/errors.ts
 var PkgActionError = class extends Error {
@@ -15277,8 +15278,9 @@ async function exists2(path4) {
 // packages/core/src/archive.ts
 var import_yazl = __toESM(require_yazl(), 1);
 import { createWriteStream } from "node:fs";
-import { stat as stat3 } from "node:fs/promises";
-import { basename as basename4 } from "node:path";
+import { mkdtemp, rm as rm3, stat as stat3, symlink as symlink2, utimes } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename as basename4, dirname as dirname4 } from "node:path";
 import { pipeline as pipeline2 } from "node:stream/promises";
 async function archive(req, deps) {
   let entry = req.entryName ?? basename4(req.inputPath), mode = req.mode ?? 493;
@@ -15300,7 +15302,7 @@ async function archive(req, deps) {
 }
 var REPRO_MTIME = new Date(Date.UTC(2020, 0, 1, 0, 0, 0)), REPRO_MTIME_TAR = "2020-01-01 00:00:00 UTC";
 async function shellTar(inputPath, outputPath, compression, entry, deps) {
-  let { dirname: dirname5 } = await import("node:path"), { mkdtemp, symlink: symlink2, utimes, rm: rm3 } = await import("node:fs/promises"), { tmpdir } = await import("node:os"), compressFlag = compression === "gz" ? "-z" : "-J", stageDir, workDir = dirname5(inputPath), fileName = basename4(inputPath);
+  let compressFlag = compression === "gz" ? "-z" : "-J", stageDir, workDir = dirname4(inputPath), fileName = basename4(inputPath);
   if (entry !== basename4(inputPath)) {
     stageDir = await mkdtemp(`${tmpdir()}/pkgaction-tar-`);
     let linkPath = `${stageDir}/${entry}`;
@@ -15344,7 +15346,7 @@ async function writeZip(inputPath, outputPath, entry, mode) {
   }
 }
 async function shell7z(inputPath, outputPath, entry, deps) {
-  let { dirname: dirname5 } = await import("node:path"), { mkdtemp, symlink: symlink2, rm: rm3 } = await import("node:fs/promises"), { tmpdir } = await import("node:os"), stageDir, workDir = dirname5(inputPath), fileName = basename4(inputPath);
+  let stageDir, workDir = dirname4(inputPath), fileName = basename4(inputPath);
   if (entry !== basename4(inputPath)) {
     stageDir = await mkdtemp(`${tmpdir()}/pkgaction-7z-`);
     let linkPath = `${stageDir}/${entry}`;
@@ -15548,13 +15550,13 @@ function normalizeFileIcons(file) {
   return [...out.values()].sort((a, b) => a.id - b.id);
 }
 async function parseWindowsMetadataInputs(opts = {}) {
-  let env = opts.env ?? process.env, readFile2 = opts.readFile ?? ((path4) => import("node:fs/promises").then((m) => m.readFile(path4, "utf8"))), prefix = opts.prefix ?? "windows-", read = (name) => readInputRaw(env, `${prefix}${name}`), fileRaw = read("metadata-file"), iconRaw = read("icon"), productName = read("product-name"), productVersion = read("product-version"), fileVersion = read("file-version"), fileDescription = read("file-description"), companyName = read("company-name"), legalCopyright = read("legal-copyright"), originalFilename = read("original-filename"), internalName = read("internal-name"), comments = read("comments"), manifestPath = read("manifest"), langRaw = read("lang"), codepageRaw = read("codepage");
+  let env = opts.env ?? process.env, readFile3 = opts.readFile ?? ((path4) => import("node:fs/promises").then((m) => m.readFile(path4, "utf8"))), prefix = opts.prefix ?? "windows-", read = (name) => readInputRaw(env, `${prefix}${name}`), fileRaw = read("metadata-file"), iconRaw = read("icon"), productName = read("product-name"), productVersion = read("product-version"), fileVersion = read("file-version"), fileDescription = read("file-description"), companyName = read("company-name"), legalCopyright = read("legal-copyright"), originalFilename = read("original-filename"), internalName = read("internal-name"), comments = read("comments"), manifestPath = read("manifest"), langRaw = read("lang"), codepageRaw = read("codepage");
   if (!(fileRaw !== void 0 || iconRaw !== void 0 || productName !== void 0 || productVersion !== void 0 || fileVersion !== void 0 || fileDescription !== void 0 || companyName !== void 0 || legalCopyright !== void 0 || originalFilename !== void 0 || internalName !== void 0 || comments !== void 0 || manifestPath !== void 0)) return null;
   let fileData;
   if (fileRaw !== void 0) {
     let contents;
     try {
-      contents = await readFile2(fileRaw);
+      contents = await readFile3(fileRaw);
     } catch (err) {
       throw new ValidationError(`Failed to read windows-metadata-file "${fileRaw}".`, {
         cause: err
@@ -15597,6 +15599,9 @@ function parseUint16(raw, inputName) {
   return n;
 }
 
+// packages/core/src/windows-metadata-apply.ts
+import { readFile as readFile2, writeFile as writeFile3 } from "node:fs/promises";
+
 // node_modules/pe-library/dist/format/FormatBase.js
 var FormatBase = (
   /** @class */
@@ -18968,13 +18973,9 @@ var SpcPeImageAttributeTypeAndOptionalValue = (
 
 // packages/core/src/windows-metadata-apply.ts
 var RT_MANIFEST = 24, defaultDeps = {
-  readFile: async (p) => {
-    let { readFile: readFile2 } = await import("node:fs/promises");
-    return readFile2(p);
-  },
+  readFile: (p) => readFile2(p),
   writeFile: async (p, d) => {
-    let { writeFile: writeFile4 } = await import("node:fs/promises");
-    await writeFile4(p, d);
+    await writeFile3(p, d);
   }
 };
 function toArrayBuffer(u) {
@@ -19044,7 +19045,7 @@ async function writeManifest(res, meta, deps) {
 }
 
 // packages/core/src/signing.ts
-import { writeFile as writeFile3 } from "node:fs/promises";
+import { writeFile as writeFile4 } from "node:fs/promises";
 import { join as join6 } from "node:path";
 import { randomBytes } from "node:crypto";
 function parseSigningInputs(opts = {}) {
@@ -19134,7 +19135,7 @@ async function runCheckedTool(deps, command, args, label, opts = {}) {
 }
 async function writeSecretBase64(deps, tempDir, base64, extension) {
   let path4 = join6(tempDir, `${randomBytes(8).toString("hex")}.${extension}`), bytes = Buffer.from(base64, "base64");
-  return await (deps.writeFile ?? ((p, d) => writeFile3(p, d, { mode: 384 })))(path4, bytes), path4;
+  return await (deps.writeFile ?? ((p, d) => writeFile4(p, d, { mode: 384 })))(path4, bytes), path4;
 }
 async function signMacos(binaryPath, cfg, deps) {
   let keychainPath = join6(
@@ -19299,14 +19300,14 @@ async function main() {
     if (cfg !== void 0) {
       let absCfg = pathResolve(workspace, cfg);
       if (pathBasename(absCfg).toLowerCase() === "package.json")
-        return dirname4(absCfg);
+        return dirname5(absCfg);
     }
     return workspace;
   })(), project = await readProjectInfo(projectDir);
   logger.info(`[pkg-action] project dir: ${projectDir}`), logger.info(`[pkg-action] project: ${project.name}@${project.version}`);
   let resolvedTargets = inputs.build.targets === "host" ? [hostTarget()] : [...inputs.build.targets];
   logger.info(`[pkg-action] targets: ${resolvedTargets.map(formatTarget).join(", ")}`);
-  let runnerTemp = process.env.RUNNER_TEMP ?? (await import("node:os")).tmpdir(), invocationDir = await createInvocationTemp(runnerTemp);
+  let runnerTemp = process.env.RUNNER_TEMP ?? tmpdir2(), invocationDir = await createInvocationTemp(runnerTemp);
   saveState("invocationDir", invocationDir);
   let pkgOutputDir = join7(invocationDir, "pkg-out");
   await mkdir3(pkgOutputDir, { recursive: !0 });

packages/build/src/main.ts

@@ -26,6 +26,7 @@
 
 import * as core from '@actions/core';
 import { mkdir, rename, stat } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
 import { basename as pathBasename, dirname, join, resolve as pathResolve } from 'node:path';
 import {
   actionsLogger,
@@ -144,7 +145,7 @@ async function main(): Promise<void> {
   logger.info(`[pkg-action] targets: ${resolvedTargets.map(formatTarget).join(', ')}`);
 
   // 4. Invocation-scoped temp dir + output dir.
-  const runnerTemp = process.env['RUNNER_TEMP'] ?? (await import('node:os')).tmpdir();
+  const runnerTemp = process.env['RUNNER_TEMP'] ?? tmpdir();
   const invocationDir = await createInvocationTemp(runnerTemp);
   core.saveState('invocationDir', invocationDir);
   const pkgOutputDir = join(invocationDir, 'pkg-out');

packages/core/src/archive.ts

@@ -14,8 +14,9 @@
 // but the input is tiny enough that run-to-run differences are cosmetic.
 
 import { createWriteStream } from 'node:fs';
-import { stat } from 'node:fs/promises';
-import { basename } from 'node:path';
+import { mkdtemp, rm, stat, symlink, utimes } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, dirname } from 'node:path';
 import { pipeline } from 'node:stream/promises';
 import yazl from 'yazl';
 import type { ExecFn } from './pkg-runner.ts';
@@ -96,10 +97,6 @@ async function shellTar(
   // rename inside the archive only if caller asked for a different entry name.
   // For the common case (entry === basename(inputPath)) we just tar the file
   // as-is. For renames we stage a symlink with the desired name.
-  const { dirname } = await import('node:path');
-  const { mkdtemp, symlink, utimes, rm } = await import('node:fs/promises');
-  const { tmpdir } = await import('node:os');
-
   const compressFlag = compression === 'gz' ? '-z' : '-J';
   let stageDir: string | undefined;
   let workDir = dirname(inputPath);
@@ -179,10 +176,6 @@ async function shell7z(
   entry: string,
   deps: ArchiveDeps,
 ): Promise<void> {
-  const { dirname } = await import('node:path');
-  const { mkdtemp, symlink, rm } = await import('node:fs/promises');
-  const { tmpdir } = await import('node:os');
-
   let stageDir: string | undefined;
   let workDir = dirname(inputPath);
   let fileName = basename(inputPath);

packages/core/src/windows-metadata-apply.ts

@@ -17,6 +17,7 @@
 //     own resedit integration emits, so re-running the sub-action is
 //     idempotent.
 
+import { readFile, writeFile } from 'node:fs/promises';
 import { Data, NtExecutable, NtExecutableResource, Resource } from 'resedit';
 import { ResEditError } from './errors.ts';
 import { padVersionQuad, type IconSpec, type WindowsMetadataInputs } from './windows-metadata.ts';
@@ -30,12 +31,8 @@ export interface WindowsMetadataApplyDeps {
 }
 
 const defaultDeps: WindowsMetadataApplyDeps = {
-  readFile: async (p) => {
-    const { readFile } = await import('node:fs/promises');
-    return readFile(p);
-  },
+  readFile: (p) => readFile(p),
   writeFile: async (p, d) => {
-    const { writeFile } = await import('node:fs/promises');
     await writeFile(p, d);
   },
 };

packages/core/test/unit/archive.test.ts

@@ -5,7 +5,7 @@
 
 import { test } from 'node:test';
 import { strictEqual, ok, rejects } from 'node:assert/strict';
-import { mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { mkdtemp, readFile, rm, stat, utimes, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { archive } from '../../src/archive.ts';
@@ -142,7 +142,6 @@ test('archive: tar normalizes the source mtime in addition to --mtime', async ()
   await withTempPair(async (inputPath, outputPath) => {
     // Pre-bump the input mtime to a recent timestamp; archive() must overwrite it.
     const bumped = new Date(Date.UTC(2025, 5, 15, 12, 0, 0));
-    const { utimes } = await import('node:fs/promises');
     await utimes(inputPath, bumped, bumped);
 
     const exec: ExecFn = async () => ({ exitCode: 0, stdout: '', stderr: '' });

packages/core/test/unit/checksum.test.ts

@@ -1,5 +1,6 @@
 import { test } from 'node:test';
 import { strictEqual, ok, rejects } from 'node:assert/strict';
+import { createHash } from 'node:crypto';
 import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
@@ -80,7 +81,6 @@ test('computeChecksum streams multi-chunk input correctly', async () => {
     const digest = await computeChecksum(path, 'sha256');
     strictEqual(digest.length, 64);
     // Compute directly in-memory for cross-check.
-    const { createHash } = await import('node:crypto');
     const expected = createHash('sha256').update(payload).digest('hex');
     strictEqual(digest, expected);
   });

packages/core/test/unit/fs-utils.test.ts

@@ -1,6 +1,6 @@
 import { test } from 'node:test';
 import { strictEqual, ok } from 'node:assert/strict';
-import { mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { mkdtemp, readdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import {
@@ -47,7 +47,6 @@ test('atomicWriteFile leaves no .tmp- sibling on success', async () => {
   await withTempParent(async (parent) => {
     const target = join(parent, 'a.bin');
     await atomicWriteFile(target, new Uint8Array([1, 2, 3]));
-    const { readdir } = await import('node:fs/promises');
     const entries = await readdir(parent);
     strictEqual(entries.filter((e) => e.includes('.tmp-')).length, 0);
     strictEqual(entries.length, 1);

packages/windows-metadata/dist/index.mjs

@@ -13759,13 +13759,13 @@ function normalizeFileIcons(file) {
   return [...out.values()].sort((a, b) => a.id - b.id);
 }
 async function parseWindowsMetadataInputs(opts = {}) {
-  let env = opts.env ?? process.env, readFile = opts.readFile ?? ((path) => import("node:fs/promises").then((m) => m.readFile(path, "utf8"))), prefix = opts.prefix ?? "windows-", read = (name) => readInputRaw(env, `${prefix}${name}`), fileRaw = read("metadata-file"), iconRaw = read("icon"), productName = read("product-name"), productVersion = read("product-version"), fileVersion = read("file-version"), fileDescription = read("file-description"), companyName = read("company-name"), legalCopyright = read("legal-copyright"), originalFilename = read("original-filename"), internalName = read("internal-name"), comments = read("comments"), manifestPath = read("manifest"), langRaw = read("lang"), codepageRaw = read("codepage");
+  let env = opts.env ?? process.env, readFile2 = opts.readFile ?? ((path) => import("node:fs/promises").then((m) => m.readFile(path, "utf8"))), prefix = opts.prefix ?? "windows-", read = (name) => readInputRaw(env, `${prefix}${name}`), fileRaw = read("metadata-file"), iconRaw = read("icon"), productName = read("product-name"), productVersion = read("product-version"), fileVersion = read("file-version"), fileDescription = read("file-description"), companyName = read("company-name"), legalCopyright = read("legal-copyright"), originalFilename = read("original-filename"), internalName = read("internal-name"), comments = read("comments"), manifestPath = read("manifest"), langRaw = read("lang"), codepageRaw = read("codepage");
   if (!(fileRaw !== void 0 || iconRaw !== void 0 || productName !== void 0 || productVersion !== void 0 || fileVersion !== void 0 || fileDescription !== void 0 || companyName !== void 0 || legalCopyright !== void 0 || originalFilename !== void 0 || internalName !== void 0 || comments !== void 0 || manifestPath !== void 0)) return null;
   let fileData;
   if (fileRaw !== void 0) {
     let contents;
     try {
-      contents = await readFile(fileRaw);
+      contents = await readFile2(fileRaw);
     } catch (err) {
       throw new ValidationError(`Failed to read windows-metadata-file "${fileRaw}".`, {
         cause: err
@@ -13808,6 +13808,9 @@ function parseUint16(raw, inputName) {
   return n;
 }
 
+// packages/core/src/windows-metadata-apply.ts
+import { readFile, writeFile as writeFile2 } from "node:fs/promises";
+
 // node_modules/pe-library/dist/format/FormatBase.js
 var FormatBase = (
   /** @class */
@@ -17179,12 +17182,8 @@ var SpcPeImageAttributeTypeAndOptionalValue = (
 
 // packages/core/src/windows-metadata-apply.ts
 var RT_MANIFEST = 24, defaultDeps = {
-  readFile: async (p) => {
-    let { readFile } = await import("node:fs/promises");
-    return readFile(p);
-  },
+  readFile: (p) => readFile(p),
   writeFile: async (p, d) => {
-    let { writeFile: writeFile2 } = await import("node:fs/promises");
     await writeFile2(p, d);
   }
 };