@platforma-sdk/block-tools 2.10.14 → 2.10.16

package/dist/cmd/index.d.ts

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

package/dist/cmd/structure/check.d.ts

@@ -0,0 +1,10 @@
+import { Command } from '@oclif/core';
+export default class StructureCheck extends Command {
+    static description: string;
+    static examples: string[];
+    static strict: boolean;
+    static flags: {
+        "sdk-internal": import('@oclif/core/interfaces').BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/cmd/structure/init.d.ts

@@ -0,0 +1,18 @@
+import { Command } from '@oclif/core';
+export default class StructureInit extends Command {
+    static description: string;
+    static examples: string[];
+    static args: {
+        path: import('@oclif/core/interfaces').Arg<string | undefined, Record<string, unknown>>;
+    };
+    static flags: {
+        "npm-org": import('@oclif/core/interfaces').OptionFlag<string | undefined, import('@oclif/core/interfaces').CustomOptions>;
+        "org-scope": import('@oclif/core/interfaces').OptionFlag<string | undefined, import('@oclif/core/interfaces').CustomOptions>;
+        "short-name": import('@oclif/core/interfaces').OptionFlag<string | undefined, import('@oclif/core/interfaces').CustomOptions>;
+        "with-software": import('@oclif/core/interfaces').BooleanFlag<boolean>;
+        "no-software": import('@oclif/core/interfaces').BooleanFlag<boolean>;
+        platform: import('@oclif/core/interfaces').OptionFlag<string | undefined, import('@oclif/core/interfaces').CustomOptions>;
+        "non-interactive": import('@oclif/core/interfaces').BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/cmd/structure/refresh.d.ts

@@ -0,0 +1,11 @@
+import { Command } from '@oclif/core';
+export default class StructureRefresh extends Command {
+    static description: string;
+    static examples: string[];
+    static strict: boolean;
+    static flags: {
+        "sdk-internal": import('@oclif/core/interfaces').BooleanFlag<boolean>;
+        "update-deps-only": import('@oclif/core/interfaces').BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/cmd/update-deps.d.ts

@@ -1,4 +1,11 @@
 import { Command } from '@oclif/core';
+/**
+ * Deprecated. Phase-2 forwarding alias (spec.md § "Coexistence And
+ * Retirement"): delegates to `structure refresh --update-deps-only`,
+ * which lands at parity with the old `blocks-deps-updater` catalog-bump
+ * semantics. Prints a deprecation warning; will be removed once the
+ * structurer path has been live without surprises.
+ */
 export default class UpdateDeps extends Command {
     static description: string;
     static examples: string[];

package/dist/structure/cli/run-structure.d.ts

@@ -0,0 +1,19 @@
+import { Change } from '../engine/runner';
+export type StructureMode = "check" | "refresh";
+export type RunStructureInput = {
+    /** User-supplied block path (resolved against cwd). */
+    blockPath: string;
+    isSdkInternal: boolean;
+    updateDepsOnly: boolean;
+    mode: StructureMode;
+    /** `<block-tools>/src/structure/templates` (from oclif `config.root`). */
+    templatesRoot: string;
+    log: (msg: string) => void;
+};
+export type RunStructureResult = {
+    blockPath: string;
+    changes: Change[];
+};
+export declare function runStructureForPath(input: RunStructureInput): Promise<RunStructureResult>;
+/** One-line-per-change summary for CLI output. */
+export declare function formatChanges(blockPath: string, changes: Change[]): string;

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

@@ -0,0 +1,55 @@
+import { ContentForm, ManagedBody, RunMode, Structure, TriggerFn } from './ir';
+export type Scope = "root" | "block" | "model" | "ui" | "workflow" | "test" | "software";
+/** Variables describing a block — populated by `init` or parsed by
+ *  `check`/`refresh` from the block's package.json `name`. */
+export type BlockVars = {
+    /** e.g. `@platforma-open/my-org.mixcr-clonotyping` */
+    facadeName: string;
+    /** e.g. `my-org.mixcr-clonotyping` */
+    baseName: string;
+    /** e.g. `@platforma-open` */
+    npmOrg: string;
+    /** e.g. `my-org` */
+    orgScope: string;
+    /** e.g. `mixcr-clonotyping` */
+    shortName: string;
+    /** Platform picked at init for the (single) software sub-package.
+     *  Only populated by `init`; absent on `check` / `refresh`. Blocks
+     *  that legitimately have multiple software modules (encountered via
+     *  DISCOVERY on refresh) are not affected — this field only governs
+     *  what `init` scaffolds. */
+    softwarePlatform?: string;
+};
+/** Discovered workspace module. */
+export type Module = {
+    scope: Scope;
+    /** Package name from the module's package.json. */
+    name: string;
+    /** Block-relative path of the module ("" for workspace root). */
+    path: string;
+};
+/** Run context — passed into engine.run and surfaced inside trigger
+ *  predicates as the `ctx` field. */
+export type RunContext = {
+    /** `--sdk-internal` flag. */
+    isSdkInternal: boolean;
+    /** `--update-deps-only` flag. When true, the run is in mode
+     *  `"updateDeps"`: only `onUpdateDeps` / `onInitOrUpdate` leaves fire;
+     *  all default-mode leaves are skipped. The caller is then expected to
+     *  run `pnpm install` and re-invoke `refresh` without the flag for the
+     *  default-mode rules to apply against the updated dep set. */
+    updateDepsOnly: boolean;
+    /** Discovered modules (every scope). */
+    modules: Module[];
+    /** Block vars; on `init` populated from flags/prompts, on
+     *  `check`/`refresh` parsed from block/package.json. */
+    blockVars: BlockVars;
+    /** Layout version read from `.structure`. */
+    version: number;
+    /** True for `check` mode and the post-run recheck. */
+    dryRun: boolean;
+};
+export type { ContentForm, ManagedBody, RunMode, Structure, TriggerFn };
+export { defineStructure, scope, when, whenFilesExist, onUpdateDeps, onInitOrUpdate, fixed, managed, scaffold, seed, remove, rename, file, binaryFile, text, tpl, generate, blockVars, } from './builders';
+export { ensureField, removeField, requireField, ensureFieldEntries, ensureScript, removeScript, ensureDep, ensureDevDep, ensurePeerDep, ensureOptionalDep, removeDep, ensureDeps, ensureDevDeps, ensurePeerDeps, ensureOptionalDeps, ensureWorkspaceScopeDeps, ensureWorkspaceScopeDevDeps, ensureWorkspaceScopePeerDeps, pruneKeysMatching, pruneKeysMatchingAt, enforceFieldOrder, enforceFieldOrderAt, enforceAlphabeticalOrder, transformAt, ensureWorkspaceModulePaths, ensureCatalogVersion, pinCatalogTo, ensureCatalogLatest, ensureCatalogAbsent, ensureGitignoreEntries, removeGitignoreEntries, withManagedBody, withManagedYaml, withManagedLines, } from './content-rules';
+export type { DepVersion } from './content-rules';

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

@@ -0,0 +1,95 @@
+import { Scope, RunContext, BlockVars, ContentForm } from './api';
+import { ManagedBody, Structure, TriggerFn } from './ir';
+/** Engine-internal: scope `blockVars()` lookups during a run. The body is
+ *  synchronous, so the module-global `activeRunContext` cannot be observed
+ *  by an interleaved run — a sync call stack runs to completion before any
+ *  other `run()` can start. The try/finally restores the previous context
+ *  (supporting the nested-run case the post-run recheck used to imply). */
+export declare function withRunContext<T>(ctx: RunContext, fn: () => T): T;
+/** Engine-internal: content-rule builders that need `ctx.modules` look
+ *  up the active context through this accessor. Returns `undefined`
+ *  outside a run. */
+export declare function tryGetActiveRunContext(): RunContext | undefined;
+/** Get-or-die counterpart of `tryGetActiveRunContext`. Generators run
+ *  only inside `engine.run()`; an absent context is framework misuse, not
+ *  a valid state, so throw rather than emit degenerate (empty) output.
+ *  Mirrors `blockVars()`. */
+export declare function getActiveRunContext(): RunContext;
+/** The single entry point: build a {@link Structure} from `fn`, which calls
+ *  the scaffold-DSL builders (`scope`, `fixed`, `managed`, `seed`, …). Throws
+ *  if called nested, or if `fn` leaves an unclosed group frame. */
+export declare function defineStructure(fn: () => void): Structure;
+/** Open a scope (`root` / `block` / `model` / `ui` / `workflow` / `test` /
+ *  `software`); builders called inside `body` attach to it. Cannot nest. */
+export declare function scope(name: Scope, body: () => void): void;
+/** Inner-mode `when` handler. Registered by `content-rules.ts` at
+ *  load time. Returns true if the call was dispatched (an inner active
+ *  state was present); false otherwise. Avoids a circular import. */
+type InnerWhenHandler = (trigger: TriggerFn, body: () => void) => boolean;
+/** Engine-internal: register the inner-mode `when` handler (set by
+ *  `content-rules.ts` at load time to avoid a circular import). */
+export declare function registerInnerWhenHandler(h: InnerWhenHandler): void;
+/**
+ * Conditionally run `body`. Two dispatch modes by active state:
+ *  - inside `defineStructure(...)` → push a `WhenFrame` into the tree;
+ *    trigger fires later at runner time per `FlatItem`.
+ *  - inside a `managed(...)` body → evaluate `trigger` immediately
+ *    against the runner-supplied `TriggerContext`; run/skip `body`
+ *    synchronously.
+ *
+ * One `when` symbol for both layers — same user contract, dispatch
+ * picks the matching execution timing.
+ */
+export declare function when(trigger: TriggerFn, body: () => void): void;
+/** Trigger factory: true when at least one file in the leaf's module
+ *  matches `glob` (module-relative — see `TriggerContext.filesMatch`). Use
+ *  to gate a rule on the presence of co-located files, e.g. add a vitest
+ *  `test` script only when `src/**\/*.test.ts` exists. Pairs with `when`:
+ *  `when(whenFilesExist("src/**\/*.test.ts"), () => { ... })`. */
+export declare function whenFilesExist(glob: string): TriggerFn;
+/** Leaves inside fire ONLY under `--update-deps-only` (mode
+ *  `"updateDeps"`); they are skipped on default refresh/check and init. */
+export declare function onUpdateDeps(body: () => void): void;
+/** Leaves inside fire on `init` AND `--update-deps-only`, but NOT on
+ *  default refresh/check. The frame for rules that resolve/write current
+ *  versions: both init and update-deps mean "fetch and write latest",
+ *  while a plain refresh leaves them as the author/lockfile has them. */
+export declare function onInitOrUpdate(body: () => void): void;
+/** Engine-OWNED file: (re)written verbatim from `content` on every refresh —
+ *  author edits are overwritten. */
+export declare function fixed(path: string, content: ContentForm): void;
+/** Engine-RECONCILED file: parsed from disk (or `initial` when absent),
+ *  mutated by `body` (the JSON/YAML/lines builders), then re-serialised.
+ *  Content the body does not touch is preserved. */
+export declare function managed(path: string, initial: ContentForm, body: ManagedBody): void;
+/** Write-once file: created from `initial` if absent (on init AND refresh),
+ *  never overwritten once present. For files the author subsequently owns. */
+export declare function scaffold(path: string, initial: ContentForm): void;
+/** Author-owned starter file: written from `initial` only on `init`, and only
+ *  if absent; `refresh` / `check` never touch it. */
+export declare function seed(path: string, initial: ContentForm): void;
+/** Delete `path` if present, on every refresh. */
+export declare function remove(path: string): void;
+/** Rename file `from` → `to` on refresh (migrating a renamed scaffold file). */
+export declare function rename(from: string, to: string): void;
+/** Content form: a UTF-8 static template read from the structurer's static
+ *  templates. Use inside `fixed` / `managed` / `scaffold` / `seed`. */
+export declare function file(path: string): ContentForm;
+/** A binary static asset (e.g. a logo) read verbatim from `<root>/static/`.
+ *  Unlike `file()`, the bytes are never decoded to a string — use for
+ *  images / archives. Only valid inside `seed()` / `scaffold()`. */
+export declare function binaryFile(path: string): ContentForm;
+/** Content form: an inline literal string. */
+export declare function text(value: string): ContentForm;
+/** Content form: a text template (the structurer's `text/` templates) with
+ *  `${var}` placeholders substituted from `vars`. */
+export declare function tpl(path: string, vars: Record<string, string> | (() => Record<string, string>)): ContentForm;
+/** Content form: content computed at run time. The return value is serialised
+ *  as JSON / YAML by the target file's extension, or used verbatim if it is
+ *  already a string. */
+export declare function generate(fn: () => unknown): ContentForm;
+/** The active run's {@link BlockVars} (block name parts + software platform).
+ *  Valid only during a run (inside a generator or managed body); throws
+ *  otherwise. */
+export declare function blockVars(): BlockVars;
+export {};

package/dist/structure/engine/content-rules.d.ts

@@ -0,0 +1,148 @@
+import { RunContext, Scope } from './api';
+import { TriggerContext } from './ir';
+import { JsonObject } from './parsers/json';
+import { YamlDocument } from './parsers/yaml';
+export type { JsonObject };
+/** Allowed dep version strings. Specific versions live in the catalog.
+ *  `"sdk:"` is an authoring abstraction, not an on-disk value: the engine
+ *  resolves it at write time (`workspace:*` when `ctx.isSdkInternal`, else
+ *  `"catalog:"`) and the resolved literal is what serializes. Use it for
+ *  every dep that is a member of the platforma monorepo's pnpm workspace
+ *  (the `@platforma-sdk/*` packages + `@milaboratories/ts-builder` /
+ *  `ts-configs`). */
+export type DepVersion = "catalog:" | "sdk:" | `workspace:${string}` | "*";
+/** Resolve the `"sdk:"` sentinel to its on-disk literal. All other
+ *  `DepVersion` forms pass through unchanged — `"sdk:"` never serializes. */
+export declare function resolveDepVersion(version: DepVersion, isSdkInternal: boolean): Exclude<DepVersion, "sdk:">;
+/** Resolve any `"sdk:"` sentinels in the dep sections of a generated
+ *  package.json object, in place. Mirrors `resolveDepVersion` for the
+ *  generator (`initial` content) path — the runner calls this on every
+ *  `generate()`-produced `.json` value so the sentinel never reaches disk
+ *  via a generator. */
+export declare function resolveSdkSentinelsInJson(value: unknown, isSdkInternal: boolean): void;
+export type WithManagedOpts = {
+    ctx?: RunContext;
+    /** Trigger context for `when(...)` calls inside the body. The runner
+     *  builds this from the post-structural-pass FS snapshot + run ctx.
+     *  Without it, `when(...)` inside the body throws. */
+    triggerContext?: TriggerContext;
+};
+/** Engine-internal: run `body` with `obj` as the active JSON state so the
+ *  JSON builders mutate it; returns the mutated object. Exported for tests —
+ *  the runner calls this for managed `.json` files. */
+export declare function withManagedBody(obj: JsonObject, body: () => void, opts?: WithManagedOpts): JsonObject;
+export type WithManagedYamlOpts = WithManagedOpts & {
+    /** Sync accessor for prefetched latest versions. Required for
+     *  `ensureCatalogLatest` to take effect. */
+    getLatestVersion?: (packageName: string) => string | undefined;
+};
+/** Engine-internal: run `body` with `doc` as the active YAML state (for
+ *  `pnpm-workspace.yaml`); returns the mutated document. Exported for tests. */
+export declare function withManagedYaml(doc: YamlDocument, body: () => void, opts?: WithManagedYamlOpts): YamlDocument;
+/** Engine-internal: run `body` with `lines` as the active line-based state
+ *  (for `.gitignore`); returns the mutated lines. Exported for tests. */
+export declare function withManagedLines(lines: string[], body: () => void, opts?: WithManagedOpts): string[];
+/** Set the value at `jsonPath` in the active managed JSON object. */
+export declare function ensureField(jsonPath: string, value: unknown): void;
+/** Remove the field at `jsonPath`. With `predicate`, only removes when
+ *  the predicate returns true against the current value. */
+export declare function removeField(jsonPath: string, predicate?: (currentValue: unknown) => boolean): void;
+/** Assert a field exists; throw if absent. No mutation. */
+export declare function requireField(jsonPath: string, message?: string): void;
+/** Merge `entries` into the object at `jsonPath`. Auto-creates the
+ *  object if missing. Existing other entries preserved. */
+export declare function ensureFieldEntries(jsonPath: string, entries: Record<string, unknown>): void;
+/** Set `scripts.<name>` to `command`. */
+export declare function ensureScript(name: string, command: string): void;
+/** Remove `scripts.<name>` if present. */
+export declare function removeScript(name: string): void;
+/** Pin `name` to `version` in `dependencies`. Enforces the single-section
+ *  invariant — `name` may live in only one dependency section, so it is
+ *  removed from the others first. A `sdk:` sentinel version is resolved
+ *  against the run's `--sdk-internal` flag before it reaches disk. */
+export declare function ensureDep(name: string, version: DepVersion): void;
+/** Pin `name` to `version` in `devDependencies` (see {@link ensureDep} for the
+ *  single-section + `sdk:` semantics). */
+export declare function ensureDevDep(name: string, version: DepVersion): void;
+/** Pin `name` to `version` in `peerDependencies` (see {@link ensureDep}). */
+export declare function ensurePeerDep(name: string, version: DepVersion): void;
+/** Pin `name` to `version` in `optionalDependencies` (see {@link ensureDep}). */
+export declare function ensureOptionalDep(name: string, version: DepVersion): void;
+/** Remove `name` from every dependency section. */
+export declare function removeDep(name: string): void;
+/** Bulk {@link ensureDep} for each `name → version` entry. */
+export declare function ensureDeps(entries: Record<string, DepVersion>): void;
+/** Bulk {@link ensureDevDep} for each `name → version` entry. */
+export declare function ensureDevDeps(entries: Record<string, DepVersion>): void;
+/** Bulk {@link ensurePeerDep} for each `name → version` entry. */
+export declare function ensurePeerDeps(entries: Record<string, DepVersion>): void;
+/** Bulk {@link ensureOptionalDep} for each `name → version` entry. */
+export declare function ensureOptionalDeps(entries: Record<string, DepVersion>): void;
+/** Add every discovered module of `scope` as a `workspace:*` entry in
+ *  `dependencies` — wires a block's intra-workspace links (e.g. the test
+ *  scope depending on the other scopes). Single-section invariant per
+ *  {@link ensureDep}. */
+export declare function ensureWorkspaceScopeDeps(scope: Scope): void;
+/** Like {@link ensureWorkspaceScopeDeps}, into `devDependencies`. */
+export declare function ensureWorkspaceScopeDevDeps(scope: Scope): void;
+/** Like {@link ensureWorkspaceScopeDeps}, into `peerDependencies`. */
+export declare function ensureWorkspaceScopePeerDeps(scope: Scope): void;
+/** Delete every top-level key for which `predicate(key, value)` is true. */
+export declare function pruneKeysMatching(predicate: (key: string, value: unknown) => boolean): void;
+/** Delete every key of the object at `jsonPath` for which
+ *  `predicate(key, value)` is true. No-op if the path is not an object. */
+export declare function pruneKeysMatchingAt(jsonPath: string, predicate: (key: string, value: unknown) => boolean): void;
+/** Reorder top-level keys to `orderedKeys`; keys not listed keep their
+ *  position relative to the preceding listed key. Typically the LAST call in
+ *  a managed body, projecting the canonical field order. */
+export declare function enforceFieldOrder(orderedKeys: string[]): void;
+/** Like {@link enforceFieldOrder}, applied to the object at `jsonPath`. No-op
+ *  if the path is not an object. */
+export declare function enforceFieldOrderAt(jsonPath: string, orderedKeys: string[]): void;
+/** Sort keys alphabetically. Called with no args it is a deliberate no-op
+ *  (guards against accidental whole-file sorts); pass a `jsonPath` to sort one
+ *  object, or `{ recursive: true }` to sort the whole tree. Matches oxfmt's
+ *  dependency-section ordering. */
+export declare function enforceAlphabeticalOrder(jsonPath?: string, opts?: {
+    recursive?: boolean;
+}): void;
+/** Escape hatch: replace the value at `jsonPath` with `transform(current)`,
+ *  for shapes the typed builders above do not cover. */
+export declare function transformAt<T = unknown>(jsonPath: string, transform: (current: T) => T): void;
+/** Set the workspace `packages:` list to all discovered NON-root module
+ *  paths (sorted lex). The block root ("") is discovered implicitly
+ *  and is NEVER written to `packages:` — listing "." there breaks turbo's
+ *  task graph. Equality-guarded — skips the rewrite when the existing
+ *  list already matches, so a YAML round-trip on an already-canonical
+ *  file produces zero churn. */
+export declare function ensureWorkspaceModulePaths(): void;
+/** Add `catalog.<name>` at `version` ONLY if the key is absent. An entry
+ *  the block already carries is left untouched — no overwrite, no
+ *  downgrade. This is the seeding primitive for curated fixed versions
+ *  (`INFRA_CATALOG_FLOOR`, the python runenv pin): on
+ *  `refresh --update-deps-only` a missing standard catalog key is added,
+ *  while a key the block already pins keeps its own version. To force a
+ *  specific version regardless of what is present, use `pinCatalogTo`. */
+export declare function ensureCatalogVersion(name: string, version: string): void;
+/** Set `catalog.<name>` to `version` EXACTLY — creates the entry if
+ *  missing, overwrites it (including a downgrade) if present. Use to force
+ *  a specific version; with top-to-bottom declaration order a later
+ *  `pinCatalogTo` overrides an earlier `ensureCatalogLatest`. Distinct
+ *  from `ensureCatalogVersion`, which never touches a present key. */
+export declare function pinCatalogTo(name: string, version: string): void;
+/** Resolve `catalog.<name>` to npm "latest" from the active state's
+ *  prefetched `getLatestVersion` accessor (the caller pre-resolves; no
+ *  network here), creating the key if absent. No-op when no latest is
+ *  available — default refresh passes no lookup, and a name that was not
+ *  prefetched resolves to `undefined`; in both cases any existing entry is
+ *  left untouched. This is the SDK-family resolver: on
+ *  `refresh --update-deps-only` it both SEEDS a missing standard SDK key
+ *  and refreshes a present one, and on `init` it overwrites the
+ *  placeholder with the real latest. */
+export declare function ensureCatalogLatest(name: string): void;
+/** Remove `catalog.<name>` if present; no-op when absent. */
+export declare function ensureCatalogAbsent(name: string): void;
+/** Append each `entry` if not already present (comment-aware equality). */
+export declare function ensureGitignoreEntries(entries: string[]): void;
+/** Drop any line whose normalised form matches any of `patterns`. */
+export declare function removeGitignoreEntries(patterns: RegExp[]): void;

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

@@ -0,0 +1,34 @@
+import { 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 declare function findModules(ctx: RunContext, scope: Scope): Module[];
+/** The single module of `scope`. Throws if absent OR if more than one
+ *  exists. Use when exactly one is required (model / ui / workflow). */
+export declare function findModule(ctx: RunContext, scope: Scope): Module;
+/** Workspace dep map `{ name: "workspace:*" }` for the single module of
+ *  `scope`. Throws if absent (via `findModule`) — guarantees the dep. */
+export declare function scopeDepMap(ctx: RunContext, scope: Scope): Record<string, string>;
+/** Workspace dep map for ALL modules of `scope` (zero or more). Never
+ *  throws — use where multiple modules are legitimate (e.g. software). */
+export declare function scopeDepMaps(ctx: RunContext, scope: Scope): Record<string, string>;
+/**
+ * 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 declare function modulesForInit(vars: BlockVars): Module[];
+export type CreateRunContextInput = {
+    isSdkInternal?: boolean;
+    updateDepsOnly?: boolean;
+    modules: Module[];
+    blockVars: BlockVars;
+    version?: number;
+    dryRun?: boolean;
+};
+export declare function createRunContext(input: CreateRunContextInput): RunContext;

package/dist/structure/engine/discovery-fs.d.ts

@@ -0,0 +1,22 @@
+import { BlockVars, RunContext } from './api';
+import { FileSystem } from './fs/api';
+export declare class StructureCliError extends Error {
+    constructor(msg: string);
+}
+/** Parse a facade package name `@npmOrg/orgScope.shortName` into BlockVars. */
+export declare function parseBlockVars(facadeName: string): BlockVars;
+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 declare function discoverRunContext(input: DiscoverInput): RunContext;

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

@@ -0,0 +1,39 @@
+import { Module, Scope } from './api';
+export declare const ALL_SCOPES: Scope[];
+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>;
+    "block-scope"?: string;
+    "block-software"?: unknown;
+};
+export declare class DiscoveryError extends Error {
+    readonly path?: string | undefined;
+    constructor(msg: string, path?: string | undefined);
+}
+/**
+ * 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 declare function classifyOne(wp: WorkspacePackage, siblingNames: Set<string>): Scope | 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 declare function discoverModules(packages: WorkspacePackage[]): Module[];

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

@@ -0,0 +1,3 @@
+import { RunContext } from './api';
+import { FlatItem, Structure } from './ir';
+export declare function flatten(structure: Structure, ctx: RunContext): FlatItem[];

package/dist/structure/engine/fs/api.d.ts

@@ -0,0 +1,27 @@
+/** 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;
+}

package/dist/structure/engine/fs/memory.d.ts

@@ -0,0 +1,16 @@
+import { DirEntry, FileSystem } from './api';
+export declare class MemoryFileSystem implements FileSystem {
+    private files;
+    constructor(initial?: Record<string, string>);
+    /** Snapshot of all files — handy for assertions. Binary entries are
+     *  rendered as a placeholder so the snapshot stays a string map. */
+    snapshot(): Record<string, string>;
+    read(path: string): string;
+    write(path: string, content: string): void;
+    writeBinary(path: string, content: Uint8Array): void;
+    exists(path: string): boolean;
+    list(dir: string): string[];
+    listDir(dir: string): DirEntry[];
+    move(from: string, to: string): void;
+    delete(path: string): void;
+}

package/dist/structure/engine/fs/node.d.ts

@@ -0,0 +1,14 @@
+import { DirEntry, FileSystem } from './api';
+export declare class NodeFileSystem implements FileSystem {
+    private root;
+    constructor(root: string);
+    private abs;
+    read(p: string): string;
+    write(p: string, content: string): void;
+    writeBinary(p: string, content: Uint8Array): void;
+    exists(p: string): boolean;
+    list(dir: string): string[];
+    listDir(dir: string): DirEntry[];
+    move(from: string, to: string): void;
+    delete(p: string): void;
+}

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

@@ -0,0 +1,4 @@
+/** Compile a glob to an anchored RegExp. */
+export declare function globToRegExp(glob: string): RegExp;
+/** True if `path` matches `glob` (whole-path, anchored). */
+export declare function matchesGlob(glob: string, path: string): boolean;