pi-harness-runtime 1.1.427 → 1.1.429

package/scripts/lib/runtime-imports.ts

@@ -0,0 +1,263 @@
+/**
+ * Resolve the relative imports of a published file.
+ *
+ * The published package is a single app: every internal package lives in
+ * `packages/<name>/` and the runtime reaches it through relative paths. A
+ * relative import that does not resolve is a broken module graph, and a
+ * consumer finds out when the import runs - long after the release.
+ *
+ * The check that used to guard this only followed specifiers that contained
+ * "packages/", so an import inside a package (`./locks.js`) was never
+ * looked at, and the compiled output was never scanned at all. That gap
+ * let a package whose entry point could not be imported ship.
+ *
+ * The rules:
+ *
+ *   1. A TYPE-only import is erased at runtime, so it does not need a
+ *      runtime target. It is skipped.
+ *   2. Comments are removed before the scan, so a commented-out import is
+ *      not a broken import. The same holds for text inside a string or a
+ *      template literal: documentation that shows an import is not an
+ *      import.
+ *   3. A relative import resolves when the target file exists:
+ *        - the specifier as written (`./x.js` -> `x.js`),
+ *        - the TypeScript source of a `.js` specifier (`./x.js` -> `x.ts`),
+ *          because the compiler and the Bun runtime map it, or
+ *        - a directory entry point (`./x` -> `x/index.js`).
+ *   4. A compiled file (`.js`) must reach a file that is PUBLISHED. A
+ *      TypeScript source (`.ts`) is resolved at compile time, so it may
+ *      reach a source file in the repository.
+ *   5. A bare import that names a WORKSPACE package cannot resolve: the
+ *      workspace packages ship inside this one tarball and are never
+ *      installed as separate packages, so the name does not exist at
+ *      runtime. Such an import must point at the built artifact instead.
+ */
+
+import { existsSync, statSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+
+/** The quoting state of the scanner. */
+type Quote = "" | '"' | "'" | "`";
+
+/** A source with its comments removed and its string content marked. */
+export interface ScannedSource {
+	/** The source without its comments. */
+	code: string;
+	/**
+	 * Whether the character at the given index of {@link code} is code.
+	 *
+	 * The content of a string or a template literal is not code, so an
+	 * import that only appears inside one is documentation, not an import.
+	 */
+	isCodeAt: (index: number) => boolean;
+}
+
+/**
+ * Remove the comments from a source file and mark its string content.
+ *
+ * A string or a template literal may contain something that looks like a
+ * comment, so the scanner tracks the quoting state instead of using a
+ * regular expression.
+ */
+export function scanSource(source: string): ScannedSource {
+	let code = "";
+	const isCode: boolean[] = [];
+	let i = 0;
+	let quote: Quote = "";
+
+	const emit = (char: string, isCodeChar: boolean) => {
+		code += char;
+		isCode.push(isCodeChar);
+	};
+
+	while (i < source.length) {
+		const char = source[i];
+		const next = source[i + 1];
+
+		if (quote) {
+			// The content of a literal is not code. The quotes are.
+			emit(char, char === quote && source[i - 1] !== "\\");
+			if (char === "\\") {
+				// An escaped character cannot end the literal.
+				emit(next ?? "", false);
+				i += 2;
+				continue;
+			}
+			if (char === quote) quote = "";
+			i += 1;
+			continue;
+		}
+
+		if (char === '"' || char === "'" || char === "`") {
+			quote = char;
+			emit(char, true);
+			i += 1;
+			continue;
+		}
+
+		if (char === "/" && next === "/") {
+			// A line comment runs to the end of the line.
+			while (i < source.length && source[i] !== "\n") i += 1;
+			continue;
+		}
+
+		if (char === "/" && next === "*") {
+			// A block comment runs to its closing marker.
+			const end = source.indexOf("*/", i + 2);
+			if (end === -1) {
+				i = source.length;
+				break;
+			}
+			// Keep the newlines, so a line number stays meaningful.
+			for (let k = i; k < end; k += 1) {
+				if (source[k] === "\n") emit("\n", false);
+			}
+			i = end + 2;
+			continue;
+		}
+
+		emit(char, true);
+		i += 1;
+	}
+
+	return { code, isCodeAt: (index: number) => isCode[index] === true };
+}
+
+/**
+ * Remove the comments from a source file.
+ */
+export function stripComments(source: string): string {
+	return scanSource(source).code;
+}
+
+/** The import forms that carry a specifier. */
+const IMPORT_PATTERNS: RegExp[] = [
+	// import ... from "..." / export ... from "..."
+	/(?:^|[\n;])[ \t]*(import|export)\s+(type\s+)?[^;\n]*?from\s*["']([^"']+)["']/g,
+	// import "..." (side effect)
+	/(?:^|[\n;])[ \t]*import\s*["']([^"']+)["']/g,
+	// import("...") (dynamic)
+	/import\s*\(\s*["']([^"']+)["']\s*\)/g,
+];
+
+/**
+ * Every VALUE import of a source file.
+ *
+ * A type-only import is skipped: `import type { X } from "..."` is erased
+ * by the compiler and never reaches the runtime. An import that only
+ * appears inside a string or a template literal is skipped as well: that
+ * is documentation, not an import.
+ */
+export function extractValueImports(source: string): string[] {
+	const { code, isCodeAt } = scanSource(source);
+	const specifiers: string[] = [];
+
+	for (const pattern of IMPORT_PATTERNS) {
+		for (const match of code.matchAll(pattern)) {
+			// The match must start in code, not inside a literal.
+			if (match.index === undefined || !isCodeAt(match.index)) continue;
+			// `type` marks an import that the compiler erases.
+			if (match[2] && match[2].trim() === "type") continue;
+			const specifier = match[3] ?? match[1];
+			if (!specifier) continue;
+			specifiers.push(specifier);
+		}
+	}
+
+	return [...new Set(specifiers)];
+}
+
+/**
+ * Every RELATIVE value import of a source file.
+ */
+export function extractRelativeValueImports(source: string): string[] {
+	return extractValueImports(source).filter((specifier) => specifier.startsWith("."));
+}
+
+/**
+ * Every BARE value import of a source file.
+ *
+ * A bare import names a package, not a file in this repository.
+ */
+export function extractBareImports(source: string): string[] {
+	return extractValueImports(source).filter((specifier) => !specifier.startsWith("."));
+}
+
+/**
+ * The package a specifier names.
+ *
+ * `@scope/name/sub/path` and `name/sub/path` both name `@scope/name` and
+ * `name`.
+ */
+export function packageNameOf(specifier: string): string {
+	if (specifier.startsWith("@")) return specifier.split("/").slice(0, 2).join("/");
+	return specifier.split("/")[0];
+}
+
+/**
+ * The files a relative specifier may point at.
+ *
+ * The candidates are absolute paths, most specific first.
+ */
+export function importTargetCandidates(
+	importer: string,
+	specifier: string,
+): string[] {
+	const base = resolve(dirname(importer), specifier);
+	const candidates = [base];
+	if (base.endsWith(".js")) candidates.push(`${base.slice(0, -3)}.ts`);
+	candidates.push(`${base}.js`, `${base}.ts`);
+	candidates.push(`${base}/index.js`, `${base}/index.ts`);
+	return [...new Set(candidates)];
+}
+
+/** The result of resolving one relative import. */
+export interface ResolvedImport {
+	ok: boolean;
+	/** The file the import points at, when one was found. */
+	target?: string;
+	/** Why the import does not resolve. */
+	reason?: string;
+}
+
+/** The options of {@link resolveRelativeImport}. */
+export interface ResolveOptions {
+	/** Absolute path of the importing file. */
+	importer: string;
+	/** The relative specifier. */
+	specifier: string;
+	/** Existence test, overridable for a test. */
+	exists?: (path: string) => boolean;
+	/** Publication test, overridable for a test. */
+	isPublished?: (path: string) => boolean;
+}
+
+/**
+ * Resolve one relative import.
+ */
+export function resolveRelativeImport({
+	importer,
+	specifier,
+	exists = existsSync,
+	isPublished = () => true,
+}: ResolveOptions): ResolvedImport {
+	const candidates = importTargetCandidates(importer, specifier);
+	const found = candidates.find((candidate) => {
+		try {
+			return exists(candidate) && statSync(candidate).isFile();
+		} catch {
+			return false;
+		}
+	});
+	if (!found) {
+		return { ok: false, reason: "the target does not exist" };
+	}
+	// A compiled file has to reach a published file: a consumer never sees
+	// the repository. A TypeScript source is resolved by the compiler, so it
+	// may point at a source file in the repository.
+	const isCompiled = /\.(js|mjs|cjs)$/.test(importer);
+	if (isCompiled && !isPublished(found)) {
+		return { ok: false, target: found, reason: "the target is not published" };
+	}
+	return { ok: true, target: found };
+}

package/scripts/verify-package-contents.ts

@@ -30,6 +30,12 @@ import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { execFile, spawnSync } from "node:child_process";
 import { join, resolve, dirname, relative } from "node:path";
 import { fileURLToPath } from "node:url";
+import {
+	extractBareImports,
+	extractRelativeValueImports,
+	packageNameOf,
+	resolveRelativeImport,
+} from "./lib/runtime-imports.js";
 
 const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const verifyTarball = process.argv.includes("--pack");
@@ -38,6 +44,7 @@ interface Problem {
 	kind:
 		| "missing-dist"
 		| "missing-import"
+		| "broken-import"
 		| "missing-tarball"
 		| "missing-package"
 		| "forbidden-path"
@@ -406,8 +413,13 @@ function checkStaleOutputs(): void {
 	}
 }
 
-/** The tarball npm would publish must contain the built output. */
-async function inspectTarball(): Promise<void> {
+/**
+ * The files npm would publish.
+ *
+ * The list comes from npm itself, so a check sees exactly what a consumer
+ * gets - not what the repository happens to contain.
+ */
+async function packFileList(): Promise<string[]> {
 	const stdout = await new Promise<string>((resolveText, rejectText) => {
 		execFile(
 			"npm",
@@ -423,29 +435,99 @@ async function inspectTarball(): Promise<void> {
 		);
 	});
 
-	let files: string[] = [];
 	try {
 		// `npm pack --json` returns an array with one entry per packed tarball.
 		const parsed = JSON.parse(stdout) as
 			| { files?: { path: string }[] }[]
 			| { files?: { path: string }[] };
 		const entries = Array.isArray(parsed) ? parsed : [parsed];
-		files = entries.flatMap((entry) => entry?.files ?? []).map((file) => file.path);
-		if (files.length === 0) {
+		return entries.flatMap((entry) => entry?.files ?? []).map((file) => file.path);
+	} catch {
+		return [];
+	}
+}
+
+/**
+ * The names of the workspace packages.
+ *
+ * The workspace packages ship inside this one tarball and are never
+ * installed as separate packages, so a bare import that names one of them
+ * cannot resolve at runtime - not in a consumer's installation, and not in
+ * the repository either, because the workspace is never linked into
+ * `node_modules` under its own name.
+ */
+function workspacePackageNames(): Set<string> {
+	const names = new Set<string>();
+	const packagesDir = join(ROOT, "packages");
+	if (!existsSync(packagesDir)) return names;
+	for (const name of readdirSync(packagesDir)) {
+		const manifestPath = join(packagesDir, name, "package.json");
+		if (!existsSync(manifestPath)) continue;
+		try {
+			const manifest = JSON.parse(readFileSync(manifestPath, "utf8")) as {
+				name?: string;
+			};
+			if (manifest.name) names.add(manifest.name);
+		} catch {
+			// A manifest that cannot be read names no package.
+		}
+	}
+	return names;
+}
+
+/**
+ * Every relative import of a published file must resolve.
+ *
+ * The published app reaches its internal packages through relative paths,
+ * so an import that does not resolve is a module graph that breaks when it
+ * runs. A published `.js` file has to reach a published file: a consumer
+ * never sees the repository. A published `.ts` file is resolved by the
+ * compiler, so it may reach a source file in the repository.
+ *
+ * The earlier import check only followed specifiers that contained
+ * "packages/" and never looked at the compiled output, so an import inside
+ * a package was never verified. That is how a package whose entry point
+ * could not be imported reached the registry.
+ */
+function checkRelativeImports(files: string[]): void {
+	const published = new Set(files);
+	const workspaceNames = workspacePackageNames();
+	for (const path of files) {
+		if (!/\.(ts|mts|cts|mjs|js|cjs)$/.test(path)) continue;
+		if (path.endsWith(".d.ts") || path.endsWith(".d.mts")) continue;
+		const full = join(ROOT, path);
+		if (!existsSync(full)) continue;
+		const content = readFileSync(full, "utf8");
+		for (const specifier of extractRelativeValueImports(content)) {
+			const result = resolveRelativeImport({
+				importer: full,
+				specifier,
+				exists: existsSync,
+				isPublished: (candidate) =>
+					published.has(relative(ROOT, candidate).split("\\").join("/")),
+			});
+			if (result.ok) continue;
 			problems.push({
-				kind: "missing-tarball",
-				detail: "npm pack --dry-run did not return a file list",
+				kind: "broken-import",
+				detail: `${path} imports ${specifier} but ${result.reason}`,
+			});
+		}
+		// A bare import that names a workspace package names something that
+		// is never installed: the workspace packages are inside this one
+		// tarball. Such an import has to point at the built artifact.
+		for (const specifier of extractBareImports(content)) {
+			const name = packageNameOf(specifier);
+			if (!workspaceNames.has(name)) continue;
+			problems.push({
+				kind: "broken-import",
+				detail: `${path} imports ${specifier} but ${name} is a workspace package: it ships inside this tarball and is never installed, so the name cannot resolve`,
 			});
-			return;
 		}
-	} catch {
-		problems.push({
-			kind: "missing-tarball",
-			detail: "npm pack --dry-run did not return a file list",
-		});
-		return;
 	}
+}
 
+/** The tarball npm would publish must contain the built output. */
+function inspectTarball(files: string[]): void {
 	for (const file of files) {
 		const posix = file.split("\\").join("/");
 		for (const prefix of FORBIDDEN_PACKAGE_PREFIXES) {
@@ -503,7 +585,19 @@ checkPluginCopySource();
 checkImports();
 checkPackageEntries();
 checkStaleOutputs();
-if (verifyTarball) await inspectTarball();
+
+// The published file list drives both the import check and the tarball
+// check: it is what a consumer receives.
+const publishedFiles = await packFileList();
+if (publishedFiles.length === 0) {
+	problems.push({
+		kind: "missing-tarball",
+		detail: "npm pack --dry-run did not return a file list",
+	});
+} else {
+	checkRelativeImports(publishedFiles);
+	if (verifyTarball) inspectTarball(publishedFiles);
+}
 
 if (problems.length > 0) {
 	console.error(`[verify-package-contents] FAILED with ${problems.length} problem(s):`);
@@ -518,7 +612,7 @@ if (problems.length > 0) {
 }
 
 console.log(
-	`[verify-package-contents] OK - ${runtimeImports.size} runtime import(s) resolved${
-		verifyTarball ? ", tarball verified" : ""
-	}`,
+	`[verify-package-contents] OK - ${runtimeImports.size} runtime import(s) resolved, ${
+		publishedFiles.length
+	} published file(s) checked${verifyTarball ? ", tarball verified" : ""}`,
 );

package/packages/telegram/package.json

@@ -1,22 +0,0 @@
-{
-  "name": "@pi-harness/telegram",
-  "version": "1.1.427",
-  "description": "pi-harness-runtime — Telegram inbound/outbound",
-  "type": "module",
-  "main": "./src/index.js",
-  "types": "./src/index.d.ts",
-  "exports": {
-    ".": {
-      "import": "./src/index.js",
-      "types": "./src/index.d.ts"
-    }
-  },
-  "files": [
-    "src"
-  ],
-  "scripts": {
-    "build": "tsc",
-    "test": "bun test"
-  },
-  "dependencies": {}
-}

package/packages/telegram/src/agent-messages.d.ts

@@ -1,28 +0,0 @@
-/**
- * Cross-instance Telegram agent message resolution and turn injection
- * Zones: multi-instance bus, inbound routing, operational delivery
- * Owns live target resolution, source attribution, same-target fencing, and synthetic turn construction; excludes Bot API delivery and bus transport.
- */
-import type { TelegramBusAgentMessage, TelegramBusAgentTargetSelector, TelegramBusFollowerRegistry } from "./bus.ts";
-import type { TelegramTarget } from "./target.ts";
-export interface TelegramAgentMessageRuntimeDeps<TContext, TUpdate> {
-    instanceId: string;
-    getAllowedChatId: () => number | undefined;
-    getLeaderTarget: () => TelegramTarget | undefined;
-    getLeaderThreadName: () => string | undefined;
-    getDisplayTitle?: (target: TelegramTarget) => string | undefined;
-    followerRegistry: TelegramBusFollowerRegistry;
-    getContext: () => TContext | undefined;
-    handleUpdate: (update: TUpdate, ctx: TContext) => Promise<void>;
-    getNowMs?: () => number;
-}
-export declare function createTelegramAgentMessageRuntime<TContext, TUpdate>(deps: TelegramAgentMessageRuntimeDeps<TContext, TUpdate>): {
-    resolveTarget: (selector: TelegramBusAgentTargetSelector, sourceTarget?: TelegramTarget) => (TelegramTarget & {
-        threadId: number;
-    }) | undefined;
-    route(input: {
-        sourceTarget?: TelegramTarget;
-        sourceThreadName?: string;
-        message: TelegramBusAgentMessage;
-    }): Promise<void>;
-};

package/packages/telegram/src/agent-messages.js

@@ -1,90 +0,0 @@
-/**
- * Cross-instance Telegram agent message resolution and turn injection
- * Zones: multi-instance bus, inbound routing, operational delivery
- * Owns live target resolution, source attribution, same-target fencing, and synthetic turn construction; excludes Bot API delivery and bus transport.
- */
-import { TELEGRAM_INTERNAL_AGENT_MESSAGE } from "./updates.js";
-export function createTelegramAgentMessageRuntime(deps) {
-    const getNowMs = deps.getNowMs ?? Date.now;
-    const sameTarget = (left, right) => left?.chatId === right?.chatId && left?.threadId === right?.threadId;
-    const listLiveTargets = () => {
-        const targets = [];
-        const leaderTarget = deps.getLeaderTarget();
-        if (leaderTarget?.threadId) {
-            targets.push({
-                target: {
-                    chatId: leaderTarget.chatId,
-                    threadId: leaderTarget.threadId,
-                },
-                threadName: deps.getDisplayTitle?.(leaderTarget) ?? deps.getLeaderThreadName(),
-            });
-        }
-        for (const follower of deps.followerRegistry.list()) {
-            if (!follower.target?.threadId)
-                continue;
-            targets.push({
-                target: {
-                    chatId: follower.target.chatId,
-                    threadId: follower.target.threadId,
-                },
-                threadName: deps.getDisplayTitle?.(follower.target) ?? follower.threadName,
-            });
-        }
-        return targets;
-    };
-    const resolveTarget = (selector, sourceTarget) => {
-        const allowedChatId = deps.getAllowedChatId();
-        const chatId = selector.chatId ?? allowedChatId;
-        if (chatId === undefined || chatId !== allowedChatId)
-            return undefined;
-        const matches = listLiveTargets().filter((candidate) => {
-            if (candidate.target.chatId !== chatId)
-                return false;
-            if (selector.threadId !== undefined) {
-                return candidate.target.threadId === selector.threadId;
-            }
-            const requestedName = selector.threadName?.trim().toLocaleLowerCase();
-            return (requestedName !== undefined &&
-                requestedName.length > 0 &&
-                candidate.threadName?.trim().toLocaleLowerCase() === requestedName);
-        });
-        if (matches.length !== 1)
-            return undefined;
-        return sameTarget(matches[0].target, sourceTarget)
-            ? undefined
-            : matches[0].target;
-    };
-    return {
-        resolveTarget,
-        async route(input) {
-            const target = resolveTarget({
-                chatId: input.message.target.chatId,
-                threadId: input.message.target.threadId,
-            }, input.sourceTarget);
-            if (!target)
-                throw new Error("Telegram agent target is no longer live.");
-            const allowedChatId = deps.getAllowedChatId();
-            const ctx = deps.getContext();
-            if (allowedChatId === undefined || !ctx) {
-                throw new Error("Telegram agent turn routing is unavailable.");
-            }
-            const sourceTitle = (input.sourceTarget
-                ? deps.getDisplayTitle?.(input.sourceTarget)
-                : undefined) ?? input.sourceThreadName;
-            const sourceLabel = sourceTitle
-                ?.replace(/[\r\n\[\]]+/g, " ")
-                .trim()
-                .slice(0, 64) || "Pi";
-            const message = {
-                message_id: input.message.messageId,
-                date: Math.floor(getNowMs() / 1000),
-                chat: { id: target.chatId, type: "private" },
-                from: { id: allowedChatId, is_bot: false, first_name: "Pi Agent" },
-                message_thread_id: target.threadId,
-                pi_telegram_agent_source_thread: sourceLabel,
-                text: input.message.text,
-            };
-            await deps.handleUpdate({ message, [TELEGRAM_INTERNAL_AGENT_MESSAGE]: true }, ctx);
-        },
-    };
-}