@starci/hfs 4.4.0 → 4.5.0

package/scaffold/add-fe-page.mjs

@@ -1,269 +1 @@
-import fs from "node:fs";
-import path from "node:path";
-import { loadSlotManifest, readRepoDeclaration } from "../runtime/scripts/hfs/slots.mjs";
-import { ScaffoldError, pascalOf } from "./service.mjs";
 
-const NAME = /^[a-z][a-z0-9-]*$/;
-const RESERVED = /^(?:con|prn|aux|nul|com[0-9]|lpt[0-9])$/i;
-const jsonText = (value) => `${JSON.stringify(value, null, 2)}\n`;
-const objectCatalog = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
-
-/** Validate a CLI name before it is used in a path, symbol or catalog key. */
-export function feName(value, label = "name") {
-  if (typeof value !== "string" || !NAME.test(value) || value.split("-").includes("") || RESERVED.test(value)) {
-    throw new ScaffoldError("HFS_ADD_NAME_INVALID", `${label} must be kebab-case, without a path or a reserved filename`);
-  }
-  return value;
-}
-
-/** An app-relative target whose existing ancestors are real directories, never symlinks. */
-function feTarget(root, relative) {
-  const target = path.resolve(root, relative);
-  const inside = path.relative(root, target);
-  if (!inside || inside.startsWith("..") || path.isAbsolute(inside)) {
-    throw new ScaffoldError("HFS_ADD_PATH_UNSAFE", `${relative} must stay inside the app root`);
-  }
-  let at = root;
-  const pieces = inside.split(path.sep);
-  for (let index = 0; index < pieces.length; index += 1) {
-    at = path.join(at, pieces[index]);
-    const stat = fs.lstatSync(at, { throwIfNoEntry: false });
-    if (!stat) continue;
-    if (stat.isSymbolicLink() || (index < pieces.length - 1 && !stat.isDirectory())) {
-      throw new ScaffoldError("HFS_ADD_PATH_UNSAFE", `${relative} has a symlink or a non-directory ancestor`);
-    }
-  }
-  return target;
-}
-
-/** Resolve the declared Next app; a multi-app repository must select one explicitly. */
-export function readFeContext({ root, app }) {
-  const repoRoot = path.resolve(root);
-  const stat = fs.lstatSync(repoRoot, { throwIfNoEntry: false });
-  if (!stat?.isDirectory() || stat.isSymbolicLink()) {
-    throw new ScaffoldError("HFS_ADD_NOT_AN_APP", "add page and overlay run at a real app root directory");
-  }
-  const declaration = feTarget(repoRoot, "hfs.json");
-  const packageFile = feTarget(repoRoot, "package.json");
-  if (!fs.existsSync(declaration) || !fs.existsSync(packageFile)) {
-    throw new ScaffoldError("HFS_ADD_NOT_AN_APP", "add page and overlay need hfs.json and package.json at the app root");
-  }
-  const repo = readRepoDeclaration(loadSlotManifest(), repoRoot);
-  const apps = repo.sides?.fe?.apps.filter((candidate) => candidate.kind === "next") ?? [];
-  if (!apps.length) throw new ScaffoldError("HFS_ADD_NO_FRONT_END", "this app has no declared Next front end");
-  if (app !== undefined) feName(app, "app");
-  if (app === undefined && apps.length !== 1) {
-    throw new ScaffoldError("HFS_ADD_OPTION_MISSING", "add page and overlay need --app when several Next apps are declared");
-  }
-  const selected = apps.find((candidate) => candidate.name === (app ?? apps[0].name));
-  if (!selected) throw new ScaffoldError("HFS_ADD_APP_UNKNOWN", `front-end app ${app} is not declared`);
-  feName(selected.name, "declared app");
-  return { root: repoRoot, app: selected.name, repo, source: `fe/apps/${selected.name}/src` };
-}
-
-/** Read a required owner file only after checking every path ancestor. */
-export function readFeFile(context, relative) {
-  const target = feTarget(context.root, relative);
-  if (!fs.existsSync(target) || !fs.statSync(target).isFile()) {
-    throw new ScaffoldError("HFS_ADD_WIRE_MISSING", `${relative} is required before this feature can be added`);
-  }
-  return fs.readFileSync(target, "utf8");
-}
-
-/** Refuse an existing owner, including a partially generated one. */
-export function requireNewFeOwner(context, relative) {
-  if (fs.existsSync(feTarget(context.root, relative))) {
-    throw new ScaffoldError("HFS_ADD_EXISTS", `${relative} already exists; add never replaces an existing owner`);
-  }
-}
-
-function readCatalogs(context) {
-  const directory = `${context.source}/modules/i18n/messages`;
-  const target = feTarget(context.root, directory);
-  if (!fs.existsSync(target)) throw new ScaffoldError("HFS_ADD_WIRE_MISSING", `${directory} is required`);
-  if (!fs.statSync(target).isDirectory()) throw new ScaffoldError("HFS_ADD_I18N_INVALID", `${directory} must be a directory`);
-  const files = fs.readdirSync(target).filter((file) => file.endsWith(".json")).sort();
-  if (!["vi.json", "en.json"].every((file) => files.includes(file))) {
-    throw new ScaffoldError("HFS_ADD_I18N_MISSING", `${directory} needs both vi.json and en.json`);
-  }
-  return files.map((file) => {
-    const relative = `${directory}/${file}`;
-    const before = readFeFile(context, relative);
-    return { relative, before, locale: file.slice(0, -5), catalog: parseCatalog(before, relative) };
-  });
-}
-
-function parseCatalog(before, relative) {
-  let catalog;
-  try { catalog = JSON.parse(before); } catch {
-    throw new ScaffoldError("HFS_ADD_I18N_INVALID", `${relative} must contain valid JSON`);
-  }
-  if (!objectCatalog(catalog)) throw new ScaffoldError("HFS_ADD_I18N_INVALID", `${relative} must contain a catalog object`);
-  return catalog;
-}
-
-function catalogNamespace(catalogs, app) {
-  const first = catalogs[0].catalog;
-  const keys = Object.keys(first);
-  let namespace = keys.length === 1 ? keys[0] : app;
-  if (!Object.hasOwn(first, namespace) && Object.hasOwn(first, "app")) namespace = "app";
-  if (!catalogs.every(({ catalog }) => Object.hasOwn(catalog, namespace) && objectCatalog(catalog[namespace]))) {
-    throw new ScaffoldError("HFS_ADD_I18N_INVALID", "the app catalogs need a shared object namespace");
-  }
-  return namespace;
-}
-
-function catalogCopy(locale, defaults, messages) {
-  const copy = messages?.[locale] ?? defaults[locale];
-  const required = Object.keys(defaults.en);
-  if (!copy || !required.every((key) => typeof copy[key] === "string" && copy[key].trim())) {
-    throw new ScaffoldError("HFS_ADD_I18N_INVALID", `provide the ${required.join(", ")} messages for locale ${locale}`);
-  }
-  return Object.fromEntries(required.map((key) => [key, copy[key]]));
-}
-
-/** Plan matching localized keys in every catalog without changing existing copy. */
-export function planFeCatalogs(context, { group, name, defaults, messages }) {
-  const catalogs = readCatalogs(context);
-  const namespace = catalogNamespace(catalogs, context.app);
-  const updates = catalogs.map(({ catalog, locale, relative, before }) => {
-    const owner = catalog[namespace];
-    if (owner[group] !== undefined && !objectCatalog(owner[group])) {
-      throw new ScaffoldError("HFS_ADD_I18N_INVALID", `${relative}: ${namespace}.${group} must be an object`);
-    }
-    owner[group] ??= {};
-    if (Object.hasOwn(owner[group], name)) {
-      throw new ScaffoldError("HFS_ADD_EXISTS", `${relative} already declares ${namespace}.${group}.${name}`);
-    }
-    owner[group][name] = catalogCopy(locale, defaults, messages);
-    return { relative, before, body: jsonText(catalog) };
-  });
-  return { namespace: `${namespace}.${group}.${name}`, updates };
-}
-
-function createParent(root, target, made) {
-  const missing = [];
-  for (let at = path.dirname(target); at !== root && !fs.existsSync(at); at = path.dirname(at)) missing.push(at);
-  for (const directory of missing.reverse()) {
-    fs.mkdirSync(directory);
-    made.push(directory);
-  }
-}
-
-function writeCreated(target, body, written) {
-  const descriptor = fs.openSync(target, "wx");
-  written.push(target);
-  try { fs.writeFileSync(descriptor, body); } finally { fs.closeSync(descriptor); }
-}
-
-/** Execute a fully checked plan and restore updated owners if a write fails. */
-export function writeFePlan(context, created, updates) {
-  for (const file of created) requireNewFeOwner(context, file.relative);
-  for (const file of updates) {
-    if (readFeFile(context, file.relative) !== file.before) {
-      throw new ScaffoldError("HFS_ADD_WIRE_INVALID", `${file.relative} changed while planning the feature`);
-    }
-  }
-  const written = [];
-  const updated = [];
-  const directories = [];
-  try {
-    for (const file of created) {
-      const target = feTarget(context.root, file.relative);
-      createParent(context.root, target, directories);
-      writeCreated(target, file.body, written);
-    }
-    for (const file of updates) {
-      updated.push(file);
-      fs.writeFileSync(feTarget(context.root, file.relative), file.body);
-    }
-  } catch (error) {
-    for (const file of updated.reverse()) fs.writeFileSync(feTarget(context.root, file.relative), file.before);
-    for (const file of written.reverse()) fs.rmSync(file);
-    for (const directory of directories.reverse()) fs.rmdirSync(directory);
-    throw error;
-  }
-  return { created: created.map((file) => file.relative), updated: updates.map((file) => file.relative) };
-}
-
-function pageSources({ name, namespace, symbol, routeSymbol }) {
-  const metadata = `${name.split("-").map((word, index) => index ? pascalOf(word) : word).join("")}Metadata`;
-  return {
-    metadata,
-    entry: `import type { Metadata } from "next"
-import { getTranslations } from "next-intl/server"
-import { ${routeSymbol} } from "@/modules/routes"
-import { ${symbol}Base } from "./component"
-
-/** The localized document title and canonical destination of this page. */
-export const ${metadata} = async (): Promise<Metadata> => {
-    const t = await getTranslations(${JSON.stringify(namespace)})
-    return { title: t("title"), alternates: { canonical: ${routeSymbol} } }
-}
-
-/** Resolve the requested locale's copy before drawing this server page. */
-export const ${symbol} = async () => {
-    const t = await getTranslations(${JSON.stringify(namespace)})
-    return <${symbol}Base props={{ title: t("title") }} />
-}
-`,
-    component: `import { Heading } from "@starci/grammar/common"
-
-/** The localized words displayed by this page. */
-export interface ${symbol}BaseProps {
-    readonly props: { readonly title: string }
-}
-
-/** Draw the page using the settled copy supplied by its server owner. */
-export const ${symbol}Base = (props: ${symbol}BaseProps) => (
-    <Heading level={1}>{props.props.title}</Heading>
-)
-`,
-  };
-}
-
-function pageRoute(symbol, metadata) {
-  return `import { ${symbol} } from "@/features/pages/${symbol}"
-
-/** The locale-aware metadata of this page. */
-export { ${metadata} as generateMetadata } from "@/features/pages/${symbol}"
-
-/** Mount the page's public server owner. */
-const Page = () => <${symbol} />
-
-export default Page
-`;
-}
-
-/** Add a server page, its thin localized route and matching vi/en catalog entries. */
-export function addFePage({ root, app, name, route = name, messages }) {
-  feName(name, "page name");
-  if (typeof route !== "string" || !route) throw new ScaffoldError("HFS_ADD_OPTION_INVALID", "--route needs one or more kebab-case path segments");
-  for (const segment of route.split("/")) feName(segment, "route segment");
-  const context = readFeContext({ root, app });
-  const symbol = `${pascalOf(name)}Page`;
-  const owner = `${context.source}/features/pages/${symbol}`;
-  requireNewFeOwner(context, owner);
-  const routeFile = `${context.source}/app/[locale]/${route}/page.tsx`;
-  requireNewFeOwner(context, routeFile);
-  const catalogs = planFeCatalogs(context, {
-    group: "pages", name, messages,
-    defaults: { vi: { title: "Trang m\u1edbi" }, en: { title: "New page" } },
-  });
-  const routeSymbol = `${name.replaceAll("-", "_").toUpperCase()}_PAGE_ROUTE`;
-  const routesFile = `${context.source}/modules/routes/index.ts`;
-  const before = readFeFile(context, routesFile);
-  if (before.split(/[^A-Za-z0-9_]/).includes(routeSymbol)) {
-    throw new ScaffoldError("HFS_ADD_EXISTS", `${routesFile} already declares ${routeSymbol}`);
-  }
-  const sources = pageSources({ name, namespace: catalogs.namespace, symbol, routeSymbol });
-  const created = [
-    { relative: `${owner}/index.tsx`, body: sources.entry },
-    { relative: `${owner}/component.tsx`, body: sources.component },
-    { relative: routeFile, body: pageRoute(symbol, sources.metadata) },
-  ];
-  const destination = `/${route}`;
-  const routeBody = `${before.trimEnd()}\n\n/** The canonical destination of the ${symbol} owner. */\nexport const ${routeSymbol} = ${JSON.stringify(destination)} as const\n`;
-  const updates = [...catalogs.updates, { relative: routesFile, before, body: routeBody }];
-  return { ...writeFePlan(context, created, updates), registered: { app: context.app, page: symbol, route: destination } };
-}

package/scaffold/supabase-ports.mjs

@@ -17,7 +17,7 @@ export const SUPABASE_PORT_VARIABLES = Object.freeze(Object.keys(OFFSETS).map((k
 const hash = (text) => [...text].reduce((value, char) => Math.imul(value ^ char.charCodeAt(0), 16777619) >>> 0, 2166136261);
 
 /** The first port of the project's block. */
-export const supabasePortBase = (project) => RANGE_START + (hash(String(project)) % BLOCK_COUNT) * BLOCK_SIZE;
+const supabasePortBase = (project) => RANGE_START + (hash(String(project)) % BLOCK_COUNT) * BLOCK_SIZE;
 
 /** { supabasePortApi: '41231', ... }: the variables a skeleton file fills. */
 export function supabasePortVars(project) {

package/src/main.mjs

@@ -15,7 +15,7 @@
 //                                            runs on those owners without clones and dead exports. No merge-base is a refusal
 //                                            (exit 2), never a silent full pass. Exit 1 on any error-level finding. The root checks run once and
 //                                            the side checks and the machine once per side, the side folder as their root; every path is app-relative.
-//   starci app lint [--cwd <dir>] [--changed <file>...] [--workspace <dir>] [--fix] [--format text|json] [--sonar <file>]
+//   starci app lint [--cwd <dir>] [--changed <file>...] [--workspace <dir>] [--side be|fe] [--fix] [--format text|json] [--sonar <file>]
 //                                            the ONE lint entry (npm run lint): ESLint per side with that side's canon config (per-file rules and
 //                                            the project-graph rules), this check's findings, and stylelint over the fe side, as one starci/lint@1
 //                                            report; --sonar writes the one Sonar import file. Exit 0 clean, 1 findings, 2 a tool could not run (lint/run.mjs).
@@ -43,6 +43,9 @@
 //   starci app secret materialize <env> | list <env> | verify <env>
 //                                            dotenv custody in .starcistacks, public age rule initialization, private KEY files outside Git;
 //                                            values reach stdout only when get explicitly receives --reveal.
+//   starci app ci secret set <NAME> [--env E | --dependabot] [--repo owner/name]  reads the value from stdin only.
+//   starci app ci var set <NAME> [--env E] [--value v] | var sync [--execute] | verify [--json]
+//                                            declared GitHub CI custody; verify compares names, scopes and public values.
 //   starci app db baseline | restamp --map <restamp.yaml> | plan
 //                                            preview the database cutover or compare its state with the repo; baseline and restamp mutate only with --apply.
 //   starci app add <api|webhook|realtime|saga|job|reactor|queue|projection> <name> [--event <event> --from <service> --service <Class>=<module>] [--owner <service> --failed <event> --done <event>] [--connection <name>] [--cwd <dir>]
@@ -83,18 +86,22 @@ import { ACTIONS as STACK_ACTIONS, stackMain as deployStackMain } from '../stack
 import { releaseMain } from '../release/index.mjs';
 import { dbMigrateMain } from '../db/migrate.mjs';
 import { dbPostCutoverMain } from '../db/post-cutover.mjs';
+import { dbDumpMain } from '../db/dump.mjs';
+import { dbResetMain } from '../db/reset.mjs';
 
-export const VERBS = Object.freeze(['scaffold', 'add', 'lint', 'sync', 'check', 'upgrade', 'stack', 'release', 'explain', 'emit', 'new', 'secret', 'db', 'hygiene']);
-const DATABASE_VERBS = new Map([['baseline', dbBaselineMain], ['restamp', dbRestampMain], ['plan', dbPlanMain], ['migrate', dbMigrateMain], ['post-cutover', dbPostCutoverMain]]);
+export const VERBS = Object.freeze(['scaffold', 'add', 'lint', 'sync', 'check', 'upgrade', 'stack', 'release', 'explain', 'emit', 'new', 'secret', 'ci', 'db', 'hygiene']);
+const DATABASE_VERBS = new Map([['baseline', dbBaselineMain], ['restamp', dbRestampMain], ['plan', dbPlanMain], ['migrate', dbMigrateMain], ['post-cutover', dbPostCutoverMain], ['dump', dbDumpMain], ['reset', dbResetMain]]);
 
 const USAGE = `starci app scaffold <name> [--into <dir>] [--edition full|lite] [--registry-visibility public|private] [--cwd <dir>]
 starci app add <api|webhook|realtime|saga|job|reactor|queue|projection|cli|table|app> <name> [options] [--cwd <dir>]
-starci app lint [--cwd <dir>] [--changed <file>...] [--workspace <dir>] [--fix] [--format text|json] [--sonar <file>]
+starci app lint [--cwd <dir>] [--changed <file>...] [--workspace <dir>] [--side be|fe] [--fix] [--format text|json] [--sonar <file>]
 starci app sync (--check | --write) [--cwd <dir>]
 starci app check [--cwd <dir>] [--json] [--fast] [--base <ref>] [--edition full] [--db-types] [--wiring] [--coverage-from <lcov>]
 starci app db baseline [--stamp <version>] [--local] [--apply] [--cwd <dir>]
 starci app db restamp --map <restamp.yaml> [--local] [--apply] [--cwd <dir>]
 starci app db plan [--local] [--json] [--cwd <dir>]
+starci app db dump (--linked | --local | --url-env <NAME>) --out <dir> [--schema-only] [--json] [--cwd <dir>]
+starci app db reset --linked --auth keep|drop --storage keep|drop --backup <receipt.json> [--execute] [--json] [--cwd <dir>]
 starci app db migrate [--execute] [--linked | --url-env <NAME>] [--json] [--cwd <dir>]
 starci app db post-cutover [--execute] [--green-at <ISO> | --owner-confirms-old-app-gone] [--linked | --url-env <NAME>] [--json] [--cwd <dir>]
 starci app release gate [--execute] [--source <ref>] [--tag-prefix <prefix>] [--json] [--cwd <dir>]
@@ -116,6 +123,10 @@ starci app secret remove <env> <slug> [--execute] [--force-nonempty] [--cwd <dir
 starci app secret materialize <env> [--cwd <dir>]
 starci app secret list <env> [--cwd <dir>]
 starci app secret verify <env> [--cwd <dir>]
+starci app ci secret set <NAME> [--env E | --dependabot] [--repo owner/name] [--cwd <dir>]
+starci app ci var set <NAME> [--env E] [--value v] [--repo owner/name] [--cwd <dir>]
+starci app ci var sync [--execute] [--repo owner/name] [--cwd <dir>]
+starci app ci verify [--json] [--repo owner/name] [--cwd <dir>]
 starci app hygiene [--cwd <dir>]
 `;
 const PER_CODE_LIMIT = 25;
@@ -318,7 +329,7 @@ async function installedStackMain(cwd) {
 function databaseMain(argv, io) {
   const [verb, ...rest] = argv;
   const dispatch = DATABASE_VERBS.get(verb);
-  if (!dispatch) throw new Error('starci app db takes baseline, restamp, plan, migrate or post-cutover');
+  if (!dispatch) throw new Error('starci app db takes baseline, restamp, plan, migrate, post-cutover, dump or reset');
   return dispatch(rest, io);
 }
 
@@ -408,7 +419,7 @@ async function stackAppMain(argv, { cwd, edition, stackMain, stdout: out, stderr
   return run(argv, { cwd, out, err });
 }
 
-const DIRECT_VERBS = new Map([['lint', lintMain], ['secret', secretMain], ['db', databaseMain], ['upgrade', upgradeAppMain], ['stack', stackAppMain], ['release', releaseMain]]);
+const DIRECT_VERBS = new Map([['ci', async (argv, io) => (await import('../ci/cli.mjs')).ciMain(argv, io)], ['lint', lintMain], ['secret', secretMain], ['db', databaseMain], ['upgrade', upgradeAppMain], ['stack', stackAppMain], ['release', releaseMain]]);
 const PARSED_VERBS = new Map([['check', checkMain], ['emit', emitMain], ['new', newMain], ['add', addMain], ['scaffold', scaffoldMain], ['explain', explainMain]]);
 
 function dispatchMain(verb, argv, io) {

package/stack/age-install.mjs

@@ -5,7 +5,7 @@ import { firstLine } from './context.mjs';
 const AGE_VERSION = 'v1.2.1';
 const AGE_URL = `https://github.com/FiloSottile/age/releases/download/${AGE_VERSION}/age-${AGE_VERSION}-linux-amd64.tar.gz`;
 /** sha256 of the official linux/amd64 archive of AGE_VERSION. */
-export const AGE_SHA256 = '7df45a6cc87d4da11cc03a539a7470c15b1041ab2b396af088fe9990f7c79d50';
+const AGE_SHA256 = '7df45a6cc87d4da11cc03a539a7470c15b1041ab2b396af088fe9990f7c79d50';
 const INSTALL = { dnf: 'sudo -n dnf install -y age', yum: 'sudo -n yum install -y age', apk: 'sudo -n apk add age', 'apt-get': 'sudo -n apt-get install -y age' };
 
 const STATIC_INSTALL = [

package/stack/cli.mjs

@@ -18,7 +18,7 @@ const VALUE = new Set(['--env', '--image', '--source-sha', '--previous', '--out'
 const REPEAT = new Set(['--image', '--keep', '--extra-compose', '--project']);
 
 /** Splits argv into { flags, positional }; an unknown flag or a flag without its value is a refusal. */
-export function parseFlags(argv) {
+function parseFlags(argv) {
   const flags = {};
   const positional = [];
   for (let index = 0; index < argv.length; index += 1) {
@@ -37,7 +37,7 @@ export function parseFlags(argv) {
 }
 
 /** `--image api=ghcr.io/o/x@sha256:...` (repeatable or comma separated) -> { api: 'ghcr.io/o/x@sha256:...' }. */
-export function parseImages(values = []) {
+function parseImages(values = []) {
   const out = {};
   for (const item of values.flatMap((value) => value.split(','))) {
     const at = item.indexOf('=');

package/stack/context.mjs

@@ -1,11 +1,18 @@
 // context.mjs - the seams every stack module runs through: spawning tools, sleeping, the clock and the output.
-// Production uses the real implementations; the specs inject fakes (tests/helpers/stack-fakes.mjs).
-import { spawnSync } from 'node:child_process';
+// Production uses the real implementations; a spec injects fakes.
+import { spawn, spawnSync } from 'node:child_process';
 import { defaultSops } from '../runtime/scripts/hfs/secret-sops.mjs';
 
 const MAX_BUFFER = 1 << 24;
 
 const realSpawn = (command, args, options = {}) => {
+  if (options.background) {
+    const childOptions = { ...options };
+    delete childOptions.background;
+    const child = spawn(command, args, { stdio: 'ignore', windowsHide: true, ...childOptions });
+    child.on('error', (error) => { child.spawnError = error; });
+    return child;
+  }
   const run = spawnSync(command, args, { encoding: 'utf8', maxBuffer: MAX_BUFFER, ...options });
   return { status: run.status, stdout: run.stdout ?? '', stderr: run.stderr ?? '', error: run.error };
 };
@@ -16,6 +23,8 @@ const realSleep = (ms) => new Promise((done) => { setTimeout(done, ms); });
  * The context of one stack invocation.
  *   cwd, env       the app root and the process environment
  *   spawn          (command, args, { input, env, cwd }) -> { status, stdout, stderr, error }; never a shell
+ *                  { background: true } -> ChildProcess, owned and killed by the command session
+ *   platform       POSIX control master or win32 loopback tunnel; sshPath optionally selects the POSIX SSH executable
  *   sleep, now     await sleep(ms); now() -> epoch ms
  *   stdout, stderr text writers
  *   fetch          the HTTP seam of verify (url, init) -> Response
@@ -29,6 +38,9 @@ export function stackContext(io = {}) {
     cwd,
     env,
     spawn: io.spawn ?? realSpawn,
+    platform: io.platform ?? process.platform,
+    username: io.username,
+    sshPath: io.sshPath,
     sleep: io.sleep ?? realSleep,
     now: io.now ?? Date.now,
     stdout: io.stdout ?? ((text) => process.stdout.write(text)),

package/stack/digest.mjs

@@ -1,6 +1,6 @@
 // digest.mjs - image reference and release identifier guards (the all-zero placeholder digest is never a real image).
 /** A registry image reference pinned by a real sha256 digest; the all-zero placeholder digest is refused. */
-export const DIGEST_REF = /^[a-z0-9./_-]+(?::[A-Za-z0-9._-]+)?@sha256:(?!0{64}$)[0-9a-f]{64}$/u;
+const DIGEST_REF = /^[a-z0-9./_-]+(?::[A-Za-z0-9._-]+)?@sha256:(?!0{64}$)[0-9a-f]{64}$/u;
 
 /** A release identifier: the first 16 hex characters of the release digest. */
 export const RELEASE_ID = /^[0-9a-f]{16}$/u;

package/stack/docker-transport.mjs

@@ -1,15 +1,19 @@
 // docker-transport.mjs - lets the verbs that drive the docker CLI (deploy, converge, verify, rollback, prune) reach the manager from an OPERATOR
-// machine. In CI `connect` writes the ssh config and DOCKER_HOST; on an operator machine the key lives in the sealed members, so the docker CLI
-// is run with a private HOME that holds an ssh config for the sealed session and DOCKER_HOST=ssh://<alias>. Only `docker` children that did not get
+// machine or CI. The command shares one POSIX control master (including remote scripts) or one Windows Docker socket tunnel. On an operator
+// machine the key lives in the sealed members, so the docker CLI is run with a private HOME that holds the session's ssh config. Only children that did not get
 // an explicit environment are affected (the minimal environment of `docker stack config` stays exactly as the render built it). The key lives in
 // a private temp directory that is overwritten and removed when the verb ends; it is never in argv, a line or an error.
 import fs from 'node:fs';
 import path from 'node:path';
 import { writePrivate } from './private-file.mjs';
 import { openSealedSession } from './remote.mjs';
+import { controlSettings, createSshSession, sessionDirectory } from './ssh-session.mjs';
+import { failure } from './errors.mjs';
 
 const ALIAS = 'stack-vps';
 const forward = (file) => file.replaceAll('\\', '/');
+const configPath = (file) => '"' + forward(file).replaceAll('"', '\\"') + '"';
+const controlLines = (controlPath) => controlSettings(configPath(controlPath)).map((setting) => `  ${setting.replace('=', ' ')}`);
 
 /** True when the operator's docker CLI has to be pointed at the manager by this module. */
 function needed(ctx, config, sshCmd) {
@@ -19,35 +23,109 @@ function needed(ctx, config, sshCmd) {
   return [sealed.ops, sealed.sshKey, sealed.knownHosts].every((slug) => fs.existsSync(path.join(config.secretsDir, `${slug}.enc`)));
 }
 
-function sshConfig(session) {
+function sshConfig(session, controlPath, windows) {
   const at = session.account.lastIndexOf('@');
   return [
     `Host ${ALIAS}`, `  HostName ${session.account.slice(at + 1)}`, `  User ${session.account.slice(0, at)}`,
-    `  IdentityFile ${forward(session.keyFile)}`, '  IdentitiesOnly yes', `  UserKnownHostsFile ${forward(session.knownFile)}`,
-    `  StrictHostKeyChecking ${session.strict}`, '  BatchMode yes', '  ConnectTimeout 20', '',
+    `  IdentityFile ${configPath(session.keyFile)}`, '  IdentitiesOnly yes', `  UserKnownHostsFile ${configPath(session.knownFile)}`,
+    `  StrictHostKeyChecking ${session.strict}`, '  BatchMode yes', '  ConnectTimeout 20',
+    ...(windows ? [] : controlLines(controlPath)), '',
   ].join('\n');
 }
 
 /** The environment of a docker child: a private HOME with the ssh config, DOCKER_HOST, and the operator's docker config (registry logins) kept. */
-function dockerEnvironment(ctx, session) {
+function dockerEnvironment(ctx, session, controlPath) {
   const home = path.join(session.dir, 'home');
-  fs.mkdirSync(path.join(home, '.ssh'), { recursive: true });
-  writePrivate(ctx, path.join(home, '.ssh', 'config'), sshConfig(session));
+  fs.mkdirSync(home, { recursive: true, mode: 0o700 });
+  fs.chmodSync(home, 0o700);
+  fs.mkdirSync(path.join(home, '.ssh'), { recursive: true, mode: 0o700 });
+  writePrivate(ctx, path.join(home, '.ssh', 'config'), sshConfig(session, controlPath, (ctx.platform ?? process.platform) === 'win32'));
   const operatorHome = ctx.env.HOME ?? ctx.env.USERPROFILE ?? '';
   const dockerConfig = ctx.env.DOCKER_CONFIG ?? (operatorHome ? path.join(operatorHome, '.docker') : undefined);
   return { ...ctx.env, HOME: home, USERPROFILE: home, DOCKER_HOST: `ssh://${ALIAS}`, ...(dockerConfig ? { DOCKER_CONFIG: dockerConfig } : {}) };
 }
 
+/** OpenSSH resolves its default config from the account database, so Docker needs a private PATH entry that supplies -F explicitly. */
+function privateSshEnvironment(ctx, env, dir, controlPath) {
+  if ((ctx.platform ?? process.platform) === 'win32') {
+    const home = path.join(dir, 'home');
+    fs.mkdirSync(home, { recursive: true, mode: 0o700 });
+    fs.chmodSync(home, 0o700);
+    const originalHome = env.HOME ?? env.USERPROFILE;
+    const dockerConfig = env.DOCKER_CONFIG ?? (originalHome ? path.join(originalHome, '.docker') : undefined);
+    return { env: { ...env, HOME: home, USERPROFILE: home, ...(dockerConfig ? { DOCKER_CONFIG: dockerConfig } : {}) }, executable: 'ssh' };
+  }
+  const originalHome = ctx.env.HOME;
+  const home = path.join(dir, 'home');
+  const config = path.join(home, '.ssh', 'config');
+  fs.mkdirSync(path.dirname(config), { recursive: true, mode: 0o700 });
+  if (!fs.existsSync(config)) {
+    const include = originalHome ? `Include ${configPath(path.join(originalHome, '.ssh', 'config'))}\n` : '';
+    writePrivate(ctx, config, ['Host *', ...controlLines(controlPath), 'Host *', include].join('\n'));
+  }
+  const executable = ctx.sshPath ?? findSsh(ctx.env.PATH);
+  const bin = path.join(home, 'bin');
+  fs.mkdirSync(bin, { mode: 0o700 });
+  const shim = path.join(bin, 'ssh');
+  writePrivate(ctx, shim, `#!/bin/sh\nexec ${posixQuote(executable)} -F ${posixQuote(config)} "$@"\n`);
+  fs.chmodSync(shim, 0o700);
+  const dockerConfig = env.DOCKER_CONFIG ?? (originalHome ? path.join(originalHome, '.docker') : undefined);
+  return { env: { ...env, HOME: home, PATH: `${bin}:${env.PATH ?? ctx.env.PATH ?? ''}`, ...(dockerConfig ? { DOCKER_CONFIG: dockerConfig } : {}) }, executable };
+}
+
+const posixQuote = (value) => "'" + value.replaceAll("'", "'\\''") + "'";
+
+function findSsh(searchPath = '') {
+  const executable = searchPath.split(':').map((dir) => path.join(dir, 'ssh')).find((file) => fs.existsSync(file));
+  if (!executable) throw failure('STACK_SSH_SESSION', 'cannot locate the SSH executable');
+  return path.resolve(executable);
+}
+
 /** Runs `body(ctx')` where ctx'.spawn points the docker CLI at the manager when this is an operator machine; otherwise `body(ctx)`. */
 export async function withDockerTransport(ctx, config, { sshCmd = null } = {}, body) {
-  if (!needed(ctx, config, sshCmd)) return body(ctx);
-  const session = openSealedSession(ctx, config);
-  const env = dockerEnvironment(ctx, session);
-  const spawn = (command, args, options = {}) => (command === 'docker' && options.env === undefined ? ctx.spawn(command, args, { ...options, env }) : ctx.spawn(command, args, options));
-  for (const note of session.notes) ctx.stderr(`${note}\n`);
+  if (sshCmd) return body(ctx);
+  const sealed = needed(ctx, config, sshCmd);
+  const alias = sealed ? ALIAS : sshAlias(ctx.env.DOCKER_HOST);
+  if (!alias) return body(ctx);
+  const session = sealed ? openSealedSession(ctx, config) : null;
+  const dir = session?.dir ?? sessionDirectory();
+  let connection;
+  let cleaned = false;
+  function cleanup() {
+    if (cleaned) return;
+    cleaned = true;
+    if (session) session.cleanup();
+    else fs.rmSync(dir, { recursive: true, force: true });
+  }
   try {
-    return await body(Object.create(ctx, { spawn: { value: spawn } }));
+    const controlPath = forward(path.join(dir, 'home', 'cm'));
+    const baseEnv = session ? dockerEnvironment(ctx, session, controlPath) : ctx.env;
+    const { env, executable } = privateSshEnvironment(ctx, baseEnv, dir, controlPath);
+    const configFile = path.join(env.HOME ?? '', '.ssh', 'config');
+    const options = ['-o', 'BatchMode=yes', '-o', 'ConnectTimeout=20'];
+    const argv = session || executable !== 'ssh' ? [executable, ...options, '-F', configFile, '--', alias] : ['ssh', ...options, '--', alias];
+    connection = createSshSession(ctx, { argv, env, controlPath, cleanup });
+    const spawn = dockerSpawn(ctx, connection, env, alias);
+    for (const note of session?.notes ?? []) ctx.stderr(`${note}\n`);
+    return await body(Object.create(ctx, { spawn: { value: spawn }, stackSsh: { value: connection } }));
   } finally {
-    session.cleanup();
+    try { await connection?.close(); } finally {
+      cleanup();
+    }
   }
 }
+
+/** Only SSH Docker endpoints belong to this connection; TCP, unix and explicitly supplied child environments keep their behavior. */
+function sshAlias(host) {
+  if (!host?.startsWith('ssh://')) return null;
+  const endpoint = new URL(host);
+  if (endpoint.port || endpoint.pathname && endpoint.pathname !== '/') return null;
+  return endpoint.username ? `${decodeURIComponent(endpoint.username)}@${endpoint.hostname}` : endpoint.hostname;
+}
+
+function dockerSpawn(ctx, connection, env, alias) {
+  return (command, args, options = {}) => {
+    if (command !== 'docker' || options.env !== undefined) return ctx.spawn(command, args, options);
+    return ctx.spawn(command, args, { ...options, env: { ...env, DOCKER_HOST: connection.dockerHost(alias) } });
+  };
+}

package/stack/edge-alias.mjs

@@ -22,7 +22,7 @@ const sameSet = (left, right) => [...new Set(left)].sort().join('\n') === [...ne
 const show = (aliases) => `[${aliases.join(', ')}]`;
 
 /** [{ service, network, aliases }]: every service attached to an `external: true` network of the stack, with the aliases it declares. */
-export function edgeAttachments(bytes) {
+function edgeAttachments(bytes) {
   const model = parseYaml(bytes) ?? {};
   const external = new Map(Object.entries(model.networks ?? {}).filter(([, definition]) => definition?.external === true).map(([key, definition]) => [key, String(definition.name ?? key)]));
   return Object.entries(model.services ?? {}).flatMap(([service, entry]) => Object.entries(networkMap(entry?.networks))

package/stack/image-scan.mjs

@@ -51,7 +51,7 @@ const paxPath = (body) => body.toString('utf8').split('\n').map((record) => /^\d
  * Walks a tar file by header: calls visit({ name, type, size, read }) for every entry (`read()` returns the content, called only for files worth
  * reading). Handles ustar prefixes, GNU long names (L) and PAX paths (x). Content is never loaded unless the visitor asks for it.
  */
-export function walkTar(file, visit) {
+function walkTar(file, visit) {
   const fd = fs.openSync(file, 'r');
   try {
     const header = Buffer.alloc(BLOCK);

package/stack/ingress-create.mjs

@@ -26,7 +26,7 @@ function readLegacy(run, ingress) {
 }
 
 /** The stack model (compose spec as JSON, which is valid YAML). */
-export function stackModel(ingress, { args, dynamicTarget, acmeTarget }) {
+function stackModel(ingress, { args, dynamicTarget, acmeTarget }) {
   const ports = [80, 443].map((port) => ({ target: port, published: port, protocol: 'tcp', mode: 'host' }));
   return {
     services: {
@@ -54,7 +54,7 @@ export function stackModel(ingress, { args, dynamicTarget, acmeTarget }) {
 }
 
 /** The guard that no task can start from this model. */
-export function refuseRunning(model) {
+function refuseRunning(model) {
   for (const [name, service] of Object.entries(model.services)) {
     if (service.deploy?.replicas !== 0) throw refusal('STACK_INGRESS_WOULD_START', `the ingress service ${name} would start a task; create deploys it with replicas 0 only`);
   }

package/stack/ingress.mjs

@@ -44,7 +44,7 @@ const originOf = (url) => {
 // ---- the live and the declared routes -------------------------------------------------------------------------------------------
 
 /** Host keys of a proxy router rule: `a.example` for Host(...), `regexp:<pattern>` for HostRegexp(...). */
-export function hostsOfRule(rule) {
+function hostsOfRule(rule) {
   const out = [];
   for (const [, kind, args] of String(rule).matchAll(MATCHER)) {
     for (const [, value] of args.matchAll(QUOTED)) out.push(kind === 'Host' ? value.toLowerCase() : `regexp:${value}`);
@@ -53,7 +53,7 @@ export function hostsOfRule(rule) {
 }
 
 /** { routes: [{ host, targets }], middlewares: [name] } of one parsed file-provider dynamic document (any shape is tolerated). */
-export function routesOfDocument(doc) {
+function routesOfDocument(doc) {
   const http = asMap(asMap(doc).http);
   const services = asMap(http.services);
   const targetsOf = (name) => {
@@ -491,7 +491,7 @@ const rehearsalVolume = (ingress) => `${ingress.acmeVolume}-rehearsal`;
 const classOf = (code) => Math.floor(code / 100);
 
 /** The static arguments of the ingress service with the ACME http challenge moved to an unused internal entrypoint. */
-export function rehearsalArgs(args) {
+function rehearsalArgs(args) {
   const quiet = args.map((arg) => arg.replace(CHALLENGE_ARG, `$1=${UNUSED_ENTRYPOINT}`));
   return [...quiet, `--entrypoints.${UNUSED_ENTRYPOINT}.address=127.0.0.1:1`];
 }