@vimhead.dev/norn-cli 0.1.0-tip.35976246970.1 → 0.1.0-tip.36533963240.1

package/assets/README.md

@@ -113,6 +113,17 @@ npm install -g @vimhead.dev/norn-cli@tip
 norn version
 ```
 
+Alternatively, install into the package that owns your workflows, without a global
+Norn installation:
+
+```bash
+npm install --save-dev --save-exact @vimhead.dev/norn-cli@tip
+./node_modules/.bin/norn version
+```
+
+Use that local executable in place of `norn` in the commands below. Connect harnesses
+with [project-local runtime selection](#project-local-runtime-selection).
+
 Releases are prereleases, not stable `latest` releases. For a standalone binary
 without Node, use the matching GitHub `tip` release:
 
@@ -149,15 +160,56 @@ methods, custom providers, and Norn's configuration directory, see
 
 ### 3. Optionally connect your harness
 
-The shipped Pi and Cursor adapters deliver Norn documentation context and
+The shipped Pi, Cursor, and Claude Code adapters deliver Norn documentation context and
 [available workflow introductions](docs/cli.md#workflow-introduction) to your
-harness at session start. Installing Norn alone does not register an adapter. Claude Code, Codex,
+harness at session start. Installing Norn alone does not register an adapter. Codex
 and other harnesses can [invoke the CLI directly](docs/cli.md#javascript-client-and-other-harnesses).
 
+#### Project-local runtime selection
+
+To use a CLI dependency from a harness launched elsewhere in your workspace, put
+`.nornrc.json` in the harness's working directory or an ancestor:
+
+```json
+{
+  "runtime": {
+    "packageRoot": "./packages/workflows"
+  }
+}
+```
+
+`packageRoot` is relative to this configuration file (absolute paths also work).
+It names a package whose `package.json` declares `@vimhead.dev/norn-cli` in
+`dependencies`, `devDependencies`, or `optionalDependencies`. Install that package's
+dependencies first; its manifest and lockfile own the version. npm hoisting and
+pnpm's linked `node_modules` installations are supported. No download occurs at
+harness startup. Node `>=22.19.0` is required for the npm runtime.
+
+The Pi, Cursor, and Claude Code adapters select an explicit executable override
+first, then the nearest `.nornrc.json`, then `norn` on `PATH` only when no configuration
+exists. Configuration files do not merge. Invalid configuration or a missing/broken
+selected installation fails without falling back. Pi ignores repository runtime
+configuration in untrusted projects; Cursor and Claude Code use their host's hook
+trust/approval boundary. Only enable adapters and runtime selection in workspaces
+you trust: the selected dependency executes code.
+
+Both introductions come from the selected runtime, and its documentation introduction
+supplies concrete argv for subsequent agent calls. The session's working directory
+is preserved; runtime selection does not select a workflow project or workspace.
+Restart the session (or `/reload` in Pi) after changing selection or dependencies.
+
+This is adapter configuration, **not CLI delegation**: globally installed Norn and
+direct CLI invocations do not read `.nornrc.json` or proxy commands. For terminal use,
+invoke the dependency directly, preserving your working directory:
+
+```bash
+./packages/workflows/node_modules/.bin/norn version
+```
+
 #### Pi
 
-With Pi already installed and `norn` available on `PATH`, install the adapter
-and start a new session:
+With Pi already installed and a runtime selected as above or available on `PATH`,
+install the adapter and start a new session:
 
 ```bash
 pi install npm:@vimhead.dev/pi-norn@tip
@@ -177,13 +229,39 @@ pi --norn-executable /absolute/path/to/norn
 3. Install the **norn** plugin, choosing user or project scope.
 4. Start a new agent conversation.
 
-By default the adapter runs `norn` from `PATH`. To select a CLI executable
-outside `PATH`, start Cursor with an executable path:
+Use [project-local runtime selection](#project-local-runtime-selection), or override
+it by starting Cursor with an executable path:
 
 ```bash
 NORN_EXECUTABLE=/absolute/path/to/norn cursor .
 ```
 
+#### Claude Code
+
+With Node and a [selected runtime](#project-local-runtime-selection), run in your terminal:
+
+```bash
+claude plugin marketplace add vimhead/norn
+claude plugin install norn@norn-adapters
+claude
+```
+
+To select a different runtime, launch Claude Code with
+`NORN_EXECUTABLE=/absolute/path/to/norn claude`. The plugin uses that runtime's
+documentation and the workflows in the session's working directory; it does not
+install Norn or configure authentication for Norn agents.
+
+Context is added on startup, `/clear`, and compaction, not again on resume or
+fork. Named-agent sessions (`--agent`) and subagent hook calls are excluded.
+Existing instructions and prompts are preserved. Introduction failures appear as
+hook errors without falling back to another runtime.
+
+To test a checkout without installing the marketplace:
+
+```bash
+claude --plugin-dir /absolute/path/to/norn
+```
+
 Need an adapter for another harness? [Open an issue](https://github.com/vimhead/norn/issues/new)
 with the harness name.
 

package/assets/docs/cli.md

@@ -10,6 +10,9 @@ norn version
 norn help
 ```
 
+For harnesses using an npm dependency without global Norn, see
+[adapter runtime selection](../README.md#project-local-runtime-selection).
+
 For a source checkout, run `pnpm install --frozen-lockfile` and `pnpm build` first. A shell function keeps all examples bound to that checkout rather than another `PATH` installation:
 
 ```bash

package/assets/package.json

@@ -1 +1 @@
-{"version":"0.1.0-tip.35976246970.1"}
+{"version":"0.1.0-tip.36533963240.1"}

package/assets/packages/cli/src/generated-build-info.ts

@@ -2,8 +2,8 @@ import type { NornBuildInfo } from "./build-info.ts";
 
 export const NORN_GENERATED_BUILD_INFO = {
   "kind": "npm-registry",
-  "version": "0.1.0-tip.35976246970.1",
-  "commit": "85fe72374183623e66290c6315b3ba51bee7a79c",
+  "version": "0.1.0-tip.36533963240.1",
+  "commit": "73cebf815a2158d1f7e7e5614225e36a52b73924",
   "packageSpec": "@vimhead.dev/norn-cli@tip",
   "upgrade": {
     "supported": false,

package/assets/packages/core/src/host-introduction.mjs

@@ -0,0 +1,47 @@
+import { execFile } from "node:child_process";
+import { Buffer } from "node:buffer";
+import { promisify } from "node:util";
+import { resolveNornRuntime } from "./runtime-resolution.mjs";
+
+const runExecutable = promisify(execFile);
+const MAX_INTRO_BYTES = 16_384;
+
+function readIntroResponse({ stdout, group }) {
+	const response = JSON.parse(stdout);
+	if (
+		!response ||
+		typeof response !== "object" ||
+		typeof response.intro !== "string" ||
+		(group === "docs" && response.intro.trim().length === 0) ||
+		Buffer.byteLength(response.intro, "utf8") > MAX_INTRO_BYTES
+	)
+		throw new Error("Invalid Norn introduction response");
+	return response.intro;
+}
+
+async function loadIntroduction({ invocation, cwd, group }) {
+	const { stdout } = await runExecutable(
+		invocation.executable,
+		[...invocation.args, group, "intro"],
+		{
+			cwd,
+			timeout: 10_000,
+			maxBuffer: MAX_INTRO_BYTES * 2,
+		},
+	);
+	return readIntroResponse({ stdout, group });
+}
+
+export async function loadHostIntroduction({ executableOverride, cwd }) {
+	const invocation = await resolveNornRuntime({
+		cwd,
+		executableOverride,
+		isProjectTrusted: true,
+		nodeExecutable: process.execPath,
+	});
+	const [intro, workflowsIntro] = await Promise.all([
+		loadIntroduction({ invocation, cwd, group: "docs" }),
+		loadIntroduction({ invocation, cwd, group: "workflows" }),
+	]);
+	return `<norn-docs-intro>\n${intro}\n</norn-docs-intro>${workflowsIntro ? `\n\n${workflowsIntro}` : ""}`;
+}

package/assets/packages/core/src/runtime-resolution.mjs

@@ -0,0 +1,137 @@
+import { lstat, readFile, realpath, stat } from "node:fs/promises";
+import { dirname, isAbsolute, join, resolve, sep } from "node:path";
+
+const CLI_PACKAGE_NAME = "@vimhead.dev/norn-cli";
+
+export class RuntimeResolutionError extends Error {}
+
+export async function resolveNornRuntime({
+	cwd,
+	executableOverride,
+	isProjectTrusted,
+	nodeExecutable,
+}) {
+	if (executableOverride !== null) {
+		if (typeof executableOverride !== "string" || !executableOverride.trim())
+			throw new RuntimeResolutionError(
+				"Norn executable override must be a nonempty executable path or name.",
+			);
+		return { executable: executableOverride, args: [] };
+	}
+	if (!isProjectTrusted) return { executable: "norn", args: [] };
+	const configPath = await findAncestorEntry({
+		cwd,
+		relativePath: ".nornrc.json",
+	});
+	if (configPath === null) return { executable: "norn", args: [] };
+	const packageRoot = await readRuntimePackageRoot(configPath);
+	const scriptPath = await resolvePackageEntrypoint(packageRoot);
+	return { executable: nodeExecutable, args: [scriptPath] };
+}
+
+async function readRuntimePackageRoot(configPath) {
+	const configuration = await readManifest(configPath);
+	if (
+		!isRecord(configuration) ||
+		Object.keys(configuration).some((key) => key !== "runtime") ||
+		!isRecord(configuration.runtime) ||
+		Object.keys(configuration.runtime).some((key) => key !== "packageRoot") ||
+		typeof configuration.runtime.packageRoot !== "string" ||
+		!configuration.runtime.packageRoot.trim()
+	)
+		throw new RuntimeResolutionError(
+			`Invalid ${JSON.stringify(configPath)}: expected { "runtime": { "packageRoot": "./path/to/package" } }.`,
+		);
+	return resolve(dirname(configPath), configuration.runtime.packageRoot);
+}
+
+async function resolvePackageEntrypoint(packageRoot) {
+	const owner = await readManifest(join(packageRoot, "package.json"));
+	if (
+		!isRecord(owner) ||
+		![
+			owner.dependencies,
+			owner.devDependencies,
+			owner.optionalDependencies,
+		].some(
+			(dependencies) =>
+				isRecord(dependencies) &&
+				typeof dependencies[CLI_PACKAGE_NAME] === "string",
+		)
+	)
+		throw new RuntimeResolutionError(
+			`The package at ${JSON.stringify(packageRoot)} must declare ${CLI_PACKAGE_NAME} as a dependency or devDependency.`,
+		);
+	const packagePath = await findAncestorEntry({
+		cwd: packageRoot,
+		relativePath: `node_modules/${CLI_PACKAGE_NAME}`,
+	});
+	if (packagePath === null)
+		throw new RuntimeResolutionError(
+			`Cannot find ${CLI_PACKAGE_NAME} from ${JSON.stringify(packageRoot)}. Install that package's dependencies and retry.`,
+		);
+	const manifestPath = join(packagePath, "package.json");
+	const installedManifestPath = await realpath(manifestPath).catch(() => {
+		throw new RuntimeResolutionError(
+			`Cannot resolve the installed CLI at ${JSON.stringify(manifestPath)}. Reinstall the selected package's dependencies.`,
+		);
+	});
+	const installed = await readManifest(installedManifestPath);
+	const entrypoint = isRecord(installed?.bin) ? installed.bin.norn : undefined;
+	if (
+		installed?.name !== CLI_PACKAGE_NAME ||
+		typeof entrypoint !== "string" ||
+		!entrypoint.trim() ||
+		isAbsolute(entrypoint)
+	)
+		throw new RuntimeResolutionError(
+			`Invalid Norn CLI manifest at ${JSON.stringify(installedManifestPath)}: expected a relative bin.norn entrypoint.`,
+		);
+	const installationRoot = dirname(installedManifestPath);
+	const scriptPath = resolve(installationRoot, entrypoint);
+	if (!scriptPath.startsWith(`${installationRoot}${sep}`))
+		throw new RuntimeResolutionError(
+			`Norn CLI entrypoint must be inside ${JSON.stringify(installationRoot)}.`,
+		);
+	try {
+		if (!(await stat(scriptPath)).isFile()) throw new Error();
+	} catch {
+		throw new RuntimeResolutionError(
+			`Missing Norn CLI entrypoint at ${JSON.stringify(scriptPath)}. Reinstall the selected package's dependencies.`,
+		);
+	}
+	return scriptPath;
+}
+
+function isRecord(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+async function readManifest(path) {
+	try {
+		return JSON.parse(await readFile(path, "utf8"));
+	} catch {
+		throw new RuntimeResolutionError(
+			`Cannot read valid JSON from ${JSON.stringify(path)}. Check the selected package and configuration.`,
+		);
+	}
+}
+
+async function findAncestorEntry({ cwd, relativePath }) {
+	let directory = resolve(cwd);
+	while (true) {
+		const candidate = join(directory, relativePath);
+		try {
+			await lstat(candidate);
+			return candidate;
+		} catch (error) {
+			if (error.code !== "ENOENT")
+				throw new RuntimeResolutionError(
+					`Cannot inspect ${JSON.stringify(candidate)}.`,
+				);
+		}
+		const parent = dirname(directory);
+		if (parent === directory) return null;
+		directory = parent;
+	}
+}

package/dist/generated-build-info.d.ts

@@ -1,7 +1,7 @@
 export declare const NORN_GENERATED_BUILD_INFO: {
     readonly kind: "npm-registry";
-    readonly version: "0.1.0-tip.35976246970.1";
-    readonly commit: "85fe72374183623e66290c6315b3ba51bee7a79c";
+    readonly version: "0.1.0-tip.36533963240.1";
+    readonly commit: "73cebf815a2158d1f7e7e5614225e36a52b73924";
     readonly packageSpec: "@vimhead.dev/norn-cli@tip";
     readonly upgrade: {
         readonly supported: false;

package/dist/generated-build-info.js

@@ -1,8 +1,8 @@
 // src/generated-build-info.ts
 var NORN_GENERATED_BUILD_INFO = {
   "kind": "npm-registry",
-  "version": "0.1.0-tip.35976246970.1",
-  "commit": "85fe72374183623e66290c6315b3ba51bee7a79c",
+  "version": "0.1.0-tip.36533963240.1",
+  "commit": "73cebf815a2158d1f7e7e5614225e36a52b73924",
   "packageSpec": "@vimhead.dev/norn-cli@tip",
   "upgrade": {
     "supported": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vimhead.dev/norn-cli",
-  "version": "0.1.0-tip.35976246970.1",
+  "version": "0.1.0-tip.36533963240.1",
   "description": "Harness-agnostic runtime for agent-driven and code-driven workflows, built primarily for agents.",
   "type": "module",
   "license": "MIT",
@@ -43,7 +43,7 @@
     "@earendil-works/pi-coding-agent": "0.85.1",
     "jiti": "^2.7.0",
     "typebox": "^1.3.34",
-    "@vimhead.dev/norn": "0.1.0-tip.35976246970.1"
+    "@vimhead.dev/norn": "0.1.0-tip.36533963240.1"
   },
   "scripts": {
     "build": "node ../../scripts/build-package.ts"