@platforma-sdk/block-tools 2.10.13 → 2.10.15

package/src/structure/rules/ui-package-json.ts

@@ -0,0 +1,108 @@
+// UI `package.json`: the initial generator and the drift-correcting body
+// rules, co-located.
+//
+// Authored oxfmt-clean: the ui is one of the two scopes `ts-builder check`
+// runs oxfmt on, so neither half enforces ordering beyond what oxfmt
+// produces — the enforce* calls match oxfmt's order exactly, so refreshing a
+// legacy block yields oxfmt-clean output and the build→check gate (oxfmt
+// --check) passes without a prior `pnpm fmt`.
+
+import {
+  ensureField,
+  ensureScript,
+  ensureDep,
+  ensureDevDep,
+  ensureDevDeps,
+  ensurePeerDeps,
+  ensureWorkspaceScopeDeps,
+  removeDep,
+  enforceAlphabeticalOrder,
+  enforceFieldOrder,
+  when,
+  whenFilesExist,
+  type RunContext,
+} from "../engine/api";
+import { scopeDepMap } from "../engine/ctx";
+import { canonicalPackageJsonOrder } from "./shared/key-order";
+import { COLOCATED_TEST_GLOB } from "./shared/colocated-tests";
+
+export function uiPackageJsonInitial(ctx: RunContext): Record<string, unknown> {
+  const v = ctx.blockVars;
+  return {
+    name: `${v.facadeName}.ui`,
+    version: "1.0.0",
+    type: "module",
+    scripts: {
+      fmt: "ts-builder format",
+      dev: "ts-builder serve --target block-ui",
+      watch: "ts-builder build --target block-ui --watch",
+      build: "ts-builder build --target block-ui",
+      check: "ts-builder check --target block-ui",
+      // No `test`: the vitest `test` script is wired by the body rule ONLY
+      // when co-located test files exist (a freshly-init'd ui has none).
+    },
+    dependencies: {
+      "@platforma-sdk/ui-vue": "sdk:",
+      vue: "catalog:",
+      // The seeded ui (app.ts) imports the block's model package; depend on
+      // it — mirrors the body rule's `ensureWorkspaceScopeDeps("model")`.
+      ...scopeDepMap(ctx, "model"),
+    },
+    devDependencies: {
+      "@milaboratories/ts-builder": "sdk:",
+      "@milaboratories/ts-configs": "sdk:",
+      vitest: "catalog:",
+    },
+    peerDependencies: {
+      typescript: "*",
+    },
+  };
+}
+
+export function uiPackageJsonRules(): void {
+  ensureField("type", "module");
+
+  ensureScript("fmt", "ts-builder format");
+  ensureScript("dev", "ts-builder serve --target block-ui");
+  ensureScript("watch", "ts-builder build --target block-ui --watch");
+  ensureScript("build", "ts-builder build --target block-ui");
+  ensureScript("check", "ts-builder check --target block-ui");
+
+  ensureDep("@platforma-sdk/ui-vue", "sdk:");
+  // The seeded ui (main.ts) imports `createApp` from vue.
+  ensureDep("vue", "catalog:");
+  // The seeded ui (app.ts) imports the block's model package.
+  ensureWorkspaceScopeDeps("model");
+
+  ensureDevDeps({
+    "@milaboratories/ts-builder": "sdk:",
+    "@milaboratories/ts-configs": "sdk:",
+    vitest: "catalog:",
+  });
+
+  // The ui builds with `--target block-ui` (types: []), so by default it
+  // carries no browser/vitest/node ambient types — only the `typescript`
+  // peer for IDE type resolution. Drop any stray `@types/node` a legacy
+  // block declares...
+  ensurePeerDeps({
+    typescript: "*",
+  });
+  removeDep("@types/node");
+
+  // ...but a ui WITH co-located unit tests (`src/**/*.test.ts`) needs the
+  // vitest `test` script AND node ambient types: re-add `@types/node` as a
+  // devDep so `types: ["node"]` in ui/tsconfig (wired under the same
+  // predicate) resolves the tests' `node:*` imports. A test-less ui keeps
+  // the lean default (no test script, no @types/node) and stays a fixpoint.
+  // Runs AFTER removeDep so the dev dep is not stripped.
+  when(whenFilesExist(COLOCATED_TEST_GLOB), () => {
+    ensureScript("test", "vitest run --passWithNoTests");
+    ensureDevDep("@types/node", "*");
+  });
+
+  enforceAlphabeticalOrder("dependencies");
+  enforceAlphabeticalOrder("devDependencies");
+  enforceAlphabeticalOrder("peerDependencies");
+  enforceAlphabeticalOrder("optionalDependencies");
+  enforceFieldOrder([...canonicalPackageJsonOrder]);
+}

package/src/structure/rules/ui.ts

@@ -0,0 +1,75 @@
+// UI-scope rules. Author owns src/main.ts and components; static config
+// files are engine-managed.
+
+import {
+  scope,
+  fixed,
+  managed,
+  scaffold,
+  seed,
+  file,
+  tpl,
+  generate,
+  blockVars,
+  when,
+  whenFilesExist,
+  ensureField,
+  removeField,
+  pruneKeysMatching,
+} from "../engine/api";
+import { getActiveRunContext } from "../engine/builders";
+import { uiPackageJsonInitial, uiPackageJsonRules } from "./ui-package-json";
+import { COLOCATED_TEST_GLOB } from "./shared/colocated-tests";
+
+export function uiRules(): void {
+  scope("ui", () => {
+    // tsconfig is managed (not fixed) so node ambient types can be provided
+    // CONDITIONALLY. The body still enforces the canonical shape —
+    // `{extends, include}` with NO stray keys — and, ONLY when the ui
+    // carries co-located unit tests (`src/**/*.test.ts`), adds
+    // `compilerOptions.types: ["node"]` so tests importing `node:*`
+    // type-check under vue-tsc: provide node types, do NOT exclude the
+    // tests. A test-less ui is canonicalised to
+    // bare `{extends, include}` and stays a refresh fixpoint. The matching
+    // `@types/node` devDep is wired by the package.json rule under the same
+    // predicate.
+    managed("tsconfig.json", file("ui/tsconfig.json"), () => {
+      ensureField("extends", "@milaboratories/ts-configs/block/ui");
+      removeField("compilerOptions");
+      when(whenFilesExist(COLOCATED_TEST_GLOB), () => {
+        ensureField("compilerOptions.types", ["node"]);
+      });
+      ensureField("include", ["src/**/*"]);
+      pruneKeysMatching((k) => k !== "extends" && k !== "include" && k !== "compilerOptions");
+    });
+    fixed(".oxlintrc.json", file("ui/.oxlintrc.json"));
+    // Block-local oxfmt config — the ui is oxfmt-checked (`ts-builder check
+    // --target block-ui`).
+    fixed(".oxfmtrc.json", file("ui/.oxfmtrc.json"));
+    // scaffold (not fixed): index.html carries a block-specific CSP. Write
+    // the canonical default only when absent; never overwrite an author's.
+    scaffold("index.html", file("ui/index.html"));
+
+    // A minimal-but-real UI: mount (main.ts), app wiring the block model
+    // (app.ts), and a landing page (MainPage.vue). An empty main.ts would
+    // trip oxlint `unicorn(no-empty-file)`. Author-owned seeds: written once
+    // at init, untouched on refresh.
+    seed("src/main.ts", file("ui/src/main.ts"));
+    seed(
+      "src/app.ts",
+      tpl("ui/src/app.tpl.ts", () => ({ modelPkg: `${blockVars().facadeName}.model` })),
+    );
+    seed(
+      "src/MainPage.vue",
+      tpl("ui/src/MainPage.tpl.vue", () => ({ shortName: blockVars().shortName })),
+    );
+
+    managed(
+      "package.json",
+      generate(() => uiPackageJsonInitial(getActiveRunContext())),
+      () => {
+        uiPackageJsonRules();
+      },
+    );
+  });
+}

package/src/structure/rules/workflow-package-json.ts

@@ -0,0 +1,92 @@
+// Workflow `package.json`: the initial generator and the drift-correcting
+// body rules, co-located. Workflow packages reference software modules at
+// workspace level when the block has any; the generator fills them from the
+// discovered modules and the body rule re-asserts them.
+
+import {
+  ensureField,
+  ensureScript,
+  ensureDep,
+  ensureDevDeps,
+  ensureWorkspaceScopeDeps,
+  enforceAlphabeticalOrder,
+  enforceFieldOrder,
+  when,
+  whenFilesExist,
+  type RunContext,
+} from "../engine/api";
+import { scopeDepMaps } from "../engine/ctx";
+import { canonicalPackageJsonOrder } from "./shared/key-order";
+import { COLOCATED_TEST_GLOB } from "./shared/colocated-tests";
+
+export function workflowPackageJsonInitial(ctx: RunContext): Record<string, unknown> {
+  const v = ctx.blockVars;
+  return {
+    name: `${v.facadeName}.workflow`,
+    version: "1.0.0",
+    type: "module",
+    scripts: {
+      // No `fmt`: the workflow is Tengo, not TS — nothing for oxlint/oxfmt
+      // to process. Tengo is built and checked by pl-tengo.
+      build: "shx rm -rf dist && pl-tengo build",
+      check: "pl-tengo check",
+      // No `test`: the vitest `test` script is wired by the body rule ONLY
+      // when co-located test files exist (a freshly-init'd workflow has none).
+      // Tengo source formatter (emacs batch). Falls back to a notice when
+      // emacs is absent, so the script never hard-fails the environment.
+      format: "/usr/bin/env emacs --script ./format.el || echo 'No emacs.'",
+    },
+    dependencies: {
+      "@platforma-sdk/workflow-tengo": "sdk:",
+      // Every block-local software module as a workspace dep (zero or more).
+      ...scopeDepMaps(ctx, "software"),
+    },
+    devDependencies: {
+      "@platforma-sdk/tengo-builder": "sdk:",
+      "@platforma-sdk/test": "sdk:",
+      vitest: "catalog:",
+      shx: "catalog:",
+    },
+  };
+}
+
+export function workflowPackageJsonRules(): void {
+  ensureField("type", "module");
+
+  // No `fmt`: the workflow is Tengo, not TS. Build + check go through
+  // pl-tengo. shx powers the cross-platform build clean-up.
+  ensureScript("build", "shx rm -rf dist && pl-tengo build");
+  ensureScript("check", "pl-tengo check");
+  // Tengo source formatter (emacs batch); no-op notice when emacs is absent.
+  ensureScript("format", "/usr/bin/env emacs --script ./format.el || echo 'No emacs.'");
+  // The vitest `test` script is wired ONLY when the workflow carries
+  // co-located integration tests (`src/**/*.test.ts`, incl. `src/test/`).
+  // A test-less workflow gets no `test` task and stays a refresh fixpoint.
+  // (Workflow tests type-check via the standalone workflow/tsconfig with
+  // `types: []` — they pull their types from `@platforma-sdk/test` — so no
+  // node-types wiring is needed here, unlike model/ui.)
+  when(whenFilesExist(COLOCATED_TEST_GLOB), () => {
+    ensureScript("test", "vitest run --passWithNoTests");
+  });
+
+  ensureDep("@platforma-sdk/workflow-tengo", "sdk:");
+
+  // Pulls in every block-local software module as a workspace dep so the
+  // workflow can reference the produced runenv assets.
+  ensureWorkspaceScopeDeps("software");
+
+  // @platforma-sdk/test: workflow integration tests (e.g. mixcr's
+  // workflow/src/test/columns.test.ts) import it.
+  ensureDevDeps({
+    "@platforma-sdk/tengo-builder": "sdk:",
+    "@platforma-sdk/test": "sdk:",
+    vitest: "catalog:",
+    shx: "catalog:",
+  });
+
+  enforceAlphabeticalOrder("dependencies");
+  enforceAlphabeticalOrder("devDependencies");
+  enforceAlphabeticalOrder("peerDependencies");
+  enforceAlphabeticalOrder("optionalDependencies");
+  enforceFieldOrder([...canonicalPackageJsonOrder]);
+}

package/src/structure/rules/workflow.ts

@@ -0,0 +1,51 @@
+// Workflow-scope rules. The Tengo entry point is a templated seed
+// (substitutes ${shortName}); other config files are static.
+
+import {
+  scope,
+  managed,
+  fixed,
+  scaffold,
+  seed,
+  file,
+  tpl,
+  generate,
+  remove,
+  blockVars,
+} from "../engine/api";
+import { getActiveRunContext } from "../engine/builders";
+import { workflowPackageJsonInitial, workflowPackageJsonRules } from "./workflow-package-json";
+
+export function workflowRules(): void {
+  scope("workflow", () => {
+    // tsconfig for the TypeScript vitest integration tests under src/test
+    // (e.g. mixcr's workflow/src/test/columns.test.ts). types:[] keeps the
+    // isomorphic workflow free of ambient Node/DOM types.
+    fixed("tsconfig.json", file("workflow/tsconfig.json"));
+    // Tengo source formatter (emacs batch); the `format` script invokes it.
+    fixed("format.el", file("workflow/format.el"));
+    // scaffold (not fixed): tengo test config is author-tunable.
+    scaffold("vitest.config.mts", file("workflow/vitest.config.mts"));
+    // No workflow facade (index.js / index.d.ts): the block loader resolves the
+    // workflow via the `block:` components dist path (workflow/dist/.../main.plj.gz),
+    // never the JS facade. It was orphaned in production — dropped. Actively
+    // removed so existing blocks that carry it get cleaned (idempotent on absence).
+    remove("index.js");
+    remove("index.d.ts");
+
+    seed(
+      "src/main.tpl.tengo",
+      tpl("workflow/src/main.tpl.tengo", () => ({
+        shortName: blockVars().shortName,
+      })),
+    );
+
+    managed(
+      "package.json",
+      generate(() => workflowPackageJsonInitial(getActiveRunContext())),
+      () => {
+        workflowPackageJsonRules();
+      },
+    );
+  });
+}

package/src/structure/structure-definition.ts

@@ -0,0 +1,28 @@
+// Canonical block structure — composes every scope's `*Rules()` function
+// inside a single `defineStructure(() => { ... })`. Re-evaluated by the
+// engine on every run; rule modules are imported by name so the
+// structure stays inspectable and the dep graph is explicit.
+
+import { defineStructure } from "./engine/api";
+import { rootRules } from "./rules/root";
+import { blockRules } from "./rules/block";
+import { modelRules } from "./rules/model";
+import { uiRules } from "./rules/ui";
+import { workflowRules } from "./rules/workflow";
+import { testRules } from "./rules/test";
+import { softwareRules } from "./rules/software";
+import { testFrameworkMigration, legacyCleanup } from "./rules/migrations";
+import { rootCatalogBumpRules } from "./rules/root-catalog-bump";
+
+export const STRUCTURE = defineStructure(() => {
+  rootRules();
+  blockRules();
+  modelRules();
+  uiRules();
+  workflowRules();
+  testRules();
+  softwareRules();
+  testFrameworkMigration();
+  legacyCleanup();
+  rootCatalogBumpRules();
+});

package/src/structure/templates/static/block/index.d.ts

@@ -0,0 +1,6 @@
+declare const blockSpec: {
+  type: "dev-v2";
+  folder: string;
+};
+
+export { blockSpec };

package/src/structure/templates/static/block/index.js

@@ -0,0 +1,8 @@
+const blockSpec = {
+  type: "dev-v2",
+  folder: __dirname,
+};
+
+module.exports = {
+  blockSpec,
+};

package/src/structure/templates/static/model/.oxfmtrc.json

@@ -0,0 +1,4 @@
+{
+  "extends": ["node_modules/@milaboratories/ts-builder/configs/oxfmt.json"],
+  "ignorePatterns": ["dist", "coverage", "CHANGELOG.md"]
+}

package/src/structure/templates/static/model/.oxlintrc.json

@@ -0,0 +1,3 @@
+{
+  "extends": ["node_modules/@milaboratories/ts-builder/dist/configs/oxlint-block-model.json"]
+}

package/src/structure/templates/static/model/src/index.ts

@@ -0,0 +1,13 @@
+import type { InferOutputsType } from "@platforma-sdk/model";
+import { BlockModelV3, DataModelBuilder } from "@platforma-sdk/model";
+
+export type BlockArgs = Record<string, never>;
+
+const dataModel = new DataModelBuilder().from<BlockArgs>("v1").init(() => ({}));
+
+export const platforma = BlockModelV3.create(dataModel)
+  .args(() => ({}))
+  .sections(() => [{ type: "link", href: "/", label: "Main" }])
+  .done();
+
+export type BlockOutputs = InferOutputsType<typeof platforma>;

package/src/structure/templates/static/model/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "@milaboratories/ts-configs/block/model",
+  "include": ["src/**/*"]
+}

package/src/structure/templates/static/root/.gitignore

@@ -0,0 +1,13 @@
+.test_auth.json
+node_modules/
+dist/
+block-pack/
+dev/
+work/
+log/
+.turbo
+vite.config.*.timestamp-*
+software/**/*.tgz
+.DS_Store
+.vscode/sftp.json
+test-dry-run.json

package/src/structure/templates/static/root/.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+  "typescript.tsdk": "node_modules/typescript/lib"
+}

package/src/structure/templates/static/root/turbo.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://turbo.build/schema.json",
+  "globalDependencies": ["tsconfig.json"],
+  "tasks": {
+    "fmt": {
+      "cache": false
+    },
+    "check": {
+      "dependsOn": ["^build"],
+      "outputs": []
+    },
+    "build": {
+      "dependsOn": ["^build", "check"],
+      "inputs": ["$TURBO_DEFAULT$"],
+      "env": ["PL_PKG_DEV", "PL_DOCKER_REGISTRY_PUSH_TO"],
+      "outputs": ["./dist/**", "./block-pack/**", "./pkg-*.tgz"]
+    },
+    "build:dev": {
+      "dependsOn": ["build"],
+      "outputs": ["./dist/**"]
+    },
+    "do-pack": {
+      "dependsOn": ["build"],
+      "outputs": ["package.tgz"]
+    },
+    "test": {
+      "dependsOn": ["build", "check"],
+      "passThroughEnv": ["PL_ADDRESS", "PL_TEST_PASSWORD", "PL_TEST_USER", "PL_TEST_PROXY", "DEBUG"]
+    },
+    "mark-stable": {
+      "passThroughEnv": ["PL_REGISTRY", "AWS_*"],
+      "cache": false
+    }
+  }
+}

package/src/structure/templates/static/test/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "@milaboratories/ts-configs/block/test",
+  "include": ["src/**/*"],
+  "files": []
+}

package/src/structure/templates/static/test/vitest.config.mts

@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    watch: false,
+    testTimeout: 30000,
+  },
+});

package/src/structure/templates/static/ui/.oxfmtrc.json

@@ -0,0 +1,3 @@
+{
+  "ignorePatterns": ["dist", "CHANGELOG.md"]
+}

package/src/structure/templates/static/ui/.oxlintrc.json

@@ -0,0 +1,3 @@
+{
+  "extends": ["node_modules/@milaboratories/ts-builder/dist/configs/oxlint-block-ui.json"]
+}

package/src/structure/templates/static/ui/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta http-equiv="Content-Security-Policy" content="script-src 'self' blob:" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/src/structure/templates/static/ui/src/main.ts

@@ -0,0 +1,5 @@
+import { createApp } from "vue";
+import { sdkPlugin } from "./app";
+import { BlockLayout } from "@platforma-sdk/ui-vue";
+
+createApp(BlockLayout).use(sdkPlugin).mount("#app");

package/src/structure/templates/static/ui/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "@milaboratories/ts-configs/block/ui",
+  "include": ["src/**/*"]
+}

package/src/structure/templates/static/workflow/format.el

@@ -0,0 +1,42 @@
+;; This program formats all files inside src directory. Usage: emacs --script ./format.el
+
+(defun install-go-mode ()
+  "Installs go-mode"
+  (require 'package)
+  (add-to-list 'package-archives
+               '("melpa-stable" . "https://stable.melpa.org/packages/"))
+  (package-initialize)
+  (unless package-archive-contents
+    (package-refresh-contents))
+
+  (package-install 'go-mode t)
+  (require 'go-mode))
+
+;; spaces -> tabs only at the beginning of lines
+(setq tabify-regexp "^\t* [ \t]+")
+
+(defun format-file (file)
+  "Formats a file according to slightly changed Go rules"
+  (message "Format %s" file)
+  (save-excursion
+    (find-file file)
+    (delete-trailing-whitespace)            ;; deletes whitespaces
+    (go-mode)                               ;; sets golang rules for indentation
+    (tabify (point-min) (point-max))        ;; spaces -> tabs in the whole file
+    (indent-region (point-min) (point-max)) ;; indentation in the whole file
+    (save-buffer)))                         ;; save file
+
+(install-go-mode)
+
+;; change syntax of a standard go-mode a bit
+(advice-add
+ 'go--in-composite-literal-p
+ :filter-return
+ (lambda (&rest r) t))
+
+;; find all files in src
+(setq files (directory-files-recursively "src" "\\.tengo\\'"))
+
+;; call format on every file.
+(dolist (file files)
+  (format-file file))

package/src/structure/templates/static/workflow/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "es2022",
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "strict": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "sourceMap": true,
+    "declaration": true
+  },
+  "types": [],
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/src/structure/templates/static/workflow/vitest.config.mts

@@ -0,0 +1,9 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    watch: false,
+    maxConcurrency: 3,
+    testTimeout: 5000,
+  },
+});

package/src/structure/templates/text/README.md

@@ -0,0 +1,5 @@
+# ${shortName}
+
+Platforma block in the `${orgScope}` org.
+
+Package: `${facadeName}`

package/src/structure/templates/text/docs/description.md

@@ -0,0 +1,3 @@
+# ${shortName}
+
+Short description of the `${shortName}` block goes here.

package/src/structure/templates/text/ui/src/MainPage.tpl.vue

@@ -0,0 +1,9 @@
+<script setup lang="ts">
+import { PlBlockPage } from "@platforma-sdk/ui-vue";
+</script>
+
+<template>
+  <PlBlockPage>
+    <h1>${shortName}</h1>
+  </PlBlockPage>
+</template>

package/src/structure/templates/text/ui/src/app.tpl.ts

@@ -0,0 +1,11 @@
+import { platforma } from "${modelPkg}";
+import { defineAppV3 } from "@platforma-sdk/ui-vue";
+import MainPage from "./MainPage.vue";
+
+export const sdkPlugin = defineAppV3(platforma, () => ({
+  routes: {
+    "/": () => MainPage,
+  },
+}));
+
+export const useApp = sdkPlugin.useApp;

package/src/structure/templates/text/workflow/src/main.tpl.tengo

@@ -0,0 +1,10 @@
+// Workflow entry point for ${shortName}.
+
+wf := import("@platforma-sdk/workflow-tengo:workflow")
+
+wf.body(func(args) {
+  return {
+    outputs: {},
+    exports: {}
+  }
+})