@platforma-sdk/block-tools 2.10.14 → 2.10.15

package/dist/structure/engine/ir.d.ts

@@ -0,0 +1,124 @@
+import { Scope, RunContext } from './api';
+/** The three leaf-firing modes. `check` and `refresh` share the
+ *  `"default"` mode — they run the same leaves, the `dryRun` flag (carried
+ *  separately on `RunContext`) only decides whether writes happen.
+ *  `"updateDeps"` is `--update-deps-only`; `"init"` is the init
+ *  constructor. A leaf declares which modes it fires in via its enclosing
+ *  mode frame (see `ModeFrame`); the runner derives the current mode from
+ *  the run context and keeps only the leaves whose membership includes it. */
+export type RunMode = "default" | "updateDeps" | "init";
+/** Predicate evaluated against derived trigger context. */
+export type TriggerContext = {
+    ctx: RunContext;
+    version: number;
+    /** Block-relative path queries against the post-structural FS snapshot. */
+    pathExists(path: string): boolean;
+    pathMissing(path: string): boolean;
+    /** True if any file in the snapshot matches `glob`, resolved
+     *  MODULE-RELATIVE to the leaf's bound module: a co-located-test glob
+     *  inside `scope("model")` is checked under the `model/` dir. At the
+     *  block root the glob is block-relative. Unlike `pathExists`/`pathMissing`
+     *  (block-relative), `filesMatch` is the module-aware predicate used by
+     *  `whenFilesExist`. */
+    filesMatch(glob: string): boolean;
+};
+export type TriggerFn = (tctx: TriggerContext) => boolean;
+/** Content forms — what to write into a file when creating it.
+ *  `tpl.vars` may be a record or a thunk returning a record; the latter
+ *  lets rule authors call `blockVars()` lazily at resolve time. */
+export type TplVarsLike = Record<string, string> | (() => Record<string, string>);
+export type ContentForm = {
+    kind: "file";
+    path: string;
+} | {
+    kind: "text";
+    value: string;
+} | {
+    kind: "tpl";
+    path: string;
+    vars: TplVarsLike;
+} | {
+    kind: "generate";
+    fn: () => unknown;
+} | {
+    kind: "binary";
+    path: string;
+};
+/** Builder-body for a `managed` file (the content-rules lambda). */
+export type ManagedBody = () => void;
+export type FixedItem = {
+    kind: "fixed";
+    path: string;
+    content: ContentForm;
+};
+export type ManagedItem = {
+    kind: "managed";
+    path: string;
+    initial: ContentForm;
+    body: ManagedBody;
+};
+export type ScaffoldItem = {
+    kind: "scaffold";
+    path: string;
+    initial: ContentForm;
+};
+export type SeedItem = {
+    kind: "seed";
+    path: string;
+    initial: ContentForm;
+};
+export type RemoveItem = {
+    kind: "remove";
+    path: string;
+};
+export type RenameItem = {
+    kind: "rename";
+    from: string;
+    to: string;
+};
+export type LeafItem = FixedItem | ManagedItem | ScaffoldItem | SeedItem | RemoveItem | RenameItem;
+export type ScopeFrame = {
+    kind: "scope";
+    scope: Scope;
+    children: TreeNode[];
+};
+export type WhenFrame = {
+    kind: "when";
+    trigger: TriggerFn;
+    children: TreeNode[];
+};
+/** Top-level mode frame: contained leaves fire only in the listed run
+ *  modes. Leaves outside any mode frame fire in `["default", "init"]`
+ *  (refresh/check + init). `onUpdateDeps()` produces `["updateDeps"]`;
+ *  `onInitOrUpdate()` produces `["init", "updateDeps"]`. */
+export type ModeFrame = {
+    kind: "mode";
+    modes: RunMode[];
+    children: TreeNode[];
+};
+export type TreeNode = LeafItem | ScopeFrame | WhenFrame | ModeFrame;
+/** Structure object returned by `defineStructure`. */
+export type Structure = {
+    /** Top-level children — may contain leaves, scope frames, when
+     *  frames, and mode frames. */
+    children: TreeNode[];
+};
+/**
+ * After fan-out: one entry per (leaf × matching module). `scope` is
+ * always set; `modulePath` is the workspace path the leaf is bound to
+ * (empty string for the workspace root). `triggers` is the AND of all
+ * enclosing `when` predicates. `modes` is the set of run modes the leaf
+ * fires in — `["default", "init"]` outside any mode frame, otherwise the
+ * enclosing mode frame's `modes`.
+ */
+export type FlatItem = {
+    leaf: LeafItem;
+    scope: Scope;
+    modulePath: string;
+    /** Block-relative resolved path(s). */
+    resolvedPath: string;
+    /** For rename, the resolved destination. */
+    resolvedTo?: string;
+    triggers: TriggerFn[];
+    modes: RunMode[];
+};

package/dist/structure/engine/parsers/json.d.ts

@@ -0,0 +1,37 @@
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [k: string]: JsonValue;
+};
+export type JsonObject = {
+    [k: string]: unknown;
+};
+/** Parse JSON; throws on invalid input. */
+export declare function parseJson(raw: string): unknown;
+/** Canonical serialiser: 2-space indent, trailing newline.
+ *  Default — every container expanded (the package.json shape, byte-identical
+ *  to `JSON.stringify(…, 2)`).
+ *  `{ collapse: true }` — oxfmt's generic-.json shape: containers that fit
+ *  `PRINT_WIDTH` collapse onto one line. Used for tsconfig.json and any other
+ *  non-package.json the engine emits, so `oxfmt --check` passes without a
+ *  prior format pass. */
+export declare function stringifyJson(value: unknown, opts?: {
+    collapse?: boolean;
+}): string;
+/** Get the value at `jsonPath`. Returns `undefined` if any segment is
+ *  missing or not an object. */
+export declare function getAtPath(obj: JsonObject, jsonPath: string): unknown;
+/** True if `jsonPath` resolves to a defined value (including `null`). */
+export declare function hasAtPath(obj: JsonObject, jsonPath: string): boolean;
+/** Set `value` at `jsonPath`. Auto-creates intermediate objects. Throws
+ *  if a non-object value is on the path (would be silently overwritten
+ *  otherwise — caller bug). */
+export declare function setAtPath(obj: JsonObject, jsonPath: string, value: unknown): void;
+/** Delete the value at `jsonPath`. No-op if any segment is missing. */
+export declare function deleteAtPath(obj: JsonObject, jsonPath: string): void;
+/**
+ * Reorder top-level keys of `obj`:
+ *  - Known keys (those listed in `order`) appear in declared order.
+ *  - Unknown keys (not in `order`) stay adjacent to the preceding known
+ *    key they followed in the source. Unknown keys appearing before any
+ *    known key go first, in source order.
+ */
+export declare function reorderTopLevel(obj: JsonObject, order: readonly string[]): JsonObject;

package/dist/structure/engine/parsers/lines.d.ts

@@ -0,0 +1,9 @@
+export declare function parseLines(raw: string): string[];
+export declare function serializeLines(lines: readonly string[]): string;
+/** Strip leading/trailing whitespace and trailing inline `# ...` comments.
+ *  Returns empty string for blank / comment-only lines. */
+export declare function normaliseLine(line: string): string;
+/** True if `line` (after normalisation) equals `entry` (after trim). */
+export declare function lineEqualsEntry(line: string, entry: string): boolean;
+/** True if any line in `lines` normalises to `entry`. */
+export declare function containsEntry(lines: readonly string[], entry: string): boolean;

package/dist/structure/engine/parsers/yaml.d.ts

@@ -0,0 +1,18 @@
+import { Document, isMap, isPair, isSeq, YAMLMap, YAMLSeq, Scalar, Node } from 'yaml';
+export type YamlDocument = Document.Parsed;
+/** Parse YAML into a CST-preserving Document. */
+export declare function parseYaml(raw: string): YamlDocument;
+/** Serialise back to string. Preserves comments + ordering of unchanged
+ *  nodes per the `yaml` library's contract. */
+export declare function stringifyYaml(doc: YamlDocument): string;
+/** Get the JS value at the given jsonPath in the document. */
+export declare function yamlGet(doc: YamlDocument, jsonPath: string): unknown;
+export declare function yamlHas(doc: YamlDocument, jsonPath: string): boolean;
+/** Set a value at jsonPath. Auto-creates intermediate maps. Existing
+ *  comments on parent map entries are preserved by the yaml library. */
+export declare function yamlSet(doc: YamlDocument, jsonPath: string, value: unknown): void;
+/** Delete a value at jsonPath. No-op if missing. */
+export declare function yamlDelete(doc: YamlDocument, jsonPath: string): void;
+/** Re-export selected `yaml` lib types for downstream content-rule builders. */
+export { isMap, isPair, isSeq, YAMLMap, YAMLSeq, Scalar };
+export type { Node };

package/dist/structure/engine/registry-client.d.ts

@@ -0,0 +1,34 @@
+export interface RegistryClient {
+    getLatestVersion(packageName: string): Promise<string>;
+}
+/** Parse the HTTP Retry-After header (RFC 9110): either a delay in
+ *  seconds or an absolute HTTP-date. Returns the delay in ms, or null
+ *  if the header is missing / unparseable. */
+export declare function parseRetryAfter(header: string | null): number | null;
+/** Live npm registry client. Hits the network on each call. */
+export declare function createRealRegistryClient(): RegistryClient;
+/** In-memory client backed by a fixed `name → version` map. */
+export declare function createMockRegistryClient(versions: Record<string, string>): RegistryClient;
+/** Resolve a batch of `name → latest` entries in parallel. */
+export declare function prefetchLatestVersions(client: RegistryClient, packageNames: readonly string[]): Promise<Map<string, string>>;
+/** Build a sync lookup function (the shape `withManagedYaml` consumes)
+ *  from a prefetched map. Returns undefined for unknown names. */
+export declare function makeSyncLookup(resolved: Map<string, string>): (packageName: string) => string | undefined;
+/** Catalog package-name patterns the version-resolution rules
+ *  (`ensureCatalogLatest`) match against — the `@platforma-sdk/*` and
+ *  `@milaboratories/*` SDK families. Infra/runtime entries (turbo, shx,
+ *  …) are deliberately NOT here: they stay a curated floor, not auto-latest.
+ *  Shared so `init` (names from the SDK pin map) and `refresh
+ *  --update-deps-only` (names from the on-disk catalog) select the same
+ *  set. */
+export declare const CATALOG_BUMP_PATTERNS: readonly RegExp[];
+/** True if `name` is a version-resolved SDK package (matches any bump
+ *  pattern). */
+export declare function matchesBumpPattern(name: string): boolean;
+/** Prefetch npm "latest" for `names` and return the sync lookup the
+ *  runner passes to the catalog ensure-family (`ensureCatalogLatest`).
+ *  Empty list → a lookup that
+ *  resolves nothing (no network). A network/registry failure REJECTS
+ *  (callers that require the network — `init` — let it propagate).
+ *  `client` defaults to the live npm client; tests inject a mock. */
+export declare function buildRegistryLookupForNames(names: readonly string[], client?: RegistryClient): Promise<(packageName: string) => string | undefined>;

package/dist/structure/engine/runner.d.ts

@@ -0,0 +1,45 @@
+import { Structure } from './ir';
+import { RunContext, Scope } from './api';
+import { FileSystem } from './fs/api';
+import { TemplateProvider } from './templates';
+export type ChangeAction = "create" | "update" | "delete" | "rename" | "noop";
+export type Change = {
+    scope: Scope;
+    /** Resolved (block-relative) path. For rename, the source path. */
+    path: string;
+    /** "fixed" | "managed" | "scaffold" | "seed" | "remove" | "rename" */
+    primitive: string;
+    action: ChangeAction;
+};
+export type RunResult = {
+    changes: Change[];
+};
+export type RunOptions = {
+    /** Called before the post-run recheck to obtain a fresh RunContext
+     *  reflecting the just-written FS state (re-reads `pnpm-workspace.yaml`).
+     *  If absent, recheck reuses the original ctx with `dryRun: true`. */
+    rediscover?: (fs: FileSystem) => RunContext;
+    /** Template provider used by `file(...)` and `tpl(...)` content forms.
+     *  Required whenever the structure references such forms. */
+    templates?: TemplateProvider;
+    /** Init mode: write seed leaves (only-if-missing semantics) and skip
+     *  the post-run recheck. The caller is expected to follow with an
+     *  explicit dry-run check (Layer-2 invariant). */
+    initMode?: boolean;
+    /** Sync accessor for prefetched npm "latest" versions, consumed by
+     *  `ensureCatalogLatest` inside `onUpdateDeps` managed bodies. The CLI
+     *  prefetches the catalog's package versions before the run (network)
+     *  and passes the resulting sync map here; unit tests pass a mock.
+     *  Absent → `ensureCatalogLatest` is a no-op (default refresh). */
+    registryLookup?: (packageName: string) => string | undefined;
+};
+export declare class RecheckError extends Error {
+    readonly failing: Change;
+    constructor(failing: Change);
+}
+/**
+ * Run the structurer engine end-to-end. See module header for mode
+ * semantics. Throws `RecheckError` if the post-run dry-run finds any
+ * leftover diff after a successful refresh.
+ */
+export declare function run(structure: Structure, fs: FileSystem, ctx: RunContext, opts?: RunOptions): RunResult;

package/dist/structure/engine/templates.d.ts

@@ -0,0 +1,30 @@
+export interface TemplateProvider {
+    /** Read a static template file (under `<root>/static/`). */
+    staticRead(p: string): string;
+    /** Read a static template file as raw bytes (under `<root>/static/`).
+     *  For binary assets (logos, images) that must not be utf-8 decoded. */
+    staticReadBinary(p: string): Uint8Array;
+    /** Read a text template file (under `<root>/text/`). */
+    textRead(p: string): string;
+}
+/** Provider backed by an on-disk template tree. Reads are synchronous
+ *  so the runner can stay sync inside content-form resolution. */
+export declare class NodeTemplateProvider implements TemplateProvider {
+    private root;
+    constructor(root: string);
+    staticRead(p: string): string;
+    staticReadBinary(p: string): Uint8Array;
+    textRead(p: string): string;
+}
+/** In-memory provider for tests. Keyed by the same `static/...` /
+ *  `text/...` shape as on disk. */
+export declare class MemoryTemplateProvider implements TemplateProvider {
+    private files;
+    constructor(files: Record<string, string>);
+    staticRead(p: string): string;
+    staticReadBinary(p: string): Uint8Array;
+    textRead(p: string): string;
+}
+/** Shell-style `${name}` substitution. Unknown names left as-is so
+ *  template authors notice. Backslash escape is not supported. */
+export declare function substituteVars(text: string, vars: Record<string, string>): string;

package/dist/structure/engine/testing.d.ts

@@ -0,0 +1,34 @@
+import { BlockVars, Module, RunContext, Structure } from './api';
+import { JsonObject } from './content-rules';
+import { MemoryFileSystem } from './fs/memory';
+import { TemplateProvider } from './templates';
+/** Layer-1 helper. */
+export declare function runRulesAgainst(input: JsonObject, body: () => void): JsonObject;
+export type SimulateInitInput = {
+    vars: BlockVars;
+    /** Override the discovered module set. Defaults to `defaultModulesFor`. */
+    modules?: Module[];
+    /** Override the structure under test (defaults to the canonical one). */
+    structure?: Structure;
+    /** Override the template provider (defaults to NodeTemplateProvider
+     *  pointing at the bundled `templates/` directory). */
+    templates?: TemplateProvider;
+    /** SDK-internal flag. Default `false` (standalone block). */
+    isSdkInternal?: boolean;
+    /** Sync npm-latest lookup for the `onInitOrUpdate` catalog resolution.
+     *  Absent → the SDK catalog keeps its seed versions (no bump), matching
+     *  an offline scaffold; tests that assert init writes latest pass a mock. */
+    registryLookup?: (packageName: string) => string | undefined;
+};
+export type SimulatedInit = {
+    fs: MemoryFileSystem;
+    ctx: RunContext;
+};
+/** Module set produced by `init` for a given BlockVars. Delegates to the
+ *  shared `modulesForInit` so the test helper and the real `init`
+ *  constructor never drift. */
+export declare function defaultModulesFor(vars: BlockVars): Module[];
+/** Default template provider — reads from the bundled templates tree
+ *  next to this file. */
+export declare function defaultTemplateProvider(): TemplateProvider;
+export declare function simulateInit(input: SimulateInitInput): SimulatedInit;

package/dist/structure/engine/version.d.ts

@@ -0,0 +1,18 @@
+import { FileSystem } from './fs/api';
+export declare const STRUCTURE_VERSION = 1;
+export declare const STRUCTURE_MIN_SUPPORTED = 0;
+/** Block-relative path of the structurer metadata file. */
+export declare const STRUCTURE_META_FILE = ".structure";
+export type StructureMeta = {
+    version: number;
+};
+/** Read `.structure`. Missing file or invalid payload → 0. */
+export declare function readStructureVersion(fs: FileSystem): number;
+/** Throw if version is below floor. */
+export declare function assertVersionAboveFloor(version: number, floor?: number): void;
+export declare class StructureVersionFloorError extends Error {
+    readonly version: number;
+    readonly floor: number;
+    constructor(version: number, floor: number);
+}
+export declare function writeStructureVersion(fs: FileSystem, version?: number): void;

package/dist/structure/init-block-constructor.d.ts

@@ -0,0 +1,32 @@
+import { BlockVars } from './engine/api';
+/** Platform choices `init` can scaffold a software module for. Python is
+ *  the only platform with a real, buildable scaffold at v1; any other
+ *  value is rejected rather than scaffolded as a non-buildable placeholder,
+ *  which would defeat the "init must produce a working block" intent.
+ *  `softwarePlatform` stays in BlockVars for when another platform gets a
+ *  real scaffold. (Note: Tengo is the workflow language, not a software
+ *  platform.) */
+export declare const SUPPORTED_PLATFORMS: readonly ["python"];
+export type InitFlagValues = {
+    npmOrg?: string;
+    orgScope?: string;
+    shortName?: string;
+    /** Tri-state: true (--with-software), false (--no-software),
+     *  undefined (unspecified → prompt or, non-interactive, default off). */
+    withSoftware?: boolean;
+    platform?: string;
+    nonInteractive: boolean;
+};
+export type InitInput = {
+    /** Resolved BlockVars (from `resolveBlockVars`). */
+    vars: BlockVars;
+    /** Resolved absolute target directory. */
+    blockPath: string;
+    /** `<block-tools>/src/structure/templates`. */
+    templatesRoot: string;
+    log: (msg: string) => void;
+};
+/** Resolve the full BlockVars (incl. softwarePlatform) from flags +
+ *  prompts. */
+export declare function resolveBlockVars(flags: InitFlagValues): Promise<BlockVars>;
+export declare function runInit(init: InitInput): Promise<BlockVars>;

package/dist/structure/rules/block-package-json.d.ts

@@ -0,0 +1,9 @@
+import { RunContext } from '../engine/api';
+/** The facade's `block.components` map: the dist artifact each module build
+ *  emits, keyed by role. Fully determined by the discovered modules — the
+ *  body rule re-asserts this exact value, so it is engine-managed (NOT an
+ *  author seed). Mirrors the artifact paths produced by each scope's build:
+ *  workflow → pl-tengo, model → build-model, ui → ts-builder. */
+export declare function blockComponents(ctx: RunContext): Record<string, string>;
+export declare function blockPackageJsonInitial(ctx: RunContext): Record<string, unknown>;
+export declare function blockPackageJsonRules(): void;

package/dist/structure/rules/block.d.ts

@@ -0,0 +1 @@
+export declare function blockRules(): void;

package/dist/structure/rules/migrations.d.ts

@@ -0,0 +1,2 @@
+export declare function testFrameworkMigration(): void;
+export declare function legacyCleanup(): void;

package/dist/structure/rules/model-package-json.d.ts

@@ -0,0 +1,3 @@
+import { RunContext } from '../engine/api';
+export declare function modelPackageJsonInitial(ctx: RunContext): Record<string, unknown>;
+export declare function modelPackageJsonRules(): void;

package/dist/structure/rules/model.d.ts

@@ -0,0 +1 @@
+export declare function modelRules(): void;

package/dist/structure/rules/root-catalog-bump.d.ts

@@ -0,0 +1 @@
+export declare function rootCatalogBumpRules(): void;

package/dist/structure/rules/root-gitignore.d.ts

@@ -0,0 +1,2 @@
+export declare const GITIGNORE_REQUIRED_LINES: string[];
+export declare function rootGitignoreRules(): void;

package/dist/structure/rules/root-package-json.d.ts

@@ -0,0 +1,3 @@
+import { RunContext } from '../engine/api';
+export declare function rootPackageJsonInitial(_ctx: RunContext): Record<string, unknown>;
+export declare function rootPackageJsonRules(): void;

package/dist/structure/rules/root-pnpm-workspace.d.ts

@@ -0,0 +1,15 @@
+import { RunContext } from '../engine/api';
+/** SDK packages that live in the catalog (membership only — no versions).
+ *  Init fetches npm latest for each; refresh leaves them as the lockfile has
+ *  them. */
+export declare const SDK_CATALOG_PACKAGES: readonly string[];
+/** Infra / tooling — a `~`-floored curated set. Not exact-pinned on refresh
+ *  and not bumped by update-deps. */
+export declare const INFRA_CATALOG_FLOOR: Record<string, string>;
+/** Catalog name of the python runenv. Added to a block's catalog only when
+ *  the block carries a software module. Pinned to an EXACT version — updating
+ *  the python runenv is an explicit author decision, never automatic. */
+export declare const RUNENV_PYTHON = "@platforma-open/milaboratories.runenv-python-3";
+export declare const RUNENV_PYTHON_VERSION = "1.8.2";
+export declare function rootPnpmWorkspaceInitial(ctx: RunContext): Record<string, unknown>;
+export declare function rootPnpmWorkspaceRules(): void;

package/dist/structure/rules/root.d.ts

@@ -0,0 +1 @@
+export declare function rootRules(): void;

package/dist/structure/rules/shared/colocated-tests.d.ts

@@ -0,0 +1,2 @@
+/** Glob (module-relative) for co-located unit tests in a scope's `src/`. */
+export declare const COLOCATED_TEST_GLOB = "src/**/*.test.ts";

package/dist/structure/rules/shared/key-order.d.ts

@@ -0,0 +1 @@
+export declare const canonicalPackageJsonOrder: readonly ["name", "version", "private", "description", "keywords", "files", "type", "main", "module", "types", "exports", "scripts", "dependencies", "devDependencies", "peerDependencies", "optionalDependencies", "packageManager", "pnpm", "block", "block-software"];

package/dist/structure/rules/software-package-json.d.ts

@@ -0,0 +1,3 @@
+import { RunContext } from '../engine/api';
+export declare function softwarePackageJsonInitial(ctx: RunContext): Record<string, unknown>;
+export declare function softwarePackageJsonRules(): void;

package/dist/structure/rules/software.d.ts

@@ -0,0 +1 @@
+export declare function softwareRules(): void;

package/dist/structure/rules/test-package-json.d.ts

@@ -0,0 +1,3 @@
+import { RunContext } from '../engine/api';
+export declare function testPackageJsonInitial(ctx: RunContext): Record<string, unknown>;
+export declare function testPackageJsonRules(): void;

package/dist/structure/rules/test.d.ts

@@ -0,0 +1 @@
+export declare function testRules(): void;

package/dist/structure/rules/ui-package-json.d.ts

@@ -0,0 +1,3 @@
+import { RunContext } from '../engine/api';
+export declare function uiPackageJsonInitial(ctx: RunContext): Record<string, unknown>;
+export declare function uiPackageJsonRules(): void;

package/dist/structure/rules/ui.d.ts

@@ -0,0 +1 @@
+export declare function uiRules(): void;

package/dist/structure/rules/workflow-package-json.d.ts

@@ -0,0 +1,3 @@
+import { RunContext } from '../engine/api';
+export declare function workflowPackageJsonInitial(ctx: RunContext): Record<string, unknown>;
+export declare function workflowPackageJsonRules(): void;

package/dist/structure/rules/workflow.d.ts

@@ -0,0 +1 @@
+export declare function workflowRules(): void;

package/dist/structure/structure-definition.d.ts

@@ -0,0 +1 @@
+export declare const STRUCTURE: import('./engine/ir').Structure;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@platforma-sdk/block-tools",
-  "version": "2.10.14",
+  "version": "2.10.15",
   "description": "Utility to manipulate Platforma Blocks and Block Registry",
   "license": "UNLICENSED",
   "bin": {
@@ -24,6 +24,7 @@
   },
   "dependencies": {
     "@aws-sdk/client-s3": "3.859.0",
+    "@inquirer/prompts": "^7.0.1",
     "@oclif/core": "^4.0.37",
     "canonicalize": "~2.1.0",
     "lru-cache": "^11.2.2",
@@ -33,13 +34,13 @@
     "yaml": "^2.8.0",
     "zod": "~3.25.76",
     "@milaboratories/pl-http": "1.2.4",
-    "@milaboratories/pl-model-backend": "1.4.7",
     "@milaboratories/pl-model-common": "1.46.1",
+    "@milaboratories/pl-model-backend": "1.4.7",
     "@milaboratories/pl-model-middle-layer": "1.30.5",
     "@milaboratories/ts-helpers": "1.8.3",
-    "@platforma-sdk/blocks-deps-updater": "2.2.0",
+    "@milaboratories/resolve-helper": "1.1.3",
     "@milaboratories/ts-helpers-oclif": "1.1.42",
-    "@milaboratories/resolve-helper": "1.1.3"
+    "@platforma-sdk/blocks-deps-updater": "2.2.0"
   },
   "devDependencies": {
     "@rollup/plugin-node-resolve": "^16.0.1",
@@ -48,16 +49,17 @@
     "@types/semver": "^7.7.0",
     "@vitest/coverage-istanbul": "^4.1.3",
     "oclif": "^4.16.2",
+    "oxfmt": "0.35.0",
     "rollup-plugin-node-externals": "^8.0.0",
     "semver": "^7.7.2",
     "typescript": "~5.9.3",
     "vite": "^8.0.6",
     "vite-plugin-dts": "^4.5.3",
     "vitest": "^4.1.3",
-    "@milaboratories/build-configs": "2.0.0",
     "@milaboratories/oclif-index": "1.1.1",
-    "@milaboratories/ts-builder": "1.5.0",
-    "@milaboratories/ts-configs": "1.2.3"
+    "@milaboratories/ts-configs": "1.2.3",
+    "@milaboratories/build-configs": "2.0.0",
+    "@milaboratories/ts-builder": "1.5.0"
   },
   "oclif": {
     "bin": "block-tools",

package/src/cmd/index.ts

@@ -8,8 +8,11 @@ import Cmd5 from "./pack";
 import Cmd6 from "./publish";
 import Cmd7 from "./refresh-registry";
 import Cmd8 from "./restore-overview-from-snapshot";
-import Cmd9 from "./upload-package-v1";
-import Cmd10 from "./update-deps";
+import Cmd9 from "./update-deps";
+import Cmd10 from "./upload-package-v1";
+import Cmd11 from "./structure/check";
+import Cmd12 from "./structure/init";
+import Cmd13 from "./structure/refresh";
 
 export const COMMANDS = {
   "build-meta": Cmd0,
@@ -20,6 +23,9 @@ export const COMMANDS = {
   publish: Cmd6,
   "refresh-registry": Cmd7,
   "restore-overview-from-snapshot": Cmd8,
-  "upload-package-v1": Cmd9,
-  "update-deps": Cmd10,
+  "update-deps": Cmd9,
+  "upload-package-v1": Cmd10,
+  "structure:check": Cmd11,
+  "structure:init": Cmd12,
+  "structure:refresh": Cmd13,
 };

package/src/cmd/structure/check.ts

@@ -0,0 +1,51 @@
+import { Command, Flags } from "@oclif/core";
+import path from "node:path";
+import { runStructureForPath, formatChanges } from "../../structure/cli/run-structure";
+
+export default class StructureCheck extends Command {
+  static override description =
+    "Check block(s) against the canonical structure (read-only). Exits non-zero if any diff would land — used as the CI gate.";
+
+  static override examples = [
+    "<%= config.bin %> <%= command.id %> ./my-block",
+    "<%= config.bin %> <%= command.id %> --sdk-internal etc/blocks/*",
+  ];
+
+  // Variadic positional block paths (shell-expanded globs).
+  static override strict = false;
+
+  static override flags = {
+    "sdk-internal": Flags.boolean({
+      description: "block(s) live inside the SDK monorepo; skip root-scope rules",
+    }),
+  };
+
+  public async run(): Promise<void> {
+    const { argv, flags } = await this.parse(StructureCheck);
+    const paths = (argv as string[]).length > 0 ? (argv as string[]) : ["."];
+    const templatesRoot = path.join(this.config.root, "src", "structure", "templates");
+
+    let anyChanged = false;
+    for (const p of paths) {
+      const res = await runStructureForPath({
+        blockPath: p,
+        isSdkInternal: flags["sdk-internal"],
+        updateDepsOnly: false,
+        mode: "check",
+        templatesRoot,
+        log: (m) => this.log(m),
+      });
+      this.log(formatChanges(p, res.changes));
+      if (res.changes.length > 0) anyChanged = true;
+    }
+
+    if (anyChanged) {
+      this.error(
+        "Structure check failed: one or more blocks are out of date. Run `structure refresh`.",
+        {
+          exit: 1,
+        },
+      );
+    }
+  }
+}