@platforma-sdk/block-tools 2.10.17 → 2.10.19

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

@@ -51,5 +51,5 @@ export type RunContext = {
 };
 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 { 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, pinCatalogToDependencyOf, ensureCatalogLatest, ensureCatalogAbsent, ensureGitignoreEntries, removeGitignoreEntries, withManagedBody, withManagedYaml, withManagedLines, } from './content-rules';
 export type { DepVersion } from './content-rules';

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

@@ -35,6 +35,9 @@ export type WithManagedYamlOpts = WithManagedOpts & {
     /** Sync accessor for prefetched latest versions. Required for
      *  `ensureCatalogLatest` to take effect. */
     getLatestVersion?: (packageName: string) => string | undefined;
+    /** Sync accessor for prefetched derived catalog pins. Required for
+     *  `pinCatalogToDependencyOf` to take effect. */
+    getDerivedDependencyPin?: (catalogEntry: 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. */
@@ -140,6 +143,20 @@ export declare function pinCatalogTo(name: string, version: string): void;
  *  and refreshes a present one, and on `init` it overwrites the
  *  placeholder with the real latest. */
 export declare function ensureCatalogLatest(name: string): void;
+/** Pin `catalog.<catalogEntry>` to the EXACT version that package `opts.of`
+ *  declares for `catalogEntry` in its own manifest (read at npm latest, or at
+ *  `opts.ofVersion` if given). The value is resolved by the runner's
+ *  prefetched `getDerivedDependencyPin` accessor (the caller pre-resolves and
+ *  validates — exact-version-only — at prefetch time; no network here).
+ *  OVERWRITES like `pinCatalogTo` (not add-if-absent): a pre-existing loose
+ *  entry (`vue: ^3.5.24`) is tightened to the exact derived version. No-op
+ *  when no derived-pin lookup is available — default refresh/check pass none,
+ *  leaving the entry exactly as the lockfile has it; the resolution leaves
+ *  live in the `onInitOrUpdate` frame. */
+export declare function pinCatalogToDependencyOf(catalogEntry: string, _opts: {
+    of: string;
+    ofVersion?: 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). */

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

@@ -1,5 +1,10 @@
 export interface RegistryClient {
     getLatestVersion(packageName: string): Promise<string>;
+    /** Read the version `packageName@version` declares for `depName` in its
+     *  published manifest. `version` may be "latest" (resolved via the
+     *  dist-tags). Looks in `dependencies` first, then `peerDependencies`.
+     *  Returns `undefined` when the dep is declared in neither section. */
+    getDeclaredDependency(packageName: string, version: string, depName: string): Promise<string | undefined>;
 }
 /** 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
@@ -7,8 +12,10 @@ export interface RegistryClient {
 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;
+/** In-memory client backed by a fixed `name → version` map. The optional
+ *  `manifests` map (`pkg@version` → declared deps) backs
+ *  `getDeclaredDependency`; "latest" keys resolve via the `versions` map. */
+export declare function createMockRegistryClient(versions: Record<string, string>, manifests?: Record<string, 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)
@@ -32,3 +39,24 @@ export declare function matchesBumpPattern(name: string): boolean;
  *  (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>;
+/** A catalog entry whose version is DERIVED from the version another
+ *  package declares for it. `entry` is the catalog key (== the dep name in
+ *  the source manifest); `of` is the package whose manifest is read; the
+ *  optional `ofVersion` pins which release of `of` to read (default: npm
+ *  latest, the same release the catalog bump pins `of` to). Consumed by
+ *  `pinCatalogToDependencyOf`. */
+export type DerivedCatalogPin = {
+    entry: string;
+    of: string;
+    ofVersion?: string;
+};
+/** Prefetch every derived pin and build the sync lookup the runner passes
+ *  to `pinCatalogToDependencyOf` (`entry → exact version`). Reads
+ *  `pin.of`'s manifest (at `pin.ofVersion`, default npm latest) and the
+ *  version it declares for `pin.entry`. Policy (b): THROWS at prefetch time
+ *  if the source declares the dep as a non-exact (ranged) version or does
+ *  not declare it at all — a derived pin must resolve to an exact version
+ *  or it is a configuration error. Empty list → a lookup that resolves
+ *  nothing (no network). A registry failure REJECTS. `client` defaults to
+ *  the live npm client; tests inject a mock. */
+export declare function buildDerivedPinLookupForPins(pins: readonly DerivedCatalogPin[], client?: RegistryClient): Promise<(entry: string) => string | undefined>;

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

@@ -32,6 +32,12 @@ export type RunOptions = {
      *  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;
+    /** Sync accessor for prefetched derived catalog pins
+     *  (`catalogEntry → exact version`), consumed by `pinCatalogToDependencyOf`
+     *  inside `onInitOrUpdate` managed bodies. The CLI / init constructor
+     *  prefetches + validates these before the run (network). Absent →
+     *  `pinCatalogToDependencyOf` is a no-op (default refresh). */
+    derivedPinLookup?: (catalogEntry: string) => string | undefined;
 };
 export declare class RecheckError extends Error {
     readonly failing: Change;

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

@@ -1,4 +1,5 @@
 import { RunContext } from '../engine/api';
+import { DerivedCatalogPin } from '../engine/registry-client';
 /** 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. */
@@ -6,6 +7,18 @@ 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 entries whose exact version is DERIVED from the version another
+ *  package declares for them (see `pinCatalogToDependencyOf`). Resolved on
+ *  init + update-deps and OVERWRITES the on-disk entry.
+ *
+ *  `vue`: the seeded ui depends on `vue` (catalog:). `@platforma-sdk/ui-vue`
+ *  pins vue as an EXACT regular dependency (not a peer), so the block must
+ *  pin the SAME exact version — a floated `~` lets the ui resolve a newer
+ *  3.5.x than ui-vue's, yielding two vue instances and a SdkPluginV3-vs-Plugin
+ *  type clash in `main.ts`. Deriving the pin from ui-vue's declared dep keeps
+ *  the block in lockstep with whatever vue ui-vue's npm-latest pins, with no
+ *  hand-maintained version here. */
+export declare const DERIVED_CATALOG_PINS: readonly DerivedCatalogPin[];
 /** 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. */

package/dist/structure/rules/shared/retired-deps.d.ts

@@ -0,0 +1,7 @@
+export declare const RETIRED_TOOLCHAIN_DEPS: readonly string[];
+/** Drop every retired toolchain dep from the current package.json scope.
+ *  Idempotent (a `removeDep` on an absent key is a no-op), so it is safe to
+ *  call uniformly from every package.json rules body regardless of which deps
+ *  a given scope ever carried. Pairs with the catalog-side removal in
+ *  `rootPnpmWorkspaceRules`. */
+export declare function removeRetiredToolchainDeps(): void;