@starci/hfs 4.7.34 → 4.7.35

package/stack/config.mjs

@@ -9,7 +9,8 @@ import { refusal } from './errors.mjs';
 export const STACKS_DIR = '.starcistacks';
 export const STACKS_FILE = 'application-stacks.yaml';
 
-const readYaml = (file, what) => {
+/** Read a YAML input, refusing with a stack error naming its purpose when it is missing or invalid. */
+export const readYaml = (file, what) => {
   let source;
   try { source = fs.readFileSync(file, 'utf8'); } catch { throw refusal('STACKS_DEPLOY_FILE_MISSING', `${what} (${file}) is not readable`); }
   try { return parseYaml(source); } catch { throw refusal('STACKS_DEPLOY_FILE_INVALID', `${what} is not valid YAML`); }

package/stack/render.mjs

@@ -1,10 +1,12 @@
 // render.mjs - renders a release: the committed stack source plus a generated override (image references, plain environment, the
 // `<KEY>_FILE` pointers and the versioned secret grants) resolved by `docker stack config`. Writes `stack.generated.yaml`, `stack.yaml`
 // and `release.json` under the output directory, and nothing at all when a guard refuses. Output carries names and counts only; the
-// docker child gets a minimal environment, never the age identity or DOCKER_HOST.
+// docker child gets a minimal environment, never the age identity or DOCKER_HOST. The override mirrors the source's compose version:
+// Docker's legacy stack loader refuses mixed versions across its input files.
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { readYaml } from './config.mjs';
 import { tool } from './context.mjs';
 import { hasPlaceholderDigest, isImageReference, isReleaseId } from './digest.mjs';
 import { failure, refusal } from './errors.mjs';
@@ -35,6 +37,22 @@ function checkInputs(config, options) {
   if (options.previous !== null && options.previous !== undefined && !isReleaseId(options.previous)) throw refusal('STACK_PREVIOUS_INVALID', 'previous must be 16 lowercase hex characters');
 }
 
+/** Docker reads an absent, empty or 3 version as its current 3.x default; every other version must match exactly. */
+const versionKey = (version) => {
+  const text = version === undefined ? '' : String(version);
+  return text === '' || text === '3' ? null : text;
+};
+
+function checkComposeVersions(sourceVersion, extraCompose) {
+  for (const file of extraCompose) {
+    const version = readYaml(file, `the extra compose file ${path.basename(file)}`)?.version;
+    if (versionKey(version) !== versionKey(sourceVersion)) {
+      throw refusal('STACK_COMPOSE_VERSION_MISMATCH',
+        `${path.basename(file)} declares compose version ${version ?? '(none)'} but the stack source declares ${sourceVersion ?? '(none)'}; docker stack config refuses files whose versions differ`);
+    }
+  }
+}
+
 /** Compose interpolation treats `$` specially; the override doubles it so a value reaches the service unchanged. */
 const escapeDollar = (value) => value.replaceAll('$', '$$$$');
 
@@ -70,9 +88,10 @@ function serviceOverride(config, sealed, images, service) {
   return out;
 }
 
-function buildOverride(config, sealed, images) {
+function buildOverride(config, sealed, images, version) {
   const services = new Set([...Object.keys(config.images), ...Object.keys(config.environment), ...Object.keys(sealed.grants)]);
   return {
+    ...(version === undefined ? {} : { version }),
     services: Object.fromEntries([...services].sort((a, b) => a.localeCompare(b)).map((service) => [service, serviceOverride(config, sealed, images, service)])),
     secrets: Object.fromEntries(Object.entries(sealed.secrets).map(([key, entry]) => [key, { external: true, name: entry.runtimeName }])),
   };
@@ -124,9 +143,11 @@ function writeOutput(out, override, stackBytes, release) {
 /** Renders a release into `options.out` (a fresh temp directory when null). Effects stay local; nothing leaves the machine. */
 export async function renderRelease(ctx, config, options) {
   checkInputs(config, options);
+  const sourceVersion = readYaml(config.stackFile, 'the stack source')?.version;
+  checkComposeVersions(sourceVersion, options.extraCompose ?? []);
   const sealed = loadSealed(ctx, config);
   const configs = configObjects(config);
-  const override = buildOverride(config, sealed, options.images);
+  const override = buildOverride(config, sealed, options.images, sourceVersion);
   const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'stack-override-'));
   try {
     const overrideFile = path.join(scratch, 'stack.generated.yaml');

package/sync/index.mjs

@@ -35,6 +35,7 @@ import { isRuntimeExampleApp } from '../runtime/scripts/lib/runtime-example.mjs'
 import { ciWorkflowCommands } from './ci-commands.mjs';
 import { dependabotUpdates, hasDeclaredServices, readDeclaredQuality, readDeclaredBadges, sonarHostLine } from './quality-services.mjs';
 import { qualityServices } from '../runtime/scripts/hfs/ci-declaration.mjs';
+import { grammarLintFor } from '../runtime/scripts/lib/grammar-lint.mjs';
 
 export const TEMPLATES_DIR = path.join(import.meta.dirname, '..', 'templates');
 const NODE_MAJOR = 22;
@@ -133,11 +134,13 @@ function readBundled(name) {
 
 /**
  * Fill `{{name}}` from vars and expand `{{> partial}}` lines. A partial line may be written as a line comment (`// {{> partial}}`)
- * so a JavaScript template stays valid source before rendering. Empty variable-only lines disappear; an unknown name is an error.
+ * so a JavaScript template stays valid source before rendering. Variable-only lines may also use a line comment;
+ * empty variable-only lines disappear and an unknown name is an error.
  */
 export function render(text, vars, readTemplate = readBundled) {
   const withPartials = text.replace(/^(?:\/\/ )?\{\{> ([\w./-]+)\}\}\n/gm, (_, name) => trailingNewline(render(readTemplate(name), vars, readTemplate)));
-  const presentLines = withPartials.replace(/^[ \t]*\{\{([A-Za-z]\w*)\}\}[ \t]*(?:\n|$)/gm, (line, key) => vars[key] === '' ? '' : line);
+  const presentLines = withPartials.replace(/^[ \t]*(?:\/\/ )?\{\{([A-Za-z]\w*)\}\}[ \t]*(?:\n|$)/gm,
+    (line, key) => vars[key] === '' ? '' : line.replace(/^(\s*)\/\/ /, '$1'));
   return presentLines.replace(/\{\{([A-Za-z]\w*)\}\}/g, (_, key) => {
     if (!Object.hasOwn(vars, key)) throw new SyncError('HFS_SYNC_TEMPLATE_VARIABLE', `template names {{${key}}}, which sync does not provide`);
     return vars[key];
@@ -341,6 +344,7 @@ export function variables(app, scope, presets, sonarKey, manifest = loadSlotMani
   const lite = app.edition === 'lite';
   const providers = (app.sides.be.connections ?? []).map(connection => connection.provider);
   const quality = source.quality ?? qualityServices({});
+  const grammarLint = scope === 'fe' ? grammarLintFor(fe.grammar) : null;
   return {
     header: HEADER(scope),
     readmeBadges: source.badges ?? '',
@@ -375,6 +379,8 @@ export function variables(app, scope, presets, sonarKey, manifest = loadSlotMani
     dependabotUpdates: dependabotUpdates(quality.dependabot),
     tsconfigPaths: ['be/tsconfig.json', ...fe.apps.map(entry => `fe/apps/${entry.name}/tsconfig.json`), ...(packages ? ['fe/packages/*/tsconfig.json'] : [])].join(','),
     styleGlob: STYLE_GLOB,
+    grammarLintImport: grammarLint?.package ? `import { ${grammarLint.factory} } from "${grammarLint.package}"` : '',
+    grammarLintExport: grammarLint?.package ? `export default [...starciFeConfig({ hfs }), ...${grammarLint.factory}({ hfs })]` : 'export default starciFeConfig({ hfs })',
     imageMatrix: imageMatrix(app, source),
     imageProject: app.project,
     ...stackWorkflowVariables(stack, app.project, name => stackDockerfile(app, name)),

package/templates/app/skeleton/.starcistacks/dev/infra/compose/stack.yaml

@@ -1,5 +1,4 @@
 # Rendered development model. App images and owner infrastructure must be provisioned before use.
-version: "3.8"
 services:
   core:
     image: "{{project}}/core:v0.0.0"

package/templates/app/skeleton/.starcistacks/production/infra/swarm/stack.yaml

@@ -1,5 +1,4 @@
 # Rendered production model. All-zero app digests are illustrative; publish verified images before use.
-version: "3.8"
 services:
   core:
     image: "{{project}}/core:v0.0.0@sha256:0000000000000000000000000000000000000000000000000000000000000000"

package/templates/app/skeleton-lite/.starcistacks/dev/infra/swarm/stack.yaml

@@ -1,5 +1,4 @@
 # Illustrative development model. Replace all-zero application digests with verified published release digests before use.
-version: "3.8"
 services:
   api:
     image: "{{project}}/api:v0.0.0@sha256:0000000000000000000000000000000000000000000000000000000000000000"

package/templates/app/skeleton-lite/.starcistacks/production/infra/swarm/stack.yaml

@@ -1,5 +1,4 @@
 # Illustrative production model. Replace all-zero application digests with verified published release digests before use.
-version: "3.8"
 services:
   api:
     image: "{{project}}/api:v0.0.0@sha256:0000000000000000000000000000000000000000000000000000000000000000"

package/templates/fe/tool-config/eslint.config.mjs

@@ -1,3 +1,6 @@
 import { loadHfs, starciFeConfig } from "@starci/eslint-canon-fe"
+// {{grammarLintImport}}
 
-export default starciFeConfig({ hfs: loadHfs(import.meta.url) })
+const hfs = loadHfs(import.meta.url)
+
+// {{grammarLintExport}}