@nebutra/agent-runtime 0.2.0 → 0.2.2

package/src/definitions.ts

@@ -1,190 +0,0 @@
-/**
- * Shared definition kernel (WRAP — Claude-Code-class harness, the delta).
- *
- * Faithful re-expression of the source harness's layered-merge + precedence +
- * dual-gate resolver and its frontmatter→record parser. One implementation
- * backs the command registry, the skill catalog, and the subagent-definition
- * registry (the source uses the same loader for all three).
- *
- * Multi-tenant: every resolution is keyed by `tenantId`; tiers from one tenant
- * never merge into another. Pure data/logic — no FS scan, no shell, no TUI.
- */
-
-import { z } from "zod";
-
-/**
- * Source-tier precedence, low → high authority. A later tier overrides an
- * earlier one on slug collision (mirrors the upstream merge order:
- * bundled → builtin → workspace → workflow → plugin → dynamic, with
- * org policy as the final, non-overridable authority).
- */
-export const SOURCE_TIERS = [
-  "bundled",
-  "builtin",
-  "workspace",
-  "workflow",
-  "plugin",
-  "dynamic",
-  "policy",
-] as const;
-export type SourceTier = (typeof SOURCE_TIERS)[number];
-
-const tierRank = new Map<SourceTier, number>(SOURCE_TIERS.map((t, i) => [t, i]));
-
-/** Frontmatter shared by skills / commands / subagents (faithful subset). */
-export const frontmatterSchema = z.object({
-  name: z.string().min(1),
-  description: z.string().default(""),
-  /** Tool allowlist this definition self-declares. */
-  allowedTools: z.array(z.string()).default([]),
-  /** Tool denylist (subagents). */
-  disallowedTools: z.array(z.string()).default([]),
-  argumentHint: z.string().optional(),
-  argNames: z.array(z.string()).default([]),
-  whenToUse: z.string().optional(),
-  version: z.string().optional(),
-  /** "inherit" | a model alias. */
-  model: z.string().optional(),
-  effort: z.enum(["low", "medium", "high"]).optional(),
-  /** Model may auto-invoke this. */
-  modelInvocable: z.boolean().default(true),
-  /** A human may invoke this. */
-  userInvocable: z.boolean().default(true),
-  /** inline = expand into current turn; fork = isolated child. */
-  executionMode: z.enum(["inline", "fork"]).default("inline"),
-  agent: z.string().optional(),
-  /** Path-activation globs (surface only after a matching file is touched). */
-  paths: z.array(z.string()).default([]),
-});
-export type Frontmatter = z.infer<typeof frontmatterSchema>;
-
-const FRONTMATTER_FENCE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
-
-/** Aliases mapping kebab/snake frontmatter keys → schema keys. */
-const KEY_ALIASES: Record<string, keyof Frontmatter> = {
-  "allowed-tools": "allowedTools",
-  "disallowed-tools": "disallowedTools",
-  "argument-hint": "argumentHint",
-  arguments: "argNames",
-  when_to_use: "whenToUse",
-  "disable-model-invocation": "modelInvocable", // inverted below
-  "user-invocable": "userInvocable",
-  context: "executionMode",
-};
-
-function coerceScalar(raw: string): string | boolean | string[] {
-  const v = raw.trim();
-  if (v === "true") return true;
-  if (v === "false") return false;
-  if (v.startsWith("[") && v.endsWith("]")) {
-    return v
-      .slice(1, -1)
-      .split(",")
-      .map((s) => s.trim().replace(/^["']|["']$/g, ""))
-      .filter(Boolean);
-  }
-  return v.replace(/^["']|["']$/g, "");
-}
-
-/**
- * Parse a `--- … ---` frontmatter block + remaining body. Dependency-light
- * line parser (the package only depends on zod) — sufficient for the simple
- * key: value / list frontmatter the source uses. Throws on missing block.
- */
-export function parseFrontmatter(raw: string): { frontmatter: Frontmatter; body: string } {
-  const m = FRONTMATTER_FENCE.exec(raw);
-  if (!m) throw new Error("definition is missing a '--- … ---' frontmatter block");
-  const block = m[1] ?? "";
-  const body = raw.slice(m[0].length);
-
-  const bag: Record<string, unknown> = {};
-  for (const line of block.split(/\r?\n/)) {
-    if (!line.trim() || /^\s*#/.test(line)) continue;
-    const idx = line.indexOf(":");
-    if (idx < 0) continue;
-    const rawKey = line.slice(0, idx).trim();
-    const value = coerceScalar(line.slice(idx + 1));
-    const key = KEY_ALIASES[rawKey] ?? (rawKey as keyof Frontmatter);
-    if (rawKey === "disable-model-invocation") {
-      bag.modelInvocable = value === true ? false : value === false ? true : true;
-      continue;
-    }
-    if (rawKey === "context") {
-      bag.executionMode = value === "fork" ? "fork" : "inline";
-      continue;
-    }
-    bag[key] = value;
-  }
-  return { frontmatter: frontmatterSchema.parse(bag), body };
-}
-
-/** A resolvable definition of any kind (skill / command / subagent). */
-export interface Definition {
-  readonly slug: string;
-  readonly tenantId: string;
-  readonly sourceTier: SourceTier;
-  readonly frontmatter: Frontmatter;
-  readonly bodyRef: string;
-  /** Entitlement gate — who may have this at all. */
-  readonly availabilityPlans?: readonly string[];
-  /** Runtime/feature toggle, recomputed per request. */
-  readonly enabled?: boolean;
-}
-
-export interface ResolveContext {
-  readonly tenantId: string;
-  readonly plan?: string;
-  /** Names already loaded this session (suppressed from re-listing). */
-  readonly loadedSlugs?: ReadonlySet<string>;
-}
-
-/**
- * Tenant-scoped layered resolver. Merges definitions by slug with tier
- * precedence and applies the dual gate (availability ∧ enabled), recomputed
- * per call so entitlement/flag changes apply live. Cross-tenant inputs are
- * rejected — fail closed.
- */
-export class DefinitionResolver<T extends Definition = Definition> {
-  readonly #all: readonly T[];
-
-  constructor(definitions: readonly T[]) {
-    this.#all = [...definitions];
-  }
-
-  /** Entitlement gate. */
-  static available(def: Definition, plan?: string): boolean {
-    if (!def.availabilityPlans || def.availabilityPlans.length === 0) return true;
-    return plan != null && def.availabilityPlans.includes(plan);
-  }
-
-  resolve(ctx: ResolveContext): T[] {
-    if (!ctx.tenantId) throw new Error("ResolveContext.tenantId is required");
-    const winner = new Map<string, T>();
-    for (const def of this.#all) {
-      if (def.tenantId !== ctx.tenantId) continue; // tenant isolation, fail-closed
-      if (def.enabled === false) continue;
-      if (!DefinitionResolver.available(def, ctx.plan)) continue;
-      const cur = winner.get(def.slug);
-      if (!cur || tierRank.get(def.sourceTier)! >= tierRank.get(cur.sourceTier)!) {
-        winner.set(def.slug, def);
-      }
-    }
-    return [...winner.values()];
-  }
-
-  /** Resolve a single slug (highest-precedence, gated). */
-  resolveOne(slug: string, ctx: ResolveContext): T | undefined {
-    return this.resolve(ctx).find((d) => d.slug === slug);
-  }
-}
-
-/** Substitute `${name}` / positional `$1` args + session/dir variables. */
-export function substituteArguments(
-  template: string,
-  args: Record<string, string>,
-  variables: Record<string, string> = {},
-): string {
-  return template.replace(/\$\{(\w+)\}/g, (_, k: string) =>
-    k in args ? args[k]! : k in variables ? variables[k]! : "",
-  );
-}

package/src/deployment-status.test.ts

@@ -1,215 +0,0 @@
-import { describe, expect, it } from "vitest";
-import {
-  advanceState,
-  type DeploymentCommitRef,
-  type DeploymentRecord,
-  deriveLatestStatus,
-  deriveTimelineFromCommits,
-  domainForCommit,
-  getDeploymentStatus,
-  getDeploymentTimeline,
-} from "./deployment-status.js";
-
-const SUFFIX = ".preview.example.test";
-
-describe("domainForCommit", () => {
-  it("is deterministic for the same input", () => {
-    expect(domainForCommit("abc1234", SUFFIX)).toBe(domainForCommit("abc1234", SUFFIX));
-  });
-
-  it("uses the injected suffix and never a hardcoded host", () => {
-    const d = domainForCommit("deadbeef", SUFFIX);
-    expect(d.endsWith(SUFFIX)).toBe(true);
-    const other = domainForCommit("deadbeef", ".other.zone");
-    expect(other.endsWith(".other.zone")).toBe(true);
-    expect(d).not.toBe(other);
-  });
-
-  it("differs per commit sha", () => {
-    expect(domainForCommit("aaa", SUFFIX)).not.toBe(domainForCommit("bbb", SUFFIX));
-  });
-});
-
-describe("deriveLatestStatus", () => {
-  it("uses the matching deployment record state when present", () => {
-    const s = deriveLatestStatus({
-      latestCommitSha: "c1",
-      deployments: [{ commitSha: "c1", deploymentId: "d1", state: "live" }],
-      isAgentRunning: false,
-    });
-    expect(s.state).toBe("live");
-    expect(s.commitSha).toBe("c1");
-    expect(s.deploymentId).toBe("d1");
-  });
-
-  it("returns deploying when no record matches and agent is running", () => {
-    const s = deriveLatestStatus({
-      latestCommitSha: "c2",
-      deployments: [{ commitSha: "other", deploymentId: "d", state: "live" }],
-      isAgentRunning: true,
-    });
-    expect(s.state).toBe("deploying");
-  });
-
-  it("returns idle when no record matches and agent not running", () => {
-    const s = deriveLatestStatus({
-      latestCommitSha: "c3",
-      deployments: [],
-      isAgentRunning: false,
-    });
-    expect(s.state).toBe("idle");
-  });
-
-  it("is live only when an explicit matching record is live", () => {
-    const s = deriveLatestStatus({
-      latestCommitSha: "c4",
-      deployments: [{ commitSha: "c4", deploymentId: "d4", state: "failed" }],
-      isAgentRunning: true,
-    });
-    expect(s.state).toBe("failed");
-  });
-
-  it("never throws on empty input", () => {
-    expect(() =>
-      deriveLatestStatus({ latestCommitSha: "", deployments: [], isAgentRunning: false }),
-    ).not.toThrow();
-  });
-});
-
-describe("deriveTimelineFromCommits", () => {
-  const commits: DeploymentCommitRef[] = [
-    { sha: "head", message: "head msg", date: "2026-05-17" },
-    { sha: "mid", message: "mid msg", date: "2026-05-16" },
-    { sha: "old", message: "old msg", date: "2026-05-15" },
-  ];
-
-  it("produces one entry per commit preserving input order", () => {
-    const t = deriveTimelineFromCommits(commits, [], {
-      domainSuffix: SUFFIX,
-      isAgentRunning: false,
-      latestCommitSha: "head",
-    });
-    expect(t.map((e) => e.commitSha)).toEqual(["head", "mid", "old"]);
-  });
-
-  it("head gets deploying when agent running and no terminal record", () => {
-    const t = deriveTimelineFromCommits(commits, [], {
-      domainSuffix: SUFFIX,
-      isAgentRunning: true,
-      latestCommitSha: "head",
-    });
-    expect(t[0]?.state).toBe("deploying");
-    expect(t[1]?.state).toBe("idle");
-    expect(t[2]?.state).toBe("idle");
-  });
-
-  it("matching deployment record wins over agent-running default", () => {
-    const t = deriveTimelineFromCommits(
-      commits,
-      [{ commitSha: "head", deploymentId: "d", state: "failed" }],
-      {
-        domainSuffix: SUFFIX,
-        isAgentRunning: true,
-        latestCommitSha: "head",
-      },
-    );
-    expect(t[0]?.state).toBe("failed");
-  });
-
-  it("url only present for live/deploying entries", () => {
-    const t = deriveTimelineFromCommits(
-      commits,
-      [{ commitSha: "mid", deploymentId: "d", state: "live" }],
-      {
-        domainSuffix: SUFFIX,
-        isAgentRunning: true,
-        latestCommitSha: "head",
-      },
-    );
-    expect(t[0]?.url).toBe(domainForCommit("head", SUFFIX)); // deploying
-    expect(t[1]?.url).toBe(domainForCommit("mid", SUFFIX)); // live
-    expect(t[2]?.url).toBeUndefined(); // idle
-  });
-
-  it("does not mutate inputs", () => {
-    const cs = structuredClone(commits);
-    const ds: DeploymentRecord[] = [{ commitSha: "head", deploymentId: "d", state: "live" }];
-    const dsClone = structuredClone(ds);
-    deriveTimelineFromCommits(cs, ds, {
-      domainSuffix: SUFFIX,
-      isAgentRunning: true,
-      latestCommitSha: "head",
-    });
-    expect(cs).toEqual(commits);
-    expect(ds).toEqual(dsClone);
-  });
-});
-
-describe("advanceState", () => {
-  it("allows legal transitions", () => {
-    expect(advanceState("idle", "start")).toBe("deploying");
-    expect(advanceState("deploying", "succeed")).toBe("live");
-    expect(advanceState("deploying", "fail")).toBe("failed");
-  });
-
-  it("reset always returns idle", () => {
-    expect(advanceState("live", "reset")).toBe("idle");
-    expect(advanceState("failed", "reset")).toBe("idle");
-    expect(advanceState("idle", "reset")).toBe("idle");
-  });
-
-  it("throws on illegal transitions", () => {
-    expect(() => advanceState("idle", "succeed")).toThrow();
-    expect(() => advanceState("live", "start")).toThrow();
-  });
-});
-
-describe("tenant-scoped entries", () => {
-  it("fails closed on empty tenantId", () => {
-    expect(() =>
-      getDeploymentStatus("", {
-        latestCommitSha: "c1",
-        deployments: [],
-        isAgentRunning: false,
-      }),
-    ).toThrow();
-    expect(() =>
-      getDeploymentTimeline("", [], [], {
-        domainSuffix: SUFFIX,
-        isAgentRunning: false,
-        latestCommitSha: "c1",
-      }),
-    ).toThrow();
-  });
-
-  it("returns status for a valid tenant", () => {
-    const s = getDeploymentStatus("tenant_1", {
-      latestCommitSha: "c1",
-      deployments: [{ commitSha: "c1", deploymentId: "d1", state: "live" }],
-      isAgentRunning: false,
-    });
-    expect(s.state).toBe("live");
-  });
-
-  it("returns timeline for a valid tenant", () => {
-    const t = getDeploymentTimeline(
-      "tenant_1",
-      [{ sha: "head", message: "m", date: "2026-05-17" }],
-      [],
-      { domainSuffix: SUFFIX, isAgentRunning: true, latestCommitSha: "head" },
-    );
-    expect(t).toHaveLength(1);
-    expect(t[0]?.state).toBe("deploying");
-  });
-
-  it("rejects malformed input via zod", () => {
-    expect(() =>
-      getDeploymentStatus("tenant_1", {
-        // @ts-expect-error invalid state
-        deployments: [{ commitSha: "c1", deploymentId: "d1", state: "bogus" }],
-        latestCommitSha: "c1",
-        isAgentRunning: false,
-      }),
-    ).toThrow();
-  });
-});

package/src/deployment-status.ts

@@ -1,227 +0,0 @@
-import { z } from "zod";
-
-/**
- * Deployment lifecycle status model.
- *
- * Commit-keyed deploy state plus a newest-first timeline derivation.
- * Pure, deterministic, immutable. Multi-tenant fail-closed at the
- * public boundary. The preview domain suffix is always injected —
- * there is no hardcoded host anywhere in this module.
- */
-
-export type DeployState = "idle" | "deploying" | "live" | "failed";
-
-export interface DeploymentUiStatus {
-  state: DeployState;
-  commitSha?: string | undefined;
-  url?: string | undefined;
-  deploymentId?: string | undefined;
-}
-
-export interface DeploymentTimelineEntry {
-  commitSha: string;
-  commitMessage: string;
-  commitDate: string;
-  state: DeployState;
-  url?: string | undefined;
-}
-
-/** Structural commit reference — declared locally, no sibling imports. */
-export interface DeploymentCommitRef {
-  sha: string;
-  message: string;
-  date: string;
-}
-
-export interface DeploymentRecord {
-  commitSha: string;
-  deploymentId: string | null;
-  state: DeployState;
-}
-
-export class DeploymentStateError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = "DeploymentStateError";
-  }
-}
-
-const deployStateSchema = z.enum(["idle", "deploying", "live", "failed"]);
-
-const deploymentRecordSchema = z.object({
-  commitSha: z.string(),
-  deploymentId: z.string().nullable(),
-  state: deployStateSchema,
-});
-
-const commitRefSchema = z.object({
-  sha: z.string(),
-  message: z.string(),
-  date: z.string(),
-});
-
-const latestStatusInputSchema = z.object({
-  latestCommitSha: z.string(),
-  deployments: z.array(deploymentRecordSchema),
-  isAgentRunning: z.boolean(),
-});
-
-const timelineOptsSchema = z.object({
-  domainSuffix: z.string().min(1),
-  isAgentRunning: z.boolean(),
-  latestCommitSha: z.string(),
-});
-
-export type LatestStatusInput = z.infer<typeof latestStatusInputSchema>;
-export type TimelineOpts = z.infer<typeof timelineOptsSchema>;
-
-/** Stable, non-cryptographic hash → short deterministic slug. */
-function slugForSha(commitSha: string): string {
-  let hash = 2166136261;
-  for (let i = 0; i < commitSha.length; i += 1) {
-    hash ^= commitSha.charCodeAt(i);
-    hash = Math.imul(hash, 16777619);
-  }
-  return (hash >>> 0).toString(36);
-}
-
-/**
- * Deterministic per-commit preview domain built from an injected suffix.
- * No hardcoded host — the suffix fully determines the zone.
- */
-export function domainForCommit(commitSha: string, domainSuffix: string): string {
-  return `${slugForSha(commitSha)}${domainSuffix}`;
-}
-
-function findRecord(
-  deployments: readonly DeploymentRecord[],
-  commitSha: string,
-): DeploymentRecord | undefined {
-  return deployments.find((d) => d.commitSha === commitSha);
-}
-
-/**
- * Faithful rule: matching record state wins; else deploying when the
- * agent is running; else idle. `live` only when a matching record is
- * explicitly live. Never throws.
- */
-export function deriveLatestStatus(input: {
-  latestCommitSha: string;
-  deployments: readonly DeploymentRecord[];
-  isAgentRunning: boolean;
-}): DeploymentUiStatus {
-  const { latestCommitSha, deployments, isAgentRunning } = input;
-  const record = findRecord(deployments, latestCommitSha);
-
-  if (record) {
-    return {
-      state: record.state,
-      commitSha: latestCommitSha,
-      deploymentId: record.deploymentId ?? undefined,
-    };
-  }
-
-  if (isAgentRunning) {
-    return { state: "deploying", commitSha: latestCommitSha };
-  }
-
-  return { state: "idle", commitSha: latestCommitSha };
-}
-
-/**
- * One entry per commit, newest-first order preserved from input.
- * Matching deployment record wins; the head commit gets `deploying`
- * when the agent is running and has no terminal record; older
- * unmatched commits resolve to `idle`. Immutable, deterministic.
- */
-export function deriveTimelineFromCommits(
-  commits: readonly DeploymentCommitRef[],
-  deployments: readonly DeploymentRecord[],
-  opts: TimelineOpts,
-): DeploymentTimelineEntry[] {
-  const { domainSuffix, isAgentRunning, latestCommitSha } = opts;
-
-  return commits.map((commit) => {
-    const record = findRecord(deployments, commit.sha);
-    let state: DeployState;
-
-    if (record) {
-      state = record.state;
-    } else if (commit.sha === latestCommitSha && isAgentRunning) {
-      state = "deploying";
-    } else {
-      state = "idle";
-    }
-
-    const entry: DeploymentTimelineEntry = {
-      commitSha: commit.sha,
-      commitMessage: commit.message,
-      commitDate: commit.date,
-      state,
-    };
-
-    if (state === "live" || state === "deploying") {
-      return { ...entry, url: domainForCommit(commit.sha, domainSuffix) };
-    }
-    return entry;
-  });
-}
-
-type TransitionEvent = "start" | "succeed" | "fail";
-
-const LEGAL_TRANSITIONS: Record<TransitionEvent, Partial<Record<DeployState, DeployState>>> = {
-  start: { idle: "deploying", failed: "deploying" },
-  succeed: { deploying: "live" },
-  fail: { deploying: "failed" },
-};
-
-/**
- * Explicit deploy state machine. Illegal transitions throw a typed
- * error. `reset` always returns to idle regardless of current state.
- */
-export function advanceState(
-  current: DeployState,
-  event: "start" | "succeed" | "fail" | "reset",
-): DeployState {
-  if (event === "reset") {
-    return "idle";
-  }
-
-  const next = LEGAL_TRANSITIONS[event][current];
-  if (next === undefined) {
-    throw new DeploymentStateError(
-      `Illegal deploy transition: cannot '${event}' from '${current}'`,
-    );
-  }
-  return next;
-}
-
-function assertTenant(tenantId: string): void {
-  if (typeof tenantId !== "string" || tenantId.trim() === "") {
-    throw new DeploymentStateError("tenantId is required (fail-closed)");
-  }
-}
-
-/** Public tenant-scoped status entry — fail-closed, zod-validated. */
-export function getDeploymentStatus(
-  tenantId: string,
-  input: LatestStatusInput,
-): DeploymentUiStatus {
-  assertTenant(tenantId);
-  const parsed = latestStatusInputSchema.parse(input);
-  return deriveLatestStatus(parsed);
-}
-
-/** Public tenant-scoped timeline entry — fail-closed, zod-validated. */
-export function getDeploymentTimeline(
-  tenantId: string,
-  commits: readonly DeploymentCommitRef[],
-  deployments: readonly DeploymentRecord[],
-  opts: TimelineOpts,
-): DeploymentTimelineEntry[] {
-  assertTenant(tenantId);
-  const parsedCommits = z.array(commitRefSchema).parse(commits);
-  const parsedDeployments = z.array(deploymentRecordSchema).parse(deployments);
-  const parsedOpts = timelineOptsSchema.parse(opts);
-  return deriveTimelineFromCommits(parsedCommits, parsedDeployments, parsedOpts);
-}