@starci/hfs 4.2.17 → 4.4.0

package/runtime/scripts/hfs/rules/stack-tooling.mjs

@@ -0,0 +1,93 @@
+// stack-tooling.mjs - R293: an app does not re-implement the Swarm deploy tooling the canon ships as `starci app stack <verb>`.
+// Deploy sources (tracked files under deploy/ and scripts/, the scripts of package.json, workflows other than the canon's managed
+// stack-deploy.yml) must not call a docker command a verb owns, and deploy/ holds no file named after a verb. A finding names the
+// replacing verb and the file, never a snippet of the source.
+import { found, readText } from './read.mjs';
+
+export const STACK_TOOLING_REIMPLEMENTED = 'STACK_TOOLING_REIMPLEMENTED';
+
+const MANAGED_WORKFLOW = /(?:^|\/)\.github\/workflows\/stack-deploy\.ya?ml$/;
+const WORKFLOW = /(?:^|\/)\.github\/workflows\/[^/]+\.ya?ml$/;
+const DEPLOY_DIR = /(?:^|\/)deploy\//;
+const SCRIPTS_DIR = /(?:^|\/)scripts\//;
+const PACKAGE_JSON = /(?:^|\/)package\.json$/;
+const SOURCE_FILE = /(?:^|\/)[^/.]+$|\.(?:sh|bash|zsh|mjs|cjs|js|ts|mts|py|ya?ml)$/;
+const TEST_FILE = /\.(?:spec|test)\.[cm]?[jt]s$/;
+const CREDENTIAL_FILE = /(?:^|\/)(?:secrets?\.env(?:\.[^/]*)?|\.env(?:\.[^/]*)?|secrets\/)|\.enc$/i;
+const VERB_FILE = /^(render|provision|converge|verify|prune|rollback|release|backup|prepare|doctor|jobs|public)\.(?:mjs|js|cjs|sh)$/;
+const COMMENT_LINE = /^[ \t]*(?:#|\/\/).*$/gm;
+const LINE_CONTINUATION = /\\\r?\n\s*/g;
+const VERB_COMMAND = /\bapp\s+stack\b[^\n;&|]*/g;
+const DOCKER_OPTIONS = String.raw`(?:\s+(?:--(?:context|host)(?:\s+|=)\S+|-H\s+\S+))*`;
+const SHELL_CALL = new RegExp(String.raw`\bdocker${DOCKER_OPTIONS}\s+(stack|secret|config|service|swarm|volume|node)\s+([a-z]+)\b`, 'g');
+const ARGV_CALL = /['"]docker['"]\s*,\s*\[\s*['"](stack|secret|config|service|swarm|volume|node)['"]\s*,\s*['"]([a-z]+)['"]/g;
+
+/** `docker <noun> <action>` pairs the canon owns, mapped to the verb that replaces them. */
+const OWNED = new Map([
+  ['stack deploy', 'deploy'], ['stack config', 'render'],
+  ['secret create', 'deploy'], ['secret rm', 'prune'], ['config create', 'deploy'], ['config rm', 'prune'],
+  ['service ls', 'converge'], ['service ps', 'converge'], ['service inspect', 'verify'], ['service update', 'rollback'],
+  ['swarm init', 'prepare'], ['volume create', 'prepare'], ['node ls', 'doctor'],
+]);
+
+/** Comments run nothing; a `starci app stack ...` command line is the canon call itself and is never judged. */
+function executableText(text) {
+  return text.replaceAll(COMMENT_LINE, '').replaceAll(LINE_CONTINUATION, ' ').replaceAll(VERB_COMMAND, ' ');
+}
+
+function ownedVerbs(text) {
+  const verbs = new Set();
+  for (const pattern of [SHELL_CALL, ARGV_CALL]) {
+    for (const [, noun, action] of text.matchAll(pattern)) {
+      const verb = OWNED.get(`${noun} ${action}`);
+      if (verb) verbs.add(verb);
+    }
+  }
+  return verbs;
+}
+
+function packageScripts(text) {
+  try {
+    return Object.values(JSON.parse(text)?.scripts ?? {}).filter((command) => typeof command === 'string').join('\n');
+  } catch { return ''; }
+}
+
+function sourceText(file, raw) {
+  return executableText(PACKAGE_JSON.test(file) ? packageScripts(raw) : raw);
+}
+
+function deploySource(file) {
+  if (MANAGED_WORKFLOW.test(file) || CREDENTIAL_FILE.test(file) || TEST_FILE.test(file)) return false;
+  if (PACKAGE_JSON.test(file) || WORKFLOW.test(file)) return true;
+  return (DEPLOY_DIR.test(file) || SCRIPTS_DIR.test(file)) && SOURCE_FILE.test(file);
+}
+
+const replacement = (file, verb) => found(
+  STACK_TOOLING_REIMPLEMENTED,
+  file,
+  `${file} re-implements deploy tooling the canon ships; call \`starci app stack ${verb}\` instead`,
+  { verb },
+);
+
+function fileFindings(repoRoot, file) {
+  const raw = readText(repoRoot, file);
+  if (raw === null) return [];
+  return [...ownedVerbs(sourceText(file, raw))].map((verb) => replacement(file, verb));
+}
+
+function verbNamedFile(file) {
+  const verb = DEPLOY_DIR.test(file) ? VERB_FILE.exec(file.slice(file.lastIndexOf('/') + 1))?.[1] : undefined;
+  return verb ? [replacement(file, verb)] : [];
+}
+
+/** Findings are names and paths only: no source snippet leaves this finder. One finding per file and replacing verb. */
+export function stackToolingFindings({ repoRoot, files, all, repo, isRoot, inScope = () => true }) {
+  if (repo?.kind !== 'app' || !['lite', 'full'].includes(repo.edition) || isRoot === false) return [];
+  const findings = new Map();
+  for (const file of new Set(all ?? files)) {
+    if (!inScope(file)) continue;
+    const candidates = [...verbNamedFile(file), ...(deploySource(file) ? fileFindings(repoRoot, file) : [])];
+    for (const finding of candidates) findings.set(`${finding.path}\0${finding.verb}`, finding);
+  }
+  return [...findings.values()];
+}

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

@@ -0,0 +1,76 @@
+// stacks-deploy.mjs - R294: `environments.<env>.deploy` in .starcistacks/application-stacks.yaml is coherent.
+// The block is judged by the same `normalizeDeploy` the `starci app stack` verbs use (scripts/hfs/stack-deploy-config.mjs), against a
+// probe of the real tree: the files below .starcistacks/<env>/, the services of the first composeFiles entry and the sealed members.
+// One finding per problem; an environment without a deploy block is not a finding.
+import fs from 'node:fs';
+import path from 'node:path';
+import { isPlainObject as plain } from '../../../engine/plain-object.mjs';
+import { findStackDeclaration, readDeclaration, STACK_ROOT } from '../../lib/stack-declaration.mjs';
+import { normalizeDeploy } from '../stack-deploy-config.mjs';
+import { found, readJson } from './read.mjs';
+
+const DECLARATION = `${STACK_ROOT}/application-stacks.yaml`;
+const ENV_NAME = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;
+const mapping = (value) => (plain(value) ? value : {});
+
+/** Service names of the first composeFiles entry; an unreadable stack source means unknown services (empty set). */
+function stackServices(envDir, spec) {
+  const relative = Array.isArray(spec.composeFiles) ? spec.composeFiles[0] : undefined;
+  if (typeof relative !== 'string' || path.isAbsolute(relative) || relative.split(/[\\/]/).includes('..')) return new Set();
+  const { doc } = readDeclaration(path.join(envDir, relative));
+  return new Set(Object.keys(mapping(doc?.services)));
+}
+
+function sealedMembers(envDir) {
+  try {
+    return new Set(fs.readdirSync(path.join(envDir, 'secrets')).filter((name) => name.endsWith('.enc')).map((name) => name.slice(0, -4)));
+  } catch { return new Set(); }
+}
+
+function probeOf(envDir, spec) {
+  return { exists: (relative) => fs.existsSync(path.join(envDir, relative)), services: stackServices(envDir, spec), members: sealedMembers(envDir) };
+}
+
+/** The shell scripts below the environment directory (node_modules aside), as absolute paths. */
+function shellScripts(directory) {
+  return fs.readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+    const file = path.join(directory, entry.name);
+    if (entry.isDirectory()) return entry.name === 'node_modules' ? [] : shellScripts(file);
+    return entry.name.endsWith('.sh') ? [file] : [];
+  });
+}
+
+/** A shell script with CRLF line endings fails inside the container (`set: Illegal option -`): one finding per such file. */
+function lineEndingFindings({ repoRoot, envDir, environment }) {
+  if (!fs.existsSync(envDir)) return [];
+  const crlf = String.fromCodePoint(13, 10);
+  return shellScripts(envDir).filter((file) => fs.readFileSync(file, 'utf8').includes(crlf)).map((file) => found(
+    'STACKS_DEPLOY_CONFIG_INVALID',
+    path.relative(repoRoot, file).split(path.sep).join('/'),
+    `environments.${environment}: this shell script has CRLF line endings and fails in the container; commit it with LF (.gitattributes: *.sh text eol=lf) and save it again`,
+  ));
+}
+
+function environmentFindings({ repoRoot, project, environment, spec }) {
+  const envDir = path.join(repoRoot, STACK_ROOT, environment);
+  const { problems } = normalizeDeploy(spec.deploy, { project, probe: probeOf(envDir, spec) });
+  return [...problems.map((problem) => found(
+    'STACKS_DEPLOY_CONFIG_INVALID',
+    DECLARATION,
+    `environments.${environment}.${problem.at}: ${problem.message}`,
+  )), ...lineEndingFindings({ repoRoot, envDir, environment })];
+}
+
+/** Only docker-swarm environments that declare a deploy block are judged. */
+function judged([environment, spec]) {
+  return ENV_NAME.test(environment) && plain(spec) && spec.runtime === 'docker-swarm' && spec.deploy !== undefined;
+}
+
+/** Findings of every declared deploy block of the app root, in both editions. */
+export function stacksDeployFindings({ repoRoot, repo, isRoot }) {
+  if (repo?.kind !== 'app' || !['lite', 'full'].includes(repo.edition) || isRoot === false) return [];
+  const { doc } = findStackDeclaration(repoRoot);
+  const project = String(readJson(repoRoot, 'hfs.json')?.project ?? 'app');
+  return Object.entries(mapping(mapping(doc).environments)).filter(judged)
+    .flatMap(([environment, spec]) => environmentFindings({ repoRoot, project, environment, spec }));
+}

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

@@ -0,0 +1,87 @@
+// R275 and R266: each Swarm environment has one declared, digest-pinned ingress, or declares that the ingress is an external shared stack
+// (`ingress.external: { stack }` with `hosts`): then the stack renders no ingress of its own and publishes no port.
+import { isPlainObject as plain } from '../../../engine/plain-object.mjs';
+import { repositoryOf } from '../../lib/stack-services.mjs';
+import { stacksDeploymentFindings } from './stacks-runtime.mjs';
+
+const PINNED = /@sha256:[a-f0-9]{64}$/i;
+const SUPPORTED = new Set(['traefik', 'caddy', 'caddy-docker-proxy']);
+const mapping = value => plain(value) ? value : {};
+const present = value => typeof value === 'string' && Boolean(value.trim());
+const imageName = image => present(image) ? repositoryOf(image).toLowerCase() : '';
+const ingressImage = image => SUPPORTED.has(imageName(image));
+
+function ingressIds(components, bindings, services, chosen) {
+  const ids = new Set();
+  if (present(chosen)) ids.add(chosen);
+  for (const id of Object.keys(bindings)) {
+    const component = mapping(components[id]);
+    if (component.role === 'ingress' || ingressImage(component.image)) ids.add(id);
+  }
+  for (const [id, entry] of Object.entries(services)) {
+    const service = mapping(entry), component = mapping(components[id]);
+    if (component.role === 'ingress' || ingressImage(service.image)) ids.add(id);
+  }
+  return [...ids];
+}
+
+/** The name of the shared external ingress stack the environment declares, or null. */
+export const externalIngressStack = spec => present(spec?.ingress?.external?.stack) ? spec.ingress.external.stack : null;
+
+function externalIssues({ spec, candidates, at }) {
+  const ingress = mapping(spec.ingress), errors = [];
+  if (externalIngressStack(spec) === null || present(ingress.component) || !Array.isArray(ingress.hosts) || ingress.hosts.length === 0)
+    errors.push({ code: 'STACKS_INGRESS_UNDECLARED', at,
+      message: 'an external ingress is declared as ingress.external.stack with ingress.hosts and without ingress.component' });
+  if (candidates.length > 0)
+    errors.push({ code: 'STACKS_SECOND_INGRESS', at,
+      message: 'a stack that declares an external shared ingress must not render an ingress of its own' });
+  return errors;
+}
+
+function declarationIssues({ chosen, components, bindings, services, candidates, at }) {
+  const errors = [];
+  if (!present(chosen) || components[chosen]?.role !== 'ingress' || !Object.hasOwn(bindings, chosen) || !Object.hasOwn(services, chosen))
+    errors.push({ code: 'STACKS_INGRESS_UNDECLARED', at,
+      message: 'Swarm ingress must name one component with role ingress that is inventoried, bound and present in the rendered model' });
+  const undeclared = candidates.filter(id => id !== chosen);
+  if (undeclared.length)
+    errors.push({ code: 'STACKS_INGRESS_UNDECLARED', at,
+      message: 'every rendered ingress must be the environment\'s declared ingress component' });
+  if (candidates.length > 1)
+    errors.push({ code: 'STACKS_SECOND_INGRESS', at,
+      message: 'a Swarm environment must run exactly one ingress component; a second ingress is forbidden' });
+  return errors;
+}
+
+function ingressImageIssues(ids, components, services) {
+  const errors = [];
+  for (const id of ids) {
+    for (const [prefix, source] of [['components', components], ['services', services]]) {
+      if (!Object.hasOwn(source, id)) continue;
+      const image = source[id]?.image;
+      if (!SUPPORTED.has(imageName(image)) || !PINNED.test(String(image)))
+        errors.push({ code: 'STACKS_INGRESS_UNKNOWN', at: `${prefix}.${id}.image`,
+          message: 'the declared ingress must use Traefik or Caddy pinned by a sha256 digest' });
+    }
+  }
+  return errors;
+}
+
+/** Static ingress contract shared by HFS and the rendered stacks gate. */
+export function ingressIssues({ doc, environment, spec = doc?.environments?.[environment], model }) {
+  if (spec?.runtime !== 'docker-swarm') return [];
+  const components = mapping(doc?.components), bindings = mapping(spec.components), services = mapping(model?.services);
+  const chosen = spec.ingress?.component, candidates = ingressIds(components, bindings, services, chosen);
+  const at = `environments.${environment}.ingress`;
+  if (mapping(spec.ingress).external !== undefined) return externalIssues({ spec, candidates, at });
+  return [
+    ...declarationIssues({ chosen, components, bindings, services, candidates, at }),
+    ...ingressImageIssues(candidates, components, services),
+  ];
+}
+
+/** HFS finder over the tracked rendered Swarm environments of either edition. */
+export function stacksIngressFindings(context) {
+  return stacksDeploymentFindings(context, ingressIssues);
+}

package/runtime/scripts/hfs/rules/stacks-lite-backing.mjs

@@ -0,0 +1,111 @@
+// R276: lite uses managed Supabase backing; sidecar SQLite persists on declared named volumes.
+import { isPlainObject as plain } from '../../../engine/plain-object.mjs';
+import { composeEntries } from '../../lib/compose-values.mjs';
+import { repositoryOf } from '../../lib/stack-services.mjs';
+import { stacksDeploymentFindings } from './stacks-runtime.mjs';
+
+const BACKING_IMAGE = /^(?:postgres(?:ql)?|postgresql-repmgr|redis(?:-stack(?:-server)?)?|mongo(?:db)?|mongodb-community-server)$/i;
+const DATABASE_ADAPTER_KEYS = new Set(['db_type', 'database_type', 'db_provider', 'database_provider', 'db_client', 'database_client', 'db_adapter', 'database_adapter']);
+const SQLITE_ADAPTERS = new Set(['sqlite', 'sqlite3', 'better-sqlite3', 'sql.js']);
+const DATABASE_URL_KEY = /DB|DATABASE|POSTGRES|REDIS|MONGO/i;
+const NON_SQLITE_URL = /^(?:postgres(?:ql)?|rediss?|mongo(?:db)?(?:\+srv)?|mysql|mariadb|mssql|sqlserver|cockroachdb):/i;
+const SQLITE_URL = /^sqlite(?:3)?:/i;
+const NAMED_VOLUME = /^[a-z0-9][a-z0-9_.-]*$/i;
+const mapping = value => plain(value) ? value : {};
+const present = value => typeof value === 'string' && Boolean(value.trim());
+
+function imageIssues(components, services) {
+  const errors = [];
+  for (const [prefix, inventory] of [['components', components], ['services', services]]) {
+    for (const [id, entry] of Object.entries(inventory)) {
+      if (present(entry?.image) && BACKING_IMAGE.test(repositoryOf(entry.image)))
+        errors.push({ code: 'STACKS_LITE_SELFHOSTED_DB', at: `${prefix}.${id}.image`,
+          message: 'lite must not run a self-hosted Postgres, Redis or Mongo database image; use managed Supabase backing' });
+    }
+  }
+  return errors;
+}
+
+function unsupportedAdapter(service) {
+  for (const [key, value] of composeEntries(service?.environment, { stringsOnly: true })) {
+    const adapterKey = DATABASE_ADAPTER_KEYS.has(key.toLowerCase());
+    if (adapterKey && !SQLITE_ADAPTERS.has(String(value).trim().toLowerCase())) return true;
+    if (DATABASE_URL_KEY.test(key) && typeof value === 'string' && NON_SQLITE_URL.test(value.trim())) return true;
+  }
+  return false;
+}
+
+function sqliteAdapter(service) {
+  return composeEntries(service?.environment, { stringsOnly: true }).some(([key, value]) => {
+    const adapter = String(value).trim().toLowerCase();
+    return DATABASE_ADAPTER_KEYS.has(key.toLowerCase()) && SQLITE_ADAPTERS.has(adapter)
+      || DATABASE_URL_KEY.test(key) && SQLITE_URL.test(adapter);
+  });
+}
+
+function renderedAdapterIssues(components, services) {
+  const errors = [];
+  for (const [id, service] of Object.entries(services)) {
+    const component = mapping(components[id]);
+    if (component.role !== 'sidecar' && component.database === undefined) continue;
+    if (!unsupportedAdapter(service)) continue;
+    errors.push({ code: 'STACKS_SIDECAR_DB_UNSUPPORTED', at: `services.${id}.environment`,
+      message: 'rendered sidecar database adapter configuration must use SQLite; Postgres, Redis and Mongo dependencies are forbidden in lite' });
+  }
+  return errors;
+}
+
+function writableVolume(entry, source) {
+  if (typeof entry === 'string') {
+    const [name, target, options = ''] = entry.split(':');
+    return name === source && present(target) && target.startsWith('/') && !options.split(',').includes('ro');
+  }
+  return plain(entry) && entry.type === 'volume' && entry.source === source && present(entry.target) && entry.target.startsWith('/') && entry.read_only !== true;
+}
+
+function sqliteVolumeIssue({ id, component, database, services, bindings, volumes }) {
+  const declared = Array.isArray(component.volumes) && component.volumes.includes(database.volume);
+  const active = Object.hasOwn(bindings, id) || Object.hasOwn(services, id);
+  const mounts = Array.isArray(services[id]?.volumes) ? services[id].volumes : [];
+  const mounted = Object.hasOwn(volumes, database.volume) && mounts.some(entry => writableVolume(entry, database.volume));
+  if (present(database.volume) && NAMED_VOLUME.test(database.volume) && declared && (!active || mounted)) return [];
+  return [{ code: 'STACKS_SIDECAR_VOLUME_UNDECLARED', at: `components.${id}.database.volume`,
+    message: 'a SQLite sidecar needs a declared persistent component volume, a top-level rendered named volume and a writable mount' }];
+}
+
+function sidecarIssues({ components, services, bindings, volumes }) {
+  const errors = [];
+  for (const [id, entry] of Object.entries(components)) {
+    const component = mapping(entry);
+    if (component.database === undefined) {
+      if (component.role === 'sidecar' && sqliteAdapter(services[id]))
+        errors.push(...sqliteVolumeIssue({ id, component, database: {}, services, bindings, volumes }));
+      continue;
+    }
+    const database = mapping(component.database);
+    if (database.provider !== 'sqlite') {
+      errors.push({ code: 'STACKS_SIDECAR_DB_UNSUPPORTED', at: `components.${id}.database.provider`,
+        message: 'a lite sidecar that needs a database must use SQLite on a declared persistent volume' });
+      continue;
+    }
+    errors.push(...sqliteVolumeIssue({ id, component, database, services, bindings, volumes }));
+  }
+  return errors;
+}
+
+/** The lite backing contract; full keeps its existing backing choices. */
+export function liteBackingIssues({ doc, environment, spec = doc?.environments?.[environment], model, repo, edition = repo?.edition }) {
+  if (edition !== 'lite' || spec?.runtime !== 'docker-swarm') return [];
+  const components = mapping(doc?.components), services = mapping(model?.services);
+  return [
+    ...imageIssues(components, services),
+    ...renderedAdapterIssues(components, services),
+    ...sidecarIssues({ components, services, bindings: mapping(spec.components), volumes: mapping(model?.volumes) }),
+  ];
+}
+
+/** HFS finder over tracked rendered models; unavailable evidence is reported by R267. */
+export function stacksLiteBackingFindings(context) {
+  if (context.repo?.edition !== 'lite') return [];
+  return stacksDeploymentFindings(context, liteBackingIssues);
+}