@catheadowl/ukp 0.1.0

package/src/config/manifest.ts

@@ -0,0 +1,188 @@
+import { readFileSync, realpathSync, statSync } from "node:fs";
+import { basename, join } from "node:path";
+import { parse } from "smol-toml";
+import { z } from "zod";
+import { isExternalToolCapability, EXTERNAL_PROVIDER } from "./external-tool.ts";
+import { isFileNativeCapability, normalizeFileNativeFlatKeys } from "./file-native.ts";
+
+export const ENDPOINT_NAME = /^(?=.{1,63}$)[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+// `provider` is optional at the schema level: file-native capabilities
+// (see file-native.ts, ADR 0016) default to `"file"` at load; every other
+// capability fails fast with a declaration error when `provider` is missing.
+const capabilitySchema = z.object({
+  provider: z.string().min(1).optional(),
+  config: z.record(z.string(), z.unknown()).optional(),
+}).strict();
+
+const endpointNameSchema = z.string().regex(ENDPOINT_NAME);
+
+const dependencyKindSchema = z.enum(["authority", "context", "implementation", "evidence"]);
+
+const dependencySchema = z.object({
+  endpoint: endpointNameSchema,
+  kind: dependencyKindSchema,
+  reason: z.string().min(1).optional(),
+}).strict();
+
+const dependenciesSchema = z.array(dependencySchema).min(1).superRefine((value, context) => {
+  const seen = new Set<string>();
+  for (const [index, dependency] of value.entries()) {
+    if (seen.has(dependency.endpoint)) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `duplicate dependency '${dependency.endpoint}'`,
+        path: [index],
+      });
+      continue;
+    }
+    seen.add(dependency.endpoint);
+  }
+});
+
+const manifestSchema = z.object({
+  name: z.string().optional(),
+  description: z.string().min(1).optional(),
+  dependencies: dependenciesSchema.optional(),
+  capabilities: z.record(z.string(), capabilitySchema),
+}).strict();
+
+export type Manifest = z.infer<typeof manifestSchema>;
+export type ManifestCapability = z.infer<typeof capabilitySchema>;
+export type ManifestDependency = z.infer<typeof dependencySchema>;
+
+export class ManifestError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "ManifestError";
+  }
+}
+
+export function assertRestrictedToml(value: unknown, path = "root"): void {
+  if (value === null || value === undefined || value instanceof Date) {
+    throw new ManifestError(`${path}: unsupported TOML value`);
+  }
+  if (typeof value === "number") {
+    if (!Number.isSafeInteger(value)) {
+      throw new ManifestError(`${path}: only safe integer TOML values are supported`);
+    }
+    return;
+  }
+  if (typeof value === "string" || typeof value === "boolean") return;
+  if (typeof value === "bigint") {
+    throw new ManifestError(`${path}: integer exceeds JavaScript safe range`);
+  }
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => assertRestrictedToml(item, `${path}[${index}]`));
+    return;
+  }
+  if (typeof value === "object") {
+    for (const [key, child] of Object.entries(value)) {
+      assertRestrictedToml(child, `${path}.${key}`);
+    }
+    return;
+  }
+  throw new ManifestError(`${path}: unsupported TOML value`);
+}
+
+function parseName(value: string, source: string): string {
+  if (!ENDPOINT_NAME.test(value)) {
+    throw new ManifestError(`${source}: invalid endpoint name '${value}'`);
+  }
+  return value;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function removeLegacyGetCapability(raw: unknown): unknown {
+  if (!isRecord(raw) || !isRecord(raw.capabilities) || !Object.hasOwn(raw.capabilities, "get")) {
+    return raw;
+  }
+
+  const { get: _ignoredLegacyGet, ...capabilities } = raw.capabilities;
+  return {
+    ...raw,
+    capabilities,
+  };
+}
+
+export interface LoadedManifest {
+  folder: string;
+  manifestPath: string;
+  manifest: Manifest;
+  effectiveName: string;
+  nameSource: "manifest" | "folder-name";
+}
+
+export function loadManifest(serviceFolder: string): LoadedManifest {
+  let folder: string;
+  try {
+    folder = realpathSync(serviceFolder);
+    if (!statSync(folder).isDirectory()) throw new Error("not a directory");
+  } catch (error) {
+    throw new ManifestError(`Service folder is not accessible: ${serviceFolder}`, { cause: error });
+  }
+
+  const manifestPath = join(folder, ".ukp", "service.toml");
+  let source: string;
+  try {
+    source = readFileSync(manifestPath, "utf8");
+  } catch (error) {
+    throw new ManifestError(`Service Manifest is not readable: ${manifestPath}`, { cause: error });
+  }
+
+  let raw: unknown;
+  try {
+    raw = parse(source);
+  } catch (error) {
+    throw new ManifestError(`Service Manifest TOML is invalid: ${manifestPath}`, { cause: error });
+  }
+  assertRestrictedToml(raw);
+
+  const withoutLegacyGet = removeLegacyGetCapability(raw);
+  // Flat file-native declaration keys (table-driven, ADR 0016) fold into
+  // `config` before the strict schema parse.
+  const normalized = normalizeFileNativeFlatKeys(withoutLegacyGet, (message) => {
+    throw new ManifestError(message);
+  });
+  const result = manifestSchema.safeParse(normalized);
+  if (!result.success) {
+    throw new ManifestError(`Service Manifest schema is invalid: ${result.error.message}`);
+  }
+  const manifest = result.data;
+  // A zero-declaration Manifest is valid (D-081): read/nav are derived
+  // file-native defaults for every registered local Service, so an empty
+  // [capabilities] table still yields a usable, diagnosable endpoint.
+
+  const nameSource = manifest.name === undefined ? "folder-name" : "manifest";
+  const effectiveName = parseName(manifest.name ?? basename(folder), nameSource);
+  if (manifest.dependencies?.some((dependency) => dependency.endpoint === effectiveName)) {
+    throw new ManifestError(`Service Manifest dependency cannot target the Service itself: '${effectiveName}'`);
+  }
+  // Capability-level provider defaults (ADR 0016 rule 1 / ADR-RG-003): a
+  // bare `[capabilities.<name>]` declaration means the UKP-native file
+  // provider for file-native capabilities, the external-tool base tier for
+  // external-tool capabilities. Every other capability fails fast at load
+  // when `provider` is missing (a typo must not degrade into a runtime
+  // "(none)" warning); an external-tool capability with a different provider
+  // is a hard error (the tier does not plugin alternative tools).
+  for (const [name, declaration] of Object.entries(manifest.capabilities)) {
+    if (declaration.provider === undefined) {
+      if (isFileNativeCapability(name)) {
+        manifest.capabilities[name] = { ...declaration, provider: "file" };
+      } else if (isExternalToolCapability(name)) {
+        manifest.capabilities[name] = { ...declaration, provider: EXTERNAL_PROVIDER };
+      } else {
+        throw new ManifestError(`[capabilities.${name}] must declare a provider`);
+      }
+    } else if (isExternalToolCapability(name) && declaration.provider !== EXTERNAL_PROVIDER) {
+      throw new ManifestError(
+        `[capabilities.${name}] provider must be '${EXTERNAL_PROVIDER}' or omitted `
+        + `(external-tool base tier: the declaration only overrides config)`,
+      );
+    }
+  }
+  return { folder, manifestPath, manifest, effectiveName, nameSource };
+}

package/src/fslock.ts

@@ -0,0 +1,95 @@
+import {
+  closeSync,
+  existsSync,
+  fsyncSync,
+  openSync,
+  readFileSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { randomUUID } from "node:crypto";
+import { hostname } from "node:os";
+import { parse } from "smol-toml";
+
+export class LockError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "LockError";
+  }
+}
+
+export class LockBusyError extends LockError {
+  constructor(path: string) {
+    super(`lock_busy: ${path}`);
+    this.name = "LockBusyError";
+  }
+}
+
+function sleep(milliseconds: number): void {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
+}
+
+function processExists(pid: number): boolean | undefined {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === "ESRCH") return false;
+    return undefined;
+  }
+}
+
+function reclaimStaleLock(lockPath: string): boolean {
+  try {
+    const metadata = parse(readFileSync(lockPath, "utf8")) as Record<string, unknown>;
+    if (metadata.hostname !== hostname()) return false;
+    if (typeof metadata.pid !== "number" || !Number.isSafeInteger(metadata.pid)) return false;
+    if (typeof metadata.created_at !== "string") return false;
+    const createdAt = Date.parse(metadata.created_at);
+    if (!Number.isFinite(createdAt) || Date.now() - createdAt <= 10 * 60 * 1000) return false;
+    if (processExists(metadata.pid) !== false) return false;
+    unlinkSync(lockPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Write-discipline sibling lock: exclusive create with owner metadata, stale
+// reclamation (same host, >10min old, dead pid), bounded retry.
+export function acquireLock(lockPath: string): number {
+  const deadline = Date.now() + 5000;
+  while (true) {
+    try {
+      const descriptor = openSync(lockPath, "wx", 0o600);
+      try {
+        writeFileSync(
+          descriptor,
+          `pid = ${process.pid}\nhostname = ${JSON.stringify(hostname())}\ncreated_at = ${JSON.stringify(new Date().toISOString())}\ntoken = ${JSON.stringify(randomUUID())}\n`,
+          "utf8",
+        );
+        fsyncSync(descriptor);
+        return descriptor;
+      } catch (error) {
+        closeSync(descriptor);
+        if (existsSync(lockPath)) unlinkSync(lockPath);
+        throw error;
+      }
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "EEXIST" && reclaimStaleLock(lockPath)) {
+        continue;
+      }
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST" || Date.now() >= deadline) {
+        if ((error as NodeJS.ErrnoException).code === "EEXIST") throw new LockBusyError(lockPath);
+        throw new LockError(`cannot acquire lock: ${lockPath}`, { cause: error });
+      }
+      sleep(25);
+    }
+  }
+}
+
+export function releaseLock(lockPath: string, descriptor: number): void {
+  closeSync(descriptor);
+  if (existsSync(lockPath)) unlinkSync(lockPath);
+}

package/src/path-safety.ts

@@ -0,0 +1,65 @@
+import { isAbsolute, relative, win32 } from "node:path";
+
+// Path-safety primitives (ADR 0023 / D-073, promoted spec
+// `path-safety-primitives`): three pure, error-class-neutral checks shared
+// by the file-facing capabilities. The module owns the *verdicts* only —
+// failure semantics (usage error vs silent drop), root semantics
+// (`allowRoot`), realpath fallbacks and existence checks are per-capability
+// policy and stay at the call sites. Primitives never throw and never do
+// I/O: containment receives already-realpathed paths; lexical checks are
+// the advisory tier, realpath containment is the authority.
+
+/** True for every input shape the file-facing capabilities reject as an
+ * endpoint-relative reference: absolute on either platform's view, a drive
+ * prefix (including drive-relative `C:foo`), or a UNC/`//` root. */
+export function isAbsoluteShapedPath(reference: string): boolean {
+  return (
+    isAbsolute(reference)
+    || win32.isAbsolute(reference)
+    || /^[A-Za-z]:/.test(reference)
+    || reference.startsWith("//")
+    || reference.startsWith("\\\\")
+  );
+}
+
+export type EndpointRelativeSegments =
+  | { ok: true; segments: string[] }
+  | { ok: false; reason: "absolute" | "empty-segment" | "dot-segment" };
+
+/** Segment-level validation of an endpoint-relative reference: rejects
+ * absolute shapes, empty segments (`a//b`), and `.`/`..` segments. Accepts
+ * both `/` and `\` separators; callers own separator normalization. The
+ * reason field lets each capability map its own error wording. */
+export function splitEndpointRelativeSegments(reference: string): EndpointRelativeSegments {
+  if (isAbsoluteShapedPath(reference)) {
+    return { ok: false, reason: "absolute" };
+  }
+  const segments = reference.split(/[\\/]/);
+  if (segments.some((segment) => segment.length === 0)) {
+    return { ok: false, reason: "empty-segment" };
+  }
+  if (segments.some((segment) => segment === "." || segment === "..")) {
+    return { ok: false, reason: "dot-segment" };
+  }
+  return { ok: true, segments };
+}
+
+/** Realpath containment authority (ADR 0023): true when `targetReal` stays
+ * strictly inside `rootReal`, or is `rootReal` itself with `allowRoot`.
+ * Inputs must already be realpathed — lexical checks, realpath calls and
+ * stat checks are caller policy. Cross-drive/UNC↔drive `relative()` results
+ * come back absolute and are rejected explicitly. */
+export function isInsideRealRoot(
+  rootReal: string,
+  targetReal: string,
+  options?: { allowRoot?: boolean },
+): boolean {
+  const rel = relative(rootReal, targetReal);
+  if (isAbsolute(rel) || win32.isAbsolute(rel)) return false;
+  // Plain `..` prefix guard — read's historical stance, kept verbatim for the
+  // zero-behavior-change acceptance line. Conservative: a sibling named
+  // `..literal` is rejected too; boundary refinement is a separate change.
+  if (rel.startsWith("..")) return false;
+  if (rel === "") return options?.allowRoot === true;
+  return true;
+}