@platforma-sdk/block-tools 2.10.14 → 2.10.15

package/src/structure/engine/ctx.ts

@@ -0,0 +1,94 @@
+// RunContext assembly helpers + module-lookup helpers. The full
+// `RunContext` type lives in `api.ts` (rule authors see it via
+// `({ ctx }) => ...` trigger predicates). This file provides convenience
+// constructors and the scope-lookup helpers generators use.
+
+import type { BlockVars, Module, RunContext, Scope } from "./api";
+
+/** All modules of `scope` (zero or more). Never throws. Use when "zero or
+ *  more" is the right intent (e.g. software). */
+export function findModules(ctx: RunContext, scope: Scope): Module[] {
+  return ctx.modules.filter((m) => m.scope === scope);
+}
+
+/** The single module of `scope`. Throws if absent OR if more than one
+ *  exists. Use when exactly one is required (model / ui / workflow). */
+export function findModule(ctx: RunContext, scope: Scope): Module {
+  const ms = findModules(ctx, scope);
+  if (ms.length === 0) {
+    throw new Error(`findModule: expected one '${scope}' module, found none`);
+  }
+  if (ms.length > 1) {
+    throw new Error(`findModule: expected exactly one '${scope}' module, found ${ms.length}`);
+  }
+  return ms[0]!;
+}
+
+/** Workspace dep map `{ name: "workspace:*" }` for the single module of
+ *  `scope`. Throws if absent (via `findModule`) — guarantees the dep. */
+export function scopeDepMap(ctx: RunContext, scope: Scope): Record<string, string> {
+  return { [findModule(ctx, scope).name]: "workspace:*" };
+}
+
+/** Workspace dep map for ALL modules of `scope` (zero or more). Never
+ *  throws — use where multiple modules are legitimate (e.g. software). */
+export function scopeDepMaps(ctx: RunContext, scope: Scope): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const m of findModules(ctx, scope)) out[m.name] = "workspace:*";
+  return out;
+}
+
+/**
+ * Module set produced by `init` for the given BlockVars: one module per
+ * base scope (root/block/model/ui/workflow/test) plus, when a platform
+ * was selected, one `software` module. `--platform` is single-valued, so
+ * `init` produces at most one software module; multi-software shapes only
+ * arise via DISCOVERY on existing blocks.
+ *
+ * Single source of truth shared by the real `init` constructor and the
+ * `simulateInit` test helper — keeping them in lockstep is what makes the
+ * init→check zero-diff invariant meaningful.
+ */
+export function modulesForInit(vars: BlockVars): Module[] {
+  const facade = vars.facadeName;
+  const mods: Module[] = [
+    { scope: "root", name: facade, path: "" },
+    { scope: "block", name: `${facade}.block`, path: "block" },
+    { scope: "model", name: `${facade}.model`, path: "model" },
+    { scope: "ui", name: `${facade}.ui`, path: "ui" },
+    { scope: "workflow", name: `${facade}.workflow`, path: "workflow" },
+    { scope: "test", name: `${facade}.test`, path: "test" },
+  ];
+  if (vars.softwarePlatform) {
+    // Single software module lives at the flat `software/` dir with name
+    // `${facade}.software` — matches the boilerplate and every real
+    // single-software block. Multi-software blocks arise only via
+    // DISCOVERY on existing workspaces, never from `init`.
+    mods.push({
+      scope: "software",
+      name: `${facade}.software`,
+      path: "software",
+    });
+  }
+  return mods;
+}
+
+export type CreateRunContextInput = {
+  isSdkInternal?: boolean;
+  updateDepsOnly?: boolean;
+  modules: Module[];
+  blockVars: BlockVars;
+  version?: number;
+  dryRun?: boolean;
+};
+
+export function createRunContext(input: CreateRunContextInput): RunContext {
+  return {
+    isSdkInternal: input.isSdkInternal ?? false,
+    updateDepsOnly: input.updateDepsOnly ?? false,
+    modules: input.modules,
+    blockVars: input.blockVars,
+    version: input.version ?? 0,
+    dryRun: input.dryRun ?? false,
+  };
+}

package/src/structure/engine/discovery-fs.ts

@@ -0,0 +1,209 @@
+// Filesystem-backed DISCOVERY.
+//
+// The engine runner consumes a fully-assembled `RunContext` (modules,
+// version, blockVars). This module is the "caller" that builds it from a
+// block directory, working through the engine's `FileSystem` abstraction
+// — so the same code path serves the CLI (NodeFileSystem) and the
+// in-memory init→check round-trip (MemoryFileSystem), which re-discovers
+// from the just-written FS instead of reusing init's module set, so a
+// discovery/classification regression surfaces in the parity invariant.
+//
+// Two enumeration modes:
+//
+//   - Standalone (default): read the block-root `pnpm-workspace.yaml`,
+//     read each `packages:` member's `package.json` (literal paths only —
+//     globs are a hard error), classify via `discoverModules`. This is the
+//     canonical path.
+//
+//   - SDK-internal (`--sdk-internal`): in-monorepo blocks (e.g.
+//     `etc/blocks/*`) have NO block-local `pnpm-workspace.yaml` — they
+//     are members of the parent monorepo's workspace. The block's
+//     modules are therefore enumerated by scanning the block directory
+//     for sub-package `package.json` files (depth-limited, skipping
+//     `node_modules`).
+//
+// `.structure` version is read (missing → 0) and floor-checked. BlockVars
+// are parsed from the block-scope module's `package.json` `name` (the
+// facade name), or — for the root-as-block shape — from the root package.
+
+import { parse as parseYamlText } from "yaml";
+import type { BlockVars, Module, RunContext } from "./api";
+import type { FileSystem } from "./fs/api";
+import { discoverModules, type WorkspacePackage, type PackageJsonLike } from "./discovery";
+import { createRunContext } from "./ctx";
+import { STRUCTURE_META_FILE, STRUCTURE_MIN_SUPPORTED, assertVersionAboveFloor } from "./version";
+
+export class StructureCliError extends Error {
+  constructor(msg: string) {
+    super(msg);
+    this.name = "StructureCliError";
+  }
+}
+
+/** Join two block-relative path segments ("" = root). */
+function joinRel(a: string, b: string): string {
+  return a === "" ? b : `${a}/${b}`;
+}
+
+function readJsonIfExists(fs: FileSystem, rel: string): PackageJsonLike | undefined {
+  try {
+    return JSON.parse(fs.read(rel)) as PackageJsonLike;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Resolve a single pnpm-workspace `packages:` entry to a block-relative
+ *  directory path. Entries are literal paths only — the structurer does
+ *  not expand globs: no real block uses them, and a globbing surface
+ *  with no caller is dead complexity. A `*` anywhere is a hard error. */
+function resolvePackagePath(pattern: string): string {
+  if (pattern.includes("*")) {
+    throw new StructureCliError(
+      `pnpm-workspace.yaml 'packages:' entry '${pattern}' contains a glob. ` +
+        `The structurer requires literal package paths — replace the glob ` +
+        `with one entry per package directory.`,
+    );
+  }
+  const p = pattern.replace(/^\.\//, "").replace(/\/$/, "");
+  return p === "." ? "" : p;
+}
+
+function enumerateStandalone(fs: FileSystem): WorkspacePackage[] {
+  let wsRaw: string;
+  try {
+    wsRaw = fs.read("pnpm-workspace.yaml");
+  } catch {
+    throw new StructureCliError(
+      `No pnpm-workspace.yaml found. This directory is empty or ` +
+        `unrecognisable as a block — run 'block-tools structure init' instead, ` +
+        `or pass --sdk-internal for an in-monorepo block.`,
+    );
+  }
+  const ws = (parseYamlText(wsRaw) ?? {}) as { packages?: string[] };
+  const patterns = Array.isArray(ws.packages) ? ws.packages : [];
+  // The block root ("") is ALWAYS a member, discovered implicitly.
+  // pnpm treats the directory holding pnpm-workspace.yaml as the implicit
+  // workspace root, so the structurer reads the root package.json directly
+  // — no real block lists "." in `packages:` (it would break turbo's task
+  // graph), and the structurer never requires or writes it. The Set
+  // dedupes if a workspace did list ".".
+  const dirs = new Set<string>([""]);
+  for (const pat of patterns) {
+    const d = resolvePackagePath(pat);
+    if (d === "" || fs.exists(d)) dirs.add(d);
+  }
+  const out: WorkspacePackage[] = [];
+  for (const d of dirs) {
+    const pkg = readJsonIfExists(fs, joinRel(d, "package.json"));
+    if (pkg) out.push({ path: d, pkg });
+  }
+  return out;
+}
+
+/** SDK-internal enumeration: scan the block directory for sub-package
+ *  `package.json` files. Depth-limited to two levels (covers `block/`,
+ *  `model/`, … and `software/<name>/`), skipping `node_modules`. */
+function enumerateSdkInternal(fs: FileSystem): WorkspacePackage[] {
+  const out: WorkspacePackage[] = [];
+  const SKIP = new Set(["node_modules", ".turbo", "dist", ".git", "block-pack"]);
+
+  function scan(rel: string, depth: number): void {
+    const entries = fs.listDir(rel);
+    for (const e of entries) {
+      if (!e.isDirectory || SKIP.has(e.name)) continue;
+      const childRel = joinRel(rel, e.name);
+      const pkg = readJsonIfExists(fs, joinRel(childRel, "package.json"));
+      if (pkg) out.push({ path: childRel, pkg });
+      if (depth < 2) scan(childRel, depth + 1);
+    }
+  }
+  scan("", 1);
+  return out;
+}
+
+/** Parse a facade package name `@npmOrg/orgScope.shortName` into BlockVars. */
+export function parseBlockVars(facadeName: string): BlockVars {
+  const slash = facadeName.indexOf("/");
+  if (!facadeName.startsWith("@") || slash < 0) {
+    throw new StructureCliError(
+      `Cannot parse block name '${facadeName}': expected '@npm-org/org-scope.short-name'.`,
+    );
+  }
+  const npmOrg = facadeName.slice(0, slash);
+  const baseName = facadeName.slice(slash + 1);
+  const dot = baseName.indexOf(".");
+  if (dot < 0) {
+    throw new StructureCliError(
+      `Cannot parse block name '${facadeName}': base name '${baseName}' has no '.' separating org-scope from short-name.`,
+    );
+  }
+  return {
+    facadeName,
+    baseName,
+    npmOrg,
+    orgScope: baseName.slice(0, dot),
+    shortName: baseName.slice(dot + 1),
+  };
+}
+
+function readVersion(fs: FileSystem): number {
+  try {
+    const parsed = JSON.parse(fs.read(STRUCTURE_META_FILE)) as { version?: number };
+    return typeof parsed.version === "number" ? parsed.version : 0;
+  } catch {
+    return 0;
+  }
+}
+
+export type DiscoverInput = {
+  /** Block-rooted filesystem (NodeFileSystem for the CLI, MemoryFileSystem
+   *  for the Layer-2 round-trip). */
+  fs: FileSystem;
+  isSdkInternal: boolean;
+  updateDepsOnly?: boolean;
+  dryRun?: boolean;
+};
+
+/**
+ * Run DISCOVERY against a block filesystem and return a fully-assembled
+ * `RunContext`, ready for `engine.run`. Throws `StructureCliError` /
+ * `DiscoveryError` / `StructureVersionFloorError` on a non-block dir,
+ * an unclassified package, or a below-floor version.
+ */
+export function discoverRunContext(input: DiscoverInput): RunContext {
+  const { fs, isSdkInternal } = input;
+
+  const packages = isSdkInternal ? enumerateSdkInternal(fs) : enumerateStandalone(fs);
+
+  if (packages.length === 0) {
+    throw new StructureCliError(
+      `No workspace packages found. ` + `Run 'block-tools structure init' to scaffold a block.`,
+    );
+  }
+
+  const modules: Module[] = discoverModules(packages);
+
+  const version = readVersion(fs);
+  assertVersionAboveFloor(version, STRUCTURE_MIN_SUPPORTED);
+
+  // BlockVars from the block-scope module's name (facade). Fall back to
+  // the root module if a block has the root-as-block shape.
+  const blockMod =
+    modules.find((m) => m.scope === "block") ?? modules.find((m) => m.scope === "root");
+  if (!blockMod) {
+    throw new StructureCliError(
+      `Could not find a 'block' (or root-as-block) package to derive BlockVars from.`,
+    );
+  }
+  const blockVars = parseBlockVars(blockMod.name);
+
+  return createRunContext({
+    isSdkInternal,
+    updateDepsOnly: input.updateDepsOnly ?? false,
+    modules,
+    blockVars,
+    version,
+    dryRun: input.dryRun ?? false,
+  });
+}

package/src/structure/engine/discovery.ts

@@ -0,0 +1,168 @@
+// Workspace-package classification — the seven scope detection rules.
+//
+// Input: the parsed package.json of every workspace member, plus its
+// block-relative path. Output: `Module[]` (scope + name + path).
+// First-match wins on the detection rules; an explicit `block-scope`
+// override on package.json skips detection.
+
+import type { Module, Scope } from "./api";
+
+export const ALL_SCOPES: Scope[] = ["root", "block", "model", "ui", "workflow", "test", "software"];
+
+export type WorkspacePackage = {
+  /** Block-relative path of the package — "" or "." means the
+   *  workspace root. */
+  path: string;
+  /** Parsed package.json. */
+  pkg: PackageJsonLike;
+};
+
+export type PackageJsonLike = {
+  name?: string;
+  main?: string;
+  files?: string[];
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+  peerDependencies?: Record<string, string>;
+  optionalDependencies?: Record<string, string>;
+  // Override field — value MUST be one of the seven scopes.
+  "block-scope"?: string;
+  "block-software"?: unknown;
+};
+
+export class DiscoveryError extends Error {
+  constructor(
+    msg: string,
+    public readonly path?: string,
+  ) {
+    super(msg);
+    this.name = "DiscoveryError";
+  }
+}
+
+function depKeys(pkg: PackageJsonLike): Set<string> {
+  const all = new Set<string>();
+  for (const section of [
+    pkg.dependencies,
+    pkg.devDependencies,
+    pkg.peerDependencies,
+    pkg.optionalDependencies,
+  ]) {
+    if (section) for (const k of Object.keys(section)) all.add(k);
+  }
+  return all;
+}
+
+function isRoot(p: string): boolean {
+  return p === "" || p === ".";
+}
+
+/**
+ * Classify one package.
+ *
+ * @param wp The workspace package.
+ * @param siblingNames Set of all workspace package `name`s (used by
+ *   rule 4 "block": depends on ≥2 sibling .model/.ui/.workflow).
+ * @returns Scope or `undefined` if unclassified.
+ */
+export function classifyOne(wp: WorkspacePackage, siblingNames: Set<string>): Scope | undefined {
+  const override = wp.pkg["block-scope"];
+  if (typeof override === "string") {
+    if (!(ALL_SCOPES as string[]).includes(override)) {
+      throw new DiscoveryError(
+        `package.json "block-scope" must be one of ${ALL_SCOPES.join(", ")}, got '${override}'`,
+        wp.path,
+      );
+    }
+    return override as Scope;
+  }
+
+  // Standalone implicit root: the package at path "" is present
+  // because pnpm-workspace.yaml lives there, so it IS the workspace root —
+  // classify it as `root` unconditionally, BEFORE any detection rule. A
+  // nameless root carrying legacy facade cruft (`files: ["index.d.ts",
+  // "index.js"]` + block-tools, e.g. sequence-properties) must NOT fall
+  // through to the rule-4 block fallback and become a nameless second
+  // `block` module — root-as-facade is a forbidden anti-pattern.
+  // SDK-internal enumeration never produces a path-"" package (it scans
+  // sub-package dirs), so this only ever fires in standalone mode.
+  if (isRoot(wp.path)) return "root";
+
+  const deps = depKeys(wp.pkg);
+
+  // 1. software — top-level `block-software` field OR
+  //    (package-builder AND any @platforma-open/*runenv* dep).
+  if (wp.pkg["block-software"] !== undefined) return "software";
+  if (deps.has("@platforma-sdk/package-builder")) {
+    for (const d of deps) {
+      if (/^@platforma-open\/.*runenv/.test(d)) return "software";
+    }
+  }
+
+  // 2. workflow — @platforma-sdk/workflow-tengo in deps.
+  if (deps.has("@platforma-sdk/workflow-tengo")) return "workflow";
+
+  // 3. ui — (ui-vue OR vue) AND main is not set.
+  if ((deps.has("@platforma-sdk/ui-vue") || deps.has("vue")) && !wp.pkg.main) {
+    return "ui";
+  }
+
+  // 4. block — block-tools in deps AND ≥2 sibling .model/.ui/.workflow.
+  if (deps.has("@platforma-sdk/block-tools")) {
+    const matches = [...deps].filter(
+      (d) =>
+        siblingNames.has(d) &&
+        (d.endsWith(".model") || d.endsWith(".ui") || d.endsWith(".workflow")),
+    );
+    if (matches.length >= 2) return "block";
+    // Fallback: `files == ["index.d.ts", "index.js"]` + block-tools.
+    const files = wp.pkg.files;
+    if (
+      Array.isArray(files) &&
+      files.length === 2 &&
+      files.includes("index.d.ts") &&
+      files.includes("index.js")
+    ) {
+      return "block";
+    }
+  }
+
+  // 5. model — @platforma-sdk/model in deps AND main is set.
+  if (deps.has("@platforma-sdk/model") && wp.pkg.main) return "model";
+
+  // 6. test — @platforma-sdk/test in deps.
+  if (deps.has("@platforma-sdk/test")) return "test";
+
+  // (root — the workspace root, path "", is classified above, before the
+  // detection rules, so it can never reach this fallthrough.)
+  return undefined;
+}
+
+/**
+ * Classify a whole workspace. Throws on the first unclassified package
+ * with a message that directs the operator to add `block-scope` to its
+ * package.json.
+ */
+export function discoverModules(packages: WorkspacePackage[]): Module[] {
+  const siblingNames = new Set<string>();
+  for (const p of packages) {
+    if (typeof p.pkg.name === "string") siblingNames.add(p.pkg.name);
+  }
+  const out: Module[] = [];
+  for (const p of packages) {
+    const scope = classifyOne(p, siblingNames);
+    if (!scope) {
+      throw new DiscoveryError(
+        `Unclassified workspace package at '${p.path}'. ` +
+          `Add a top-level "block-scope" string to its package.json.`,
+        p.path,
+      );
+    }
+    out.push({
+      scope,
+      name: p.pkg.name ?? p.path,
+      path: isRoot(p.path) ? "" : p.path,
+    });
+  }
+  return out;
+}

package/src/structure/engine/flatten.ts

@@ -0,0 +1,117 @@
+// Flatten: DFS over the tree IR; fan out each scope frame once per
+// matching module in `ctx.modules`. Compose enclosing `when` triggers
+// (AND of all on the path from root). Track which run modes the leaf
+// fires in (its enclosing mode frame, or the `["default", "init"]`
+// default) and emit that as `modes` on the FlatItem. No execution here —
+// execution lives in `runner.ts`.
+
+import type { Module, RunContext, Scope } from "./api";
+import type { FlatItem, LeafItem, RunMode, Structure, TreeNode, TriggerFn } from "./ir";
+
+/** Modes a leaf fires in when it sits outside any mode frame: default
+ *  refresh/check plus init. (`onUpdateDeps` / `onInitOrUpdate` frames
+ *  override this for their children.) */
+const DEFAULT_MODES: RunMode[] = ["default", "init"];
+
+function resolveRelative(modulePath: string, fileRel: string): string {
+  if (!modulePath) return fileRel;
+  if (!fileRel) return modulePath;
+  // Strip trailing slash on modulePath, leading slash on fileRel.
+  const m = modulePath.endsWith("/") ? modulePath.slice(0, -1) : modulePath;
+  const f = fileRel.startsWith("/") ? fileRel.slice(1) : fileRel;
+  return f ? `${m}/${f}` : m;
+}
+
+/**
+ * Lexicographic sort of modules by `path`.
+ * Used for deterministic fan-out order.
+ */
+function modulesByScope(modules: Module[], scope: Scope): Module[] {
+  return modules
+    .filter((m) => m.scope === scope)
+    .slice()
+    .sort((a, b) => a.path.localeCompare(b.path));
+}
+
+export function flatten(structure: Structure, ctx: RunContext): FlatItem[] {
+  const out: FlatItem[] = [];
+
+  function visit(
+    node: TreeNode,
+    boundScope: Scope | undefined,
+    boundModulePath: string | undefined,
+    triggers: TriggerFn[],
+    modes: RunMode[],
+  ): void {
+    if (node.kind === "scope") {
+      const matches = modulesByScope(ctx.modules, node.scope);
+      for (const m of matches) {
+        for (const child of node.children) {
+          visit(child, node.scope, m.path, triggers, modes);
+        }
+      }
+      return;
+    }
+    if (node.kind === "when") {
+      const nextTriggers = triggers.concat(node.trigger);
+      for (const child of node.children) {
+        visit(child, boundScope, boundModulePath, nextTriggers, modes);
+      }
+      return;
+    }
+    if (node.kind === "mode") {
+      for (const child of node.children) {
+        visit(child, boundScope, boundModulePath, triggers, node.modes);
+      }
+      return;
+    }
+    // Leaf.
+    if (boundScope === undefined || boundModulePath === undefined) {
+      throw new Error(`flatten: leaf '${describeLeaf(node)}' is not inside a scope() frame`);
+    }
+    if (node.kind === "rename") {
+      out.push({
+        leaf: node,
+        scope: boundScope,
+        modulePath: boundModulePath,
+        resolvedPath: resolveRelative(boundModulePath, node.from),
+        resolvedTo: resolveRelative(boundModulePath, node.to),
+        triggers,
+        modes,
+      });
+      return;
+    }
+    out.push({
+      leaf: node,
+      scope: boundScope,
+      modulePath: boundModulePath,
+      resolvedPath: resolveRelative(boundModulePath, leafPath(node)),
+      triggers,
+      modes,
+    });
+  }
+
+  for (const node of structure.children) {
+    visit(node, undefined, undefined, [], DEFAULT_MODES);
+  }
+
+  return out;
+}
+
+function leafPath(leaf: LeafItem): string {
+  switch (leaf.kind) {
+    case "fixed":
+    case "managed":
+    case "scaffold":
+    case "seed":
+    case "remove":
+      return leaf.path;
+    case "rename":
+      return leaf.from;
+  }
+}
+
+function describeLeaf(leaf: LeafItem): string {
+  if (leaf.kind === "rename") return `rename ${leaf.from} -> ${leaf.to}`;
+  return `${leaf.kind} ${leaf.path}`;
+}

package/src/structure/engine/fs/api.ts

@@ -0,0 +1,40 @@
+// Small filesystem abstraction used by the engine. Two implementations:
+//   - memory.ts: in-memory map, used by tests and the post-run recheck
+//     dry-run.
+//   - node.ts:   thin wrapper around node:fs (synchronous).
+// Paths are always block-relative ("/"-separated) — the impls anchor
+// them against a configured root.
+//
+// The interface is SYNCHRONOUS. The structurer is a one-shot CLI, so
+// blocking fs calls (readFileSync, …) carry no event-loop cost, and a
+// sync engine keeps the module-global run context race-free by
+// construction (a sync call stack cannot interleave).
+
+/** One shallow child of a directory (file or sub-directory). */
+export type DirEntry = {
+  name: string;
+  isDirectory: boolean;
+};
+
+export interface FileSystem {
+  /** Read file as utf-8 string. Throws on missing file. */
+  read(path: string): string;
+  /** Write file (utf-8). Creates parent dirs as needed. Overwrites. */
+  write(path: string, content: string): void;
+  /** Write raw bytes. Creates parent dirs as needed. Overwrites. For binary
+   *  assets (logos, images) that must not be utf-8 encoded. */
+  writeBinary(path: string, content: Uint8Array): void;
+  /** Path exists (file or directory). */
+  exists(path: string): boolean;
+  /** Recursive listing under a directory (relative paths, files only).
+   *  Empty array if directory missing. */
+  list(dir: string): string[];
+  /** Shallow listing of a directory's immediate children (files +
+   *  sub-dirs). Empty array if the directory is missing. Used by
+   *  filesystem-backed DISCOVERY. */
+  listDir(dir: string): DirEntry[];
+  /** Move a file or directory. Source must exist; dest must not. */
+  move(from: string, to: string): void;
+  /** Delete a file or directory recursively. Missing is no-op. */
+  delete(path: string): void;
+}