@sdxc/spec 0.0.0-pre.1

package/dist/workspace.js

@@ -0,0 +1,116 @@
+/**
+ * The isolated per-test workspace: a runtime primitive every capability
+ * shares, not a filesystem-plugin detail. Each test gets a fresh ephemeral
+ * directory that `fs` tools write into, `cli` processes start in, and
+ * assertions inspect; the runtime cleans it up when the test ends.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { lstatSync, realpathSync } from "node:fs";
+import { mkdtemp, realpath, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, isAbsolute, join, resolve as resolvePath, sep } from "node:path";
+import { failure, isFailure, success } from "@sdxc/result";
+import { SpecError, WorkspaceEscapeError } from "./errors.js";
+/**
+ * Create a fresh isolated workspace: a temp directory whose real path
+ * (often behind a symlink) bounds every relative path, symlinked
+ * ancestors included; absolute paths delegate to the host-fs permission.
+ *
+ * @param permissions - The run's permission set, consulted for absolute paths.
+ * @returns The workspace, or the error that prevented creating its directory.
+ */
+export async function createWorkspace(permissions) {
+    let root;
+    try {
+        let created = await mkdtemp(join(tmpdir(), "spec-workspace-"));
+        root = await realpath(created);
+    }
+    catch (error) {
+        let reason = error instanceof Error ? error.message : String(error);
+        return failure(new SpecError("tool-error", `Failed to create a test workspace: ${reason}`));
+    }
+    let workspace = {
+        root,
+        resolve(path) {
+            if (isAbsolute(path)) {
+                let resolved = resolvePath(path);
+                let checked = permissions.checkHostFs(resolved);
+                if (isFailure(checked))
+                    return checked;
+                return success(resolved);
+            }
+            let resolved = resolvePath(root, path);
+            if (!isInside(root, resolved))
+                return failure(new WorkspaceEscapeError(path));
+            let ancestor = deepestExistingAncestor(resolved);
+            let realAncestor;
+            try {
+                realAncestor = realpathSync(ancestor);
+            }
+            catch {
+                return failure(new WorkspaceEscapeError(path));
+            }
+            let followed = realAncestor + resolved.slice(ancestor.length);
+            if (!isInside(root, followed))
+                return failure(new WorkspaceEscapeError(path));
+            return success(resolved);
+        },
+        async cleanup() {
+            try {
+                await rm(root, { recursive: true, force: true });
+            }
+            catch { }
+            return undefined;
+        },
+    };
+    return success(workspace);
+}
+/**
+ * Walk up from a resolved path to the deepest component that exists on disk
+ * (symlinks count as existing without being followed), so symlinked ancestors
+ * can be re-resolved before the containment check.
+ *
+ * @param path - An absolute, syntactically resolved path.
+ * @returns The deepest existing ancestor, at worst the filesystem root.
+ */
+function deepestExistingAncestor(path) {
+    let current = path;
+    while (!entryExists(current)) {
+        let parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return current;
+}
+/**
+ * Does a filesystem entry exist at this path, without following symlinks?
+ *
+ * @param path - The absolute path to probe.
+ * @returns Whether lstat finds an entry there.
+ */
+function entryExists(path) {
+    try {
+        lstatSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Path-segment-aware containment test: the root contains itself and its
+ * descendants, never a sibling that merely shares a name prefix.
+ *
+ * @param root - The workspace root, already an absolute real path.
+ * @param path - The absolute path being checked.
+ * @returns Whether the path stays inside the root.
+ */
+function isInside(root, path) {
+    if (path === root)
+        return true;
+    let prefix = root.endsWith(sep) ? root : root + sep;
+    return path.startsWith(prefix);
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+	"name": "@sdxc/spec",
+	"version": "0.0.0-pre.1",
+	"description": "Executable specification runner for .spec files",
+	"license": "MIT",
+	"bin": {
+		"spec": "dist/cli.js"
+	},
+	"type": "module",
+	"exports": {
+		".": "./dist/index.js",
+		"./workers": "./dist/workers.js"
+	},
+	"dependencies": {
+		"@sdxc/duration": "0.0.0-pre.1",
+		"@sdxc/result": "0.0.0-pre.1",
+		"@sdxc/sample": "0.0.0-pre.1"
+	},
+	"gitHead": "bbc1db99f3fcc3c903251a70582c6b0cf8e808cb",
+	"publishConfig": {
+		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/sergiodxa/monorepo.git",
+		"directory": "packages/spec"
+	}
+}