@vimhead.dev/norn-cli 0.1.0-tip.0

package/dist/plugin-loader.js

@@ -0,0 +1,353 @@
+// src/plugin-loader.ts
+import { access, readFile, readdir } from "node:fs/promises";
+import { dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+import { createJiti } from "jiti/static";
+import * as typeboxModule from "typebox";
+import { z } from "zod";
+import * as zodModule from "zod";
+import * as nornModule from "@vimhead.dev/norn";
+import * as nornFilesModule from "@vimhead.dev/norn/files";
+import * as nornSchemaModule from "@vimhead.dev/norn/schema";
+import * as nornSeerModule from "@vimhead.dev/norn/seer";
+import { isWorkflowPlugin } from "@vimhead.dev/norn";
+import { errorMessage, NornProjectLoadError } from "./internal/errors.js";
+
+// ../core/src/errors.ts
+function isNodeError(error) {
+  return error instanceof Error && "code" in error;
+}
+
+// src/plugin-loader.ts
+import { NornMemoryWorkflowState } from "./internal/state-store.js";
+import { NornWorkflowRegistry } from "./internal/workflow-registry.js";
+import { schemaType, unwrapSchema } from "@vimhead.dev/norn/schema";
+import { resolveSeerModeConfig } from "@vimhead.dev/norn/seer";
+var NORN_PROJECT_FILE_NAME = "norn.project.json";
+var seerModeConfigSchema = z.object({
+  writableRoots: z.array(z.string().min(1)).min(1)
+});
+var nornConfigSchema = z.object({
+  plugins: z.array(z.string().min(1)).default([]),
+  includes: z.array(z.string().min(1)).default([]),
+  config: z.record(z.string(), z.unknown()).default({})
+});
+var nornProjectConfigSchema = nornConfigSchema.extend({
+  version: z.literal(1).default(1),
+  seerMode: seerModeConfigSchema.optional()
+});
+async function loadNornProject(cwd) {
+  const { project, diagnostics } = await collectNornProject(cwd);
+  if (diagnostics.length > 0) throw new NornProjectLoadError({ diagnostics });
+  return project;
+}
+async function discoverNornProject(cwd) {
+  const { project, diagnostics } = await collectNornProject(cwd);
+  return { project: buildProjectInfo(project), workflows: project.registry.list(), isComplete: diagnostics.length === 0, diagnostics };
+}
+async function inspectNornWorkflow(input) {
+  const { project, diagnostics } = await collectNornProject(input.cwd);
+  const summary = project.registry.list().find((workflow) => workflow.id === input.workflowId);
+  if (!summary) {
+    if (diagnostics.length === 0) throw new Error(`Unknown workflow: ${input.workflowId}`);
+    return { workflow: null, isComplete: false, diagnostics };
+  }
+  const info = summary.plugin;
+  if (!info?.path || !info.configPath) throw new Error(`Loaded workflow lacks plugin source: ${input.workflowId}`);
+  try {
+    return { workflow: project.registry.inspect(input.workflowId) ?? null, isComplete: diagnostics.length === 0, diagnostics };
+  } catch (error) {
+    return { workflow: null, isComplete: false, diagnostics: [...diagnostics, createPluginDiagnostic({
+      source: { configPath: info.configPath, pluginPath: info.path, pluginId: info.id },
+      workflowId: input.workflowId,
+      stage: "schema",
+      error
+    })] };
+  }
+}
+function buildProjectInfo(project) {
+  return {
+    cwd: project.cwd,
+    projectPath: project.projectPath,
+    projectRoot: project.projectRoot,
+    configPath: project.configPath,
+    configRoot: project.configRoot,
+    configFiles: project.configFiles.map((file) => file.path),
+    plugins: project.pluginInfos,
+    seerMode: project.seerMode ?? null
+  };
+}
+async function findNornProject(cwd) {
+  const projectPath = await findNearestNornProject(cwd);
+  const projectRootConfig = await readNornProjectConfigFile(projectPath);
+  const configFiles = await loadIncludedNornConfigFiles(projectRootConfig, /* @__PURE__ */ new Set([projectRootConfig.path]));
+  return {
+    cwd: resolve(cwd),
+    projectPath: projectRootConfig.path,
+    projectRoot: projectRootConfig.root,
+    configPath: projectRootConfig.path,
+    configRoot: projectRootConfig.root,
+    config: projectRootConfig.config,
+    configFiles,
+    projectConfig: mergeProjectConfig(configFiles),
+    seerMode: resolveSeerModeConfig({ configPath: projectRootConfig.path, configRoot: projectRootConfig.root, seerMode: projectRootConfig.config.seerMode })
+  };
+}
+async function findNearestNornProject(cwd) {
+  let current = resolve(cwd);
+  while (true) {
+    const projectPath = join(current, NORN_PROJECT_FILE_NAME);
+    try {
+      await access(projectPath);
+      return projectPath;
+    } catch (error) {
+      if (!isNodeError(error) || error.code !== "ENOENT") throw error;
+    }
+    const parent = dirname(current);
+    if (parent === current) throw new Error(`Could not find ${NORN_PROJECT_FILE_NAME} from ${cwd}`);
+    current = parent;
+  }
+}
+async function loadIncludedNornConfigFiles(projectFile, visitedPaths) {
+  const includedConfigFiles = await Promise.all(projectFile.config.includes.map(async (includePath) => {
+    const configPaths = await expandIncludePath(projectFile.root, includePath);
+    return Promise.all(configPaths.map(readNornConfigFile));
+  }));
+  const descendants = await Promise.all(includedConfigFiles.flat().map((includedConfigFile) => loadNornConfigTree(includedConfigFile, visitedPaths)));
+  return [createProjectConfigEntry(projectFile), ...descendants.flat()];
+}
+async function loadNornConfigTree(configFile, visitedPaths) {
+  if (visitedPaths.has(configFile.path)) return [];
+  visitedPaths.add(configFile.path);
+  const includedConfigFiles = await Promise.all(configFile.config.includes.map(async (includePath) => {
+    const configPaths = await expandIncludePath(configFile.root, includePath);
+    return Promise.all(configPaths.map(readNornConfigFile));
+  }));
+  const descendants = await Promise.all(includedConfigFiles.flat().map((includedConfigFile) => loadNornConfigTree(includedConfigFile, visitedPaths)));
+  return [configFile, ...descendants.flat()];
+}
+async function readNornProjectConfigFile(path) {
+  const config = nornProjectConfigSchema.parse(JSON.parse(await readFile(path, "utf8")));
+  return { path, root: dirname(path), config };
+}
+async function readNornConfigFile(path) {
+  const config = nornConfigSchema.parse(JSON.parse(await readFile(path, "utf8")));
+  return { path, root: dirname(path), config };
+}
+function createProjectConfigEntry(projectFile) {
+  return {
+    path: projectFile.path,
+    root: projectFile.root,
+    config: {
+      plugins: projectFile.config.plugins,
+      includes: projectFile.config.includes,
+      config: projectFile.config.config
+    }
+  };
+}
+async function collectNornProject(cwd) {
+  const project = await findNornProject(cwd);
+  const imported = await importWorkflowPlugins(project);
+  const diagnostics = [...imported.diagnostics];
+  const registry = new NornWorkflowRegistry();
+  const state = new NornMemoryWorkflowState();
+  const loaded = [];
+  const conflicts = collectPluginConflicts(imported.plugins);
+  for (const candidate of imported.plugins) {
+    const pluginConflicts = conflicts.get(candidate);
+    if (pluginConflicts) {
+      diagnostics.push(...pluginConflicts);
+      continue;
+    }
+    const result = registerProjectPlugin({ candidate, project, registry, state });
+    diagnostics.push(...result.diagnostics);
+    if (result.loaded) loaded.push(result.loaded);
+  }
+  return {
+    project: { ...project, plugins: loaded.map((entry) => entry.plugin), pluginInfos: loaded.map((entry) => entry.info), registry, workflows: registry.launchableEntries(), state },
+    diagnostics
+  };
+}
+function collectPluginConflicts(plugins) {
+  const byPluginId = /* @__PURE__ */ new Map();
+  const byWorkflowId = /* @__PURE__ */ new Map();
+  for (const candidate of plugins) {
+    const id = candidate.plugin.manifest.id;
+    byPluginId.set(id, [...byPluginId.get(id) ?? [], candidate]);
+    for (const workflowId of new Set(Object.values(candidate.plugin.manifest.workflows).map((workflow) => workflow.id))) {
+      byWorkflowId.set(workflowId, [...byWorkflowId.get(workflowId) ?? [], candidate]);
+    }
+  }
+  const conflicts = /* @__PURE__ */ new Map();
+  for (const [pluginId, candidates] of byPluginId) {
+    if (candidates.length < 2) continue;
+    for (const candidate of candidates) conflicts.set(candidate, [createPluginDiagnostic({
+      source: candidate.source,
+      workflowId: null,
+      stage: "duplicate",
+      error: new Error(`Duplicate Norn plugin id: ${pluginId} (${candidates.map((other) => other.source.pluginPath).join(", ")})`)
+    })]);
+  }
+  for (const [workflowId, candidates] of byWorkflowId) {
+    const distinctPlugins = candidates.filter((candidate) => byPluginId.get(candidate.plugin.manifest.id)?.length === 1);
+    if (distinctPlugins.length < 2) continue;
+    for (const candidate of distinctPlugins) conflicts.set(candidate, [...conflicts.get(candidate) ?? [], createPluginDiagnostic({
+      source: candidate.source,
+      workflowId,
+      stage: "duplicate",
+      error: new Error(`Workflow already registered: ${workflowId} (${distinctPlugins.map((other) => other.source.pluginPath).join(", ")})`)
+    })]);
+  }
+  return conflicts;
+}
+async function importWorkflowPlugins(project) {
+  const plugins = [];
+  const diagnostics = [];
+  for (const configFile of project.configFiles) {
+    const jiti = createJiti(pathToFileURL(configFile.path).href, { moduleCache: false, virtualModules: nornWorkflowVirtualModules() });
+    for (const pluginPath of configFile.config.plugins) {
+      const source = { configPath: configFile.path, pluginPath: resolveConfigPath(configFile.root, pluginPath), pluginId: null };
+      let stage = "import";
+      try {
+        const module = await jiti.import(pathToFileURL(source.pluginPath).href);
+        stage = "declaration";
+        if (!isWorkflowPlugin(module?.default)) throw new Error(`Norn plugin must be the default export: ${source.pluginPath}`);
+        plugins.push({ plugin: module.default, source: { ...source, pluginId: module.default.manifest.id } });
+      } catch (error) {
+        diagnostics.push(createPluginDiagnostic({ source, workflowId: null, stage, error }));
+      }
+    }
+  }
+  return { plugins, diagnostics };
+}
+function registerProjectPlugin(input) {
+  const { plugin, source } = input.candidate;
+  const diagnostics = [];
+  const unregister = [];
+  let stage = "config";
+  try {
+    const configInput = input.project.projectConfig[plugin.manifest.id];
+    if (!plugin.manifest.config && configInput !== void 0) throw new Error(`Norn config provided for plugin without config schema: ${plugin.manifest.id}`);
+    const config = plugin.manifest.config ? plugin.manifest.config.parse(defaultConfigInput(plugin.manifest.config, configInput)) : void 0;
+    stage = "schema";
+    const info = {
+      id: plugin.manifest.id,
+      path: source.pluginPath,
+      configPath: source.configPath,
+      configSchema: plugin.manifest.config ? z.toJSONSchema(plugin.manifest.config, { io: "input" }) : null,
+      config
+    };
+    stage = "implementation";
+    const implementation = typeof plugin.implementation === "function" ? plugin.implementation({ cwd: input.project.cwd, state: input.state }) : plugin.implementation;
+    for (const [key, workflow] of Object.entries(plugin.manifest.workflows)) {
+      stage = "implementation";
+      try {
+        const workflowImplementation = implementation.workflows?.[key];
+        if (typeof workflowImplementation?.execute !== "function") throw new Error(`Missing implementation for workflow ${workflow.id}`);
+        stage = "duplicate";
+        if (input.registry.workflowById(workflow.id)) throw new Error(`Workflow already registered: ${workflow.id}`);
+        stage = "declaration";
+        unregister.push(input.registry.register(workflow, workflowImplementation, { plugin: workflowPluginInfo(info), configSchema: plugin.manifest.config, config }));
+      } catch (error) {
+        diagnostics.push(createPluginDiagnostic({ source, workflowId: workflow.id, stage: error instanceof z.ZodError ? "config" : stage, error }));
+      }
+    }
+    if (diagnostics.length === 0) return { loaded: { plugin, info }, diagnostics };
+  } catch (error) {
+    diagnostics.push(createPluginDiagnostic({ source, workflowId: null, stage, error }));
+  }
+  for (const dispose of unregister) dispose();
+  return { loaded: null, diagnostics };
+}
+function createPluginDiagnostic(input) {
+  return {
+    ...input.source,
+    workflowId: input.workflowId,
+    stage: input.stage,
+    message: errorMessage(input.error),
+    issues: input.error instanceof z.ZodError ? input.error.issues.map((issue) => ({
+      path: issue.path.map((part) => typeof part === "symbol" ? String(part) : part),
+      code: issue.code,
+      message: issue.message
+    })) : []
+  };
+}
+function workflowPluginInfo(info) {
+  return { id: info.id, path: info.path, configPath: info.configPath };
+}
+function nornWorkflowVirtualModules() {
+  return {
+    "@vimhead.dev/norn": nornModule,
+    "@vimhead.dev/norn/files": nornFilesModule,
+    "@vimhead.dev/norn/schema": nornSchemaModule,
+    "@vimhead.dev/norn/seer": nornSeerModule,
+    typebox: typeboxModule,
+    zod: zodModule
+  };
+}
+function mergeProjectConfig(configFiles) {
+  const [projectFile, ...reusableConfigFiles] = configFiles;
+  let reusableConfig = {};
+  for (const configFile of reusableConfigFiles) {
+    reusableConfig = mergeReusableConfigObjects(reusableConfig, configFile.config.config, ["config"]);
+  }
+  return mergeProjectConfigObjects(reusableConfig, projectFile?.config.config ?? {});
+}
+function mergeReusableConfigObjects(base, override, path) {
+  const result = { ...base };
+  for (const [key, overrideValue] of Object.entries(override)) {
+    result[key] = Object.prototype.hasOwnProperty.call(result, key) ? mergeReusableConfigValue(result[key], overrideValue, [...path, key]) : overrideValue;
+  }
+  return result;
+}
+function mergeReusableConfigValue(base, override, path) {
+  if (isPlainObject(base) && isPlainObject(override)) return mergeReusableConfigObjects(base, override, path);
+  if (JSON.stringify(base) === JSON.stringify(override)) return base;
+  throw new Error(`Conflicting Norn reusable config at ${path.join(".")}`);
+}
+function mergeProjectConfigObjects(base, override) {
+  const result = { ...base };
+  for (const [key, overrideValue] of Object.entries(override)) {
+    result[key] = isPlainObject(result[key]) && isPlainObject(overrideValue) ? mergeProjectConfigObjects(result[key], overrideValue) : overrideValue;
+  }
+  return result;
+}
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function defaultConfigInput(configSchema, config) {
+  if (config !== void 0) return config;
+  return schemaType(unwrapSchema(configSchema)) === "object" ? {} : void 0;
+}
+async function expandIncludePath(configRoot, includePath) {
+  const resolvedIncludePath = resolveConfigPath(configRoot, includePath);
+  if (!hasGlobSegment(includePath)) return [resolvedIncludePath];
+  return expandGlobSegments(isAbsolute(includePath) ? sep : configRoot, splitPathSegments(includePath));
+}
+async function expandGlobSegments(root, segments) {
+  if (segments.length === 0) return [root];
+  const [segment, ...remainingSegments] = segments;
+  if (segment === "*") {
+    const entries = await readdir(root, { withFileTypes: true });
+    const expanded = await Promise.all(entries.filter((entry) => entry.isDirectory()).sort((left, right) => left.name.localeCompare(right.name)).map((entry) => expandGlobSegments(join(root, entry.name), remainingSegments)));
+    return expanded.flat();
+  }
+  return expandGlobSegments(join(root, segment), remainingSegments);
+}
+function resolveConfigPath(configRoot, path) {
+  if (path.length === 0) throw new Error("Norn path must not be empty");
+  return isAbsolute(path) ? path : resolve(configRoot, path);
+}
+function hasGlobSegment(path) {
+  return splitPathSegments(path).includes("*");
+}
+function splitPathSegments(path) {
+  return path.split(/[\\/]+/).filter((segment) => segment.length > 0 && segment !== ".");
+}
+export {
+  NORN_PROJECT_FILE_NAME,
+  discoverNornProject,
+  findNornProject,
+  inspectNornWorkflow,
+  loadNornProject
+};

package/dist/resources.d.ts

@@ -0,0 +1,11 @@
+import { type NornFileCoordinator } from "@vimhead.dev/norn/files";
+import type { NornResourceDefinition, NornResources } from "@vimhead.dev/norn";
+export declare class NornRunResources implements NornResources {
+    private readonly runRoot;
+    readonly files: NornFileCoordinator;
+    private readonly entries;
+    private constructor();
+    static initialize(runRoot: string): Promise<NornRunResources>;
+    ensure<T>(definition: NornResourceDefinition<T>): Promise<T>;
+    private initializeResource;
+}

package/dist/resources.js

@@ -0,0 +1,98 @@
+// src/resources.ts
+import { mkdir as mkdir2, readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { z } from "zod";
+import { createRunFileCoordinator } from "@vimhead.dev/norn/files";
+
+// ../core/src/errors.ts
+function isNodeError(error) {
+  return error instanceof Error && "code" in error;
+}
+
+// ../core/src/atomic-files.ts
+import { randomUUID } from "node:crypto";
+import { chmod, mkdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+async function writeJsonAtomically(path, value) {
+  await writeTextAtomically(path, `${JSON.stringify(value, null, 2)}
+`);
+}
+async function writeTextAtomically(path, content) {
+  await mkdir(dirname(path), { recursive: true });
+  let existingMode;
+  try {
+    existingMode = (await stat(path)).mode & 511;
+  } catch (error) {
+    if (!isNodeError(error) || error.code !== "ENOENT") throw error;
+  }
+  const tmpPath = `${path}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(tmpPath, content, { encoding: "utf8", mode: existingMode });
+    if (existingMode !== void 0) await chmod(tmpPath, existingMode);
+    await rename(tmpPath, path);
+  } catch (error) {
+    await rm(tmpPath, { force: true }).catch(() => void 0);
+    throw error;
+  }
+}
+
+// src/resources.ts
+var definitionSchema = z.strictObject({ name: z.string(), kind: z.string().min(1), configuration: z.json() });
+var recordSchema = definitionSchema.extend({ isInitialized: z.boolean() });
+var NornRunResources = class _NornRunResources {
+  constructor(runRoot) {
+    this.runRoot = runRoot;
+    this.files = createRunFileCoordinator(runRoot);
+  }
+  runRoot;
+  files;
+  entries = /* @__PURE__ */ new Map();
+  static async initialize(runRoot) {
+    const resources = new _NornRunResources(resolve(runRoot));
+    await mkdir2(join(resources.runRoot, "current", "resources"), { recursive: true });
+    return resources;
+  }
+  async ensure(definition) {
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(definition.name)) throw new Error(`Invalid resource name: ${definition.name}`);
+    const identity = definitionSchema.parse({ name: definition.name, kind: definition.kind, configuration: definition.configuration });
+    const existing = this.entries.get(definition.name);
+    if (existing) {
+      if (!isDeepStrictEqual(existing.definition, identity)) throw new Error(`Incompatible resource definition: ${definition.name}`);
+      return existing.value;
+    }
+    const value = this.initializeResource(definition, identity);
+    const entry = { definition: identity, value };
+    this.entries.set(definition.name, entry);
+    try {
+      return await value;
+    } catch (error) {
+      if (this.entries.get(definition.name) === entry) this.entries.delete(definition.name);
+      throw error;
+    }
+  }
+  async initializeResource(definition, identity) {
+    const directory = join(this.runRoot, "current", "resources", definition.name);
+    await mkdir2(directory, { recursive: true });
+    return this.files.withExclusiveLock(join(directory, "definition.json"), async (path) => {
+      let stored;
+      try {
+        stored = recordSchema.parse(JSON.parse(await readFile(path, "utf8")));
+      } catch (error) {
+        if (!isNodeError(error) || error.code !== "ENOENT") throw error;
+      }
+      if (stored) {
+        const { isInitialized: _isInitialized, ...storedIdentity } = stored;
+        if (!isDeepStrictEqual(storedIdentity, identity)) throw new Error(`Incompatible resource definition: ${definition.name}`);
+      } else {
+        await writeJsonAtomically(path, { ...identity, isInitialized: false });
+      }
+      const value = await definition.initialize({ directory, files: this.files, mode: stored?.isInitialized ? "open" : "create" });
+      if (!stored?.isInitialized) await writeJsonAtomically(path, { ...identity, isInitialized: true });
+      return value;
+    });
+  }
+};
+export {
+  NornRunResources
+};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@vimhead.dev/norn-cli",
+  "version": "0.1.0-tip.0",
+  "description": "Harness-agnostic runtime for agent-driven and code-driven workflows, built primarily for agents.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vimhead/norn.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/vimhead/norn#readme",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "tip"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "assets",
+    "README.md"
+  ],
+  "bin": {
+    "norn": "./bin/norn.mjs"
+  },
+  "exports": {
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    },
+    "./documentation": {
+      "types": "./dist/documentation.d.ts",
+      "import": "./dist/documentation.js"
+    }
+  },
+  "devDependencies": {
+    "@vimhead.dev/norn-core": "0.0.0"
+  },
+  "dependencies": {
+    "@earendil-works/pi-coding-agent": "0.85.1",
+    "jiti": "^2.7.0",
+    "typebox": "^1.3.17",
+    "zod": "^4.4.3",
+    "@vimhead.dev/norn": "0.1.0-tip.0"
+  },
+  "scripts": {
+    "build": "node ../../scripts/build-package.ts"
+  }
+}