@starci/hfs 4.11.17 → 4.11.19

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 4.11.19 - 2026-10-30
+
+- Fixed: `HFS_SCHEDULE_UNDECLARED` (R268) reads an application SQL template whose `${}` sits where Postgres wants an identifier (`LISTEN ${channel}`, `SET x = ${n}`): the template is read with each `${}` as NULL, and when that does not parse, again with each as an identifier (`stacks-release.mjs` `templateObservations`). Such a statement was taken for an undeclared pg_cron job. A bare interpolated function name (`FROM ${fn}(...)`) still fails closed, since it may be `cron.schedule`; the skeleton's `callDbFunction` quotes `"${schema}"."${name}"` and parses as it is.
+- Fixed: SQL named in a same-file `const` before its `query`/`execute` call is judged as if inline (`sqlConstants`); moving the text out of the call no longer hid it from the scanner. Specs: `src/hfs-stacks-release.spec.mjs`.
+
+## 4.11.18 - 2026-10-30
+
+- Fixed: `HFS_STACKS_SHAPE` (R10) accepts the sealed member `app secret set` writes, `<env>/secrets/<slug>.enc.yaml` (ruling app-secrets-one-standard, `scripts/lib/sealed-member.mjs`), beside the legacy `<slug>.enc`. The `.starcistacks` slot (`knowledge/hfs/slots.yaml`, both editions) allowed only `<slug>.enc`, so every standard member was refused; the messages and `goesTo` name `.enc.yaml`. Spec: `src/hfs-stacks-shape.spec.mjs` holds one of each.
+- Fixed: `application-stacks.schema.yaml` declares `deploy.remote.serverRecipient` (a public `age1…` recipient), which `app secret server-key <env> --execute` records and the deploy config parser reads, and takes `deploy.secrets.settings` as one `{ member, keys }` or a non-empty list of them, as `stack-deploy-config.mjs` does. Spec: `src/hfs-stacks-deploy-schema.spec.mjs`.
+
 ## 4.11.17 - 2026-10-30
 
 - Fixed: `stemOfEvent` (the event class file name of R151) maps underscores to dashes as well as dots, matching eslint-canon-be's `event-consumer-shape` and the kebab case of `source-suffix`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/hfs",
-  "version": "4.11.17",
+  "version": "4.11.19",
   "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

@@ -31,35 +31,35 @@ pins:
     source: packages/event-stream/package.json
     why: 'the one server-sent-events client of every front end (fe-stack event-stream, owner:event-stream-package): the transport client layer (modules/api/sse/clients) creates one instance for the app with the bearer token source and the stream operations follow on it; it carries Last-Event-ID resume, the capped doubling backoff, the heartbeat timeout, the single 401 renewal and the useSWRSubscription adapter, so no app keeps a hand-written reader.'
   '@starci/grammar':
-    version: 0.15.29
+    version: 0.15.31
     group: starci
     install: registry
     side: fe
     source: packages/grammar/package.json
     why: 'the grammar front ends read: the brand layer sets `--font-sans` and `--font-mono` and the grammar reads them; it carries the Input tel kind, the copyable and read-only Input, the IconButton disclosure props and count badge, ChatBubble, FillViewport, Textarea mentions and Enter-to-send, the leading PrimaryRailLayout rail, the plate-less Image, ListRow, the soft Alert, Progress steps, the floating primary IconButton, FlowGraph, the STATE-8 loading views and the bordered selectable TagGroup chips. The runtime source version wins for a @starci package.'
   '@starci/eslint-canon-be':
-    version: 3.8.16
+    version: 3.8.18
     group: starci
     install: registry
     side: be
     source: packages/eslint-canon-be/package.json
     why: 'the back-end ESLint canon: `loadHfs(import.meta.url)` of be/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the be side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; `starciBeConfig({ hfs: loadHfs(import.meta.url) })` is the typed factory and the BE-CONVENTION laws are its rules.'
   '@starci/eslint-canon-fe':
-    version: 9.5.18
+    version: 9.5.20
     group: starci
     install: registry
     side: fe
     source: packages/eslint-canon-fe/package.json
     why: 'the front-end ESLint canon: `loadHfs(import.meta.url)` of fe/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the fe side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; the front end has no tests (FE_NO_TESTS R97 in hfs) and no-vietnamese-in-source (R91) applies.'
   '@starci/eslint-grammar-core':
-    version: 0.15.29
+    version: 0.15.31
     group: starci
     install: registry
     side: fe
     source: packages/eslint-grammar-core/package.json
     why: 'the StarCi Grammar component API lint, versioned with @starci/grammar; front ends compose this family package with the universal FE canon.'
   '@starci/eslint-grammar-offset-pop':
-    version: 0.15.29
+    version: 0.15.31
     group: starci
     install: registry
     side: fe
@@ -106,7 +106,7 @@ pins:
     source: packages/ai-router/package.json
     why: 'the AI pool router of a back end: a NestJS module that routes OpenAI-compatible chat, stream and embeddings calls across keys, models and providers, with @starci/ai-router/testing for its specs; @starci/jest-preset compiles it as an ESM-only dependency.'
   '@starci/hfs':
-    version: 4.11.17
+    version: 4.11.19
     group: starci
     install: registry
     side: both

package/runtime/knowledge/hfs/slots.yaml

@@ -887,14 +887,14 @@ slots:
     tests: none
     requires: [application-stacks.yaml]
     allows: [application-stacks.yaml, "<env>/README.md", "<env>/environment.json", "<env>/infra/{compose,swarm,k8s,terraform}/**", "<env>/infra/metadata.json",
-             "<env>/runtime/{config,env}/**", "<env>/runtime/env/KEYS.md", "<env>/secrets/<slug>.enc", "<env>/secrets/.gitkeep", "<env>/seeds/**"]
+             "<env>/runtime/{config,env}/**", "<env>/runtime/env/KEYS.md", "<env>/secrets/<slug>.{enc.yaml,enc}", "<env>/secrets/.gitkeep", "<env>/seeds/**"]
     forbids: ["<env>/runtime/files/**", "**/*.enc outside <env>/secrets/", DESIGN.md, deployment.json, "k8s/ at root"]
     # Owner ruling 2026-10-14: lite declares docker-swarm production, app runtime config, sealed custody and seed data.
     # The db service supplies the database; schedules are platform/jobs ticks (R335); production has no Compose or host cron.
     lite:
       requires: [application-stacks.yaml]
       allows: [application-stacks.yaml, images/db/Dockerfile, "<env>/README.md", "<env>/environment.json", "<env>/infra/swarm/**", "<env>/infra/metadata.json",
-               "<env>/runtime/{config,env}/**", "<env>/runtime/env/KEYS.md", "<env>/secrets/<slug>.enc", "<env>/secrets/.gitkeep", "<env>/seeds/**"]
+               "<env>/runtime/{config,env}/**", "<env>/runtime/env/KEYS.md", "<env>/secrets/<slug>.{enc.yaml,enc}", "<env>/secrets/.gitkeep", "<env>/seeds/**"]
       forbids: ["<env>/runtime/files/**", "**/*.enc outside <env>/secrets/", DESIGN.md, deployment.json, "k8s/ at root"]
     rules: [HFS_STACKS_SHAPE, HFS_STACKS_IN_SIDE, HFS_PLAINTEXT_SECRET, HFS_IDENTITY_CUSTODY]
   - id: app.sops
@@ -950,7 +950,7 @@ slots:
     tracked: external
     tier: none
     tests: none
-    goesTo: ".starcistacks/<env>/secrets/<slug>.enc (at the app root); decrypted values only in memory or under %LOCALAPPDATA%/StarCi/secrets/<project>/<env>/ via *_FILE"
+    goesTo: ".starcistacks/<env>/secrets/<slug>.enc.yaml (at the app root); decrypted values only in memory or under %LOCALAPPDATA%/StarCi/secrets/<project>/<env>/ via *_FILE"
     rules: [HFS_PLAINTEXT_SECRET]
 
   # ----- app root: the database of a lite app (ruling:lite-self-hosted-postgres-passport-minio): a self-hosted PostgreSQL in the app's
@@ -1248,7 +1248,7 @@ slots:
     tracked: external
     tier: none
     tests: none
-    goesTo: ".starcistacks/<env>/secrets/<slug>.enc (at the app root); decrypted values only in memory or under %LOCALAPPDATA%/StarCi/secrets/<project>/<env>/ via *_FILE"
+    goesTo: ".starcistacks/<env>/secrets/<slug>.enc.yaml (at the app root); decrypted values only in memory or under %LOCALAPPDATA%/StarCi/secrets/<project>/<env>/ via *_FILE"
     rules: [HFS_PLAINTEXT_SECRET]
   - id: be.root-e2e
     since: 3.1.0

package/runtime/modules/schemas/application-stacks.schema.yaml

@@ -658,6 +658,10 @@ $defs:
           ops: {$ref: '#/$defs/deployName'}
           sshKey: {$ref: '#/$defs/deployName'}
           knownHosts: {$ref: '#/$defs/deployName'}
+      serverRecipient:
+        description: The deploy server's public age recipient, recorded by starci app secret server-key <env> --execute.
+        type: string
+        pattern: '^age1[a-z0-9]+$'
   deployImage:
     type: object
     additionalProperties: false
@@ -682,7 +686,11 @@ $defs:
         description: Which sealed keys become which Swarm secrets, granted to which services.
         type: array
         items: {$ref: '#/$defs/deployGrant'}
-      settings: {$ref: '#/$defs/deployMemberKeys'}
+      settings:
+        description: One sealed member and its keys, or a list of them (one per member); a key is named by one entry only.
+        oneOf:
+          - {$ref: '#/$defs/deployMemberKeys'}
+          - {type: array, minItems: 1, items: {$ref: '#/$defs/deployMemberKeys'}}
   deployGrant:
     type: object
     additionalProperties: false

package/runtime/scripts/hfs/rules/stacks-release.mjs

@@ -269,25 +269,61 @@ function sqlObservations(text, file) {
 
 function sourceSqlObservations(source, file) {
   const observations = [];
+  const constants = sqlConstants(source);
   const visit = node => {
     if (ts.isCallExpression(node) && /(?:^|\.)(?:query|execute)$/.test(node.expression.getText())) {
       const argument = unwrap(node.arguments[0]);
-      const text = sqlTemplateText(argument);
-      if (text !== null) observations.push(...sqlObservations(text, file));
+      const text = argument && ts.isIdentifier(argument) ? constants.get(argument.text) : argument;
+      if (text) observations.push(...templateObservations(text, file));
     }
     if (ts.isTaggedTemplateExpression(node) && /(?:^|\.)sql$/.test(node.tag.getText()))
-      observations.push(...sqlObservations(sqlTemplateText(node.template), file));
+      observations.push(...templateObservations(node.template, file));
     ts.forEachChild(node, visit);
   };
   visit(source);
   return observations;
 }
 
-function sqlTemplateText(node) {
-  if (!node) return null;
-  if (ts.isStringLiteralLike(node)) return node.text;
-  if (!ts.isTemplateExpression(node)) return null;
-  return node.head.text + node.templateSpans.map(span => `NULL${span.literal.text}`).join('');
+/** The file's `const NAME = <string or template>` statements, so SQL named before its query call is judged as if inline. */
+function sqlConstants(source) {
+  const constants = new Map();
+  const visit = node => {
+    if (ts.isVariableDeclarationList(node) && (node.flags & ts.NodeFlags.Const)) {
+      for (const declaration of node.declarations) {
+        const value = unwrap(declaration.initializer);
+        if (ts.isIdentifier(declaration.name) && value && (ts.isStringLiteralLike(value) || ts.isTemplateExpression(value)))
+          constants.set(declaration.name.text, value);
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+  return constants;
+}
+
+const DYNAMIC = 'starci_dynamic_sql';
+
+/**
+ * The observations of an application SQL text. A template is read with each `${}` as NULL; when that does not parse (an
+ * interpolated identifier: `LISTEN ${channel}`, `SET x = ${n}`, `FROM ${fn}(...)`), it is read again with each `${}` as an
+ * identifier. A function whose name is interpolated bare may be pg_cron, so it stays an unknown observation; the skeleton's
+ * `callDbFunction` quotes `"${schema}"."${name}"`, which parses as it is.
+ */
+function templateObservations(node, file) {
+  if (ts.isStringLiteralLike(node)) return sqlObservations(node.text, file);
+  if (!ts.isTemplateExpression(node)) return [];
+  const spell = placeholder => node.head.text + node.templateSpans.map(span => `${placeholder}${span.literal.text}`).join('');
+  const nulls = spell('NULL');
+  if (parseSql(nulls)) return sqlObservations(nulls, file);
+  const named = spell(DYNAMIC);
+  const tree = parseSql(named);
+  if (!tree) return [{ id: null, cadence: null, at: file }];
+  let dynamicCall = false;
+  walkSql(tree, value => {
+    if (value.FuncCall && (value.FuncCall.funcname ?? []).some(part => part.String?.sval === DYNAMIC)) dynamicCall = true;
+  });
+  if (dynamicCall) return [{ id: null, cadence: null, at: file }];
+  return sqlObservations(named, file);
 }
 
 function recurringObservations({ doc, repoRoot, files, file, issues }) {

package/runtime/scripts/hfs/rules/stacks.mjs

@@ -1,7 +1,7 @@
 // stacks.mjs - HFS_STACKS_SHAPE (R10): standard stack shape, Sonar owner and deployment runtime consistency.
 //   - every tracked path under the app root's `.starcistacks/` is one the app.starcistacks slot allows (its `allows` list is the shape:
 //     application-stacks.yaml and <env>/{README.md, environment.json, infra/{compose,swarm,k8s,terraform}, runtime/{config,env},
-//     secrets/<slug>.enc, seeds}); a `.enc` outside <env>/secrets/ is never allowed, `runtime/files/`, a root `DESIGN.md`,
+//     secrets/<slug>.enc.yaml, seeds}); a `.enc` outside <env>/secrets/ is never allowed, `runtime/files/`, a root `DESIGN.md`,
 //     `deployment.json` and `k8s/` are not in the list, so they fall out of it;
 //   - the declaration (read by scripts/lib/stack-declaration.mjs, the one reader of it) states a sonar service, a local
 //     Sonar is owned by the host (`stack.owner: host`, root `.claude/ext/sonar`).
@@ -26,8 +26,8 @@ function treeFindings(files, allowed, prefix) {
   const findings = [];
   for (const file of files.filter((f) => f.startsWith(prefix))) {
     const rel = file.slice(prefix.length);
-    if (/\.enc(?:\.yaml)?$/.test(rel) && !INSIDE_SECRETS.test(rel)) findings.push(shapeFinding(file, `${file} is a sealed secret outside <env>/secrets/<slug>.enc; move it to .starcistacks/<env>/secrets/`));
-    else if (!allowed.some((expression) => expression.test(rel))) findings.push(shapeFinding(file, `${file} is not part of the standard .starcistacks shape (application-stacks.yaml, images/db/Dockerfile in lite and <env>/{README.md, environment.json, infra, runtime/{config,env}, secrets/<slug>.enc, seeds}); move or delete it`));
+    if (/\.enc(?:\.yaml)?$/.test(rel) && !INSIDE_SECRETS.test(rel)) findings.push(shapeFinding(file, `${file} is a sealed secret outside <env>/secrets/<slug>.enc.yaml; move it to .starcistacks/<env>/secrets/`));
+    else if (!allowed.some((expression) => expression.test(rel))) findings.push(shapeFinding(file, `${file} is not part of the standard .starcistacks shape (application-stacks.yaml, images/db/Dockerfile in lite and <env>/{README.md, environment.json, infra, runtime/{config,env}, secrets/<slug>.enc.yaml, seeds}); move or delete it`));
   }
   return findings;
 }