@starci/hfs 4.7.21 → 4.7.22

package/CHANGELOG.md

@@ -1,5 +1,8 @@
 # Changelog
 
+## 4.7.22 - 2026-10-22
+- Fixed: the bundled runtime carries `modules/schemas/provision-operation.schema.yaml`; 4.7.21 left it out, so `starci app check` and `starci app lint` failed with ENOENT in every app whose stack declaration has an `operations` block. The composition reads both schemas through `new URL(..., import.meta.url)`, the form the runtime copy follows. Spec: `src/provision-operation-schema-bundle.spec.mjs`.
+
 ## 4.7.21 - 2026-10-22
 - Fixed: the release gate's Sonar read retries a network error or HTTP 5xx up to 5 times with backoff inside its 600 s wait; a 4xx and every gate status keep their verdict. Spec: `src/sonar-quality-gate.spec.mjs`.
 - Fixed: `starci app db dump` archives its parts with tar run inside the scratch directory and relative names only (no `-C`, no absolute path): GNU tar, first on PATH under Git Bash on Windows, read the absolute drive-letter archive path as a remote host and every backup failed with `DB_BACKUP_TOOL_FAILED`. Spec: `src/db-dump-archive.spec.mjs`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/hfs",
-  "version": "4.7.21",
+  "version": "4.7.22",
   "description": "The StarCi app command implementation for scaffolding, linting, checking and synchronizing one product repository.",
   "type": "module",
   "license": "MIT",

package/runtime/knowledge/hfs/canon-pins.yaml

@@ -76,14 +76,14 @@ pins:
     source: packages/test-world/package.json
     why: 'the shared e2e library of every back end (R47, R48), a devDependency of every back end: the warm stack behind toxiproxy, the network-edge fakes, the Nest boot, the typed useTestWorld handle, useSandbox for contract specs and the outage lock. Kafka is real own infra (the one digest-pinned apache/kafka KRaft image, a broker listener and proxy per slot, slot-prefixed topics, consumer groups and client ids) and Postgres is schema-per-context (a schema and a login role per context in a shared database). Each worker has its own data slot (<ns>_w<k>) with its own databases, Keycloak realm, leased Redis DB, bucket/collection/topic prefixes, fakes host, toxiproxy proxies and outage lock; a run provisions min(jest workers, workers cap, default 2) slots, and state file protocol 2 pairs exactly with @starci/jest-preset (TEST_WORLD_PAIR_MISMATCH otherwise). A modules world boots real peer apps beside its modules, world.apps.<name>.during(fn) is the outage of a peer app, w.keycloak.clientSecret(client) answers the run-generated secret of a confidential realm client, world.keycloak.events/sessions read the realm user events and live sessions, world.infra.postgresql.connection(name) takes one database connection down while the others serve, and world.resolve and scope.resolve take any Nest token. Every path a declaration names (`stack`, seeds, the realm, Dockerfiles) resolves from the app root (the directory of hfs.json); the globalSetup registers the path aliases as TypeScript resolves them. Its CLI main is exported at ./cli for starci app stack.'
   '@starci/cli':
-    version: 1.7.21
+    version: 1.7.22
     group: starci
     install: registry
     side: both
     source: packages/cli/package.json
     why: 'the only StarCi command package; product repositories install it for starci app, while @starci/hfs remains its pinned transitive implementation.'
   '@starci/hfs':
-    version: 4.7.21
+    version: 4.7.22
     group: starci
     install: registry
     side: both

package/runtime/modules/schemas/provision-operation.schema.yaml

@@ -0,0 +1,165 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+$id: urn:starci:provision-operation:1
+title: Target-bound provider operations
+description: Public target and custody references for executable provider adapters; values never enter this declaration.
+type: object
+additionalProperties: false
+required: [targets]
+properties:
+  targets:
+    type: object
+    minProperties: 1
+    additionalProperties: {$ref: '#/$defs/target'}
+$defs:
+  goalGrants:
+    type: object
+    additionalProperties: false
+    required: [schema, grants]
+    properties:
+      schema: {const: 'starci/provision-grants@1'}
+      grants:
+        type: array
+        items:
+          type: object
+          additionalProperties: false
+          required: [op, operation, digest]
+          properties:
+            op: {type: string, pattern: '^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+$'}
+            operation: {type: string, pattern: '^[a-zA-Z0-9][a-zA-Z0-9-]{0,127}$'}
+            digest: {type: string, pattern: '^[a-f0-9]{64}$'}
+  credential:
+    oneOf:
+      - {$ref: '#/$defs/serviceCredential'}
+      - {$ref: '#/$defs/hostCredential'}
+  serviceCredential:
+    $ref: application-stacks.schema.yaml#/$defs/serviceCredential
+  hostCredential:
+    description: >-
+      A fixed host bridge for the admin role, never a value. sonar-selfhost-admin is the native self-hosted Sonar administrator;
+      sonar-runtime-secret-env is the variable `env` of the runtime's untracked secret.env (the reader `starci gate sonar up` uses),
+      for a SonarCloud target only.
+    oneOf:
+      - type: object
+        additionalProperties: false
+        required: [id, hostConnection]
+        properties:
+          id: {const: admin}
+          hostConnection: {const: sonar-selfhost-admin}
+      - type: object
+        additionalProperties: false
+        required: [id, hostConnection, env]
+        properties:
+          id: {const: admin}
+          hostConnection: {const: sonar-runtime-secret-env}
+          env: {type: string, pattern: '^[A-Z][A-Z0-9_]{0,63}$'}
+          purpose: {type: string, minLength: 1}
+  target:
+    type: object
+    additionalProperties: false
+    required: [provider, context, resource, credentials]
+    oneOf:
+      - required: [origin]
+        properties:
+          provider: {enum: [supabase-cloud, supabase-auth, sonar-server, sonar-community, sonar-cloud, app, github, ghcr]}
+          endpoint: false
+      - required: [endpoint]
+        properties:
+          provider: {const: app-stack}
+          origin: false
+          endpoint: {$ref: '#/$defs/swarmEndpoint'}
+      - required: [endpoint]
+        properties:
+          provider: {const: app-db}
+          origin: false
+          endpoint: {$ref: '#/$defs/databaseEndpoint'}
+        oneOf:
+          - properties:
+              context: {const: local}
+              endpoint:
+                properties:
+                  mode: {const: local}
+          - properties:
+              endpoint:
+                properties:
+                  mode: {enum: [linked, url-env]}
+    properties:
+      provider:
+        enum: [supabase-cloud, supabase-auth, sonar-server, sonar-community, sonar-cloud, app, github, ghcr, app-stack, app-db]
+      context:
+        enum: [local, development, staging, production]
+      origin:
+        type: string
+        pattern: '^https?://[^\s]+$'
+        description: Auth-free origin; the resolver permits HTTP only for an explicitly local loopback target.
+      endpoint:
+        type: object
+        description: Closed native endpoint selected by app-stack or app-db; public declaration checks precede custody and the effective private endpoint is compared before network access.
+      resource:
+        type: object
+        description: Adapter-owned public configuration; each adapter refuses fields outside its action contract.
+      credentials:
+        type: array
+        items: {$ref: '#/$defs/credential'}
+        description: Named roles using the existing service credential contract; ids become the execution role map.
+      optionalCredentials:
+        type: array
+        uniqueItems: true
+        items: {type: string, pattern: '^[a-z][a-z0-9-]*$'}
+        description: Declared roles whose absence may be inspected without substituting another credential.
+      destination:
+        $ref: '#/$defs/credential'
+      actions:
+        type: array
+        minItems: 1
+        uniqueItems: true
+        items: {type: string, pattern: '^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+$'}
+        description: Exact action ids allowed for this target; the catalog and execution owner enforce the selected action.
+  swarmEndpoint:
+    type: object
+    additionalProperties: false
+    required: [kind, environment, stack, host, user, port]
+    properties:
+      kind: {const: docker-swarm}
+      environment: {type: string, pattern: '^[a-z][a-z0-9-]*$'}
+      stack: {type: string, pattern: '^[a-z][a-z0-9-]*$'}
+      host: {type: string, pattern: '^[a-zA-Z0-9][a-zA-Z0-9.-]*$'}
+      user: {type: string, pattern: '^[a-zA-Z0-9_][a-zA-Z0-9_.-]*$'}
+      port: {const: 22}
+  databaseEndpoint:
+    type: object
+    additionalProperties: false
+    required: [kind, mode, environment]
+    oneOf:
+      - required: [localProject, port]
+        properties:
+          mode: {const: local}
+          projectRef: false
+          urlEnv: false
+          host: false
+          database: false
+          user: false
+      - required: [projectRef]
+        properties:
+          mode: {const: linked}
+          localProject: false
+          port: false
+          urlEnv: false
+          host: false
+          database: false
+          user: false
+      - required: [urlEnv, host, port, database, user]
+        properties:
+          mode: {const: url-env}
+          localProject: false
+          projectRef: false
+    properties:
+      kind: {const: supabase-db}
+      mode: {enum: [local, linked, url-env]}
+      environment: {type: string, pattern: '^[a-z][a-z0-9-]*$'}
+      localProject: {type: string, pattern: '^[a-zA-Z0-9_][a-zA-Z0-9_.-]*$'}
+      projectRef: {type: string, pattern: '^[a-z0-9]{20}$'}
+      urlEnv: {type: string, pattern: '^[A-Z][A-Z0-9_]*$'}
+      host: {type: string, pattern: '^[a-zA-Z0-9][a-zA-Z0-9.-]*$'}
+      port: {type: integer, minimum: 1, maximum: 65535}
+      database: {type: string, pattern: '^[a-zA-Z0-9_][a-zA-Z0-9_.-]*$'}
+      user: {type: string, pattern: '^[a-zA-Z0-9_][a-zA-Z0-9_.-]*$'}

package/runtime/scripts/lib/provision-operation-schema.mjs

@@ -1,17 +1,17 @@
 // The schema of a stack declaration's `operations` block, composed once for its two readers: the provision target owner and the
 // stacks gate. provision-operation.schema.yaml refers to the service credential of application-stacks.schema.yaml; the composition
 // inlines that definition so the self-contained walker of json-schema.mjs resolves every reference.
+// Both schemas are read through `new URL(<literal>, import.meta.url)`: that is the form sync-runtime follows, so the copy
+// bundled in @starci/hfs carries them beside this module (a skillRoot join left provision-operation.schema.yaml out of it).
 import fs from 'node:fs';
-import path from 'node:path';
 import { parseYaml } from '../../engine/yaml.mjs';
-import { skillRoot } from '../../engine/runtime-root.mjs';
 
 /** The `$ref` application-stacks.schema.yaml uses for its `operations` block. */
 export const PROVISION_OPERATION_SCHEMA_REF = 'provision-operation.schema.yaml';
 
 /** The composed `operations` schema, read from this runtime's modules/schemas. */
 export function provisionOperationSchema() {
-  const schema = parseYaml(fs.readFileSync(path.join(skillRoot, 'modules/schemas', PROVISION_OPERATION_SCHEMA_REF), 'utf8'));
-  const stacks = parseYaml(fs.readFileSync(path.join(skillRoot, 'modules/schemas/application-stacks.schema.yaml'), 'utf8'));
+  const schema = parseYaml(fs.readFileSync(new URL('../../modules/schemas/provision-operation.schema.yaml', import.meta.url), 'utf8'));
+  const stacks = parseYaml(fs.readFileSync(new URL('../../modules/schemas/application-stacks.schema.yaml', import.meta.url), 'utf8'));
   return { ...schema, $defs: { ...schema.$defs, serviceCredential: stacks.$defs.serviceCredential } };
 }