@nebutra/contracts 0.1.2 → 2.0.0

package/dist/sleptons.js

@@ -0,0 +1,61 @@
+import {
+  DEFAULT_RESUME_MARGINS,
+  ExperienceKindSchema,
+  RESUME_CONTENT_VERSION,
+  RESUME_SKILL_CATEGORIES,
+  ResumeAchievementSchema,
+  ResumeBasicSchema,
+  ResumeCertificateSchema,
+  ResumeContentV1Schema,
+  ResumeDerivedSchema,
+  ResumeEducationSchema,
+  ResumeExperienceSchema,
+  ResumeFundingSchema,
+  ResumeLangSchema,
+  ResumeLinksSchema,
+  ResumeMarginsSchema,
+  ResumeObjectiveSchema,
+  ResumeOpenSourceSchema,
+  ResumePatentSchema,
+  ResumePeriodSchema,
+  ResumePreferencesSchema,
+  ResumePressSchema,
+  ResumeProjectSchema,
+  ResumePublicationSchema,
+  ResumeSkillsSchema,
+  ResumeVentureSchema,
+  ResumeVolunteeringSchema,
+  ResumeWriteSchema,
+  VentureStageSchema
+} from "./chunk-PU65L2HQ.js";
+export {
+  DEFAULT_RESUME_MARGINS,
+  ExperienceKindSchema,
+  RESUME_CONTENT_VERSION,
+  RESUME_SKILL_CATEGORIES,
+  ResumeAchievementSchema,
+  ResumeBasicSchema,
+  ResumeCertificateSchema,
+  ResumeContentV1Schema,
+  ResumeDerivedSchema,
+  ResumeEducationSchema,
+  ResumeExperienceSchema,
+  ResumeFundingSchema,
+  ResumeLangSchema,
+  ResumeLinksSchema,
+  ResumeMarginsSchema,
+  ResumeObjectiveSchema,
+  ResumeOpenSourceSchema,
+  ResumePatentSchema,
+  ResumePeriodSchema,
+  ResumePreferencesSchema,
+  ResumePressSchema,
+  ResumeProjectSchema,
+  ResumePublicationSchema,
+  ResumeSkillsSchema,
+  ResumeVentureSchema,
+  ResumeVolunteeringSchema,
+  ResumeWriteSchema,
+  VentureStageSchema
+};
+//# sourceMappingURL=sleptons.js.map

package/dist/sleptons.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "@nebutra/contracts",
-  "version": "0.1.2",
+  "version": "2.0.0",
   "description": "Canonical API/event/domain contracts for Nebutra superstarter",
   "private": false,
+  "nebutra": {
+    "status": "foundation",
+    "graph": "core",
+    "productionReady": false
+  },
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -27,6 +32,14 @@
     "./notifications": {
       "import": "./dist/notifications.js",
       "types": "./dist/notifications.d.ts"
+    },
+    "./admin": {
+      "import": "./dist/admin.js",
+      "types": "./dist/admin.d.ts"
+    },
+    "./sleptons": {
+      "import": "./dist/sleptons.js",
+      "types": "./dist/sleptons.d.ts"
     }
   },
   "dependencies": {
@@ -35,7 +48,8 @@
   "devDependencies": {
     "@types/node": "^22.19.15",
     "tsup": "^8.5.1",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.4"
   },
   "homepage": "https://github.com/Nebutra/Nebutra-Sailor/tree/main/packages/commerce/contracts#readme",
   "repository": {
@@ -52,6 +66,7 @@
   "scripts": {
     "build": "tsup",
     "typecheck": "tsc --noEmit",
-    "clean": "rm -rf dist .turbo"
+    "clean": "rm -rf dist .turbo",
+    "test": "vitest run"
   }
 }

package/src/__tests__/admin.test.ts

@@ -0,0 +1,120 @@
+import { describe, expect, it } from "vitest";
+import {
+  ActionRequestSchema,
+  AdminManifestSchema,
+  assertApplyAllowed,
+  resolveContractUrl,
+  roleAtLeast,
+  SignalReadingSchema,
+} from "../admin";
+
+const manifest = {
+  contract: "nebutra.admin/v1",
+  product: "router",
+  label: "Nebutra Router",
+  version: "0.1.1",
+  origin: "https://router.example.com",
+  graph: "core",
+  status: "wip",
+  health: "/api/health",
+  domains: [
+    {
+      id: "supply",
+      label: "Supply",
+      resources: [
+        {
+          id: "account",
+          label: "Accounts",
+          list: "/api/admin/v1/supply/accounts",
+          columns: [{ key: "provider", label: "Provider" }],
+          actions: ["account.relogin"],
+        },
+      ],
+      actions: [
+        {
+          id: "account.relogin",
+          verb: "Re-login",
+          resource: "account",
+          role: "platform_operator",
+          url: "/api/admin/v1/supply/actions/account.relogin",
+        },
+        {
+          id: "channel.sync",
+          verb: "Sync channel",
+          role: "platform_operator",
+          url: "/api/admin/v1/supply/actions/channel.sync",
+        },
+      ],
+      signals: [
+        {
+          id: "channel.drift",
+          label: "Channel out of sync",
+          severity: "warn",
+          probe: "/api/admin/v1/supply/signals/channel.drift",
+          action: "channel.sync",
+        },
+      ],
+      policies: [
+        {
+          id: "channel.autosync",
+          label: "Auto-sync",
+          on: "nebutra/supply.account.changed",
+          runs: "channel.sync",
+        },
+      ],
+    },
+  ],
+};
+
+describe("admin contract", () => {
+  it("accepts a well-formed manifest and applies defaults", () => {
+    const parsed = AdminManifestSchema.parse(manifest);
+    expect(parsed.domains[0]?.actions[0]?.plan).toBe(true);
+    expect(parsed.domains[0]?.resources[0]?.key).toBe("id");
+  });
+
+  it("rejects dangling references", () => {
+    const bad = structuredClone(manifest) as typeof manifest;
+    const signal = bad.domains[0]?.signals[0];
+    if (!signal) throw new Error("fixture");
+    signal.action = "does.not.exist";
+    const result = AdminManifestSchema.safeParse(bad);
+    expect(result.success).toBe(false);
+    expect(JSON.stringify(result.error?.issues)).toContain("unknown action does.not.exist");
+  });
+
+  it("requires a plan before applying a planned action", () => {
+    const action = AdminManifestSchema.parse(manifest).domains[0]?.actions[1];
+    if (!action) throw new Error("fixture");
+    expect(
+      assertApplyAllowed(action, ActionRequestSchema.parse({ mode: "apply" }))?.error.code,
+    ).toBe("plan_required");
+    expect(
+      assertApplyAllowed(action, ActionRequestSchema.parse({ mode: "apply", planId: "p1" })),
+    ).toBeNull();
+    expect(assertApplyAllowed(action, ActionRequestSchema.parse({ mode: "plan" }))).toBeNull();
+  });
+
+  it("signal readings must carry probedAt", () => {
+    expect(
+      SignalReadingSchema.safeParse({ id: "channel.drift", status: "raised", severity: "warn" })
+        .success,
+    ).toBe(false);
+    expect(
+      SignalReadingSchema.safeParse({
+        id: "channel.drift",
+        status: "ok",
+        severity: "warn",
+        probedAt: new Date().toISOString(),
+      }).success,
+    ).toBe(true);
+  });
+
+  it("role ladder and url resolution", () => {
+    expect(roleAtLeast("platform_owner", "platform_operator")).toBe(true);
+    expect(roleAtLeast("platform_readonly", "platform_support")).toBe(false);
+    expect(resolveContractUrl(manifest, "/api/health")).toBe(
+      "https://router.example.com/api/health",
+    );
+  });
+});

package/src/admin.ts

@@ -0,0 +1,297 @@
+import { z } from "zod";
+
+/**
+ * Admin Contract — `nebutra.admin/v1`.
+ *
+ * Every Nebutra SaaS exposes one manifest describing the admin surface it
+ * owns: resources (nouns), actions (audited verbs, plan → apply), signals
+ * (probed facts) and policies (actions the system runs by itself). The
+ * platform admin renders any product from its manifest; an agent derives
+ * tools from it. Nothing product-specific lives in the renderer.
+ *
+ * See docs/plans/2026-09-08-admin-of-admins-model.md.
+ */
+
+export const ADMIN_CONTRACT_VERSION = "nebutra.admin/v1" as const;
+
+/** One status vocabulary. `unknown` is first-class and never renders green. */
+export const AdminStatusSchema = z.enum(["healthy", "degraded", "down", "unknown"]);
+export type AdminStatus = z.infer<typeof AdminStatusSchema>;
+
+/** One role ladder; product roles map onto it, staff grants mean the same everywhere. */
+export const StaffRoleSchema = z.enum([
+  "platform_readonly",
+  "platform_support",
+  "platform_operator",
+  "platform_owner",
+]);
+export type StaffRole = z.infer<typeof StaffRoleSchema>;
+export const STAFF_ROLE_RANK: Record<StaffRole, number> = {
+  platform_readonly: 0,
+  platform_support: 1,
+  platform_operator: 2,
+  platform_owner: 3,
+};
+export function roleAtLeast(role: StaffRole, required: StaffRole): boolean {
+  return STAFF_ROLE_RANK[role] >= STAFF_ROLE_RANK[required];
+}
+
+export const AdminSeveritySchema = z.enum(["info", "warn", "critical"]);
+export type AdminSeverity = z.infer<typeof AdminSeveritySchema>;
+
+/** The canonical eleven. A product declares the subset it has. */
+export const AdminDomainIdSchema = z.enum([
+  "identity",
+  "access",
+  "commerce",
+  "usage",
+  "catalog",
+  "operations",
+  "integrations",
+  "trust",
+  "support",
+  "growth",
+  "settings",
+  // Platform-only cross-cutting domain: shared AI supply (router).
+  "supply",
+]);
+export type AdminDomainId = z.infer<typeof AdminDomainIdSchema>;
+
+const IdSchema = z
+  .string()
+  .min(1)
+  .max(64)
+  .regex(/^[a-z][a-z0-9._-]*$/, "ids are lowercase dotted identifiers");
+const UrlPathSchema = z.string().min(1).regex(/^\//, "contract urls are origin-relative paths");
+
+export const AdminColumnSchema = z.object({
+  key: z.string().min(1),
+  label: z.string().min(1),
+  kind: z.enum(["text", "mono", "status", "badge", "number", "time", "link"]).default("text"),
+  /** Right-align numbers; the renderer does not guess from values. */
+  align: z.enum(["start", "end"]).default("start"),
+});
+export type AdminColumn = z.infer<typeof AdminColumnSchema>;
+
+export const AdminResourceSchema = z.object({
+  id: IdSchema,
+  label: z.string().min(1),
+  /** `GET list` → ResourceList */
+  list: UrlPathSchema,
+  /** `GET detail` with `{id}` placeholder → one item */
+  detail: UrlPathSchema.optional(),
+  columns: z.array(AdminColumnSchema).min(1),
+  /** Column key that identifies a row. */
+  key: z.string().min(1).default("id"),
+  search: z.boolean().default(false),
+  /** Action ids applicable per row. */
+  actions: z.array(IdSchema).default([]),
+});
+export type AdminResource = z.infer<typeof AdminResourceSchema>;
+
+export const AdminActionSchema = z.object({
+  id: IdSchema,
+  verb: z.string().min(1),
+  /** Resource the action belongs to; omitted = domain-level action. */
+  resource: IdSchema.optional(),
+  /** Minimum staff role. Read-only tier never sees write controls. */
+  role: StaffRoleSchema,
+  /** `POST url` with ActionRequest (`mode: plan | apply`). */
+  url: UrlPathSchema,
+  /** Plan step is mandatory; `false` only for idempotent, non-destructive refreshes. */
+  plan: z.boolean().default(true),
+  destructive: z.boolean().default(false),
+  /** JSON Schema for `input`; doubles as the MCP tool inputSchema. */
+  input: z.record(z.string(), z.unknown()).optional(),
+  description: z.string().optional(),
+});
+export type AdminAction = z.infer<typeof AdminActionSchema>;
+
+export const AdminSignalSchema = z.object({
+  id: IdSchema,
+  label: z.string().min(1),
+  severity: AdminSeveritySchema,
+  /** `GET probe` → SignalReading. Probed, never configured. */
+  probe: UrlPathSchema,
+  resource: IdSchema.optional(),
+  /** Action that resolves the signal when raised. */
+  action: IdSchema.optional(),
+});
+export type AdminSignal = z.infer<typeof AdminSignalSchema>;
+
+export const AdminPolicySchema = z.object({
+  id: IdSchema,
+  label: z.string().min(1),
+  /** Event name (`nebutra/<domain>.<thing>.<verb>`) that triggers the policy. */
+  on: z.string().min(1),
+  runs: IdSchema,
+  enabled: z.boolean().default(true),
+  /** Natural-language intent the policy was compiled from, when it was. */
+  intent: z.string().optional(),
+});
+export type AdminPolicy = z.infer<typeof AdminPolicySchema>;
+
+export const AdminDomainSchema = z.object({
+  id: AdminDomainIdSchema,
+  label: z.string().min(1),
+  resources: z.array(AdminResourceSchema).default([]),
+  actions: z.array(AdminActionSchema).default([]),
+  signals: z.array(AdminSignalSchema).default([]),
+  policies: z.array(AdminPolicySchema).default([]),
+  /** Product-owned browser surface for what the generic renderer cannot express. */
+  slot: UrlPathSchema.optional(),
+});
+export type AdminDomain = z.infer<typeof AdminDomainSchema>;
+
+export const AdminManifestSchema = z
+  .object({
+    contract: z.literal(ADMIN_CONTRACT_VERSION),
+    product: IdSchema,
+    label: z.string().min(1),
+    version: z.string().min(1),
+    /** Absolute origin every relative url resolves against. */
+    origin: z.string().url(),
+    graph: z.enum(["core", "runtime", "labs"]),
+    status: z.enum(["stable", "foundation", "wip", "experimental"]),
+    /** `GET health` → @nebutra/health HealthCheckResult. */
+    health: UrlPathSchema,
+    /** `GET audit?…` → audit events (nebutra.audit/v1). */
+    audit: UrlPathSchema.optional(),
+    domains: z.array(AdminDomainSchema).min(1),
+  })
+  .superRefine((m, ctx) => {
+    for (const d of m.domains) {
+      const actionIds = new Set(d.actions.map((a) => a.id));
+      const resourceIds = new Set(d.resources.map((r) => r.id));
+      for (const r of d.resources) {
+        for (const a of r.actions) {
+          if (!actionIds.has(a)) {
+            ctx.addIssue({
+              code: "custom",
+              message: `resource ${r.id} references unknown action ${a}`,
+            });
+          }
+        }
+      }
+      for (const s of d.signals) {
+        if (s.action && !actionIds.has(s.action)) {
+          ctx.addIssue({
+            code: "custom",
+            message: `signal ${s.id} references unknown action ${s.action}`,
+          });
+        }
+        if (s.resource && !resourceIds.has(s.resource)) {
+          ctx.addIssue({
+            code: "custom",
+            message: `signal ${s.id} references unknown resource ${s.resource}`,
+          });
+        }
+      }
+      for (const p of d.policies) {
+        if (!actionIds.has(p.runs)) {
+          ctx.addIssue({ code: "custom", message: `policy ${p.id} runs unknown action ${p.runs}` });
+        }
+      }
+    }
+  });
+export type AdminManifest = z.infer<typeof AdminManifestSchema>;
+
+// -----------------------------------------------------------------------------
+// Wire envelopes
+// -----------------------------------------------------------------------------
+
+export const ResourceListSchema = z.object({
+  items: z.array(z.record(z.string(), z.unknown())),
+  total: z.number().int().min(0),
+  /** When the list was produced from live probes; omitted for pure reads. */
+  probedAt: z.string().datetime().optional(),
+});
+export type ResourceList = z.infer<typeof ResourceListSchema>;
+
+export const ActionRequestSchema = z.discriminatedUnion("mode", [
+  z.object({ mode: z.literal("plan"), input: z.record(z.string(), z.unknown()).default({}) }),
+  z.object({
+    mode: z.literal("apply"),
+    input: z.record(z.string(), z.unknown()).default({}),
+    /** Required when the action is destructive; ties the apply to a reviewed plan. */
+    planId: z.string().min(1).optional(),
+  }),
+]);
+export type ActionRequest = z.infer<typeof ActionRequestSchema>;
+
+export const PlanDiffEntrySchema = z.object({
+  op: z.enum(["add", "remove", "change"]),
+  path: z.string().min(1),
+  from: z.unknown().optional(),
+  to: z.unknown().optional(),
+});
+export const ActionPlanSchema = z.object({
+  planId: z.string().min(1),
+  summary: z.string().min(1),
+  diff: z.array(PlanDiffEntrySchema),
+  affected: z
+    .array(z.object({ resource: IdSchema, id: z.string(), label: z.string().optional() }))
+    .default([]),
+  warnings: z.array(z.string()).default([]),
+  /** Plans expire; an apply after this is refused. */
+  expiresAt: z.string().datetime(),
+});
+export type ActionPlan = z.infer<typeof ActionPlanSchema>;
+
+export const ActionResultSchema = z.object({
+  /** Audit event id written by the product for this apply. */
+  auditId: z.string().min(1),
+  summary: z.string().min(1),
+  result: z.record(z.string(), z.unknown()).optional(),
+});
+export type ActionResult = z.infer<typeof ActionResultSchema>;
+
+export const SignalReadingSchema = z.object({
+  id: IdSchema,
+  status: z.enum(["ok", "raised", "unknown"]),
+  severity: AdminSeveritySchema,
+  probedAt: z.string().datetime(),
+  title: z.string().optional(),
+  detail: z.string().optional(),
+  resource: IdSchema.optional(),
+  action: IdSchema.optional(),
+  data: z.record(z.string(), z.unknown()).optional(),
+});
+export type SignalReading = z.infer<typeof SignalReadingSchema>;
+
+/** Standard error body for contract endpoints. */
+export const AdminErrorSchema = z.object({
+  error: z.object({
+    code: z.enum([
+      "unauthenticated",
+      "forbidden",
+      "not_found",
+      "invalid_input",
+      "plan_required",
+      "plan_expired",
+      "upstream_unavailable",
+      "internal",
+    ]),
+    message: z.string(),
+  }),
+});
+export type AdminError = z.infer<typeof AdminErrorSchema>;
+
+/** Validate an apply against its action: destructive applies must reference a plan. */
+export function assertApplyAllowed(action: AdminAction, request: ActionRequest): AdminError | null {
+  if (request.mode !== "apply") return null;
+  if ((action.destructive || action.plan) && !request.planId) {
+    return {
+      error: {
+        code: "plan_required",
+        message: `${action.id} requires a reviewed plan before apply`,
+      },
+    };
+  }
+  return null;
+}
+
+/** Resolve a contract path against the manifest origin. */
+export function resolveContractUrl(manifest: Pick<AdminManifest, "origin">, path: string): string {
+  return new URL(path, manifest.origin).toString();
+}

package/src/index.ts

@@ -1,4 +1,6 @@
+export * from "./admin";
 export * from "./billing";
 export * from "./events";
 export * from "./identity";
 export * from "./notifications";
+export * from "./sleptons";

package/src/sleptons.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it } from "vitest";
+import { RESUME_CONTENT_VERSION, ResumeContentV1Schema, ResumeWriteSchema } from "./sleptons";
+
+describe("ResumeContentV1Schema", () => {
+  it("accepts a minimal résumé and fills defaults", () => {
+    const parsed = ResumeContentV1Schema.parse({ basic: { name: "Zhang Wei" } });
+    expect(parsed.version).toBe(RESUME_CONTENT_VERSION);
+    expect(parsed.objective).toEqual({});
+    expect(parsed.preferences.paper).toBe("A4");
+    expect(parsed.preferences.margins.top).toBe("12mm");
+    expect(parsed.preferences.show_contact_public).toBe(false);
+  });
+
+  it("defaults experience kind to work", () => {
+    const parsed = ResumeContentV1Schema.parse({
+      basic: { name: "A" },
+      experiences: [{ period: "2024", org: "Acme", title: "Eng" }],
+    });
+    expect(parsed.experiences?.[0]?.kind).toBe("work");
+  });
+
+  it("rejects an empty name, bad email, and more than 8 advantage tags", () => {
+    expect(ResumeContentV1Schema.safeParse({ basic: { name: "" } }).success).toBe(false);
+    expect(ResumeContentV1Schema.safeParse({ basic: { name: "A", email: "nope" } }).success).toBe(
+      false,
+    );
+    expect(
+      ResumeContentV1Schema.safeParse({
+        basic: { name: "A" },
+        objective: { advantage_tags: Array.from({ length: 9 }, (_, i) => `t${i}`) },
+      }).success,
+    ).toBe(false);
+  });
+
+  it("rejects a wrong content version", () => {
+    expect(ResumeContentV1Schema.safeParse({ version: 2, basic: { name: "A" } }).success).toBe(
+      false,
+    );
+  });
+
+  it("only allows known skill categories", () => {
+    const res = ResumeContentV1Schema.safeParse({
+      basic: { name: "A" },
+      skills: { programming: ["TypeScript"], unknown_cat: ["x"] },
+    });
+    // unknown keys are stripped by default, never persisted
+    expect(res.success).toBe(true);
+    expect(res.success && "unknown_cat" in (res.data.skills ?? {})).toBe(false);
+  });
+});
+
+describe("ResumeWriteSchema", () => {
+  it("wraps content with optional visibility and language", () => {
+    const parsed = ResumeWriteSchema.parse({
+      content: { basic: { name: "A" } },
+      is_public: true,
+      language: "EN",
+    });
+    expect(parsed.is_public).toBe(true);
+    expect(parsed.language).toBe("EN");
+  });
+});