@synap-core/workspace-templates 0.11.0 → 0.23.0

package/src/lifecycle-presets.ts

@@ -0,0 +1,494 @@
+/**
+ * The ten base lifecycles, as TEMPLATE-TIME presets.
+ * ==================================================
+ *
+ * A profile's lifecycle may be written in full (`options: [...]`) or adopt one
+ * of the ten bases below and say only how it differs:
+ *
+ *   lifecycle:
+ *     property: brand-status
+ *     adopts: asset
+ *     rename: { in-review: studied, deprecated: archived }  # base key → this kind's key
+ *     drop: [in-review]                                      # base keys this kind does not use
+ *     add:                                                   # steps the base does not have
+ *       - { key: signed, category: active, after: sent }     # `after` / `before` a resulting key
+ *     humanOnly: { deprecated: true }                        # per resulting key
+ *     stuckAfterDays: { sent: 14 }                           # per resulting key
+ *     dateBinding: { sent: dueDate }                         # per resulting key
+ *     waits: { sent: { on: external, waitKind: payment } }   # per resulting key
+ *
+ * `resolveLifecyclePresets` compiles that into the flat declaration the pod
+ * already stores (`{ property, options }`), and fills the lifecycle select's
+ * `enumValues` from the options when the YAML leaves them out (the pod
+ * replaces them with the option keys anyway, `declare-lifecycle.ts`). There is
+ * no inheritance at runtime: the pod never sees `adopts`, and a change to a
+ * base reaches a kind only when its template is rebuilt and republished.
+ *
+ * Decision: status-flow plan, document aac47c4a, Q1.3 ("ten bases, as template
+ * presets, not a runtime engine"); the steps are the deep dive's table
+ * (document 152478c2 §1), `humanOnly` and `stuckAfterDays` where it gives them
+ * (§1 table 👤, §7 agreement sketch). The deep dive's "waits on the outside" (⧗)
+ * is not encoded in the bases; a kind declares a step's wait (`waits`) and its
+ * date (`dateBinding`) itself, on an added step or per resulting key. Their
+ * shapes are the validator's (`lifecycleOptionWaitsProblems`, the pod's rules):
+ * this compiler only carries them.
+ *
+ * Callers: `generate.mjs` (build + every corpus test), `validateTemplate` (any
+ * authored YAML), `toWorkspaceDefinition` / `toPackageDefinition`, and the
+ * catalog loader (through the built dist). The resolver is idempotent: a flat
+ * lifecycle with its `enumValues` comes back as the same object.
+ *
+ * Only `import type` here: `build.mjs` and `generate.mjs` load this file under
+ * Node's type stripping, before `dist/` exists.
+ */
+
+import type {
+  TemplateLifecycle,
+  TemplateLifecycleCategory,
+  TemplateLifecycleOption,
+  TemplateLifecycleOptionWaits,
+  TemplateProfile,
+  TemplateProperty,
+  WorkspaceYaml,
+} from "./types.ts";
+
+type BaseStep = Pick<
+  TemplateLifecycleOption,
+  "key" | "category" | "tone" | "humanOnly" | "stuckAfterDays"
+>;
+
+const step = (
+  key: string,
+  category: TemplateLifecycleCategory,
+  extra: Partial<BaseStep> = {}
+): BaseStep => ({
+  key,
+  category,
+  ...extra,
+});
+const PERSON = { humanOnly: true } as const;
+/**
+ * A lost step that is a DECISION (cancelled, withdrawn, superseded, archived,
+ * deprecated), not a failure, wears the muted tone. Without it the pod paints
+ * it with the lost category's default, `error` (`LIFECYCLE_CATEGORY_TONE`,
+ * `@synap-core/types/lifecycle`). Failures (failed, a lost deal, churned) keep
+ * that default. UX review of 2026-10-29.
+ */
+const ENDED = { tone: "textMuted" } as const;
+
+/** The ten bases: default steps in picker order (open → active → paused → done → lost). */
+export const BASE_LIFECYCLES = {
+  "work-item": [
+    step("backlog", "open"),
+    step("todo", "open"),
+    step("doing", "active"),
+    step("review", "active"),
+    step("on-hold", "paused"),
+    step("done", "done"),
+    // Every `cancelled` the corpus declares is a person's call (features, engagements, campaigns).
+    step("cancelled", "lost", { ...PERSON, ...ENDED }),
+  ],
+  run: [
+    step("queued", "open"),
+    step("running", "active"),
+    step("waiting", "paused"),
+    step("succeeded", "done"),
+    step("failed", "lost"),
+    step("cancelled", "lost", ENDED),
+  ],
+  decision: [
+    step("proposed", "open"),
+    step("discussing", "active"),
+    step("on-hold", "paused"),
+    step("accepted", "done"),
+    step("rejected", "lost"),
+    step("superseded", "lost", ENDED),
+    step("withdrawn", "lost", ENDED),
+    step("expired", "lost"),
+  ],
+  // No paused step: an asset is in use or deprecated (plan Q1.2).
+  asset: [
+    step("draft", "open"),
+    step("in-review", "active"),
+    step("approved", "done"),
+    step("deprecated", "lost", ENDED),
+  ],
+  publication: [
+    step("idea", "open"),
+    step("drafting", "active"),
+    step("review", "active"),
+    step("scheduled", "active"),
+    step("on-hold", "paused"),
+    step("published", "done"),
+    step("archived", "lost", ENDED),
+  ],
+  agreement: [
+    step("draft", "open"),
+    step("sent", "active", { stuckAfterDays: 7 }),
+    step("in-progress", "active"),
+    step("on-hold", "paused"),
+    step("fulfilled", "done"),
+    step("declined", "lost", PERSON),
+    step("void", "lost", PERSON),
+    step("expired", "lost"),
+  ],
+  pipeline: [
+    step("new", "open"),
+    step("contacted", "active"),
+    step("qualified", "active"),
+    step("proposal", "active"),
+    step("nurturing", "paused"),
+    step("won", "done", PERSON),
+    step("lost", "lost", PERSON),
+  ],
+  // `former` is a clean end, `churned` a loss (plan Q1.4).
+  relationship: [
+    step("prospect", "open"),
+    step("active", "active"),
+    step("paused", "paused"),
+    step("former", "done"),
+    step("churned", "lost"),
+  ],
+  offering: [
+    step("planned", "open"),
+    step("building", "active"),
+    step("live", "active"),
+    step("paused", "paused"),
+    step("retired", "done"),
+    step("abandoned", "lost"),
+  ],
+  initiative: [
+    step("proposed", "open"),
+    step("agreed", "open", PERSON),
+    step("ready", "open"),
+    step("active", "active"),
+    step("on-hold", "paused"),
+    step("completed", "done", PERSON),
+    step("dropped", "lost"),
+  ],
+} as const satisfies Record<string, readonly BaseStep[]>;
+
+export type BaseLifecycleName = keyof typeof BASE_LIFECYCLES;
+
+/** A step a kind adds to its base. */
+export interface TemplateLifecycleStepAdd extends TemplateLifecycleOption {
+  /** Insert after this resulting key (default: after the last step of its category). */
+  after?: string;
+  /** Insert before this resulting key. */
+  before?: string;
+}
+
+/** The authored form of a lifecycle that adopts a base; compiled to `TemplateLifecycle`. */
+export interface TemplateLifecycleAdoption {
+  property: string;
+  adopts: BaseLifecycleName;
+  /** Base key → this kind's key. */
+  rename?: Record<string, string>;
+  /** Base keys this kind does not use. */
+  drop?: string[];
+  add?: TemplateLifecycleStepAdd[];
+  /** Per resulting key; `false` removes a base's person-only mark. */
+  humanOnly?: Record<string, boolean>;
+  /** Per resulting key. */
+  stuckAfterDays?: Record<string, number>;
+  /** Per resulting key: the date property the step is bound to. */
+  dateBinding?: Record<string, string>;
+  /** Per resulting key: the wait the step declares. */
+  waits?: Record<string, TemplateLifecycleOptionWaits>;
+}
+
+export interface LifecyclePresetProblem {
+  path: string;
+  message: string;
+}
+
+export interface LifecyclePresetResolution {
+  /** The template with every resolvable lifecycle flat; the same object when nothing changed. */
+  template: WorkspaceYaml;
+  /** Overlays that could not be resolved; their lifecycle is left as authored. */
+  problems: LifecyclePresetProblem[];
+}
+
+const ADOPTION_KEYS = new Set([
+  "property",
+  "adopts",
+  "rename",
+  "drop",
+  "add",
+  "humanOnly",
+  "stuckAfterDays",
+  "dateBinding",
+  "waits",
+]);
+const ADD_KEYS = new Set([
+  "key",
+  "label",
+  "category",
+  "tone",
+  "humanOnly",
+  "stuckAfterDays",
+  "dateBinding",
+  "waits",
+  "after",
+  "before",
+]);
+const CATEGORY_ORDER: readonly TemplateLifecycleCategory[] = [
+  "open",
+  "active",
+  "paused",
+  "done",
+  "lost",
+];
+
+const isRecord = (v: unknown): v is Record<string, unknown> =>
+  !!v && typeof v === "object" && !Array.isArray(v);
+
+/** One option in the key order the corpus writes: key, label, category, tone, humanOnly, stuckAfterDays, dateBinding, waits. */
+function option(o: Partial<TemplateLifecycleOption>): TemplateLifecycleOption {
+  const out: Record<string, unknown> = { key: o.key };
+  if (o.label !== undefined) out.label = o.label;
+  out.category = o.category;
+  if (o.tone !== undefined) out.tone = o.tone;
+  if (o.humanOnly) out.humanOnly = true;
+  if (o.stuckAfterDays !== undefined) out.stuckAfterDays = o.stuckAfterDays;
+  if (o.dateBinding !== undefined) out.dateBinding = o.dateBinding;
+  if (o.waits !== undefined) out.waits = o.waits;
+  return out as unknown as TemplateLifecycleOption;
+}
+
+/** Compile one `adopts:` lifecycle; `null` options when it has problems. */
+function resolveAdoption(
+  lc: Record<string, unknown>,
+  at: string,
+  problems: LifecyclePresetProblem[]
+): TemplateLifecycle | null {
+  const before = problems.length;
+  const fail = (path: string, message: string) =>
+    problems.push({ path: `${at}${path}`, message });
+
+  for (const k of Object.keys(lc))
+    if (!ADOPTION_KEYS.has(k))
+      fail(
+        `.${k}`,
+        k === "options"
+          ? "a lifecycle either adopts a base or lists its options, not both"
+          : `"${k}" is not a lifecycle overlay key (${[...ADOPTION_KEYS].join(", ")})`
+      );
+
+  const name = lc.adopts as string;
+  if (!Object.hasOwn(BASE_LIFECYCLES, name)) {
+    fail(
+      ".adopts",
+      `"${String(name)}" is not a base lifecycle (${Object.keys(BASE_LIFECYCLES).join(", ")})`
+    );
+    return null;
+  }
+  const base: readonly BaseStep[] = BASE_LIFECYCLES[name as BaseLifecycleName];
+  const baseKeys = new Set(base.map((s) => s.key));
+  const isBaseKey = (k: unknown, path: string) => {
+    if (typeof k === "string" && baseKeys.has(k)) return true;
+    fail(
+      path,
+      `"${String(k)}" is not a step of the ${name} base (${[...baseKeys].join(", ")})`
+    );
+    return false;
+  };
+
+  const rename = isRecord(lc.rename)
+    ? (lc.rename as Record<string, unknown>)
+    : {};
+  if (lc.rename !== undefined && !isRecord(lc.rename))
+    fail(".rename", "rename maps a base key to this kind's key");
+  for (const [from, to] of Object.entries(rename)) {
+    isBaseKey(from, `.rename.${from}`);
+    if (typeof to !== "string" || to.length === 0)
+      fail(`.rename.${from}`, "a renamed key is a non-empty string");
+  }
+
+  const drop = Array.isArray(lc.drop) ? (lc.drop as unknown[]) : [];
+  if (lc.drop !== undefined && !Array.isArray(lc.drop))
+    fail(".drop", "drop lists base keys");
+  drop.forEach((k, i) => {
+    if (!isBaseKey(k, `.drop[${i}]`)) return;
+    if (Object.hasOwn(rename, k as string))
+      fail(`.drop[${i}]`, `"${String(k)}" is both renamed and dropped`);
+  });
+
+  const steps: TemplateLifecycleOption[] = base
+    .filter((s) => !drop.includes(s.key))
+    .map((s) =>
+      option({ ...s, key: (rename[s.key] as string | undefined) ?? s.key })
+    );
+
+  const adds = Array.isArray(lc.add) ? (lc.add as unknown[]) : [];
+  if (lc.add !== undefined && !Array.isArray(lc.add))
+    fail(".add", "add lists steps");
+  adds.forEach((raw, i) => {
+    const path = `.add[${i}]`;
+    if (
+      !isRecord(raw) ||
+      typeof raw.key !== "string" ||
+      typeof raw.category !== "string"
+    ) {
+      fail(path, "an added step has a key and a category");
+      return;
+    }
+    const unknownKeys = Object.keys(raw).filter((k) => !ADD_KEYS.has(k));
+    if (unknownKeys.length > 0) {
+      fail(
+        path,
+        `${unknownKeys.map((k) => `"${k}"`).join(", ")} is not a step field (${[...ADD_KEYS].join(", ")})`
+      );
+      return;
+    }
+    const {
+      after,
+      before: beforeKey,
+      ...rest
+    } = raw as unknown as TemplateLifecycleStepAdd;
+    if (after !== undefined && beforeKey !== undefined)
+      fail(path, "an added step goes after OR before a step, not both");
+    const anchor = after ?? beforeKey;
+    let index: number;
+    if (anchor !== undefined) {
+      const found = steps.findIndex((s) => s.key === anchor);
+      if (found < 0) {
+        fail(
+          `${path}.${after !== undefined ? "after" : "before"}`,
+          `"${anchor}" is not a step of this lifecycle`
+        );
+        return;
+      }
+      index = after !== undefined ? found + 1 : found;
+    } else {
+      // After the last step of its category, else before the first step of a later one.
+      const rank = CATEGORY_ORDER.indexOf(rest.category);
+      const later = steps.findIndex(
+        (s) => CATEGORY_ORDER.indexOf(s.category) > rank
+      );
+      index = later < 0 ? steps.length : later;
+    }
+    steps.splice(index, 0, option(rest));
+  });
+
+  const keys = steps.map((s) => s.key);
+  keys.forEach((k, i) => {
+    if (keys.indexOf(k) !== i)
+      fail("", `step "${k}" appears twice after the overlay`);
+  });
+  const byKey = new Map(steps.map((s) => [s.key, s]));
+  // Each override's TYPE is checked here; a `dateBinding` / `waits` shape is
+  // the validator's (`lifecycleOptionWaitsProblems`), which runs on the result.
+  const OVERRIDE_TYPE = {
+    humanOnly: ["boolean", "a boolean"],
+    stuckAfterDays: ["number", "a number of days"],
+    dateBinding: ["string", "a date property's slug"],
+    waits: ["object", "an object { on, waitKind?, refFrom?, dateBinding? }"],
+  } as const;
+  for (const field of ["humanOnly", "stuckAfterDays", "dateBinding", "waits"] as const) {
+    const overrides = lc[field];
+    if (overrides === undefined) continue;
+    if (!isRecord(overrides)) {
+      fail(`.${field}`, `${field} maps a step key to its value`);
+      continue;
+    }
+    for (const [k, v] of Object.entries(overrides)) {
+      const s = byKey.get(k);
+      if (!s) {
+        fail(
+          `.${field}.${k}`,
+          `"${k}" is not a step of this lifecycle (${keys.join(", ")})`
+        );
+        continue;
+      }
+      const [type, words] = OVERRIDE_TYPE[field];
+      if (typeof v !== type || v === null || Array.isArray(v)) {
+        fail(`.${field}.${k}`, `${field} of "${k}" must be ${words}`);
+        continue;
+      }
+      const next = option({ ...s, [field]: v });
+      steps[steps.indexOf(s)] = next;
+      byKey.set(k, next);
+    }
+  }
+  if (!steps.some((s) => s.category === "done"))
+    fail("", "a lifecycle keeps at least one done step");
+
+  return problems.length === before
+    ? { property: lc.property as string, options: steps }
+    : null;
+}
+
+/** The property with its `enumValues` generated from the options, placed after `inputType`. */
+function withEnumValues(
+  prop: TemplateProperty,
+  keys: string[]
+): TemplateProperty {
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(prop)) {
+    out[k] = v;
+    if (k === "inputType") out.enumValues = keys;
+  }
+  if (!("enumValues" in out)) out.enumValues = keys;
+  return out as unknown as TemplateProperty;
+}
+
+function resolveProfile(
+  profile: TemplateProfile,
+  problems: LifecyclePresetProblem[]
+): TemplateProfile {
+  const authored = profile.lifecycle as unknown;
+  if (!isRecord(authored)) return profile;
+  const at = `profiles.${profile.slug}.lifecycle`;
+  const adopted = authored.adopts !== undefined;
+  const lifecycle = adopted
+    ? resolveAdoption(authored, at, problems)
+    : (authored as unknown as TemplateLifecycle);
+  if (!lifecycle) return profile;
+
+  // Only a well-formed option list generates enumValues; anything else is left
+  // to the validator, which names what is wrong with it.
+  const optionKeys: unknown[] | null = Array.isArray(lifecycle.options)
+    ? lifecycle.options.map((o: unknown) => (isRecord(o) ? o.key : undefined))
+    : null;
+  const keys =
+    optionKeys && optionKeys.every((k): k is string => typeof k === "string")
+      ? optionKeys
+      : null;
+  const properties = profile.properties ?? [];
+  const index = properties.findIndex((p) => p.slug === lifecycle.property);
+  const prop = properties[index];
+  const fillEnum =
+    !!keys &&
+    !!prop &&
+    prop.inputType === "select" &&
+    prop.enumValues === undefined;
+
+  if (!adopted && !fillEnum) return profile;
+  const next: TemplateProfile = { ...profile, lifecycle };
+  if (fillEnum)
+    next.properties = properties.map((p, i) =>
+      i === index ? withEnumValues(p, keys) : p
+    );
+  return next;
+}
+
+/**
+ * Compile every `adopts:` lifecycle of a template into its flat declaration and
+ * generate the lifecycle select's `enumValues` where the YAML omits them. Pure;
+ * never throws. An unresolvable overlay is reported and left as authored, so
+ * `validateTemplate` refuses it.
+ */
+export function resolveLifecyclePresets(
+  tpl: WorkspaceYaml
+): LifecyclePresetResolution {
+  const problems: LifecyclePresetProblem[] = [];
+  if (!tpl || !Array.isArray(tpl.profiles)) return { template: tpl, problems };
+  let changed = false;
+  const profiles = tpl.profiles.map((p) => {
+    const next = resolveProfile(p, problems);
+    if (next !== p) changed = true;
+    return next;
+  });
+  return { template: changed ? { ...tpl, profiles } : tpl, problems };
+}

package/src/lifecycle-stuck.test.ts

@@ -0,0 +1,46 @@
+/**
+ * `stuckAfterDays` on a catalog lifecycle option (surfaces W1.5): the
+ * validator accepts a whole number of days on an option that can still move,
+ * and refuses a bad value or a done/lost option — the same rules the pod's
+ * `parseLifecycleOptions` applies, so a template never publishes a lifecycle
+ * the pod would refuse at install.
+ */
+import { describe, expect, it } from "vitest";
+import { validateTemplate } from "./validate.js";
+import type { WorkspaceYaml } from "./types.js";
+import { readYamlTemplates } from "./generate.mjs";
+
+const crm = readYamlTemplates()
+  .map((t) => t.data as WorkspaceYaml)
+  .find((t) => t.meta.slug === "crm")!;
+
+function withStuck(byKey: Record<string, unknown>): WorkspaceYaml {
+  const clone = structuredClone(crm);
+  const deal = clone.profiles.find((p) => p.slug === "deal")!;
+  deal.lifecycle!.options = deal.lifecycle!.options.map((o) =>
+    o.key in byKey ? { ...o, stuckAfterDays: byKey[o.key] as number } : o
+  );
+  return clone;
+}
+const stuckErrors = (t: WorkspaceYaml) =>
+  validateTemplate(t).errors.filter((e) => e.path.endsWith(".stuckAfterDays"));
+
+describe("lifecycle stuckAfterDays", () => {
+  it("accepts whole days on open/active options", () => {
+    expect(stuckErrors(withStuck({ draft: 14, negotiating: 7 }))).toEqual([]);
+  });
+
+  it("refuses a non-integer, a zero, a string and a done/lost option", () => {
+    const errs = stuckErrors(
+      withStuck({ draft: 2.5, proposed: 0, negotiating: "7", won: 5 })
+    );
+    expect(errs.map((e) => e.path.match(/options\[(\d)\]/)?.[1])).toEqual([
+      "0",
+      "1",
+      "2",
+      "3",
+    ]);
+    expect(errs[3]!.message).toMatch(/cannot be stuck/);
+    expect(errs.every((e) => e.rule === "lifecycle-option-shape")).toBe(true);
+  });
+});