neurastream 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 umiddey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,37 @@
-# Temporary Holding Version
+# neurastream
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Agent orchestration (queue, guards, blockers, scoring, ledger) as one installable package. The core does not name a harness. Adapters translate harness events into core calls. The first adapter is omp.
+
+## Install
+
+Do not install into the real home while this package is still being built. Use a sandbox home.
+
+```sh
+export HOME=/tmp/neurastream-home-dev
+bun add -g neurastream
+neurastream init
+neurastream adapter install omp
+```
+
+`init` writes `~/.config/neurastream/config.yml` from the defaults in `docs/config.md`, plus an empty index, notes, the queue template, blocker wrappers, and the state directories. A second run changes nothing. `adapter install omp` links the extension under that same home (`~/.omp/agent/extensions` and `omp plugin link`). Neither command touches `~/.omp` or `~/.local` of the real user.
+
+Check the merged result:
+
+```sh
+neurastream config --json
+```
+
+Compatibility bins keep today's names (`agent-score`, `agent-ledger`, `brief-lint`, `oc-run`, `wip-check`, `wip-backup`, `wip-snapshot`, `pm-fail-facts`, `main-health`, `queue-check`, `queue-close`, `queue-cancel`, `main-start`, `machine-guard`, `glm-reset`, `priority-watch`, `resource-alerts`, `tmp-snapshot`, `heavy-run`). They are the same program, selected by the bin name.
+
+Green is `bun run typecheck` and `bun test`, both exit 0.
+
+## Changing a script
+
+Edit the script in this repo. Green is `bun run typecheck` and `bun test`, both exit 0. Main tags the release. The publish workflow puts that tag on npm. Then:
+
+```sh
+bun add -g neurastream@latest
+neurastream adapter install omp
+```
+
+Live copies are never hand-edited. `neurastream doctor` names each hand-edited or foreign installed file, and a stale install (the installed version is not `npm view neurastream version`). If the registry cannot be reached, that check is a warning, not a failure.

package/bin/agent-ledger

@@ -0,0 +1,6 @@
+#!/usr/bin/env bun
+import { basename } from "node:path";
+import { run } from "../src/cli/dispatch.ts";
+
+const invoked = basename(process.argv[1] ?? "");
+process.exit(await run(invoked, process.argv.slice(2)));

package/bin/agent-score

@@ -0,0 +1,6 @@
+#!/usr/bin/env bun
+import { basename } from "node:path";
+import { run } from "../src/cli/dispatch.ts";
+
+const invoked = basename(process.argv[1] ?? "");
+process.exit(await run(invoked, process.argv.slice(2)));

package/bin/brief-lint

@@ -0,0 +1,6 @@
+#!/usr/bin/env bun
+import { basename } from "node:path";
+import { run } from "../src/cli/dispatch.ts";
+
+const invoked = basename(process.argv[1] ?? "");
+process.exit(await run(invoked, process.argv.slice(2)));

package/bin/glm-reset

@@ -0,0 +1,6 @@
+#!/usr/bin/env bun
+import { basename } from "node:path";
+import { run } from "../src/cli/dispatch.ts";
+
+const invoked = basename(process.argv[1] ?? "");
+process.exit(await run(invoked, process.argv.slice(2)));

package/bin/heavy-run

@@ -0,0 +1,6 @@
+#!/usr/bin/env bun
+import { basename } from "node:path";
+import { run } from "../src/cli/dispatch.ts";
+
+const invoked = basename(process.argv[1] ?? "");
+process.exit(await run(invoked, process.argv.slice(2)));

package/bin/machine-guard

@@ -0,0 +1,6 @@
+#!/usr/bin/env bun
+import { basename } from "node:path";
+import { run } from "../src/cli/dispatch.ts";
+
+const invoked = basename(process.argv[1] ?? "");
+process.exit(await run(invoked, process.argv.slice(2)));

package/bin/main-health

@@ -0,0 +1,6 @@
+#!/usr/bin/env bun
+import { basename } from "node:path";
+import { run } from "../src/cli/dispatch.ts";
+
+const invoked = basename(process.argv[1] ?? "");
+process.exit(await run(invoked, process.argv.slice(2)));

package/bin/main-start

@@ -0,0 +1,6 @@
+#!/usr/bin/env bun
+import { basename } from "node:path";
+import { run } from "../src/cli/dispatch.ts";
+
+const invoked = basename(process.argv[1] ?? "");
+process.exit(await run(invoked, process.argv.slice(2)));

package/bin/oc-run

@@ -0,0 +1,6 @@
+#!/usr/bin/env bun
+import { basename } from "node:path";
+import { run } from "../src/cli/dispatch.ts";
+
+const invoked = basename(process.argv[1] ?? "");
+process.exit(await run(invoked, process.argv.slice(2)));

package/bin/pm-fail-facts

@@ -0,0 +1,6 @@
+#!/usr/bin/env bun
+import { basename } from "node:path";
+import { run } from "../src/cli/dispatch.ts";
+
+const invoked = basename(process.argv[1] ?? "");
+process.exit(await run(invoked, process.argv.slice(2)));

package/bin/priority-watch

@@ -0,0 +1,6 @@
+#!/usr/bin/env bun
+import { basename } from "node:path";
+import { run } from "../src/cli/dispatch.ts";
+
+const invoked = basename(process.argv[1] ?? "");
+process.exit(await run(invoked, process.argv.slice(2)));

package/bin/queue-cancel

@@ -0,0 +1,6 @@
+#!/usr/bin/env bun
+import { basename } from "node:path";
+import { run } from "../src/cli/dispatch.ts";
+
+const invoked = basename(process.argv[1] ?? "");
+process.exit(await run(invoked, process.argv.slice(2)));

package/bin/queue-check

@@ -0,0 +1,6 @@
+#!/usr/bin/env bun
+import { basename } from "node:path";
+import { run } from "../src/cli/dispatch.ts";
+
+const invoked = basename(process.argv[1] ?? "");
+process.exit(await run(invoked, process.argv.slice(2)));

package/bin/queue-close

@@ -0,0 +1,6 @@
+#!/usr/bin/env bun
+import { basename } from "node:path";
+import { run } from "../src/cli/dispatch.ts";
+
+const invoked = basename(process.argv[1] ?? "");
+process.exit(await run(invoked, process.argv.slice(2)));

package/bin/resource-alerts

@@ -0,0 +1,6 @@
+#!/usr/bin/env bun
+import { basename } from "node:path";
+import { run } from "../src/cli/dispatch.ts";
+
+const invoked = basename(process.argv[1] ?? "");
+process.exit(await run(invoked, process.argv.slice(2)));

package/bin/tmp-snapshot

@@ -0,0 +1,6 @@
+#!/usr/bin/env bun
+import { basename } from "node:path";
+import { run } from "../src/cli/dispatch.ts";
+
+const invoked = basename(process.argv[1] ?? "");
+process.exit(await run(invoked, process.argv.slice(2)));

package/bin/wip-backup

@@ -0,0 +1,6 @@
+#!/usr/bin/env bun
+import { basename } from "node:path";
+import { run } from "../src/cli/dispatch.ts";
+
+const invoked = basename(process.argv[1] ?? "");
+process.exit(await run(invoked, process.argv.slice(2)));

package/bin/wip-check

@@ -0,0 +1,6 @@
+#!/usr/bin/env bun
+import { basename } from "node:path";
+import { run } from "../src/cli/dispatch.ts";
+
+const invoked = basename(process.argv[1] ?? "");
+process.exit(await run(invoked, process.argv.slice(2)));

package/bin/wip-snapshot

@@ -0,0 +1,6 @@
+#!/usr/bin/env bun
+import { basename } from "node:path";
+import { run } from "../src/cli/dispatch.ts";
+
+const invoked = basename(process.argv[1] ?? "");
+process.exit(await run(invoked, process.argv.slice(2)));

package/blockers/deny-command

@@ -0,0 +1,4 @@
+#!/usr/bin/env bun
+import { denyCommand, runBlockerScript } from "../src/core/blockers.ts";
+
+runBlockerScript(denyCommand);

package/blockers/deny-path

@@ -0,0 +1,4 @@
+#!/usr/bin/env bun
+import { denyPath, runBlockerScript } from "../src/core/blockers.ts";
+
+runBlockerScript(denyPath);

package/blockers/deny-text

@@ -0,0 +1,4 @@
+#!/usr/bin/env bun
+import { denyText, runBlockerScript } from "../src/core/blockers.ts";
+
+runBlockerScript(denyText);

package/blockers/no-push

@@ -0,0 +1,4 @@
+#!/usr/bin/env bun
+import { noPush, runBlockerScript } from "../src/core/blockers.ts";
+
+runBlockerScript(noPush);

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "neurastream",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Harness-agnostic agent orchestration: queue, guards, blockers, scoring, ledger.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/umiddey/neurastream.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "bin",
+    "templates",
+    "blockers",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "neurastream": "src/cli/main.ts",
+    "agent-score": "bin/agent-score",
+    "agent-ledger": "bin/agent-ledger",
+    "brief-lint": "bin/brief-lint",
+    "oc-run": "bin/oc-run",
+    "wip-check": "bin/wip-check",
+    "wip-backup": "bin/wip-backup",
+    "wip-snapshot": "bin/wip-snapshot",
+    "pm-fail-facts": "bin/pm-fail-facts",
+    "main-health": "bin/main-health",
+    "queue-check": "bin/queue-check",
+    "queue-close": "bin/queue-close",
+    "queue-cancel": "bin/queue-cancel",
+    "main-start": "bin/main-start",
+    "machine-guard": "bin/machine-guard",
+    "glm-reset": "bin/glm-reset",
+    "priority-watch": "bin/priority-watch",
+    "resource-alerts": "bin/resource-alerts",
+    "tmp-snapshot": "bin/tmp-snapshot",
+    "heavy-run": "bin/heavy-run"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "omp": {
+    "extensions": [
+      "./src/adapters/omp/index.ts"
+    ]
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14",
+    "typescript": "^5.9.3"
+  }
+}

package/src/adapters/omp/doctor.ts

@@ -0,0 +1,186 @@
+// Reports hand-edited or foreign live files the omp adapter installs, and a stale
+// registry version. Offline `npm view` is a warning, not a failure.
+// Notes, INDEX, queue state and config are user state: not checked.
+
+import { spawnSync } from "node:child_process";
+import { existsSync, lstatSync, readdirSync, readFileSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "../../..");
+
+export interface LiveFile {
+	live: string;
+	source: string;
+}
+
+interface PackageJson {
+	name?: string;
+	version?: string;
+	bin?: Record<string, string>;
+}
+
+function readPackage(root: string): PackageJson {
+	return JSON.parse(readFileSync(join(root, "package.json"), "utf8")) as PackageJson;
+}
+
+export function packageBins(root: string): { name: string; source: string }[] {
+	const pkg = readPackage(root);
+	return Object.entries(pkg.bin ?? {}).map(([name, rel]) => ({ name, source: join(root, rel) }));
+}
+
+/** Files adapter install places under this home. Bun's global bin dir is extra, checked only when a name is present. */
+export function adapterLiveFiles(home: string, root: string = PACKAGE_ROOT): LiveFile[] {
+	const files: LiveFile[] = [];
+	for (const bin of packageBins(root)) {
+		files.push({ live: join(home, ".local/bin", bin.name), source: bin.source });
+	}
+	files.push({
+		live: join(home, ".omp/agent/extensions/neurastream.ts"),
+		source: join(root, "src/adapters/omp/index.ts"),
+	});
+	files.push({
+		live: join(home, ".omp/agent/queue/lib.ts"),
+		source: join(root, "src/core/queue/lib.ts"),
+	});
+	files.push({
+		live: join(home, ".omp/agent/queue/TEMPLATE.md"),
+		source: join(root, "templates/queue/TEMPLATE.md"),
+	});
+	const agents = join(root, "templates/agents");
+	for (const name of readdirSync(agents).sort()) {
+		if (!name.endsWith(".md") || name.includes(".bak")) continue;
+		files.push({ live: join(home, ".omp/agent/agents", name), source: join(agents, name) });
+	}
+	return files;
+}
+
+function bunLiveFiles(home: string, root: string): LiveFile[] {
+	const dir = join(home, ".bun/bin");
+	if (!existsSync(dir)) return [];
+	const files: LiveFile[] = [];
+	for (const bin of packageBins(root)) {
+		const live = join(dir, bin.name);
+		if (existsSync(live)) files.push({ live, source: bin.source });
+	}
+	return files;
+}
+
+function packageRootOf(file: string): string | null {
+	let dir = dirname(file);
+	for (let i = 0; i < 8; i++) {
+		const manifest = join(dir, "package.json");
+		if (existsSync(manifest)) {
+			try {
+				const pkg = JSON.parse(readFileSync(manifest, "utf8")) as PackageJson;
+				if (pkg.name === readPackage(PACKAGE_ROOT).name) return dir;
+			} catch {
+				return null;
+			}
+		}
+		const parent = dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	return null;
+}
+
+function sameBytes(a: string, b: string): boolean {
+	try {
+		return readFileSync(a).equals(readFileSync(b));
+	} catch {
+		return false;
+	}
+}
+
+/** A launcher is a symlink into an installed copy of this package, at the same relative path. A copy is byte-identical. */
+export function isPackageFile(live: string, source: string): boolean {
+	let st;
+	try {
+		st = lstatSync(live);
+	} catch {
+		return false;
+	}
+	if (st.isSymbolicLink()) {
+		let target: string;
+		try {
+			target = realpathSync(live);
+		} catch {
+			return false;
+		}
+		const root = packageRootOf(target);
+		if (!root) return false;
+		const rel = relative(PACKAGE_ROOT, source);
+		return target === resolve(root, rel);
+	}
+	if (!st.isFile()) return false;
+	return sameBytes(live, source);
+}
+
+export interface DoctorReport {
+	ok: string[];
+	problems: string[];
+	warnings: string[];
+	installed: string;
+	registry: string | null;
+}
+
+function npmViewVersion(name: string, env: NodeJS.ProcessEnv): { version: string } | { warning: string } {
+	const r = spawnSync("npm", ["view", name, "version"], { encoding: "utf8", env, timeout: 8000 });
+	if (r.error || r.status !== 0) {
+		const why = r.error ? r.error.message : `exit ${r.status ?? "signal"}`;
+		return { warning: `offline: npm view ${name} version failed (${why})` };
+	}
+	const version = (r.stdout ?? "").trim().split("\n").filter(Boolean).at(-1) ?? "";
+	if (!version) return { warning: `offline: npm view ${name} version returned nothing` };
+	return { version };
+}
+
+export function doctorReport(home: string, env: NodeJS.ProcessEnv = process.env): DoctorReport {
+	const pkg = readPackage(PACKAGE_ROOT);
+	const name = pkg.name ?? "neurastream";
+	const installed = pkg.version ?? "";
+	const problems: string[] = [];
+	const ok: string[] = [];
+	const seen = new Set<string>();
+	for (const file of [...adapterLiveFiles(home), ...bunLiveFiles(home, PACKAGE_ROOT)]) {
+		if (seen.has(file.live)) continue;
+		seen.add(file.live);
+		if (!existsSync(file.live)) {
+			problems.push(`foreign: ${file.live}`);
+			continue;
+		}
+		if (isPackageFile(file.live, file.source)) {
+			ok.push(file.live);
+			continue;
+		}
+		problems.push(`hand-edited: ${file.live}`);
+	}
+	const warnings: string[] = [];
+	const viewed = npmViewVersion(name, env);
+	let registry: string | null = null;
+	if ("warning" in viewed) warnings.push(viewed.warning);
+	else {
+		registry = viewed.version;
+		if (registry !== installed) problems.push(`stale version: installed ${installed}, registry ${registry}`);
+	}
+	return { ok, problems, warnings, installed, registry };
+}
+
+export function formatDoctor(report: DoctorReport): string {
+	const lines: string[] = [];
+	if (report.problems.length === 0) lines.push("neurastream doctor: ok");
+	else lines.push(`neurastream doctor: ${report.problems.length} problem(s)`);
+	for (const p of report.problems) lines.push(p);
+	lines.push(`installed ${report.installed}`);
+	if (report.registry !== null) lines.push(`registry ${report.registry}`);
+	for (const w of report.warnings) lines.push(`warning: ${w}`);
+	return lines.join("\n");
+}
+
+export function runDoctor(): number {
+	const report = doctorReport(homedir());
+	console.log(formatDoctor(report));
+	return report.problems.length === 0 ? 0 : 1;
+}