@decohere/core 0.0.1-dev.126 → 0.0.1-dev.5

package/{types/src/extensibility/step.d.ts → src/extensibility/step.ts}

@@ -1,5 +1,6 @@
 import type { Constructable } from "../reflection/index.js";
 import type { PipelineStep } from "./pipeline.js";
+
 /**
  * Wraps a pipeline step with an optional `when` predicate.
  * When `when` is provided, the step only runs if `when(ctx)` returns `true`.
@@ -9,8 +10,9 @@ import type { PipelineStep } from "./pipeline.js";
  * Predicates are declared in the command constructor via `addDisableStepOption`,
  * keeping skip conditions co-located with the option that controls them.
  */
-export declare class Step<T extends Record<string, unknown> = Record<string, unknown>> {
-    readonly type: Constructable<PipelineStep<T>>;
-    readonly when?: (ctx: T) => boolean;
-    constructor(type: Constructable<PipelineStep<T>>, when?: (ctx: T) => boolean);
+export class Step<T extends Record<string, unknown> = Record<string, unknown>> {
+	public constructor(
+		public readonly type: Constructable<PipelineStep<T>>,
+		public readonly when?: (ctx: T) => boolean,
+	) {}
 }

package/src/interop/docker/docker.ts

@@ -0,0 +1,57 @@
+import { InteropError } from "../errors/interop.error.js";
+import { Shell } from "../shell/shell.js";
+
+export type DockerBuildOptions = {
+	cwd?: string;
+	dockerfile?: string;
+	tags?: string[];
+	buildArgs?: Record<string, string>;
+	secrets?: Record<string, string>;
+	noCache?: boolean;
+	pull?: boolean;
+};
+
+export type DockerPushOptions = {
+	cwd?: string;
+};
+
+export class Docker extends Shell {
+	public readonly name = "docker" as const;
+	protected program = "docker";
+
+	public async build(contextDir: string, options: DockerBuildOptions = {}) {
+		if (contextDir == null || contextDir.trim() === "") {
+			throw new InteropError("Docker build context is required");
+		}
+
+		const args = ["build"];
+		if (options.dockerfile) {
+			args.push("-f", options.dockerfile);
+		}
+		for (const tag of options.tags ?? []) {
+			args.push("-t", tag);
+		}
+		for (const [key, value] of Object.entries(options.buildArgs ?? {})) {
+			args.push("--build-arg", `${key}=${value}`);
+		}
+		for (const [id, env] of Object.entries(options.secrets ?? {})) {
+			args.push("--secret", `id=${id},env=${env}`);
+		}
+		if (options.noCache) {
+			args.push("--no-cache");
+		}
+		if (options.pull) {
+			args.push("--pull");
+		}
+		args.push(contextDir);
+		return await this.run({ cwd: options.cwd }, ...args);
+	}
+
+	public async push(tag: string, options: DockerPushOptions = {}) {
+		if (tag == null || tag.trim() === "") {
+			throw new InteropError("Docker tag is required");
+		}
+
+		return await this.run({ cwd: options.cwd }, "push", tag);
+	}
+}

package/src/interop/errors/interop.error.ts

@@ -0,0 +1 @@
+export class InteropError extends Error {}

package/src/interop/git/git.ts

@@ -0,0 +1,98 @@
+import { InteropError } from "../errors/interop.error.js";
+import { Shell } from "../shell/shell.js";
+import type { ShellResponse } from "../shell/shell.types.js";
+import type { CommitOptions, GitOptions, PushOptions, StageOptions } from "./git.types.js";
+
+const Commands = {
+	stage: "stage",
+	tag: "tag",
+	add: "add",
+	commit: "commit",
+	push: "push",
+	listFiles: "ls-files",
+};
+
+const defaultOptions: GitOptions = { cwd: "./" };
+
+export class Git extends Shell {
+	protected program: string = "git";
+	public async getModifiedFiles(options: GitOptions = defaultOptions) {
+		const args = [Commands.listFiles, "--modified"];
+		const { cwd } = options;
+		const result = await this.run({ cwd }, ...args);
+		return result.data;
+	}
+
+	public async getBranchName(options: GitOptions = defaultOptions) {
+		const { cwd } = options;
+		const args = ["rev-parse", "--symbolic-full-name", "--abbrev-ref", "HEAD"];
+		const result = await this.run({ cwd }, ...args);
+		return result.data[0];
+	}
+
+	public async tag(tag: string, options: GitOptions = defaultOptions) {
+		const args = [Commands.tag, tag];
+		const { cwd } = options;
+		const result = await this.run({ cwd }, ...args);
+		return result;
+	}
+
+	public async pushTag(
+		tag: string,
+		options: GitOptions & { remote?: string } = defaultOptions,
+	) {
+		const { cwd, remote = "origin" } = options;
+		const result = await this.run({ cwd }, Commands.push, remote, tag);
+		return result;
+	}
+
+	public async commit(message: string, options: CommitOptions): Promise<ShellResponse> {
+		const optionsAndDefaults = { ...defaultOptions, ...options };
+		const { cwd, files = [], all } = optionsAndDefaults;
+		const args = [Commands.commit];
+
+		if (files.length > 0 && all) {
+			throw new InteropError("Cannot commit all and files at the same time");
+		}
+
+		if (files.length > 0) {
+			await this.stage({ files });
+		}
+
+		if (options.all) {
+			args.push("-a");
+		}
+
+		args.push("-m", message);
+		const result = await this.run({ cwd }, ...args);
+		return result;
+	}
+
+	public async push(branch: string, options?: PushOptions) {
+		const optionsAndDefaults = { ...defaultOptions, ...options };
+		const { cwd, setUpstream } = optionsAndDefaults;
+		const args = [Commands.push];
+		args.push("--set-upstream", setUpstream ?? "origin");
+		args.push(branch);
+		const result = await this.run({ cwd }, ...args);
+		return result;
+	}
+
+	public async pull(branch: string, options: GitOptions = defaultOptions) {
+		const { cwd } = options;
+		return this.run({ cwd }, "pull", "--rebase", "origin", branch);
+	}
+
+	public async stage(options: StageOptions) {
+		const optionsAndDefaults = { ...defaultOptions, ...options };
+		const { cwd, files = [], all } = optionsAndDefaults;
+		if (all) {
+			await this.run({ cwd }, Commands.stage, "-a");
+			return;
+		}
+
+		for (const file of files) {
+			await this.run({ cwd }, Commands.stage, file);
+		}
+	}
+}

package/src/interop/git/git.types.ts

@@ -0,0 +1,17 @@
+export type GitOptions = {
+	cwd?: string;
+};
+
+export type CommitOptions = {
+	files?: string[];
+	all?: boolean;
+} & GitOptions;
+
+export type PushOptions = {
+	setUpstream: string;
+} & GitOptions;
+
+export type StageOptions = {
+	files?: string[];
+	all?: string;
+};

package/src/interop/index.ts

@@ -0,0 +1,22 @@
+// << Git >>
+
+// << Docker >>
+export * from "./docker/docker.js";
+export * from "./git/git.js";
+export * as git from "./git/git.types.js";
+// << Node >>
+export * from "./node/node.js";
+// << Npm >>
+export * from "./npm/npm.js";
+export * as npm from "./npm/npm.types.js";
+// << Pnpm >>
+export * from "./pnpm/pnpm.js";
+export * as pnpm from "./pnpm/pnpm.types.js";
+// << Shell >>
+export * from "./shell/shell.js";
+export * as shell from "./shell/shell.types.js";
+export * from "./types/detect-package-manager.js";
+export * from "./types/package-manager.js";
+// << Yarn >>
+export * from "./yarn/yarn.js";
+export * as yarn from "./yarn/yarn.types.js";

package/src/interop/node/index.ts

@@ -0,0 +1 @@
+export * from "./node.js";

package/src/interop/node/node.ts

@@ -0,0 +1,38 @@
+import { type SpawnOptions, spawn } from "node:child_process";
+import { Shell } from "../shell/shell.js";
+
+export class Node extends Shell {
+	protected program: string = "node";
+
+	public async runScript(script: string, ...args: string[]) {
+		const spawnOpt: SpawnOptions = {
+			cwd: ".",
+			stdio: "inherit",
+			env: {
+				...process.env,
+			},
+		};
+
+		return new Promise((resolve, reject) => {
+			const proc = spawn("node", [script, ...args], spawnOpt);
+
+			proc.on("exit", (code) => {
+				if (code !== 0) {
+					reject();
+				}
+
+				resolve(null);
+			});
+
+			proc.on("close", (code) => {
+				resolve(null);
+				if (code === 0) {
+					resolve({
+						message: `${script} completed`,
+					});
+				}
+				reject(`Running '${script}' failed with code ${code}`);
+			});
+		});
+	}
+}

package/src/interop/npm/npm.ts

@@ -0,0 +1,168 @@
+import { InteropError } from "../errors/interop.error.js";
+import { Shell } from "../shell/shell.js";
+import type { PackageManager } from "../types/package-manager.js";
+import type { NpmOptions, PublishOptions, VersionOptions, VersionType } from "./npm.types.js";
+
+const Commands = {
+	publish: "publish",
+	version: "version",
+	link: "link",
+	install: "install",
+};
+
+export class Npm extends Shell implements PackageManager {
+	public readonly name = "npm" as const;
+	protected program: string = "npm";
+
+	public async publish(directory: string, options: PublishOptions = { channel: "beta" }) {
+		const { cwd, dryRun, skipIfPublished, channel, authToken, otp, provenance } = options;
+		if (directory == null) {
+			throw new InteropError("Directory is required");
+		}
+
+		if (skipIfPublished && !dryRun) {
+			const alreadyPublished = await this.isPublished(directory, { cwd });
+			if (alreadyPublished) {
+				return { message: `Skipping publish — version already exists on registry`, data: [] };
+			}
+		}
+
+		const args = [Commands.publish, directory];
+		let tmpUserConfigPath: string | undefined;
+
+		args.push("--tag", channel ?? "beta");
+
+		if (provenance) {
+			args.push("--provenance");
+		}
+
+		// Explicit --token (local bootstrap). OIDC publish must not inherit cwd .npmrc / NODE_AUTH_TOKEN.
+		if (authToken?.trim()) {
+			tmpUserConfigPath = await this.createTempUserConfig(authToken.trim());
+			args.push("--userconfig", tmpUserConfigPath);
+		}
+
+		if (dryRun) {
+			args.push("--dry-run");
+		}
+
+		const env = { ...process.env };
+		if (!authToken?.trim()) {
+			delete env.NODE_AUTH_TOKEN;
+			delete env.NPM_TOKEN;
+			env.NPM_CONFIG_USERCONFIG = "/dev/null";
+		}
+		if (otp) {
+			env.NPM_CONFIG_OTP = otp;
+		}
+
+		try {
+			return await this.run({ cwd, env }, ...args);
+		} catch (error) {
+			if (skipIfPublished && !dryRun && isAlreadyPublishedError(error)) {
+				return { message: `Skipping publish — version already exists on registry`, data: [] };
+			}
+			throw error;
+		} finally {
+			if (tmpUserConfigPath) {
+				await this.removeTempUserConfig(tmpUserConfigPath);
+			}
+		}
+	}
+
+	/**
+	 * @description Runs in the directory of the package
+	 * @param options
+	 * @returns
+	 */
+	public async version(versionType: VersionType, options: VersionOptions) {
+		const { cwd, noTag, preid } = options;
+		const args = [Commands.version, versionType];
+		if (noTag) {
+			args.push("--no-git-tag-version");
+		}
+
+		if (preid) {
+			args.push("--preid", preid);
+		}
+
+		return this.run({ cwd }, ...args);
+	}
+
+	public async link(directory: string, options: NpmOptions = { cwd: "./" }) {
+		const { cwd } = options;
+		const args = [Commands.link, directory];
+		return this.run({ cwd }, ...args);
+	}
+
+	public async install(options: NpmOptions = { cwd: "./" }) {
+		const { cwd } = options;
+		return this.run({ cwd }, Commands.install);
+	}
+
+	/**
+	 * Install only `dependencies` as real folders: `--omit=dev` skips devDependencies and
+	 * `--no-bin-links` skips the `.bin` symlinks, so the result holds no symlinks at all.
+	 */
+	public async installProduction(options: NpmOptions = { cwd: "./" }) {
+		const { cwd } = options;
+		return this.run(
+			{ cwd },
+			Commands.install,
+			"--omit=dev",
+			"--no-bin-links",
+			"--no-audit",
+			"--no-fund",
+			"--loglevel=error",
+		);
+	}
+
+	public async syncLockFile(options: NpmOptions = { cwd: "./" }) {
+		const { cwd } = options;
+		return this.run({ cwd }, Commands.install, "--package-lock-only", "--ignore-scripts");
+	}
+
+	/**
+	 * True when package@version exists on the registry.
+	 * Uses ambient npm config (cwd `.npmrc`); do not pass tokens on argv.
+	 */
+	private async isPublished(directory: string, options: NpmOptions): Promise<boolean> {
+		const { readFileSync } = await import("node:fs");
+		const { join } = await import("node:path");
+		try {
+			const pkgJson = JSON.parse(readFileSync(join(directory, "package.json"), "utf8"));
+			const spec = `${pkgJson.name}@${pkgJson.version}`;
+			await this.run(options, "view", spec, "version");
+			return true;
+		} catch {
+			return false;
+		}
+	}
+
+	private async createTempUserConfig(authToken: string): Promise<string> {
+		const { mkdtemp, writeFile } = await import("node:fs/promises");
+		const { tmpdir } = await import("node:os");
+		const { join } = await import("node:path");
+		const tempDir = await mkdtemp(join(tmpdir(), "decohere-npmrc-"));
+		const npmrcPath = join(tempDir, ".npmrc");
+		const npmrc = [
+			"registry=https://registry.npmjs.org/",
+			"always-auth=true",
+			`//registry.npmjs.org/:_authToken=${authToken}`,
+		].join("\n");
+		await writeFile(npmrcPath, `${npmrc}\n`, { mode: 0o600 });
+		return npmrcPath;
+	}
+
+	private async removeTempUserConfig(npmrcPath: string): Promise<void> {
+		const { rm } = await import("node:fs/promises");
+		const { dirname } = await import("node:path");
+		const dir = dirname(npmrcPath);
+		await rm(dir, { recursive: true, force: true });
+	}
+}
+
+function isAlreadyPublishedError(error: unknown): boolean {
+	const message = error instanceof Error ? error.message : String(error);
+	return /cannot publish over the previously published versions/i.test(message);
+}

package/src/interop/npm/npm.types.ts

@@ -0,0 +1,28 @@
+export type NpmOptions = {
+	cwd?: string;
+};
+
+export type PublishOptions = {
+	dryRun?: boolean;
+	skipIfPublished?: boolean;
+	authToken?: string;
+	otp?: string;
+	provenance?: boolean;
+	/** @deprecated use channel */
+	versionType?: VersionType;
+	channel?: string;
+} & NpmOptions;
+
+export type VersionType = "major" | "minor" | "patch" | "prerelease";
+
+export const VersionTypes = {
+	major: "major",
+	minor: "minor",
+	patch: "patch",
+	prerelease: "prerelease",
+} satisfies Record<VersionType, VersionType>;
+
+export type VersionOptions = {
+	preid?: string;
+	noTag?: boolean;
+} & NpmOptions;

package/src/interop/pnpm/pnpm.ts

@@ -0,0 +1,22 @@
+import { Shell } from "../shell/shell.js";
+import type { PackageManager } from "../types/package-manager.js";
+import type { PnpmOptions } from "./pnpm.types.js";
+
+const Commands = {
+	install: "install",
+};
+
+export class Pnpm extends Shell implements PackageManager {
+	public readonly name = "pnpm" as const;
+	protected program: string = "pnpm";
+
+	public async install(options: PnpmOptions = { cwd: "./" }) {
+		const { cwd } = options;
+		return this.run({ cwd }, Commands.install);
+	}
+
+	public async syncLockFile(options: PnpmOptions = { cwd: "./" }) {
+		const { cwd } = options;
+		return this.run({ cwd }, Commands.install, "--lockfile-only", "--ignore-scripts");
+	}
+}

package/src/interop/pnpm/pnpm.types.ts

@@ -0,0 +1,3 @@
+export type PnpmOptions = {
+	cwd?: string;
+};

package/src/interop/shell/shell.argv.ts

@@ -0,0 +1,31 @@
+function fields(args: string[]): Record<string, string | boolean | string[]> {
+	const positional: string[] = [];
+	const flags: Record<string, string | boolean> = {};
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+		if (arg === "--") {
+			positional.push(...args.slice(i + 1));
+			break;
+		}
+		if (arg.startsWith("--")) {
+			const body = arg.slice(2);
+			const eq = body.indexOf("=");
+			if (eq !== -1) {
+				flags[body.slice(0, eq)] = body.slice(eq + 1);
+				continue;
+			}
+			const next = args[i + 1];
+			if (next != null && !next.startsWith("-")) {
+				flags[body] = next;
+				i += 1;
+			} else {
+				flags[body] = true;
+			}
+			continue;
+		}
+		positional.push(arg);
+	}
+	return { _: positional, ...flags };
+}
+
+export const shellArgv = { fields };

package/src/interop/shell/shell.ts

@@ -0,0 +1,100 @@
+import { type SpawnOptions, spawn } from "node:child_process";
+import { scribe } from "@decohere/scribe";
+import { InteropError } from "../errors/interop.error.js";
+import { shellArgv } from "./shell.argv.js";
+import type { ShellOptions, ShellResponse } from "./shell.types.js";
+
+export abstract class Shell {
+	protected abstract program: string;
+	protected async run(options: ShellOptions, ...args: string[]) {
+		const logger = scribe.logger(Shell.name);
+		const argv = args ?? [];
+		const argvFields = shellArgv.fields(argv);
+		const positionals = Array.isArray(argvFields._) ? argvFields._ : [];
+		const commandName = [this.program, ...positionals].join(" ").trim();
+		logger.info("Running", { program: this.program, args: argvFields });
+		return new Promise<ShellResponse>((resolve, reject) => {
+			let settled = false;
+			const resolveOnce = (response: ShellResponse) => {
+				if (settled) {
+					return;
+				}
+				settled = true;
+				resolve(response);
+			};
+
+			const rejectOnce = (error: unknown) => {
+				if (settled) {
+					return;
+				}
+				settled = true;
+				reject(error);
+			};
+
+			const { cwd, env } = options;
+			const spawnOpt: SpawnOptions = {
+				cwd: cwd ?? ".",
+				stdio: ["inherit", "pipe", "pipe"],
+				env: env ?? { ...process.env },
+			};
+
+			const proc = spawn(this.program, argv, spawnOpt);
+			const responseData: string[] = [];
+			const errorData: string[] = [];
+
+			proc.on("close", (code, signal) => {
+				if (code === 0) {
+					resolveOnce({
+						message: `${commandName} completed`,
+						data: responseData,
+					});
+					return;
+				}
+
+				const stderr = errorData.join("\n").trim();
+				const stdout = responseData.join("\n").trim();
+				const exitCodeText = code == null ? "unknown" : String(code);
+				const signalText = signal ? ` signal ${signal}` : "";
+				const base = `Running '${commandName}' failed with code ${exitCodeText}${signalText}`;
+				const details = [
+					stderr ? `stderr:\n${stderr}` : "",
+					!stderr && stdout ? `stdout:\n${stdout}` : "",
+				]
+					.filter(Boolean)
+					.join("\n");
+
+				rejectOnce(new InteropError(details ? `${base}\n${details}` : base));
+			});
+
+			proc.on("error", (err) => {
+				rejectOnce(err);
+			});
+
+			proc.stdout.on("error", (err) => {
+				rejectOnce(err);
+			});
+
+			proc.stdout.on("data", (data) => {
+				const lines = this.parseStream(data);
+				console.log(data.toString());
+				responseData.push(...lines);
+			});
+
+			proc.stderr?.on("error", (err) => {
+				rejectOnce(err);
+			});
+
+			proc.stderr?.on("data", (data) => {
+				const lines = this.parseStream(data);
+				console.error(data.toString());
+				errorData.push(...lines);
+			});
+		});
+	}
+
+	private parseStream(data: Buffer | string) {
+		const dataStr: string = data.toString();
+		const lines = dataStr.split("\n").filter((l) => l !== "");
+		return lines;
+	}
+}

package/src/interop/shell/shell.types.ts

@@ -0,0 +1,9 @@
+export type ShellResponse = {
+	message: string;
+	data: string[];
+};
+export interface ShellOptions {
+	cwd?: string;
+	/** Spawn env. Defaults to `process.env`. Not written to logs. */
+	env?: NodeJS.ProcessEnv;
+}

package/src/interop/types/detect-package-manager.ts

@@ -0,0 +1,45 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { Npm } from "../npm/npm.js";
+import { Pnpm } from "../pnpm/pnpm.js";
+import { Yarn } from "../yarn/yarn.js";
+import type { PackageManager } from "./package-manager.js";
+
+const LOCKFILES: Array<[string, () => PackageManager]> = [
+	["pnpm-lock.yaml", () => new Pnpm()],
+	["yarn.lock", () => new Yarn()],
+	["package-lock.json", () => new Npm()],
+];
+
+function fromLockfile(cwd: string): PackageManager | undefined {
+	for (const [file, factory] of LOCKFILES) {
+		if (existsSync(join(cwd, file))) return factory();
+	}
+	return undefined;
+}
+
+function fromUserAgent(): PackageManager | undefined {
+	const agent = process.env.npm_config_user_agent ?? "";
+	if (agent.startsWith("pnpm")) return new Pnpm();
+	if (agent.startsWith("yarn")) return new Yarn();
+	if (agent.startsWith("npm")) return new Npm();
+	return undefined;
+}
+
+export function detectPackageManager(cwd: string): PackageManager | undefined {
+	return fromLockfile(cwd) ?? fromUserAgent();
+}
+
+export function packageManagerFromString(name: string): PackageManager {
+	if (name === "yarn") return new Yarn();
+	if (name === "npm") return new Npm();
+	return new Pnpm();
+}
+
+export async function promptForPackageManager(): Promise<PackageManager> {
+	const rl = createInterface({ input: process.stdin, output: process.stdout });
+	const answer = await rl.question("Package manager? [pnpm/yarn/npm] (default: pnpm): ");
+	rl.close();
+	return packageManagerFromString(answer.trim().toLowerCase());
+}

package/src/interop/types/package-manager.ts

@@ -0,0 +1,7 @@
+import type { ShellResponse } from "../shell/shell.types.js";
+
+export interface PackageManager {
+	readonly name: "npm" | "pnpm" | "yarn";
+	install(options?: { cwd?: string }): Promise<ShellResponse>;
+	syncLockFile(options?: { cwd?: string }): Promise<ShellResponse>;
+}